--- name: sap-cap-mcp-server-essentials description: How to use the SAP CAP MCP Server well and safely. Confirms the CAP project or model scope before searching, chooses between searching the project model and searching CAP documentation, keeps results narrow so context is not flooded, and handles empty or blocked searches. Use when the user asks about a CAP model, entity, service, annotation, or CDS question, wants to look something up in the CAP documentation, or asks what the SAP CAP MCP Server can do. --- # Use the SAP CAP MCP Server This connector gives read-only access to two things: the **model** of a CAP project (`search_model`) and the **CAP documentation** (`search_docs`). Its job is to find the right fact quickly and say where it came from. It does not change anything in the project. Use it to answer questions, then check the answer against the user's source files before relying on it. ## 1. Confirm the scope before the first search Search results are only meaningful for one specific project. Before calling `search_model`, establish: - **Which project or model** the user means. A workspace can contain several CAP applications, and each has its own services and entities. If the user has not said, ask one short question: "Which CAP project should I search?" Do not guess from a similarly named entity in another project. - **Whether the question is about their project or about CAP in general.** "Which entities does my `BookshopService` expose?" is a model question. "How do I write a `@restrict` rule?" is a documentation question. Mixing them produces answers that sound authoritative but describe the wrong thing. - **The CDS version or runtime in use, if it affects the answer** (Node.js or Java runtime, CAP version). Annotation syntax and service behaviour changed across CAP releases. If the user has not said and the answer depends on it, say so instead of assuming the latest version. ## 2. Choose the right tool Use the first tool that answers the question. Do not run both by default. 1. **`search_model`** for anything about *this* project's structure: services, entities, fields, types, associations, actions and functions, annotations applied in the model. Start with the most specific name you have (the entity or service name). Broad queries like "all entities" flood the context; search for the one you need, then widen only if it is not there. 2. **`search_docs`** for how CAP itself works: syntax, concepts, configuration options, recommended patterns, error meanings. Phrase the query as the concept ("draft-enabled entities", "unbound actions", "managed associations"), not as a full sentence about the user's code. 3. **Both** when the user asks how something they have already built should look under CAP rules, for example "is my `@readonly` placement correct?". Get the model fact from `search_model`, then the rule from `search_docs`, and compare them yourself. Say which part came from which tool. ## 3. Keep results narrow - Ask for one object at a time. A single service or entity answers most questions; a whole model dump does not. - When results are long, quote only the lines that bear on the question, with the name of the object they belong to. Do not paste whole model listings into the reply. - If the first result set is large, refine the query with the exact entity or annotation name rather than paging through everything. Only page further when the user needs the complete list. - Report counts when they matter ("3 services match; the one exposing `Books` is `CatalogService`") so the user knows whether the list is complete. ## 4. Treat output as evidence, not as truth about their app Tool output tells you what the connector found. It does not prove the running application behaves that way. Before stating a conclusion about the user's project: - Check the entity, field or annotation in the user's own `.cds` files when you have access to them. A model view can be stale, or can reflect a different branch. - For documentation answers, note the CAP version the docs describe if the user's version may differ. - Keep the wording honest: "The model shows X" or "The CAP docs describe Y" is accurate; "your app does X" is not, until you have checked it. ## 5. Handle empty, partial or blocked results - **No results from `search_model`:** the name may be wrong, the object may be in another project, or the model may not include it. Try the singular and plural form, the service name rather than the entity name, and the unqualified name. If it still returns nothing, say so and ask the user to confirm the project and the exact name. Do not invent the object. - **No results from `search_docs`:** rephrase with the CAP term used in the official docs, then say the documentation did not cover it. Do not fill the gap with recalled behaviour from memory of older CAP releases. - **Blocked or failed call** (permission denied, connection error, timeout): report the exact error, do not retry in a loop, and say what the user can check (the server is running, the project is connected, the account has access). Continue with whatever you can answer from the user's own files, and label that clearly. - **Partial results:** say what was returned and what is missing, rather than presenting the subset as the full answer. ## Common patterns and traps - **Searching the wrong project.** The most common error. Two projects may both define an entity called `Books`. Always state the project name in the answer. - **Confusing model and docs.** A docs answer about the default behaviour of `@restrict` is not the same as the rule enforced in this project's service. Keep the two apart in the reply. - **Version drift.** CAP syntax and defaults change between releases. An answer correct for one release can be wrong for the user's. Name the version whenever it could matter. - **Over-broad queries.** Asking for "everything about the model" produces a wall of text that hides the one fact needed. Narrow first. - **Treating absence as proof.** A search that finds nothing shows the connector did not find it, not that it does not exist. Say "not found by search_model" rather than "does not exist". - **Guessing names.** If a name is not in the results, do not construct a plausible one (for example, a generated `.drafts` or `.texts` entity) and present it as real. Confirm it in the model or the user's files first. ## Output ``` Scope: Tool used: Answer: Source: Checked against project files: Not established: ``` ## Rules - Do not run `search_model` before the project or model is confirmed when more than one project could be meant. - Never present search output as verified fact about the user's application until it has been checked against their source, or the reply says it was not checked. - Do not invent entity, service, field or annotation names that the search did not return. - Do not paste large model or documentation dumps into the reply; quote only what answers the question. - This connector is read-only. It cannot create, change or deploy anything. If the user asks for a change to their project, make the change suggestion in the reply and wait for the user's explicit yes before editing any file, and do not treat the connector as able to make the change. ## Done when - The project or model scope is stated in the reply, or the user was asked which project to search. - The answer names the tool it came from, and the objects or docs topic it relies on. - Any claim about the user's application is either checked against their source or labelled as not checked. - Empty or blocked results are reported honestly, with the next step for the user.