# Siemens MCP Server for iX Angular A Model Context Protocol (MCP) server that provides AI assistants (Agents) with access to [Siemens Industrial Experience](https://ix.siemens.io) design system and component API documentation through Retrieval-Augmented Generation (RAG). This enables more accurate and relevant assistance with design system and component library APIs. ## Usage and use cases - Local MCP server installation includes all design system documentation, component APIs, examples and icon information - MCP server integration with your AI Agent setup of choice, integrated into your IDE (for example, GitHub Copilot Agent integration within VS Code, or OpenCode, with project-related MCP configuration) - Use cases include (but are not limited to): - Get design system best practice information - Export components - Review project text according to UX writing guidelines - Generate new pages using design system components - Add and modify pages ## Installation ### 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/ix-mcp-angular` for every `@siemens/ix-angular` version. The version of `@siemens/ix-mcp-angular` must match your version of `@siemens/ix-angular`. The version number of the MCP package `@siemens/ix-mcp-angular` is a combination of the `@siemens/ix-angular` version and the version of the MCP code. For example, `@siemens/ix-mcp-angular@4.0.0-v.1.4.8` comes with the data of `@siemens/ix-angular@4.0.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) `@ix` that match the version of `@siemens/ix-angular`. When using the corresponding distribution tag on installation, you get the latest version of the MCP package that matches your `@siemens/ix-angular` version and simplifies handling in your `package.json`. ```json "dependencies": { "@siemens/ix-angular": "4.0.0", }, "devDependencies": { "@siemens/ix-mcp-angular": "4.0.0-v.1.4.8", } ``` New MCP package versions on the same `ix` version are incremented like `4.0.0-v.1.4.9`, `4.0.0-v.1.4.10`, `4.0.0-v.1.5.0`. ### Project installation ```bash npm install --save-dev --save-exact @siemens/ix-mcp-angular@ix4.0.0 # Or with yarn yarn add -D --exact @siemens/ix-mcp-angular@ix4.0.0 ``` ### Global installation ```bash npm install -g @siemens/ix-mcp-angular@ix4.0.0 ``` ### Upgrading Simply install the tag for your version and framework again: ```bash # in project npm install --save-dev --save-exact @siemens/ix-mcp-angular@ix4.1.0 # with yarn yarn add -D --exact @siemens/ix-mcp-angular@ix4.1.0 # global npm install -g --save-exact @siemens/ix-mcp-angular@ix4.1.0 ``` ## Quick Start After local project or global package installation, you need to initialize the MCP server and provide the access token. 1. **Navigate to your project directory**: ```bash cd your-project ``` 2. **Run initial setup**: ```bash npx @siemens/ix-mcp-angular init ``` Or if token is already set up: ```bash npx @siemens/ix-mcp-angular setup ``` > 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, Claude Code, Zed, etc.) - Optionally set up iX 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, 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 like **Claude Sonnet 4.5**. 5. **Start prompting**: - "How do I use the search component from @siemens/ix?" - "Show me examples of @siemens/charts-ng usage" - "Implement a dashboard with different widgets" - "Find icons related to AI or machine learning" - "Review the texts of this project" > The MCP server starts automatically when your AI tools need it. ## 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 `.vscode/mcp.json` in the current repository - **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) After MCP configuration, you can set up iX instruction files so AI agents work more effectively with your codebase. Do this in each repository where you want instructions. You have two options: - **Symbolic link to receive updates** Keeps files synced with the installed package. Requires the package to remain installed and may not work on all systems or package managers. The tool can create symlinks automatically; otherwise, create links yourself pointing to the installed package's `AGENTS.md` and iX instructions. - **Copy the content** Copy the contents of the package’s `AGENTS.md` into one of the following in your repo: - `.github/instructions/ix.instructions.md` - `AGENTS.md` - `.github/copilot-instructions.md` 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. ## Logging Per default no logging is performed, 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 local log files in `~/.ix-mcp-angular`. ```json { "servers": { "@siemens/ix-mcp-angular": { "type": "stdio", "command": "npx", "args": ["@siemens/ix-mcp-angular", "--log"] } } } ``` ### Viewing and sharing logs To view logs, use the `npx @siemens/ix-mcp-angular log` command, select any 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. ## Usage ### Commands #### Init (First-time setup) Complete initial setup: configure token and create all MCP configurations. ```bash npx @siemens/ix-mcp-angular init ``` #### Setup (Update configurations) Create or update MCP configuration files for your tools (uses existing token). ```bash npx @siemens/ix-mcp-angular setup ``` #### Setup Token Set or update only the LLM token in system keychain. ```bash npx @siemens/ix-mcp-angular setup-token ``` #### Check Verify your installation and configuration. ```bash npx @siemens/ix-mcp-angular check ``` #### Test Test the MCP server with a sample query. ```bash npx @siemens/ix-mcp-angular test ``` #### Log Check your previous MCP retrieval logs (if enabled / not disabled). ```bash npx @siemens/ix-mcp-angular log ``` ### Use within WSL (Windows Subsystem for Linux) 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): ``` SDL_MCP_TOKEN_ENV=true OPENAI_API_KEY= ``` Make sure the `.env` file is in your `.gitignore` and can't be committed. Alternatively, or if you're using global installation, add these to your shell profile (`~/.zprofile` or `~/.bash_profile`): ```bash export SDL_MCP_TOKEN_ENV=true export OPENAI_API_KEY= ``` ### 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/ ## Manual Configuration If you prefer to set up the configurations manually, here are the required files and their contents. ### VS Code (.vscode/mcp.json or User/mcp.json) ```json { "servers": { "@siemens/ix-mcp-angular": { "type": "stdio", "command": "npx", "args": ["@siemens/ix-mcp-angular"] } } } ``` ### OpenCode (Local or Global) For repository-level configuration, create `opencode.json` in your project root: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "ix-mcp-angular": { "type": "local", "command": ["npx", "-y", "@siemens/ix-mcp-angular"], "enabled": true } }, "instructions": ["iX.instructions.md"] } ``` For global configuration, edit `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "ix-mcp-angular": { "type": "local", "command": ["npx", "-y", "@siemens/ix-mcp-angular"], "enabled": true } } } ``` Learn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config). ### Claude Code (Global Claude Code MCP settings) ```json { "mcpServers": { "@siemens/ix-mcp-angular": { "type": "stdio", "command": "npx", "args": ["-y", "@siemens/ix-mcp-angular"], "env": {} } } } ``` On Windows, prefer the full path to `npx`, for example: ```json { "mcpServers": { "@siemens/ix-mcp-angular": { "type": "stdio", "command": "", "args": ["-y", "@siemens/ix-mcp-angular"], "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. - https://code.siemens.com/ai/opencode/#getting-started - https://open.code.siemens.io ### Zed (Global Zed settings) ```json { "context_servers": { "@siemens/ix-mcp-angular": { "source": "custom", "command": "npx", "args": ["@siemens/ix-mcp-angular"], "env": {} } } } ``` ## License The following applies for code and documentation of the git repository, unless explicitly mentioned. Copyright (c) Siemens 2016 - 2025 MIT, see [LICENSE.md](LICENSE.md). ### Open Source Software The software of this distributed MCP npm package consists of the database file and JavaScript files, which provide access to the database, implementing the Model Context Protocol. This package does not include any third party software. However, to use this software, you need the Open Source Software packages specified in the `dependencies` part of the [package.json](package.json) file, and their dependencies. When installing this package with a npm package manager, the dependencies are automatically installed (e.g., when using npm). ## Support For issues and questions, please use the issue tracker at: [https://code.siemens.com/ux/sdl-mcp/issues](https://code.siemens.com/ux/sdl-mcp/issues) For suboptimal retrievals / agent behavior, consider attaching a relevant log to help us figure out how to improve the service, see [Viewing and sharing logs](#viewing-and-sharing-logs).