@aleph-alpha/lib-mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,17 +1,30 @@
 # @aleph-alpha/lib-mcp
 
-MCP (Model Context Protocol) Server for UI Library component discovery tools.
+MCP (Model Context Protocol) Server for UI Library and ChatKit component discovery tools.
 
 ## Overview
 
-This package provides an MCP server that enables AI assistants (like Claude and Cursor) to discover and understand UI Library components. It offers tools to list available components and retrieve detailed documentation including props, examples, and usage guidance.
+This package provides an MCP server that enables AI assistants (like Claude and Cursor) to discover and understand components from:
+
+- [`@aleph-alpha/ui-library`](../ui-library) — `Ui*` components
+- [`@aleph-alpha/chat-kit`](../chat-kit) — `Ck*` components
+
+It offers tools to list available components and retrieve detailed documentation including props, examples, and usage guidance.
 
 ## Installation
 
+Install `@aleph-alpha/lib-mcp` together with the component packages whose docs you want to query. UI Library is required; ChatKit is optional and only needed if you want `Ck*` component docs.
+
 ```bash
+# UI Library only
 pnpm add @aleph-alpha/lib-mcp @aleph-alpha/ui-library
+
+# UI Library + ChatKit
+pnpm add @aleph-alpha/lib-mcp @aleph-alpha/ui-library @aleph-alpha/chat-kit
 ```
 
+> ChatKit docs require `@aleph-alpha/chat-kit` to publish its `src/` directory (component `types.ts` and `*.stories.ts` files). If `get_chat_kit_docs` returns "Could not find chat-kit source directory", upgrade `@aleph-alpha/chat-kit` to a version that includes `src/` in its published files.
+
 ## Usage
 
 ### Configure MCP Server
@@ -24,6 +37,9 @@ npx @aleph-alpha/lib-mcp mcp-install
 
 # For both Claude Code and Cursor
 npx @aleph-alpha/lib-mcp mcp-install --cursor
+
+# For VS Code
+npx @aleph-alpha/lib-mcp mcp-install --vscode
 ```
 
 After installation, restart your IDE to activate the MCP tools.
@@ -32,9 +48,11 @@ After installation, restart your IDE to activate the MCP tools.
 
 Once configured, the following tools are available to your AI assistant:
 
-#### `list_components`
+#### UI Library tools
+
+##### `list_components`
 
-Lists all available UI components. Supports optional filtering by name, category, or description.
+Lists all available UI Library components. Supports optional filtering by name, category, or description.
 
 ```
 list_components
@@ -42,9 +60,9 @@ list_components --filter="button"
 list_components --filter="form"
 ```
 
-#### `get_component_docs`
+##### `get_component_docs`
 
-Retrieves full documentation for a specific component including:
+Retrieves full documentation for a specific UI Library component including:
 
 - Component description
 - Props with types, defaults, and descriptions
@@ -57,6 +75,45 @@ get_component_docs UiButton
 get_component_docs Button  # "Ui" prefix is optional
 ```
 
+#### ChatKit tools
+
+Available when `@aleph-alpha/chat-kit` is installed alongside this package.
+
+##### `list_chat_kit_components`
+
+Lists all available ChatKit (`Ck*`) components. Supports optional filtering by name, category, or description.
+
+```
+list_chat_kit_components
+list_chat_kit_components --filter="history"
+list_chat_kit_components --filter="message"
+```
+
+##### `get_chat_kit_docs`
+
+Retrieves full documentation for a specific ChatKit component, with the same shape as `get_component_docs`:
+
+- Component description
+- Props with types, defaults, and descriptions
+- Sub-components (if applicable)
+- Usage guidance
+- Code examples
+
+```
+get_chat_kit_docs CkHistory
+get_chat_kit_docs History  # "Ck" prefix is optional
+```
+
+#### Setup tool
+
+##### `get_setup_guide`
+
+Returns the setup and installation guide for integrating the UI library into a project (UnoCSS config, Vite config, required dependencies, and MCP setup instructions).
+
+```
+get_setup_guide
+```
+
 ## Development
 
 ### Building
@@ -67,6 +124,8 @@ pnpm build
 
 ### Generating Component Metadata
 
+Regenerates `components-meta.json` (UI Library) and `chat-kit-components-meta.json` (ChatKit) by scanning each package's source files.
+
 ```bash
 pnpm generate:component-meta
 ```
@@ -79,21 +138,23 @@ pnpm test
 
 ## How It Works
 
-The MCP server reads component metadata from:
+The MCP server reads component metadata from each package's source layout:
 
 1. **`types.ts`**: Extracts props, their types, descriptions, and component-level JSDoc tags (`@category`, `@useCases`, `@keywords`, `@related`)
 2. **`*.stories.ts`**: Extracts code examples and usage guidance from Storybook stories
-3. **`components-meta.json`**: Pre-generated metadata for faster lookups
+3. **`index.ts`**: Detects sub-component exports for the documented component
+4. **`components-meta.json` / `chat-kit-components-meta.json`**: Pre-generated metadata for faster lookups
+
+UI Library components are read from `@aleph-alpha/ui-library/src/**`, and ChatKit components from `@aleph-alpha/chat-kit/src/components/**`. Both packages must publish their `src/` directory for docs to resolve when consumed from `node_modules`.
 
 ## CLI Commands
 
-| Command | Description |
-|---------|-------------|
-| `mcp-install` | Configure MCP server for IDE |
-| `serve` | Start the MCP server (used internally by IDE) |
-| `--help` | Show help message |
+| Command       | Description                                                             |
+| ------------- | ----------------------------------------------------------------------- |
+| `mcp-install` | Configure MCP server for IDE (`--cursor`, `--vscode` to add extra IDEs) |
+| `serve`       | Start the MCP server (used internally by IDE)                           |
+| `--help`      | Show help message                                                       |
 
 ## License
 
 Apache-2.0
-

package/components-meta.json

@@ -526,7 +526,7 @@
       "WithRadioItems",
       "WithDestructiveAction",
       "WithSubmenu",
-      "WithIconButton",
+      "WithIconTrigger",
       "WithSoftToggleTrigger",
       "WithSoftToggleTriggerAndText",
       "WithAvatarTrigger"
@@ -714,53 +714,7 @@
     "examples": [
       "Default",
       "Sizes",
-      "InIconButton"
-    ],
-    "_autoGenerated": true
-  },
-  "UiIconButton": {
-    "description": "A button that displays only an icon without text. Use for compact actions like close, edit, delete, or toolbar buttons. It is being merged into `UiButton` — use `UiButton` with an icon-only child and an `aria-label` instead (e.g. `<UiButton size=\"icon-sm\" aria-label=\"Close\"><UiIcon name=\"x\" /></UiButton>`).",
-    "category": "Actions",
-    "useCases": [
-      "close button",
-      "edit action",
-      "toolbar button",
-      "compact action"
-    ],
-    "keywords": [
-      "iconbutton",
-      "icon",
-      "button",
-      "action",
-      "close",
-      "edit",
-      "delete"
-    ],
-    "related": [
-      "UiButton",
-      "UiIcon"
-    ],
-    "props": [
-      "variant",
-      "size",
-      "asChild",
-      "type",
-      "disabled",
-      "loading",
-      "ariaLabel"
-    ],
-    "examples": [
-      "Default",
-      "Secondary",
-      "Destructive",
-      "Outline",
-      "Ghost",
-      "Link",
-      "Loading",
-      "Disabled",
-      "AllVariants",
-      "AllSizes",
-      "AsChild"
+      "IconLibrary"
     ],
     "_autoGenerated": true
   },
@@ -1349,6 +1303,48 @@
     ],
     "_autoGenerated": true
   },
+  "UiSnackbar": {
+    "description": "Toast notification container (Sonner). Place once near the app root, then call `toast()` (or `toast.success()`, `toast.error()`, etc.) from anywhere to display a non-blocking notification.",
+    "category": "Feedback",
+    "useCases": [
+      "success confirmation",
+      "error notice",
+      "undo action",
+      "async progress",
+      "background updates"
+    ],
+    "keywords": [
+      "snackbar",
+      "toast",
+      "sonner",
+      "notification",
+      "alert",
+      "message",
+      "banner",
+      "undo"
+    ],
+    "related": [
+      "UiAlert",
+      "UiAlertDialog"
+    ],
+    "props": [],
+    "examples": [
+      "SuccessHigh",
+      "SuccessLow",
+      "InfoHigh",
+      "InfoLow",
+      "WarningHigh",
+      "WarningLow",
+      "ErrorHigh",
+      "ErrorLow",
+      "AllVariants",
+      "Default",
+      "WithDescription",
+      "PromiseSnackbar",
+      "WithDialog"
+    ],
+    "_autoGenerated": true
+  },
   "UiSpinner": {
     "description": "An animated loading indicator. Use while content is loading or an action is processing.",
     "category": "Feedback",
@@ -1681,7 +1677,7 @@
     ],
     "examples": [
       "Default",
-      "WithIconButton",
+      "WithIconTrigger",
       "InstantDelay",
       "LongDelay",
       "Disabled",

package/dist/cli.js

@@ -21425,11 +21425,15 @@ function detectCategoryDirs() {
     return [];
   }
   const entries = fs4.readdirSync(srcPath, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).filter((entry) => !entry.name.startsWith(".") && entry.name !== "node_modules").filter((entry) => {
+  return entries.filter((entry) => entry.isDirectory()).filter(
+    (entry) => !entry.name.startsWith(".") && entry.name !== "node_modules"
+  ).filter((entry) => {
     try {
       const dirPath = path4.join(srcPath, entry.name);
       const subEntries = fs4.readdirSync(dirPath, { withFileTypes: true });
-      return subEntries.some((sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX));
+      return subEntries.some(
+        (sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX)
+      );
     } catch {
       return false;
     }
@@ -21970,7 +21974,10 @@ function parseInterface2(content, interfaceName) {
     const propName = propMatch[2];
     const isOptional = !!propMatch[3];
     const typeStartIndex = propMatch.index + propMatch[0].length;
-    const { type: propType, endIndex } = extractType2(interfaceBody, typeStartIndex);
+    const { type: propType, endIndex } = extractType2(
+      interfaceBody,
+      typeStartIndex
+    );
     propStartRegex.lastIndex = endIndex + 1;
     const jsdoc = parseJSDoc2(jsdocComment);
     props.push({
@@ -21987,7 +21994,9 @@ function parseInterface2(content, interfaceName) {
 function extractComponentDescription2(content, interfaceName) {
   const lines = content.split("\n");
   const interfaceLineIndex = lines.findIndex(
-    (line) => line.match(new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+${interfaceName}`))
+    (line) => line.match(
+      new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+${interfaceName}`)
+    )
   );
   if (interfaceLineIndex === -1) {
     return "";
@@ -22013,7 +22022,9 @@ function extractComponentDescription2(content, interfaceName) {
   return "";
 }
 function resolveUnionOrIntersectionProps2(content, typeName) {
-  const typeDefRegex = new RegExp(`export\\s+type\\s+${typeName}\\s*=\\s*([^;]+)`);
+  const typeDefRegex = new RegExp(
+    `export\\s+type\\s+${typeName}\\s*=\\s*([^;]+)`
+  );
   const match = content.match(typeDefRegex);
   if (!match) return [];
   const referencedTypes = match[1].split(/[|&]/).map((t) => t.trim()).filter((t) => t.endsWith("Props"));
@@ -22041,7 +22052,9 @@ function readChatKitTypesFile(filePath, componentName) {
     return null;
   }
   const resolvedName = componentName || path9.basename(path9.dirname(filePath));
-  const exactRegex = new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+(${resolvedName}Props)\\b`);
+  const exactRegex = new RegExp(
+    `export\\s+${TYPE_OR_INTERFACE2}\\s+(${resolvedName}Props)\\b`
+  );
   let propsInterfaceMatch = content.match(exactRegex);
   if (!propsInterfaceMatch) {
     const prefixRegex = new RegExp(
@@ -22307,7 +22320,9 @@ async function startServer() {
   server.tool(
     "list_chat_kit_components",
     "List all Chat Kit components. Optionally filter by name, category, or description.",
-    { filter: external_exports.string().optional().describe("Filter by name/category/description") },
+    {
+      filter: external_exports.string().optional().describe("Filter by name/category/description")
+    },
     async ({ filter }) => {
       try {
         const components = listChatKitComponents(filter);
@@ -22322,7 +22337,10 @@ async function startServer() {
           },
           {}
         );
-        const sections = [`Found ${components.length} chat-kit component(s):`, ""];
+        const sections = [
+          `Found ${components.length} chat-kit component(s):`,
+          ""
+        ];
         Object.entries(grouped).forEach(([category, comps]) => {
           sections.push(`## ${category}`, "");
           comps.forEach((comp) => {
@@ -22339,11 +22357,14 @@ async function startServer() {
   server.tool(
     "get_chat_kit_docs",
     "Get full documentation for a Chat Kit component including props, examples, and usage.",
-    { componentName: external_exports.string().describe('Component name (e.g., "CkChatBubble" or "ChatBubble")') },
+    {
+      componentName: external_exports.string().describe('Component name (e.g., "CkChatBubble" or "ChatBubble")')
+    },
     async ({ componentName }) => {
       try {
         const docs = getChatKitComponentDocs(componentName);
-        if (!docs) return error2(`Chat Kit component "${componentName}" not found.`);
+        if (!docs)
+          return error2(`Chat Kit component "${componentName}" not found.`);
         return text(formatComponentDocs(docs));
       } catch (e) {
         return handleError(e);

package/dist/scripts/generate-component-meta.js

@@ -97,11 +97,15 @@ function detectCategoryDirs() {
     return [];
   }
   const entries = fs3.readdirSync(srcPath, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).filter((entry) => !entry.name.startsWith(".") && entry.name !== "node_modules").filter((entry) => {
+  return entries.filter((entry) => entry.isDirectory()).filter(
+    (entry) => !entry.name.startsWith(".") && entry.name !== "node_modules"
+  ).filter((entry) => {
     try {
       const dirPath = path2.join(srcPath, entry.name);
       const subEntries = fs3.readdirSync(dirPath, { withFileTypes: true });
-      return subEntries.some((sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX));
+      return subEntries.some(
+        (sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX)
+      );
     } catch {
       return false;
     }
@@ -177,7 +181,10 @@ var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = path3.dirname(__filename2);
 var PACKAGE_ROOT = getPackageRoot();
 var OUTPUT_PATH = path3.join(PACKAGE_ROOT, "components-meta.json");
-var CHAT_KIT_OUTPUT_PATH = path3.join(PACKAGE_ROOT, "chat-kit-components-meta.json");
+var CHAT_KIT_OUTPUT_PATH = path3.join(
+  PACKAGE_ROOT,
+  "chat-kit-components-meta.json"
+);
 function extractJSDocTags(content, interfaceName) {
   const declarationRegex = new RegExp(
     `export\\s+(?:interface|type)\\s+${escapeRegex(interfaceName)}\\b`
@@ -265,13 +272,17 @@ function processComponent(componentDir, componentName) {
     typesContent = fs4.readFileSync(typesPath, "utf-8");
   }
   const escapedName = escapeRegex(componentName);
-  const exactPropsRegex = new RegExp(`export\\s+(?:interface|type)\\s+(${escapedName}Props)\\b`);
+  const exactPropsRegex = new RegExp(
+    `export\\s+(?:interface|type)\\s+(${escapedName}Props)\\b`
+  );
   const exactMatch = typesContent.match(exactPropsRegex);
   const subComponentPropsRegex = new RegExp(
     `export\\s+(?:interface|type)\\s+(${escapedName}\\w*Props)\\b`
   );
   const subComponentMatch = typesContent.match(subComponentPropsRegex);
-  const anyPropsMatch = typesContent.match(/export\s+(?:interface|type)\s+((?:Ui|Ck)\w+Props)/);
+  const anyPropsMatch = typesContent.match(
+    /export\s+(?:interface|type)\s+((?:Ui|Ck)\w+Props)/
+  );
   const interfaceName = exactMatch?.[1] || subComponentMatch?.[1] || anyPropsMatch?.[1] || `${componentName}Props`;
   const jsdocData = extractJSDocTags(typesContent, interfaceName);
   const nameKeywords = extractKeywordsFromName(componentName);
@@ -342,8 +353,12 @@ function scanChatKitComponents() {
 }
 function summarize(label, meta) {
   const total = Object.keys(meta).length;
-  const withUseCases = Object.values(meta).filter((m) => m.useCases.length > 0).length;
-  const withKeywords = Object.values(meta).filter((m) => m.keywords.length > 0).length;
+  const withUseCases = Object.values(meta).filter(
+    (m) => m.useCases.length > 0
+  ).length;
+  const withKeywords = Object.values(meta).filter(
+    (m) => m.keywords.length > 0
+  ).length;
   console.log(`
 ${label} summary:`);
   console.log(`  Components with @useCases: ${withUseCases}/${total}`);

package/dist/server.js

@@ -21313,11 +21313,15 @@ function detectCategoryDirs() {
     return [];
   }
   const entries = fs3.readdirSync(srcPath, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).filter((entry) => !entry.name.startsWith(".") && entry.name !== "node_modules").filter((entry) => {
+  return entries.filter((entry) => entry.isDirectory()).filter(
+    (entry) => !entry.name.startsWith(".") && entry.name !== "node_modules"
+  ).filter((entry) => {
     try {
       const dirPath = path3.join(srcPath, entry.name);
       const subEntries = fs3.readdirSync(dirPath, { withFileTypes: true });
-      return subEntries.some((sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX));
+      return subEntries.some(
+        (sub) => sub.isDirectory() && sub.name.startsWith(COMPONENT_PREFIX)
+      );
     } catch {
       return false;
     }
@@ -21858,7 +21862,10 @@ function parseInterface2(content, interfaceName) {
     const propName = propMatch[2];
     const isOptional = !!propMatch[3];
     const typeStartIndex = propMatch.index + propMatch[0].length;
-    const { type: propType, endIndex } = extractType2(interfaceBody, typeStartIndex);
+    const { type: propType, endIndex } = extractType2(
+      interfaceBody,
+      typeStartIndex
+    );
     propStartRegex.lastIndex = endIndex + 1;
     const jsdoc = parseJSDoc2(jsdocComment);
     props.push({
@@ -21875,7 +21882,9 @@ function parseInterface2(content, interfaceName) {
 function extractComponentDescription2(content, interfaceName) {
   const lines = content.split("\n");
   const interfaceLineIndex = lines.findIndex(
-    (line) => line.match(new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+${interfaceName}`))
+    (line) => line.match(
+      new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+${interfaceName}`)
+    )
   );
   if (interfaceLineIndex === -1) {
     return "";
@@ -21901,7 +21910,9 @@ function extractComponentDescription2(content, interfaceName) {
   return "";
 }
 function resolveUnionOrIntersectionProps2(content, typeName) {
-  const typeDefRegex = new RegExp(`export\\s+type\\s+${typeName}\\s*=\\s*([^;]+)`);
+  const typeDefRegex = new RegExp(
+    `export\\s+type\\s+${typeName}\\s*=\\s*([^;]+)`
+  );
   const match = content.match(typeDefRegex);
   if (!match) return [];
   const referencedTypes = match[1].split(/[|&]/).map((t) => t.trim()).filter((t) => t.endsWith("Props"));
@@ -21929,7 +21940,9 @@ function readChatKitTypesFile(filePath, componentName) {
     return null;
   }
   const resolvedName = componentName || path8.basename(path8.dirname(filePath));
-  const exactRegex = new RegExp(`export\\s+${TYPE_OR_INTERFACE2}\\s+(${resolvedName}Props)\\b`);
+  const exactRegex = new RegExp(
+    `export\\s+${TYPE_OR_INTERFACE2}\\s+(${resolvedName}Props)\\b`
+  );
   let propsInterfaceMatch = content.match(exactRegex);
   if (!propsInterfaceMatch) {
     const prefixRegex = new RegExp(
@@ -22195,7 +22208,9 @@ async function startServer() {
   server.tool(
     "list_chat_kit_components",
     "List all Chat Kit components. Optionally filter by name, category, or description.",
-    { filter: external_exports.string().optional().describe("Filter by name/category/description") },
+    {
+      filter: external_exports.string().optional().describe("Filter by name/category/description")
+    },
     async ({ filter }) => {
       try {
         const components = listChatKitComponents(filter);
@@ -22210,7 +22225,10 @@ async function startServer() {
           },
           {}
         );
-        const sections = [`Found ${components.length} chat-kit component(s):`, ""];
+        const sections = [
+          `Found ${components.length} chat-kit component(s):`,
+          ""
+        ];
         Object.entries(grouped).forEach(([category, comps]) => {
           sections.push(`## ${category}`, "");
           comps.forEach((comp) => {
@@ -22227,11 +22245,14 @@ async function startServer() {
   server.tool(
     "get_chat_kit_docs",
     "Get full documentation for a Chat Kit component including props, examples, and usage.",
-    { componentName: external_exports.string().describe('Component name (e.g., "CkChatBubble" or "ChatBubble")') },
+    {
+      componentName: external_exports.string().describe('Component name (e.g., "CkChatBubble" or "ChatBubble")')
+    },
     async ({ componentName }) => {
       try {
         const docs = getChatKitComponentDocs(componentName);
-        if (!docs) return error2(`Chat Kit component "${componentName}" not found.`);
+        if (!docs)
+          return error2(`Chat Kit component "${componentName}" not found.`);
         return text(formatComponentDocs(docs));
       } catch (e) {
         return handleError(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/lib-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/server.js",
@@ -36,8 +36,8 @@
     "@aleph-alpha/tsconfig-frontend": "0.6.0"
   },
   "peerDependencies": {
-    "@aleph-alpha/chat-kit": "1.0.0",
-    "@aleph-alpha/ui-library": "2.0.0"
+    "@aleph-alpha/ui-library": "2.2.0",
+    "@aleph-alpha/chat-kit": "1.1.0"
   },
   "homepage": "https://docs.aleph-alpha.com",
   "scripts": {