Cap Js MCP

Welcome to @cap-js/mcp-server

About This Project

A Model Context Protocol (MCP) server for the SAP Cloud Application Programming Model (CAP). Use it for AI-assisted development of CAP applications (_agentic coding_).

The server helps AI models answer questions such as:

• _Which CDS services are in this project, and where are they served?_
• _What are the entities about and how do they relate?_
• _How do I add columns to a select statement in CAP Node.js?_

Table of Contents

• About This Project
• Requirements
• Setup
• Usage in VS Code
• Usage in Claude Code
• Usage in OpenAI Codex
• Usage in opencode
• CLI Usage
• Environment Variables
• Available Tools
• search_model
• search_docs
• JavaScript API
• Support, Feedback, Contributing
• Security / Disclosure
• Code of Conduct
• Licensing
• Acknowledgments

Requirements

See Getting Started on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model.

Setup

Configure your MCP client (Cline, opencode, Claude Code, GitHub Copilot, etc.) to start the server using the command npx -y @cap-js/mcp-server as in the following examples.

Usage in Claude Code

Register the server with Claude Code.

For all projects (user scope):

claude mcp add --scope user cds-mcp -- npx -y @cap-js/mcp-server

For the current project only (local scope, not committed):

claude mcp add cds-mcp -- npx -y @cap-js/mcp-server

For the current project only (committed to the repository):

claude mcp add --scope project cds-mcp -- npx -y @cap-js/mcp-server

To set an environment variable, add --env before the server name:

claude mcp add --scope user --env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 cds-mcp -- npx -y @cap-js/mcp-server

Usage in VS Code

Example for VS Code extension Cline:

{

"mcpServers": { "cds-mcp": { "command": "npx", "args": ["-y", "@cap-js/mcp-server"], "env": {} } } }

Example for VS Code global mcp.json:

Note: GitHub Copilot uses the mcp.json file as source for it's Agent mode.

{

"servers": { "cds-mcp": { "command": "npx", "args": ["-y", "@cap-js/mcp-server"], "env": {}, "type": "stdio" }, "inputs": [] } }

To set an environment variable, replace the server's empty env object with:

"env": {

"CDS_MCP_MODEL": "nomic-ai/nomic-embed-text-v1.5" }

See VS Code Marketplace for more agent extensions.

Usage in OpenAI Codex

Register the server with OpenAI Codex:

codex mcp add cds-mcp -- npx -y @cap-js/mcp-server

To set an environment variable, add --env before the command:

codex mcp add cds-mcp --env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 -- npx -y @cap-js/mcp-server

Usage in opencode

Add to opencode.jsonc in your project, or to ~/.config/opencode/opencode.jsonc for global use:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "cds-mcp": { "type": "local", "command": ["npx", "-y", "@cap-js/mcp-server"], "environment": { "CDS_MCP_MODEL": "nomic-ai/nomic-embed-text-v1.5" }, "enabled": true } } }

This is the opencode v1 format. In opencode v2, use the same config but nest the server under "servers" — "mcp": { "servers": { "cds-mcp": { ... } } } — or use the CLI instead:

opencode mcp add --global cds-mcp -- npx -y @cap-js/mcp-server

To set an environment variable:

opencode mcp add --global cds-mcp \

--env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 \ -- npx -y @cap-js/mcp-server

Environment Variables

[!WARNING]

The following environment variables are still experimental.

Rules

The following rules help the LLM use the server correctly:

- You MUST search for CDS definitions, like entities, fields and services (which include HTTP endpoints) with cds-mcp, only if it fails you MAY read \*.cds files in the project.

• You MUST search for CAP docs with cds-mcp EVERY TIME you create, modify CDS models or when using APIs or the cds CLI from CAP. Do NOT propose, suggest or make any changes without first checking it.

Add these rules to your existing global or project-specific AGENTS.md (specifics may vary based on respective MCP client).

CLI Usage

You can also use the tools directly from the command line.

npm i -g @cap-js/mcp-server

[!WARNING]

When the package is installed globally, npx uses the installed version instead of downloading the latest from npm. You must update the package manually:

`sh

npm update -g @cap-js/mcp-server

`

This will provide the command cds-mcp, with which you can invoke the tools directly as follows.

# Search CAP documentation

cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1

Search for CDS model definitions

cds-mcp search_model . Books entity

Available Tools

[!NOTE]

Tools are meant to be used by AI models and do not constitute a stable API.

The server provides these tools for CAP development:

search_docs

This tool uses vector embeddings to locally search through preprocessed CAP documentation, stored as embeddings. The process works as follows:

1. Query processing: Your search query is converted to an embedding vector.
2. Similarity search: The system finds documentation chunks with the highest semantic similarity to your query.

This semantic search approach enables you to find relevant documentation even when your query does not use the exact keywords found in the docs, all locally on your machine.

search_model

This tool performs fuzzy searches against names of definitions from the compiled CDS model (Core Schema Notation). CDS compiles all your .cds files into a unified model representation that includes:

• All definitions and their relationships
• Annotations
• HTTP endpoints

The fuzzy search algorithm matches definition names and allows for partial matches, making it easy to find entities like "Books" even when searching for "book".

JavaScript API

Import the supported named exports from the package root:

import { createCapireEmbeddings, DEFAULT_MODEL } from '@cap-js/mcp-server'

Generate capire embeddings from the command line

Generate CAP documentation embeddings with a custom model. The CLI fetches https://cap.cloud.sap/docs/llms-full.txt automatically:

cds-mcp createCapireEmbeddings --model nomic-ai/nomic-embed-text-v1.5

See Configuration for supported flags. Pass them after cds-mcp createCapireEmbeddings.

Use --output ./generated-embeddings to select the output directory.

Generate capire embeddings programmatically

The API fetches CAP documentation from https://cap.cloud.sap/docs/llms-full.txt by default.

Pass the chunking settings, custom model, and output settings to the API:

import { createCapireEmbeddings } from '@cap-js/mcp-server'

const result = await createCapireEmbeddings( { minTokens: 10, maxHeadingDepth: 5 }, { model: 'nomic-ai/nomic-embed-text-v1.5', capireMetadata: { commitId: 'documentation-revision', version: '1.0.0' } } )

To generate multiple models programmatically, pass an array to embeddingConfig.model. The API returns an array of results in the same order. A single model name, or an omitted model, still returns one result object.

To read a local file, use chunkingConfig.input. To supply Markdown directly, use chunkingConfig.text. An explicit input file takes precedence over supplied text.

await createCapireEmbeddings(

{ input: './guide.md', minTokens: 10 }, { model: 'nomic-ai/nomic-embed-text-v1.5' } )

Use generated embeddings in the MCP server

Test your created embeddings with cds-mcp:

CDS_MCP_OFFLINE=true CDS_MCP_OFFLINE_DIR="/absolute/path/to/generated/output" cds-mcp search_docs "How do I define a service?"

To use your generated embeddings, configure your MCP client with the folder that contains them:

{

"mcpServers": { "cds-mcp": { "command": "npx", "args": ["-y", "@cap-js/mcp-server"], "env": { "CDS_MCP_OFFLINE": "true", "CDS_MCP_OFFLINE_DIR": "/absolute/path/to/generated/output" } } } }

Configuration

The CLI and JavaScript API use these settings:

| --model | embeddingConfig.model | Embedding model.