chore: improve readme

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
+<!--
+To **register the server** (once), follow these steps:
+1. Run command `MCP: Add Server...`
+1. Select `Command`
+1. Set `cds-mcp` as the command
+1. Provide `@cap-js/mcp-server` as the Server ID
+1. Choose to install globally
+
+**In an application project**, open the _Chat_ panel.
+Select the server through the _Select tools_ button.
+-->
+
+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.