@siemens/ix-mcp-angular 3.2.0-v.1.10.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# iX Development Guidelines
+
+## Project Overview
+
+This document provides guidelines for developing applications using the Siemens iX design system
+packages. The libraries are available as `@siemens/ix-angular` and related packages including
+`@siemens/ix-aggrid`, `@siemens/ix-echarts`, and `@siemens/ix-icons`.
+
+The iX design system is built on Angular and includes comprehensive theming capabilities for
+consistent styling across industrial and enterprise applications.
+
+## Development Approach
+
+Always search iX documentation first before implementing any UI components or patterns. This
+includes looking up component APIs, design patterns, accessibility guidelines, and theming options
+from the official documentation.
+
+Use modern Angular syntax with standalone components, Angular Signals for state management, and
+separate template/style files. Avoid inline templates or styles unless they are very short. Import
+components individually and use arrow functions with const declarations.
+
+Prefer using existing iX components and patterns over implementing custom solutions. Follow the
+established design principles of atomic design, composition over inheritance, and
+accessibility-first development. Use the iX theme system with CSS custom properties rather than
+hardcoded styles.
+
+## Code Quality
+
+Write minimal comments only where necessary, focusing on why rather than what. Avoid meta-comments
+about changes or obvious explanations. Don't add unnecessary error handling for well-established iX
+component APIs and assume components work as documented.
+
+Use iX design tokens and CSS custom properties from the theme system when available instead of
+writing custom CSS. Don't override iX component internals - use documented APIs, props, and CSS
+custom properties for customization. Leverage the established color tokens, spacing system, and
+layout patterns.
+
+Use modern HTML5 and JavaScript features and avoid deprecated syntax. Maintain type safety with iX
+component interfaces and event types.
+
+## Package Management and Testing
+
+Install iX packages using the appropriate package manager and follow the integration guides for each
+framework. Fix import paths when packages exist but imports fail - check for correct package names
+and component exports.
+
+Run available lint, format, and test commands from package.json scripts.
+
+## Implementation Strategy
+
+When building applications, research iX layout patterns and navigation components first. Plan
+component structure using iX building blocks like cards, buttons, modals, and navigation elements.
+Create appropriate mock data that reflects real industrial/enterprise use cases.
+
+Apply iX themes consistently throughout the application. Use the documented layout patterns and
+component compositions. Verify accessibility compliance using iX's built-in accessibility features
+and test with screen readers and keyboard navigation.
+
+Follow the established iX component lifecycle patterns for events, state management, and data
+binding. Use documented event handlers and avoid direct DOM manipulation of iX components.
+
+## Theming and Customization
+
+Use the iX theme system with CSS custom properties for customization. Available themes include
+classic-light, classic-dark, and brand-specific variants not available to non-Siemens projects.
+Apply themes at the application level and use theme-aware CSS custom properties for consistent
+styling.
+
+Don't override iX component styles directly. Instead, use the documented CSS custom properties,
+theme tokens, and layout utilities. Create custom themes following the established token structure
+when brand customization is required.
+
+## Testing and Quality Assurance
+
+Test iX component integration using the established testing patterns. Refrain from testing iX
+component internals. Use ARIA properties in case you need access to shadow DOM elements, instead of
+custom selectors. Verify functionality across different browsers and devices using iX's browser
+support matrix.
+
+Ensure accessibility compliance by testing with screen readers, keyboard navigation, and following
+WCAG 2.1 AA guidelines that iX components are designed to meet. Use iX's built-in accessibility
+features rather than implementing custom solutions.
+
+This approach ensures high-quality development within the iX ecosystem while maintaining modern
+framework practices and leveraging the full design system capabilities for industrial and enterprise
+applications.

package/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License
+
+Copyright (c) Siemens 2016 - 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,391 @@
+# 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 <https://my.siemens.com> 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<version>` 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, Cline, 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, 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**.
+
+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`)
+- **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
+
+## 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=<your-key-here>
+```
+
+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=<your-key-here>
+```
+
+### 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"]
+    }
+  }
+}
+```
+
+### Cline (Global Cline MCP settings)
+
+```json
+{
+  "mcpServers": {
+    "@siemens/ix-mcp-angular": {
+      "command": "npx",
+      "args": ["@siemens/ix-mcp-angular"]
+    }
+  }
+}
+```
+
+### Zed (Global Zed settings)
+
+```json
+{
+  "context_servers": {
+    "@siemens/ix-mcp-angular": {
+      "source": "custom",
+      "command": "<path-to-npx, run which/where npx to find>",
+      "args": ["@siemens/ix-mcp-angular"],
+      "env": {}
+    }
+  }
+}
+```
+
+### 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).
+
+## 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).

package/config.json

@@ -0,0 +1,51 @@
+{
+  "name": "@siemens/ix-mcp-angular",
+  "description": "iX MCP server for Angular",
+  "displayName": "iX Angular",
+  "binName": "ix-mcp-angular",
+  "compatTokenName": "ix-mcp",
+  "documentedName": "iX",
+  "projectName": "iX",
+  "searchToolName": "ix-search",
+  "iconSearch": true,
+  "iconSearchToolName": "ix-icon-search",
+  "iconName": "@siemens/ix-icons",
+  "agentsFile": true,
+  "instructionFileName": "iX.instructions.md",
+  "observabilityLogging": false,
+  "exampleQuestions": [
+    "How do I use the Breadcrumb component from @siemens/ix-angular?",
+    "Show me examples of a pane layout",
+    "Implement a form for adding a new user with name, email, and role",
+    "Find icons related to settings or configuration"
+  ],
+  "texts": {
+    "DOC_SEARCH_INSTRUCTION": "MANDATORY: For ANY Angular development question, UI component inquiry, design pattern request, or frontend implementation need, you MUST immediately use the search tool before providing any response relevant to UI / Design Systems or Angular implementations. Re-check it to get clarifications and more accurate API often, but do not search if completely unrelated or you just searched the exact same. This applies to ALL Angular-related queries regardless of whether iX libraries are explicitly mentioned. The tool provides access to version-specific Siemens iX documentation that is automatically tuned to match the user's library versions. This ensures you get the exact APIs, components, and implementation patterns available in their specific setup rather than generic Angular advice. Always search first to leverage the comprehensive ix and ix-react documentation before offering any Angular guidance.",
+    "DOC_SEARCH_TOOL_DESCRIPTION": "Semantic search tool for Siemens iX Design System and Angular component library. This tool provides intelligent search across comprehensive documentation for:\n\nSupported Libraries:\n• @siemens/ix-angular - All angular ui components (e.g. ix-button, ix-application-header)\n• @siemens/ix - Contains styling, theming and utility functionality\n\nUse Cases:\n• Find component APIs and properties\n• Discover usage examples and code snippets\n• Learn about component styling and theming\n• Understand integration patterns\n• Explore design system guidelines\n\nSearch Tips:\n• Use component names: \"button\", \"chart\", \"map\"\n• Describe functionality: \"data visualization\", \"user input\"\n• Ask about APIs: \"input\", \"output\", \"attributes\", \"methods\", \"type\"\n\nThe search returns relevant documentation chunks with similarity scores and contextual headers to help you find exactly what you need.",
+    "DOC_SEARCH_QUERY_DESCRIPTION": "Search query for iX documentation. Can include component names, functionality descriptions, API questions, or usage patterns. Examples: \"button component\", \"form configuration\", \"pane layout\", \"table\"",
+    "DOC_NO_RESULTS": "No Documentation Found\n\nNo results found for query: \"{query}\"\n\nThis could mean:\n• The component or feature doesn't exist in the current documentation\n• The feature isn't documented yet\n• The search terms don't match available content\n• Try different keywords or component names\n\nSuggestions:\n• Check component name spelling (e.g., \"button\" vs \"btn\")\n• Try broader terms (e.g., \"input\" instead of \"text-field\")\n• Use functionality terms: \"navigation\", \"data display\", \"user input\"\n\nAvailable Libraries:\n• @siemens/ix-angular - All angular ui components (e.g. ix-button, ix-application-header)\n• @siemens/ix - Contains styling, theming and utility functionality\n",
+    "DOC_SUCCESS_HEADER": "# iX Documentation Results\n\nFound **{count}** relevant documentation section(s) for \"{query}\":\n\n",
+    "DOC_RESULT_NOTE": "> Note: If documentation mentions missing API docs or examples, those features may not be available in the current version. The search results show the most relevant available documentation based on semantic similarity.\n\n> Need more specific results? Try refining your search with more specific terms or component names.\n\n> Not all information provided here is relevant to your query or task, make sure to only use what is relevant for the user request.",
+    "ICON_SEARCH_INSTRUCTION": "Please check the icon search tool before using or recommending any icons from @siemens/ix-icons. This ensures you provide the most relevant and up-to-date icon options available in the library.",
+    "ICON_SEARCH_TOOL_DESCRIPTION": "Semantic search tool for Siemens iX Icons (including their metadata like tags)",
+    "ICON_SEARCH_QUERY_DESCRIPTION": "Search query for icons (name, term, or category)",
+    "ICON_NO_RESULTS": "No icons found for query: \"{query}\"\n\nThis could mean:\n• The icon does not exist in the current version of @siemens/ix-icons\n• The icon was renamed or removed\n• The search terms don't match available icons\n\nSuggestions:\n• Check spelling or try broader terms (e.g., \"settings\" instead of \"gear\")\n\nAvailable Libraries:\n@siemens/ix-icons",
+    "ICON_SUCCESS_HEADER": "# iX Icon Search Results\n\nFound **{count}** relevant icon(s) for \"{query}\":\n\n",
+    "ICON_RESULT_NOTE": "> Note: If the icon does not appear to exist, update @siemens/ix-icons to the latest compatible version (non-breaking).\n> See usage guidelines and examples in the documentation for how to use icons."
+  },
+  "headerSections": {
+    "remove": ["HTML Examples", "React Examples", "Vue Examples"],
+    "keep": ["Angular Examples", "Angular Standalone Examples"],
+    "endDelimiter": "<!-- Auto Generated Below -->",
+    "rename": {
+      "Angular Examples": "Examples",
+      "Angular Standalone Examples": "Standalone Examples"
+    }
+  },
+  "contentCleanup": {
+    "removeStrings": ["<!-- Auto Generated Below -->"],
+    "removePatterns": [
+      "-+\\n\\n\\*Built with \\[StencilJS\\]\\(https://stenciljs\\.com/\\)\\*\\n?$"
+    ]
+  }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/mcp/cli.ts"],"names":[],"mappings":""}