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

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,330 @@
+# 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 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
+- **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
+```
+
+### 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": {}
+    }
+  }
+}
+```
+
+## 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,48 @@
+{
+  "name": "@siemens/ix-mcp-angular",
+  "description": "iX MCP server for Angular",
+  "displayName": "iX Angular",
+  "binName": "ix-mcp-angular",
+  "designSystem": "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": {
+    "FRAMEWORK_DEV_QUESTION": "Angular development question",
+    "FRAMEWORK_IMPLEMENTATIONS": "Angular implementations",
+    "FRAMEWORK_SUPPORTED_LIBRARIES": "• @siemens/ix-angular - All angular ui components (e.g. ix-button, ix-application-header)\n• @siemens/ix - Contains styling, theming and utility functionality\n",
+    "FRAMEWORK_SEMANTIC_SEARCH_TOOL": "Semantic search tool for Siemens iX Design System and Angular component library",
+    "FRAMEWORK_ALL_QUERIES": "This applies to ALL Angular-related queries regardless of whether iX libraries are explicitly mentioned",
+    "FRAMEWORK_VERSION_SPECIFIC": "The tool provides access to version-specific Siemens iX documentation that is automatically tuned to match the user's library versions",
+    "FRAMEWORK_SETUP_ADVICE": "This ensures you get the exact APIs, components, and implementation patterns available in their specific setup rather than generic Angular advice",
+    "FRAMEWORK_COMPREHENSIVE_GUIDANCE": "Always search first to leverage the comprehensive ix and ix-react documentation before offering any Angular guidance",
+    "FRAMEWORK_SEARCH_QUERY": "Search query for iX documentation. Can include component names, functionality descriptions, API questions, or usage patterns. Examples: \"button component\", \"form configuration\", \"pane layout\", \"table\"",
+    "FRAMEWORK_DOCUMENTATION_RESULTS": "# iX Documentation Results"
+  },
+  "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":""}