diff --git a/README.md b/README.md index 8f39fbc..bcbe6b5 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,74 @@ -# @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_). -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?_ -> [!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) + - [CLI UsageI](#cli-usage) +- [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` -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 @@ -31,24 +77,44 @@ 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 -## Setup -```sh -npm i -g @cap-js/mcp-server + +## Usage + +Configure your MCP client (Cline, opencode, Claude Code, etc.) to start the server using the `cds-mcp` command. + +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. +- 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. +Add these rules to your existing global or project-specific [`AGENTS.md`](https://agents.md/) (specifics may vary based on respective MCP client). -## Usage +### Usage in VS Code -Configure your MCP client (Claude Code, opencode, and so on) to start the server with command `cds-mcp`. +Example for VS Code extension [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev): +```json +{ + "mcpServers": { + "cds-mcp": { + "command": "cds-mcp", + "args": [], + "env": {} + } + } +} +``` -Example for opencode: +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 + +Example for [opencode](https://github.com/sst/opencode): ```json { "mcp": { @@ -61,16 +127,9 @@ Example for opencode: } ``` -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. -``` - ### 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,14 +139,16 @@ 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: +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 @@ -97,30 +158,40 @@ 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 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 semantic search approach enables you to find relevant documentation even when your query does not use the exact keywords found in the docs. -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. -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.