From 14f31c4c3dadb3ff22b3021e47d8696cc35fd5c0 Mon Sep 17 00:00:00 2001 From: Linus Schlumberger Date: Wed, 3 Jun 2026 13:09:33 +0200 Subject: [PATCH] docs(mcp): update docs to include claude code, drop cline and make easier to follow --- docs/get-started/element-mcp.md | 273 ++++++++++++++++++++------------ 1 file changed, 175 insertions(+), 98 deletions(-) diff --git a/docs/get-started/element-mcp.md b/docs/get-started/element-mcp.md index e8d8430e6c..18715107ee 100644 --- a/docs/get-started/element-mcp.md +++ b/docs/get-started/element-mcp.md @@ -23,38 +23,12 @@ system and component library APIs. ### Prerequisites - Node.js (20+ recommended) -- Access to the API [https://api.siemens.com/llm](https://api.siemens.com) by creating a free token - at with `llm` scope. We use the `embeddings` API. Siemens access is - required to request a token. We are working on a configurable alternative. -- IDE/Agent/LLM setup of your choice (for example: VS Code, GitHub Copilot, Claude Sonnet 4.5) - -### Version selection - -We distribute a MCP server package `@siemens/element-mcp` for every `@siemens/element-ng` version. -The version of `@siemens/element-mcp` must match your version of `@siemens/element-ng`. The version -number of the MCP package `@siemens/element-mcp` is a combination of the `@siemens/element-ng` -version and the version of the MCP code. - -For example, `@siemens/element-mcp@48.2.0-v.1.4.8` comes with the data of -`@siemens/element-ng@48.2.0` and `v.1.4.8` is the version of the MCP script. - -To facilitate the version selection, we use -[npm distribution tags](https://docs.npmjs.com/cli/commands/npm-dist-tag) `@element` that -match the version of `@siemens/element-ng`. When using the corresponding distribution tag on -installation, you get the latest version of the MCP package that matches your `@siemens/element-ng` -version and simplifies handling in your `package.json`. - -```json -"dependencies": { - "@siemens/element-ng": "48.2.0", - }, - "devDependencies": { - "@siemens/element-mcp": "48.2.0-v.1.4.8", - } -``` - -New MCP package versions on the same `element-ng` version are incremented like `48.2.0-v.1.4.9`, -`48.2.0-v.1.4.10`, `48.2.0-v.1.5.0`. +- Create a free token at [https://my.siemens.com](https://my.siemens.com) with `llm` scope to get + access to the `embeddings` API at + [https://api.siemens.com/llm](https://api.siemens.com/llm). + (Currently, Siemens access is required to request a token, but we are working on a configurable alternative for all users.) +- IDE/agent/LLM setup of your choice, e.g. VS Code, GitHub Copilot, Claude Sonnet 4.5, OpenCode +- Use `@siemens/element-mcp` for Element projects. ### Project installation @@ -71,25 +45,9 @@ yarn add -D --exact @siemens/element-mcp@element48.2.0 npm install -g @siemens/element-mcp@element48.2.0 ``` -### Upgrading - -Simply install the tag for your version and framework again: - -```bash -# in project -npm install --save-dev --save-exact @siemens/element-mcp@element48.3.0 - -# with yarn -yarn add -D --exact @siemens/element-mcp@element48.3.0 - -# global -npm install -g --save-exact @siemens/element-mcp@element48.3.0 -``` - ## Quick Start -After local project or global package installation, you need to initialize the MCP server and -provide the access token. +After successful installation you need to initialize the MCP server and provide the access token: 1. **Navigate to your project directory**: @@ -103,7 +61,7 @@ provide the access token. npx @siemens/element-mcp init ``` - Or if token is already set up: + Or if the token is already set up: ```bash npx @siemens/element-mcp setup @@ -112,21 +70,21 @@ provide the access token. > Important: Run this command in the root of every project where you want to use the MCP server. 3. **Follow the prompts**: - - Enter your LLM token from https://my.siemens.com/ (requires 'llm' scope) - - This token is needed to generate embeddings for semantic search of the documentation. The - embeddings help find relevant documentation chunks, but the actual LLM (language model) that - processes your queries and generates responses is provided separately by your AI tool (e.g., - GitHub Copilot, Claude, etc.) - - Choose which tools to configure (VS Code, Cline, Zed, etc.) - - Optionally set up Element instruction files for AI agents - - The tool will create MCP configuration files based on your selection, commit the local - configuration to share it (make sure it is not ignored by `.gitignore`) - -4. **Restart your AI tools** (VS Code, Cline, Zed, etc.) - - Ensure the server is running and trust the MCP server, e.g. click the "Server" icon in the - Github Copilot Chat panel in VS Code. - - **For GitHub Copilot in VS Code**: Make sure you are in Agent Mode (not Chat Mode). Use models - like **Claude Sonnet 4.5**. + - **Token setup**: Enter your LLM token from [https://my.siemens.com/](https://my.siemens.com/) (requires 'llm' scope) + - **Tool configuration**: + 1. Choose which tools to configure (VS Code, OpenCode, Claude Code, Zed, etc.). + 2. Enable logging of MCP queries and responses (optional) + - **Agent instructions**: + 1. Setup can add predefined instruction files to your project that guide agents how to develop with Element + 2. Use symlinks/aliases to help keep instruction files updated (optional) + > This may not work for every package manager or platform (e.g. Windows) + - Commit the local configuration to share it (make sure it isn't ignored by `.gitignore`). + +4. **Restart your AI tools** (VS Code, OpenCode, Claude Code, Zed, etc.) + - Ensure the server is running and trust the MCP server, e.g., click the "Server" icon in the + GitHub Copilot Chat panel in VS Code. + - **For GitHub Copilot in VS Code**: Make sure you are in Agent Mode, not Chat Mode. Use models, + e.g. **Claude Sonnet 4.5**. 5. **Start prompting**: - "How do I use the Filtered-Search component from @siemens/element-ng?" @@ -137,22 +95,24 @@ provide the access token. > The MCP server starts automatically when your AI tools need it. -## Setup Options +## Setup options During `init` or `setup`, select which configuration(s) to create: -- **Local VS Code / GitHub Copilot (Repository)** creates a VS Code MCP configuration file at +- **Local VS Code / GitHub Copilot (repository)** creates a VS Code MCP configuration file at `.vscode/mcp.json` in the current repository -- **Cline Global Settings** updates global Cline MCP configuration -- **VS Code / GitHub Copilot Global Config** writes user-level MCP config -- **Zed Global Settings** configures Zed editor / agent MCP +- **OpenCode (repository)** creates `opencode.json` in the current repository for OpenCode AI +- **OpenCode global settings** updates global OpenCode configuration (`~/.config/opencode/opencode.json`) +- **Claude Code global settings** updates global Claude Code MCP configuration +- **VS Code / GitHub Copilot global config** writes user-level MCP config +- **Zed global settings** configures Zed editor / agent MCP -## AI Agent Instructions (optional) +## AI agent instructions (optional) -After MCP configuration, you can set up Element and Angular instruction files so AI agents work more -effectively with your codebase. Do this in each repository where you want instructions. +After MCP configuration, set up Element instruction files so AI agents work more effectively with +your codebase. Do this in each repository where you want instructions. -You have two options: +For this, you have two options: - **Symbolic link to receive updates** Keeps files synced with the installed package. Requires the package to remain installed and may @@ -160,7 +120,8 @@ You have two options: otherwise, create links yourself pointing to the installed package's `AGENTS.md` and Element instructions. -- **Copy the content** Copy the contents of the package’s `AGENTS.md` into one of the following in +- **Copy the content** + Copy the contents of the package’s `AGENTS.md` into one of the following files in your repo: - `.github/instructions/Element.instructions.md` - `AGENTS.md` @@ -169,14 +130,59 @@ You have two options: If you prefer manual copy, open the package’s `AGENTS.md`, then paste it into your chosen file and commit it. Repeat per repository whenever you want to update the instructions. +## Version selection + +We distribute an MCP server package `@siemens/element-mcp` for every `@siemens/element-ng` version. +The version of `@siemens/element-mcp` must match your version of `@siemens/element-ng`. The version +number of the MCP package `@siemens/element-mcp` is a combination of the `@siemens/element-ng` +version and the version of the MCP code. + +For instance, `@siemens/element-mcp@48.2.0-v.1.4.8` comes with the data of +`@siemens/element-ng@48.2.0` and `v.1.4.8` is the version of the MCP script. + +To facilitate version selection, we use +[npm distribution tags](https://docs.npmjs.com/cli/commands/npm-dist-tag) `@element` that +match the version of `@siemens/element-ng`. When using the corresponding distribution tag on +installation, you get the latest version of the MCP package that matches your `@siemens/element-ng` +version and simplifies handling in your `package.json`. + +```json +"dependencies": { + "@siemens/element-ng": "48.2.0", + }, + "devDependencies": { + "@siemens/element-mcp": "48.2.0-v.1.4.8", + } +``` + +New MCP package versions on the same `element-ng` version are incremented like `48.2.0-v.1.4.9`, +`48.2.0-v.1.4.10`, `48.2.0-v.1.5.0`. + +## Upgrading + +Simply install the package again with the updated version. + +For example, if you want to upgrade from Element 48.2.0 to 48.3.0: + +```bash +# in project +npm install --save-dev --save-exact @siemens/element-mcp@element48.3.0 + +# with yarn +yarn add -D --exact @siemens/element-mcp@element48.3.0 + +# global +npm install -g --save-exact @siemens/element-mcp@element48.3.0 +``` + ## Logging -Per default no logging is performed, but you can enable local-only logging of all search queries and +By default, the server performs no logging, but you can enable local-only logging of all search queries and retrieval results during setup. ### Manually enabling logging -In your MCP configuration add the flag `--log` to log all search queries and retrieval results to +In your MCP configuration, add the `--log` flag to log all search queries and retrieval results to local log files in `~/.element-mcp`. ```json @@ -193,18 +199,18 @@ local log files in `~/.element-mcp`. ### Viewing and sharing logs -To view logs, use the `npx @siemens/element-mcp log` command, select any relevant session and look -at the output or the files copied to your current working directory. +To view logs, use the `npx @siemens/element-mcp log` command. +Select a relevant session and look at the output or the files copied to your current working directory. -For feedback about the MCP and Agent results, please create an issue at -[https://code.siemens.com/ux/sdl-mcp/issues](https://code.siemens.com/ux/sdl-mcp/issues), share your -information, and include the relevant logs. +To help us improve the MCP agent, please send feedback on your MCP and agent results by creating an issue at +[https://code.siemens.com/ux/sdl-mcp/issues](https://code.siemens.com/ux/sdl-mcp/issues). Share your +details and include the relevant logs. ## Usage ### Commands -#### Init (First-time setup) +#### Init (first-time setup) Complete initial setup: configure token and create all MCP configurations. @@ -212,7 +218,7 @@ Complete initial setup: configure token and create all MCP configurations. npx @siemens/element-mcp init ``` -#### Setup (Update configurations) +#### Setup (update configurations) Create or update MCP configuration files for your tools (uses existing token). @@ -220,9 +226,14 @@ Create or update MCP configuration files for your tools (uses existing token). npx @siemens/element-mcp setup ``` -#### Setup Token +#### Setup token -Set or update only the LLM token in system keychain. +Set or update only the LLM token in the system keychain. + +This token is used to generate embeddings for a semantic search of the documentation. +These embeddings help find relevant documentation chunks, but your AI tool +(e.g. GitHub Copilot, Claude, etc.) provides the actual LLM (language model) +that processes your queries and generates responses separately. ```bash npx @siemens/element-mcp setup-token @@ -256,16 +267,16 @@ npx @siemens/element-mcp log If you're using WSL, you need to configure the LLM token using environment variables instead of the system keychain. Before running any commands, add the following to a `.env` file in the project root -(if you're using project installation): +(if you’re using a project installation): ``` SDL_MCP_TOKEN_ENV=true OPENAI_API_KEY= ``` -Make sure the `.env` file is in your `.gitignore` and can't be committed. +Make sure the `.env` file is in your `.gitignore` and cannot be committed. -Alternatively, or if you're using global installation, add these to your shell profile +Alternatively, or if you’re using a global installation, add these to your shell profile (`~/.zprofile` or `~/.bash_profile`): ```bash @@ -273,17 +284,17 @@ export SDL_MCP_TOKEN_ENV=true export OPENAI_API_KEY= ``` -### Connection Issues +### Connection issues - Verify that the MCP server is running (it should start automatically) - Restart your AI tool after configuration changes -- Verify your LLM token is valid at https://my.siemens.com/ +- Verify your LLM token is valid at [https://my.siemens.com/](https://my.siemens.com/) -## Manual Configuration +## Manual configuration -If you prefer to set up the configurations manually, here are the required files and their contents. +If you prefer to set up configuration manually, here are the required files and their contents. -### VS Code (.vscode/mcp.json or User/mcp.json) +### VS Code (.vscode/mcp.json or user/mcp.json) ```json { @@ -297,27 +308,93 @@ If you prefer to set up the configurations manually, here are the required files } ``` -### Cline (Global Cline MCP settings) +### OpenCode (local or global) + +For repository-level configuration, create `opencode.json` in your project root: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "element-mcp": { + "type": "local", + "command": ["npx", "-y", "@siemens/element-mcp"], + "enabled": true + } + }, + "instructions": ["Element.instructions.md"] +} +``` + +For global configuration, edit `~/.config/opencode/opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "element-mcp": { + "type": "local", + "command": ["npx", "-y", "@siemens/element-mcp"], + "enabled": true + } + } +} +``` + +Learn more about OpenCode configuration at +[https://opencode.ai/docs/config](https://opencode.ai/docs/config). + +Learn how to install it +[here](https://code.siemens.com/ai/opencode/#getting-started) or use the script at +[https://open.code.siemens.io](https://open.code.siemens.io). + +### Claude Code (global Claude Code MCP settings) ```json { "mcpServers": { "@siemens/element-mcp": { + "type": "stdio", "command": "npx", - "args": ["@siemens/element-mcp"] + "args": ["-y", "@siemens/element-mcp"], + "env": {} } } } ``` -### Zed (Global Zed settings) +On Windows, prefer the full path to `npx`, for example: + +```json +{ + "mcpServers": { + "@siemens/element-mcp": { + "type": "stdio", + "command": "", + "args": ["-y", "@siemens/element-mcp"], + "env": {} + } + } +} +``` + +Consider OpenCode as an open alternative + +OpenCode is the established open-source alternative to Claude Code. It offers the same feature set, +broader model support, and is often considered more stable. As a proprietary closed-source tool, +Claude Code may not offer the same transparency and data handling guarantees as a fully open +alternative. See the OpenCode docs for setup. + +- + +### Zed (global Zed settings) ```json { "context_servers": { "@siemens/element-mcp": { "source": "custom", - "command": "", + "command": "npx", "args": ["@siemens/element-mcp"], "env": {} }