@onemrvapublic/design-system-mcp-server 2.0.1-rc.1

package/README.md

@@ -0,0 +1,420 @@
+# Design System MCP Server
+
+MCP server for the ONEM/RVA Design System. It supports local IDE integrations over stdio and hosted deployments over HTTP, and can run from live source or synced `mcp-data` JSON.
+
+## MCP concept (quick overview)
+
+MCP stands for Model Context Protocol. It is a standard way for an AI client (for example Copilot in an IDE) to call external capabilities safely.
+
+At a high level:
+
+1. The AI client connects to an MCP server.
+2. The server exposes typed tools (name, description, JSON schema input).
+3. The AI chooses a tool and sends arguments.
+4. The server executes logic and returns structured output.
+
+In this project, the MCP server is the bridge between AI and ONEM/RVA design-system knowledge (Angular APIs, synced Figma metadata, theme utilities, migration helpers).
+
+## What this server does
+
+- Lists Angular design-system components
+- Shows APIs (inputs, outputs, methods, slots, host listeners)
+- Generates usage examples
+- Provides accessibility notes
+- Exposes synced Figma data (components, tokens, styles, icons) when available
+- Helps migration from legacy Material/custom patterns to DS components
+
+## How this MCP server works
+
+Runtime flow:
+
+1. `src/index.ts` starts stdio, HTTP, or both transports.
+2. The server selects a data mode (`auto`, `mcp-data`, or `live`).
+3. Tool metadata is registered through `getTools()`.
+4. Incoming MCP calls are routed to `handleToolCall()` in `src/tools.ts`.
+5. Tool handlers read from live scanner data and/or synced JSON under `mcp-data`.
+6. Results are returned as MCP tool responses for the AI to use in follow-up reasoning.
+
+For migration workflows, the typical loop is:
+
+1. Run `analyze_repo_migration` on a target repo.
+2. Review migration findings and DS usage issues.
+3. Use the generated Copilot fix-pack prompts file by file.
+4. Re-run `analyze_repo_migration` until findings reach zero.
+
+This is the core mechanism that lets Copilot move from diagnosis to concrete remediation.
+
+## Local demo mode (use this now)
+
+For a local demonstration, run only stdio transport and skip hosted HTTP setup.
+
+1. Build and verify locally:
+
+```bash
+cd tools/mcp-server
+npm install
+npm run build
+npm run test
+```
+
+2. In your MCP client config, use stdio with either:
+
+- published package via `npx -y @onemrvapublic/design-system-mcp-server`
+- local build path via `node .../tools/mcp-server/dist/index.js --transport=stdio`
+
+3. If you want fresh synced data before the demo, run from repo root:
+
+```bash
+npm run sync:mcp
+```
+
+4. During the demo, do not run `start:http` and do not set `MCP_TRANSPORT=http`.
+
+5. Optional: use the inspector for a direct local walkthrough:
+
+```bash
+cd tools/mcp-server
+npm run inspector
+```
+
+Hosting can be enabled later by following the hosted sections in this file.
+
+## Fast IDE setup (recommended)
+
+If you just want this working quickly, run one command from the repository root:
+
+```bash
+npm run mcp:setup
+```
+
+This command builds the MCP server, detects your IDE, and writes the MCP config automatically.
+It supports both VS Code and JetBrains IDEs.
+
+If you are actively developing design-system components and want automatic detection, use the dev profile:
+
+```bash
+npm run mcp:setup:dev
+```
+
+The dev profile config starts MCP with `--data-source=live --watch`.
+
+If you want one command that both configures and starts live watch mode:
+
+```bash
+npm run mcp:dev
+```
+
+If you want to force one target, run the setup script directly from the MCP
+server package (there is no root `mcp:setup:vscode`/`mcp:setup:jetbrains` alias):
+
+```bash
+npm --prefix tools/mcp-server run setup:vscode
+npm --prefix tools/mcp-server run setup:jetbrains
+```
+
+After running setup, restart your IDE (or reload the VS Code window).
+
+## Best practices for invoking MCP from AI chat
+
+The MCP server works best when prompts are explicit about scope, desired outcome, and safety constraints.
+
+Use this structure for reliable results:
+
+1. Target: file, folder, or component name.
+2. Task: analyze, migrate, fix, or explain.
+3. Constraints: what must not change (behavior, public API, styling, etc.).
+4. Validation: run tests/lint/build and summarize diff.
+
+Prompt template:
+
+```text
+Use the design-system MCP server on <target>.
+Task: <analyze|migrate|fix|explain>.
+Constraints: <keep behavior|no public API changes|minimal diff>.
+Validation: <run tests/build/lint if available>.
+Output: <apply patch + summary of what changed and why>.
+```
+
+Recommended prompts developers can copy:
+
+```text
+Use the design-system MCP server to audit this component and fix invalid DS inputs/outputs/imports. Keep behavior unchanged and apply the patch.
+```
+
+```text
+Run migration analysis on this folder, fix only high-confidence findings first, and re-run analysis until no high-confidence issues remain.
+```
+
+```text
+Migrate Angular Material usage in this template to DS equivalents where safe, and leave TODO notes for risky cases.
+```
+
+```text
+Validate this component against DS accessibility guidance and patch missing aria labels/roles/focus handling without changing UI behavior.
+```
+
+```text
+Explain which MCP tools you used, what each found, and show the final diff summary.
+```
+
+Tips:
+
+- Ask for "high-confidence fixes first" to reduce regressions.
+- Ask for "minimal diff" for easier reviews.
+- Ask for "show skipped/risky items" so manual follow-up is clear.
+- Provide concrete targets (exact file paths) instead of broad repo-wide requests when starting.
+
+## Manual setup (if you want full control)
+
+### VS Code
+
+1. Press `F1` and run `MCP: Open User Configuration`.
+2. Add:
+
+```json
+{
+  "servers": {
+    "design-system-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@onemrvapublic/design-system-mcp-server"]
+    }
+  }
+}
+```
+
+3. Reload VS Code (`F1` -> `Developer: Reload Window`).
+
+### Claude Desktop
+
+Edit your config file:
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "design-system-mcp": {
+      "command": "npx",
+      "args": ["-y", "@onemrvapublic/design-system-mcp-server"]
+    }
+  }
+}
+```
+
+### JetBrains
+
+In Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP), add:
+
+```json
+{
+  "name": "design-system-mcp",
+  "command": "npx",
+  "args": ["-y", "@onemrvapublic/design-system-mcp-server"]
+}
+```
+
+## Runtime modes
+
+- `stdio` (default): local IDE clients
+- `http`: hosted MCP endpoint
+- `both`: stdio + HTTP in one process
+
+Examples (the `start:*` scripts live in the MCP server package, so run them from
+`tools/mcp-server` or with `--prefix`):
+
+```bash
+npx -y @onemrvapublic/design-system-mcp-server --transport=stdio
+npm --prefix tools/mcp-server run start:http
+npm --prefix tools/mcp-server run start:both
+```
+
+## Data source behavior
+
+By default, the server uses synced `mcp-data/codebase.json` as the source of truth when it is available. This keeps answers consistent even when the MCP server is used from other repositories.
+
+You can control this with `MCP_DATA_SOURCE`:
+
+- `auto` (default): use synced `mcp-data` when available, otherwise use live scan
+- `mcp-data`: force synced data only (fails fast if `codebase.json` is missing)
+- `live`: force live scan from `DESIGN_SYSTEM_PATH`
+
+Example:
+
+```bash
+MCP_DATA_SOURCE=mcp-data node dist/index.js --transport=stdio
+```
+
+In synced-data mode, `rescan_components` is intentionally disabled.
+
+For Design System developers who want automatic detection while editing components, use live watch mode:
+
+```bash
+npm run mcp:start:live:watch
+```
+
+Run this command from the repository root. It watches design-system source folders and triggers automatic rescan on file changes, so developers do not need to run `sync:mcp` after each edit.
+
+## Hosted mode hardening (current defaults)
+
+- HTTP startup fails closed unless `MCP_API_KEY` is set, or `MCP_ALLOW_UNAUTHENTICATED_HTTP=true` is explicitly set for trusted local networks.
+- `GET /health` is protected by API key checks in hosted mode.
+- Rate limiting and HTTP session caps are enabled.
+- Legacy SSE routes are disabled by default and only enabled with `MCP_ENABLE_LEGACY_SSE=true`.
+
+Environment variables:
+
+- `MCP_API_KEY`
+- `MCP_ALLOW_UNAUTHENTICATED_HTTP=true`
+- `MCP_ENABLE_LEGACY_SSE=true`
+- `MCP_MAX_HTTP_SESSIONS` (default `100`)
+- `MCP_RATE_LIMIT_WINDOW_MS` (default `60000`)
+- `MCP_RATE_LIMIT_MAX_REQUESTS` (default `300`)
+- `MCP_TRANSPORT=stdio|http|both`
+- `PORT` (default `3001`)
+
+## Endpoints and what is exposed
+
+When HTTP transport is enabled:
+
+- `ALL /mcp` for Streamable HTTP MCP transport
+- `GET /health` for runtime health
+- `GET /sse` and `POST /messages` only if legacy SSE is explicitly enabled
+
+Important: this server does not expose `README.md`, `SETUP.md`, or arbitrary files as MCP resources/endpoints. Documentation files stay in the repository only.
+
+## Sync workflow (`sync:mcp`)
+
+Run from the repository root:
+
+```bash
+npm run sync:mcp
+```
+
+The sync pipeline runs codebase sync then Figma sync, and writes to `tools/mcp-server/mcp-data`.
+
+`.env` loading is supported from:
+
+- repository root `.env`
+- `tools/mcp-server/.env`
+
+Key env vars for Figma sync:
+
+- `FIGMA_TOKEN` (required)
+- `FIGMA_FILE_KEY` (optional, falls back to default)
+- proxy vars such as `HTTPS_PROXY` if needed
+
+Figma scopes:
+
+- To read file/component/style content, the token needs file content read access.
+- To read Variables (`tokens.json`), the token also needs Variables read access. If Variables access is missing, component/style sync can still succeed and Variables calls can return 403.
+
+Figma sync exclusions live in `tools/mcp-server/mcp-data/mapping.json` under `figma_sync_exclusions`.
+
+- `files` skips an entire Figma file key before the sync starts.
+- `pages` skips named pages before page/node fetches happen.
+- `components` skips named components before component/node fetches happen.
+- `componentSets` skips named component sets before node fetches happen.
+
+Page mapping still supports `figma_page_mapping` values of `_ignore` and `_docs`, which are treated as non-sync pages.
+
+For token extraction, `figma_sync_options.tokenPages` limits the expensive deep page analysis to the pages that matter most. The default config keeps `Foundations` in that list, and `tokenPageHints` adds a name-based fallback for other token-heavy pages.
+
+## Available MCP tools
+
+The server registers 27 tools (see `getTools()` in `src/tool-registry.ts`).
+
+Discovery:
+
+- `help_friend`
+
+Core design-system tools:
+
+- `list_components`
+- `get_component`
+- `search_components`
+- `generate_component_usage`
+- `get_component_props`
+- `get_accessibility_info`
+- `list_jsonforms_renderers`
+- `get_jsonforms_renderer`
+- `list_theme_utilities`
+- `get_theme_utility`
+- `suggest_component`
+- `audit_component`
+- `compare_components`
+- `get_color_palette`
+
+Synced-data and Figma-aware tools:
+
+- `list_icons`
+- `get_sync_status`
+- `list_figma_components`
+- `get_figma_component`
+- `list_design_tokens`
+- `get_design_token`
+- `explain_token_diff`
+- `list_figma_styles`
+
+Migration and remediation tools:
+
+- `migrate_to_ds`
+- `migrate_file`
+- `analyze_repo_migration`
+
+Admin tools:
+
+- `rescan_components`
+
+## Verify locally
+
+```bash
+cd tools/mcp-server
+npm install
+npm run build
+npm run test
+npm run inspector
+```
+
+For hosted mode smoke checks (still from `tools/mcp-server`):
+
+1. Run `npm run start:http` without `MCP_API_KEY` and verify startup fails.
+2. Set `MCP_API_KEY`, restart, and verify `GET /health` requires auth.
+3. Verify `/mcp` calls succeed with valid API key.
+
+## Architecture
+
+- `src/index.ts`: transport bootstrap (stdio/http), auth guards, rate/session limits, health and rescan routes
+- `src/tool-registry.ts`: `getTools()` tool metadata registry and `TOOL_NAMES`
+- `src/component-scanner.ts`: component/jsonforms/theme scanning and rescan
+- `src/component-parser.ts`: parser for decorators/JSDoc/API extraction
+- `src/tools.ts`: MCP tool handlers and synced-data fallback logic
+- `scripts/codebase-sync.ts`: codebase metadata sync
+- `scripts/figma-sync.ts`: 3-pass Figma sync (components/layers/tokens+styles)
+
+The server prefers live scan when source is mounted. If source is unavailable but `mcp-data` exists, it starts in synced-data-only mode.
+
+## Known parser gaps
+
+`src/component-parser.ts` is regex-based, not a full TypeScript AST. A few
+component patterns are not extracted today. Authors relying on these fields
+should be aware they can come back empty:
+
+- Public methods declared without the `public` keyword (implicitly-public
+  methods are skipped; only `public`-prefixed methods populate `methods[]`).
+- Query decorators that use a quoted template-reference selector, e.g.
+  `@ViewChild('ref')` / `@ViewChildren('items')` — these are not added to
+  `queryChildren[]` (type-selector queries like `@ViewChild(ChildComp)` and
+  `@ContentChild(...)` are extracted).
+- Function-typed `@Input` types such as `(event: Event) => Promise<void>` are
+  not preserved as-is.
+
+Related: `hasEffects` tracks Angular signal `effect()` calls, not lifecycle-hook
+implementations (`OnInit`, `OnDestroy`, ...). These gaps are captured by the ten
+skipped cases in `src/component-parser.comprehensive.test.ts`.
+
+## Notes for component authors
+
+The detailed component authoring guide (JSDoc tags, input/output docs, accessibility annotation examples) remains in `SETUP.md`.

package/dist/component-parser.d.ts

@@ -0,0 +1,79 @@
+export interface ParsedInput {
+    name: string;
+    type: string;
+    description: string;
+    defaultValue?: string;
+    required?: boolean;
+    deprecated?: string;
+    examples: string[];
+}
+export interface ParsedOutput {
+    name: string;
+    type: string;
+    description: string;
+    deprecated?: string;
+}
+export interface ParsedMethod {
+    name: string;
+    description: string;
+    params: {
+        name: string;
+        type: string;
+    }[];
+    returnType: string;
+    deprecated?: string;
+}
+export interface ParsedSlot {
+    name: string;
+    selector: string;
+    description: string;
+}
+export interface ParsedHostListener {
+    event: string;
+    methodName: string;
+    args: string[];
+}
+export interface ParsedQueryChild {
+    name: string;
+    type: string;
+    queryType: 'ViewChild' | 'ContentChild' | 'ViewChildren' | 'ContentChildren';
+    required: boolean;
+    static: boolean;
+}
+export interface ParsedComponent {
+    selector: string;
+    description: string;
+    inputs: ParsedInput[];
+    outputs: ParsedOutput[];
+    methods: ParsedMethod[];
+    slots: ParsedSlot[];
+    hostListeners: ParsedHostListener[];
+    queryChildren: ParsedQueryChild[];
+    hasEffects: boolean;
+    standalone: boolean;
+    imports: string[];
+    accessibility: string[];
+    keywords: string[];
+    group: string;
+    themes: string[];
+    deprecated?: string;
+}
+export declare class ComponentParser {
+    parse(content: string, filePath: string, htmlContent?: string): ParsedComponent | null;
+    private extractClassJSDoc;
+    private extractInputs;
+    private extractOutputs;
+    private extractNearbyPropertyJSDoc;
+    private buildInputFallbackDescription;
+    private buildOutputFallbackDescription;
+    private truncateForDescription;
+    private extractMethods;
+    private extractSlots;
+    private parsePropertyJSDoc;
+    private cleanType;
+    private inferTypeFromValue;
+    private extractHostListeners;
+    private extractQueryChildren;
+    private extractAccessibilityInfo;
+    private extractAriaFromHtml;
+}