@fundamental-ngx/mcp 0.62.4-rc.9 → 0.62.4

package/README.md

@@ -1,29 +1,32 @@
 # @fundamental-ngx/mcp
 
-MCP (Model Context Protocol) server that exposes the [Fundamental NGX](https://github.com/SAP/fundamental-ngx) component catalog to AI coding assistants.
+MCP (Model Context Protocol) server that exposes the entire Fundamental NGX component catalog to AI coding assistants.
 
-## Quick Start
+## What It Does
 
-### With Claude Code
+AI coding assistants (Claude Code, Cursor, VS Code Copilot, Windsurf, etc.) can connect to this MCP server and get structured access to:
 
-**Option 1: Using claude mcp add (Recommended)**
+- **1000+ components** across 8 libraries (core, platform, btp, cx, cdk, ui5-webcomponents, ui5-webcomponents-fiori, ui5-webcomponents-ai)
+- **Full API metadata** — inputs, outputs, slots, methods, enum values, CSS properties
+- **Component recommendations** — describe what you want to build and get matching components
+- **Design tokens** — SAP theming CSS custom properties and utility classes
+- **Migration guidance** — breaking changes and upgrade paths from changelogs
+- **Accessibility guidance** — ARIA inputs, keyboard handling, and a11y examples
+- **Component comparison** — side-by-side comparison of alternative components
+- **Usage guides** — decision trees and composition patterns for complex components (dialog, table, card, etc.)
+- **Selector classification** — whether a component is an element, attribute directive, or both, with correct template usage
 
-```bash
-# Install latest version
-claude mcp add fundamental-ngx -- npx -y @fundamental-ngx/mcp
+This eliminates hallucinated APIs and outdated documentation — the assistant works from the actual component metadata.
 
-# Or install a specific version
-claude mcp add fundamental-ngx -- npx -y @fundamental-ngx/mcp@0.62.4
-```
+## Quick Start
 
-This command automatically adds the MCP server to your `.claude/mcp.json` configuration.
+### VS Code / Cursor
 
-**Option 2: Manual configuration**
+Create or edit `.vscode/mcp.json` in your project root:
 
 ```json
-// .claude/mcp.json
 {
-    "mcpServers": {
+    "servers": {
         "fundamental-ngx": {
             "command": "npx",
             "args": ["-y", "@fundamental-ngx/mcp"]
@@ -32,59 +35,44 @@ This command automatically adds the MCP server to your `.claude/mcp.json` config
 }
 ```
 
-### With Cursor
+### Claude Code
 
-```json
-// .cursor/mcp.json
-{
-    "mcpServers": {
-        "fundamental-ngx": {
-            "command": "npx",
-            "args": ["-y", "@fundamental-ngx/mcp"]
-        }
-    }
-}
+Run this command in your terminal to register the server for the current project:
+
+```bash
+claude mcp add fundamental-ngx -- npx -y @fundamental-ngx/mcp
 ```
 
-### With VS Code (Copilot)
+Or to make it available across all your projects:
+
+```bash
+claude mcp add --scope user fundamental-ngx -- npx -y @fundamental-ngx/mcp
+```
+
+You can verify it was added with:
+
+```bash
+claude mcp list
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
-// .vscode/mcp.json
 {
-    "servers": {
+    "mcpServers": {
         "fundamental-ngx": {
             "command": "npx",
-            "args": ["-y", "@fundamental-ngx/mcp"],
-            "type": "stdio"
+            "args": ["-y", "@fundamental-ngx/mcp"]
         }
     }
 }
 ```
 
-### How it works
-
-`npx -y @fundamental-ngx/mcp` starts a Node.js process that listens on **stdio** for JSON-RPC messages following the [Model Context Protocol](https://modelcontextprotocol.io/). Running it directly in a terminal will appear to hang — that is intentional. The process is idle, waiting for a client to send tool requests over stdin. It is designed to be launched and managed by an MCP client (Claude Code, Cursor, VS Code Copilot), not run interactively.
-
-To explore the server's tools from a browser UI, use the MCP Inspector instead (see below).
-
-**Debugging with MCP Inspector:**
-
-The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a web UI for testing MCP servers interactively:
-
-```bash
-npx @modelcontextprotocol/inspector npx -y @fundamental-ngx/mcp
-```
-
-This opens a browser UI where you can:
+That's it — your AI assistant now has full access to the Fundamental NGX component catalog.
 
-- Browse all 10 available tools
-- Send test requests with custom parameters
-- View formatted JSON responses
-- Debug tool behavior without an AI client
-
-The server communicates over **stdio** using the MCP JSON-RPC protocol.
-
-## Tools
+## Available Tools
 
 | Tool                      | Purpose                                                          | Example Query                                                  |
 | ------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------- |
@@ -99,78 +87,58 @@ The server communicates over **stdio** using the MCP JSON-RPC protocol.
 | `compare_components`      | Side-by-side comparison of two components                        | `{ "component_a": "fd-button", "component_b": "ui5-button" }`  |
 | `get_usage_guide`         | Decision tree and composition patterns for a component           | `{ "component": "dialog" }`                                    |
 
-## Example Queries
-
-```
-"What components are available in the core library?"
-  → list_components with library "core"
-
-"Find a component for selecting a date range"
-  → search_components with query "date range"
-
-"What inputs does fd-button accept?"
-  → get_component_api with name "fd-button"
-
-"Show me HTML examples for fd-dialog"
-  → get_component_examples with name "fd-dialog"
-
-"I need to build a filterable data table with pagination"
-  → recommend_components with description "filterable data table with pagination"
-
-"What broke between 0.60.0 and 0.62.0?"
-  → get_migration_guide with from_version "0.60.0", to_version "0.62.0"
-
-"What SAP design tokens are available for background colors?"
-  → get_design_tokens with query "background color", category "color"
-
-"How do I handle keyboard navigation in fd-menu?"
-  → get_accessibility_guide with name "fd-menu"
-
-"What is the difference between fd-table and fdp-table?"
-  → compare_components with component_a "fd-table", component_b "fdp-table"
-
-"Which dialog API should I use?"
-  → get_usage_guide with component "dialog"
+## Metadata Schema
+
+Each component in the catalog follows this structure:
+
+```typescript
+interface ComponentMetadata {
+    name: string; // "ButtonComponent"
+    selector: string; // "fd-button" or "ui5-button"
+    selectorType: 'element' | 'attribute' | 'both'; // how to use in templates
+    templateUsage: string; // "<button fd-button>...</button>"
+    library: Library; // "@fundamental-ngx/core"
+    category: string; // "Actions", "Form", "Layout"
+    description: string;
+    deprecated?: string; // deprecation message
+    inputs: InputMetadata[];
+    outputs: OutputMetadata[];
+    slots: SlotMetadata[]; // UI5 components
+    methods: MethodMetadata[];
+    cssProperties: CssPropertyMetadata[];
+    keyboardHandling?: string; // keyboard interaction notes (UI5 components)
+    source: 'cem' | 'typedoc';
+}
 ```
 
-## Contributing
+See `src/types/component-metadata.ts` for full type definitions.
 
-### Prerequisites
+## AI Onboarding
 
-- Node.js 18+
-- Yarn 4.x (the monorepo uses Yarn workspaces)
+The MCP server is designed as the primary AI-assisted onboarding path for Fundamental NGX. Here's the recommended workflow:
 
-### Setup
+1. **Discover** — Use `recommend_components` to find the right components for your UI
+2. **Decide** — Use `get_usage_guide` to choose the right variant (e.g., which dialog API surface)
+3. **Learn** — Use `get_component_api` and `get_component_examples` for API details and working code
+4. **Build** — Use `get_design_tokens` and `get_accessibility_guide` while implementing
+5. **Compare** — Use `compare_components` when choosing between alternatives (e.g., `fd-table` vs `fdp-table`)
 
-```bash
-# From the repo root
-yarn install
-```
+### Usage Guides
 
-### Build
+The `get_usage_guide` tool provides structured decision trees for components with multiple API surfaces or variants:
 
-```bash
-npx nx build mcp-server
-```
-
-This compiles TypeScript and copies data assets (JSON files) into `dist/libs/mcp-server/`.
+- **Dialog** — template-based vs component-based vs object-based; fd-dialog vs ui5-dialog vs fd-message-box
+- **Table** — fd-table (core, lightweight) vs fdp-table (platform, feature-rich) vs ui5-table (Web Components)
+- **Button** — standard vs split-button vs segmented-button
+- **Card** — fd-card (core) vs ui5-card (Web Components)
+- **Layout Grid** — fd-layout-grid vs fd-flexible-column-layout
 
-### Extract metadata
+### Selector Classification
 
-The server's component catalog is generated from the built library artifacts. Re-run this after changing component source files:
+Each component now includes `selectorType` and `templateUsage` fields to prevent incorrect template usage:
 
-```bash
-npx nx run mcp-server:extract-metadata
-```
-
-Use `--dry-run` to validate without writing:
-
-```bash
-npx nx run mcp-server:check-metadata
-```
-
-### Test
-
-```bash
-npx nx test mcp-server
-```
+| selectorType | Meaning                               | Example                          |
+| ------------ | ------------------------------------- | -------------------------------- |
+| `element`    | Use as an HTML element                | `<fd-card>...</fd-card>`         |
+| `attribute`  | Use as an attribute on a host element | `<h2 fd-title>...</h2>`          |
+| `both`       | Element + attribute combined          | `<button fd-button>...</button>` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fundamental-ngx/mcp",
-  "version": "0.62.4-rc.9",
-  "description": "MCP server exposing Fundamental NGX component metadata for AI coding assistants. Includes companion Claude Code skills for project setup, forms, tables, page layouts, and more",
+  "version": "0.62.4",
+  "description": "MCP server exposing Fundamental NGX component metadata for AI coding assistants",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",