From d47c8444c290bfa8cd79c6f4942d14b4309694a9 Mon Sep 17 00:00:00 2001 From: D050513 Date: Mon, 25 Aug 2025 11:32:37 +0200 Subject: [PATCH 1/5] chore: improve readme --- README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 106 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 8f39fbc..da40c37 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,16 @@ -# @cap-js/mcp-server +# Welcome to @cap-js/mcp-server [![REUSE status](https://api.reuse.software/badge/github.com/cap-js/mcp-server)](https://api.reuse.software/info/github.com/cap-js/mcp-server) + + +> [!NOTE] +> This project is in alpha state. Don't use it for production code. + + + +## About This Project + A Model Context Protocol (MCP) server for the [SAP Cloud Application Programming Model (CAP)](https://cap.cloud.sap). Use it for AI-assisted development of CAP applications (_agentic coding_). @@ -12,11 +21,50 @@ The server helps AI models answer questions like: - _How do they relate?_ - _How do I add columns to a select statement in CAP Node.js?_ -> [!NOTE] -> This project is in alpha state. Don't use it for production code. + + +## Table of Contents + +- [About This Project](#about-this-project) +- [Requirements](#requirements) +- [Setup](#setup) +- [Available Tools](#available-tools) + - [`search_model`](#search_model) + - [`search_docs`](#search_docs) +- [Usage](#usage) + - [Usage in VS Code](#usage-in-vs-code) + - [Usage in opencode](#usage-in-opencode) + - [Usage in CLI](#usage-in-cli) +- [How It Works](#how-it-works) +- [Support, Feedback, Contributing](#support-feedback-contributing) +- [Security / Disclosure](#security--disclosure) +- [Code of Conduct](#code-of-conduct) +- [Licensing](#licensing) +- [Acknowledgments](#acknowledgments) + + + +## Requirements + +See [Getting Started](https://cap.cloud.sap/docs/get-started) on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model. + + + +## Setup + +```sh +npm i -g @cap-js/mcp-server +``` + +This will provide the command `cds-mcp` to start the CAP MCP server. + + ## 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_model` @@ -35,19 +83,52 @@ Search [CAP documentation](https://cap.cloud.sap) for: - Code snippets and examples - API usage patterns -## Setup -```sh -npm i -g @cap-js/mcp-server + +## Usage + +Configure your MCP client (Cline, opencode, Claude Code, etc.) to start the server with command `cds-mcp`. + +The following rules help guide the LLM to use the server correctly: + +```markdown +- 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 modify CDS models or when using APIs from CAP. Do NOT propose, suggest or make any changes without first checking it. ``` -This will provide the command `cds-mcp` to start the CAP MCP server. +### Usage in VS Code -## Usage + + +TODO: + +```json +{ + "mcpServers": { + "cds-mcp": { + "command": "cds-mcp", + "args": [], + "env": {} + } + } +} +```json + +See the [VS Code docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. -Configure your MCP client (Claude Code, opencode, and so on) to start the server with command `cds-mcp`. +### Usage in opencode -Example for opencode: +Example for [opencode](https://github.com/sst/opencode): ```json { @@ -61,16 +142,11 @@ Example for opencode: } ``` -The following rules help guide the LLM to use the server correctly: +Don't forget to add the rules to `~/.config/opencode/AGENTS.md`, or in your project-specific `AGENTS.md` file. -```markdown -- 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 modify CDS models or when using APIs from CAP. Do NOT propose, suggest or make any changes without first checking it. -``` +### Usage in CLI -### CLI Usage - -You can also use the tools directly from the command line: +For experimental purposes, you can also use the tools directly from the command line: ```sh # Search for CDS model definitions @@ -80,6 +156,8 @@ cds-mcp search_model . Books entity cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1 ``` + + ## How It Works The server provides two complementary search mechanisms optimized for different use cases: @@ -105,22 +183,32 @@ This tool uses vector embeddings to search through preprocessed CAP documentatio This approach enables semantic search - you can find relevant documentation even when your query doesn't contain exact keywords from the docs. + + ## Support, Feedback, Contributing This project is open to feature requests/suggestions, bug reports, and so on, via [GitHub issues](https://github.com/cap-js/mcp-server/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md). + + ## Security / Disclosure If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/cap-js/mcp-server/security/policy) on how to report it. Please don't create GitHub issues for security-related doubts or problems. + + ## Code of Conduct We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times. + + ## Licensing Copyright 2025 SAP SE or an SAP affiliate company and @cap-js/cds-mcp contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cap-js/mcp-server). + + ## Acknowledgments - **onnxruntime-web** is used for creating embeddings in Node.js. From fdcfd35a45ca4cb581ec18f6f2e8c14fba6869ee Mon Sep 17 00:00:00 2001 From: "Dr. David A. Kunz" Date: Mon, 25 Aug 2025 14:02:19 +0200 Subject: [PATCH 2/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index da40c37..49583da 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ TODO: See the [VS Code docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. -### Usage in opencode +### Usage in [opencode](https://github.com/sst/opencode) Example for [opencode](https://github.com/sst/opencode): From 52442443639d9857f6fae5d1e8ddde7602993038 Mon Sep 17 00:00:00 2001 From: D050513 Date: Mon, 25 Aug 2025 14:26:02 +0200 Subject: [PATCH 3/5] AGENTS.md + Usage in VS Code --- README.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 49583da..1d32abd 100644 --- a/README.md +++ b/README.md @@ -96,21 +96,11 @@ The following rules help guide the LLM to use the server correctly: - You MUST search for CAP docs with cds-mcp EVERY TIME you modify CDS models or when using APIs from CAP. Do NOT propose, suggest or make any changes without first checking it. ``` -### Usage in VS Code - - +### Usage in VS Code -TODO: +Example for VS Code extension [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev): ```json { @@ -122,9 +112,9 @@ TODO: } } } -```json +``` -See the [VS Code docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details. +See [VS Code Marketplace](https://marketplace.visualstudio.com/search?term=tag%3Aagent&target=VSCode&category=All%20categories&sortBy=Relevance) for more agent extensions. ### Usage in [opencode](https://github.com/sst/opencode) @@ -142,8 +132,6 @@ Example for [opencode](https://github.com/sst/opencode): } ``` -Don't forget to add the rules to `~/.config/opencode/AGENTS.md`, or in your project-specific `AGENTS.md` file. - ### Usage in CLI For experimental purposes, you can also use the tools directly from the command line: From 57e893f63d5cdb4462cdf3242fca63db7373aa0c Mon Sep 17 00:00:00 2001 From: D050513 Date: Mon, 25 Aug 2025 14:26:42 +0200 Subject: [PATCH 4/5] opencode --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1d32abd..4af160c 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ Example for VS Code extension [Cline](https://marketplace.visualstudio.com/items See [VS Code Marketplace](https://marketplace.visualstudio.com/search?term=tag%3Aagent&target=VSCode&category=All%20categories&sortBy=Relevance) for more agent extensions. -### Usage in [opencode](https://github.com/sst/opencode) +### Usage in opencode Example for [opencode](https://github.com/sst/opencode): From 8d936f63590befe711a6b9272328ccf2241fc00f Mon Sep 17 00:00:00 2001 From: D050513 Date: Mon, 25 Aug 2025 14:39:30 +0200 Subject: [PATCH 5/5] adjusted copilot review --- README.md | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 4af160c..bcbe6b5 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,8 @@ A Model Context Protocol (MCP) server for the [SAP Cloud Application Programming Model (CAP)](https://cap.cloud.sap). Use it for AI-assisted development of CAP applications (_agentic coding_). -The server helps AI models answer questions like: - -- _Which CDS services are there in this project and where are they served?_ +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?_ - _How do they relate?_ - _How do I add columns to a select statement in CAP Node.js?_ @@ -34,7 +33,7 @@ The server helps AI models answer questions like: - [Usage](#usage) - [Usage in VS Code](#usage-in-vs-code) - [Usage in opencode](#usage-in-opencode) - - [Usage in CLI](#usage-in-cli) + - [CLI UsageI](#cli-usage) - [How It Works](#how-it-works) - [Support, Feedback, Contributing](#support-feedback-contributing) - [Security / Disclosure](#security--disclosure) @@ -69,8 +68,7 @@ The server provides these tools for CAP development: ### `search_model` -Search for CDS definitions (entities, services, actions) including: - +Search for CDS definitions (entities, services, actions), including: - Model structure and relationships - Annotations and metadata - HTTP endpoints and OData URLs @@ -79,7 +77,6 @@ Search for CDS definitions (entities, services, actions) including: ### `search_docs` Search [CAP documentation](https://cap.cloud.sap) for: - - Code snippets and examples - API usage patterns @@ -87,9 +84,9 @@ Search [CAP documentation](https://cap.cloud.sap) for: ## Usage -Configure your MCP client (Cline, opencode, Claude Code, etc.) to start the server with command `cds-mcp`. +Configure your MCP client (Cline, opencode, Claude Code, etc.) to start the server using the `cds-mcp` command. -The following rules help guide the LLM to use the server correctly: +The following rules help the LLM use the server correctly: ```markdown - 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. @@ -101,7 +98,6 @@ Add these rules to your existing global or project-specific [`AGENTS.md`](https: ### Usage in VS Code Example for VS Code extension [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev): - ```json { "mcpServers": { @@ -119,7 +115,6 @@ See [VS Code Marketplace](https://marketplace.visualstudio.com/search?term=tag%3 ### Usage in opencode Example for [opencode](https://github.com/sst/opencode): - ```json { "mcp": { @@ -132,7 +127,7 @@ Example for [opencode](https://github.com/sst/opencode): } ``` -### Usage in CLI +### CLI Usage For experimental purposes, you can also use the tools directly from the command line: @@ -148,12 +143,12 @@ cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1 ## How It Works -The server provides two complementary search mechanisms optimized for different use cases: +The server provides two complementary search mechanisms, optimized for different use cases: ### `search_model` - Compiled Model Search -This tool performs fuzzy search against the compiled CDS model (CSN - Core Schema Notation). When you run a CAP project, CDS compiles all your `.cds` files into a unified model representation that includes: - +This tool performs fuzzy searches against the compiled CDS model (CSN - Core Schema Notation). +When you run a CAP project, CDS compiles all your `.cds` files into a unified model representation that includes: - All entities, services, actions, and their relationships - Resolved annotations and metadata - Generated HTTP endpoints and OData URLs @@ -163,13 +158,13 @@ The fuzzy search algorithm matches definition names and allows for partial match ### `search_docs` - Embedding-Based Documentation Search -This tool uses vector embeddings to search through preprocessed CAP documentation content stored locally. The process works as follows: +This tool uses vector embeddings to search through preprocessed CAP documentation stored locally. The process works as follows: -1. **Pre-processing**: CAP documentation is chunked into semantic sections and converted to vector embeddings using a local embedding model. -2. **Query processing**: Your search query is also converted to an embedding vector. -3. **Similarity search**: The system finds documentation chunks with the highest semantic similarity to your query. +1. **Pre-processing:** CAP documentation is split into semantic sections and converted to vector embeddings using a local embedding model. +2. **Query processing:** Your search query is also converted to an embedding vector. +3. **Similarity search:** The system finds documentation chunks with the highest semantic similarity to your query. -This approach enables semantic search - you can find relevant documentation even when your query doesn't contain exact keywords from the docs. +This semantic search approach enables you to find relevant documentation even when your query does not use the exact keywords found in the docs.