@aleph-alpha/lib-mcp 1.7.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/chat-kit-components-meta.json

@@ -0,0 +1,546 @@
+{
+  "CkAgentMessage": {
+    "description": "Layout for a single assistant (agent) turn in a conversation. Exposes `icon`, `header`, default content and `footer` slots for full control over each section while keeping consistent spacing and alignment.",
+    "category": "Messages",
+    "useCases": [
+      "render assistant reply",
+      "AI message layout",
+      "conversation turn",
+      "streaming message container"
+    ],
+    "keywords": [
+      "agent",
+      "assistant",
+      "message",
+      "bubble",
+      "reply",
+      "ai",
+      "conversation"
+    ],
+    "related": [
+      "CkUserMessage",
+      "CkConversation",
+      "CkMarkdownRenderer",
+      "CkCopyMessageActionButton"
+    ],
+    "props": [],
+    "examples": [
+      "Default",
+      "WithFooterActions",
+      "WithRichContent",
+      "WithCustomHeader",
+      "WithoutIcon"
+    ],
+    "_autoGenerated": true
+  },
+  "CkConversationLayout": {
+    "description": "Scroll-aware container that renders a list of messages with sticky-to-bottom behavior, a shrinking spacer so streaming agent replies don't jitter the viewport, and slots for rendering user/agent messages.",
+    "category": "Layout",
+    "useCases": [
+      "conversation scroll container",
+      "streaming chat layout",
+      "chat viewport with auto-scroll",
+      "follow-the-bottom chat list"
+    ],
+    "keywords": [
+      "conversation",
+      "layout",
+      "scroll",
+      "auto-scroll",
+      "streaming",
+      "chat",
+      "container"
+    ],
+    "related": [
+      "CkConversation",
+      "CkAgentMessage",
+      "CkUserMessage"
+    ],
+    "props": [
+      "messages"
+    ],
+    "examples": [
+      "Default",
+      "StreamingSimulation",
+      "Empty"
+    ],
+    "_autoGenerated": true
+  },
+  "CkCopyMessageActionButton": {
+    "description": "Copy-to-clipboard action button for chat messages. Shows a check icon and announces success for assistive technologies, then reverts after a delay.",
+    "category": "Actions",
+    "useCases": [
+      "copy assistant reply",
+      "copy message to clipboard",
+      "chat message action",
+      "feedback action on message footer"
+    ],
+    "keywords": [
+      "copy",
+      "clipboard",
+      "action",
+      "message",
+      "button",
+      "icon",
+      "feedback"
+    ],
+    "related": [
+      "CkMessageActionButton",
+      "CkAgentMessage",
+      "CkConversation"
+    ],
+    "props": [
+      "text",
+      "disabled",
+      "durationMs",
+      "ariaLabelCopy",
+      "ariaLabelCopied",
+      "writeToClipboard"
+    ],
+    "examples": [
+      "Default",
+      "Disabled"
+    ],
+    "_autoGenerated": true
+  },
+  "CkHistoryItem": {
+    "description": "A single chat history entry with title, optional meta line, active indicator, and a trailing action control (plain button or popover). Sidebar-agnostic: can be used anywhere, not only inside a sidebar.",
+    "category": "Actions",
+    "useCases": [
+      "chat history row",
+      "thread list entry",
+      "recent conversation item"
+    ],
+    "keywords": [
+      "chat",
+      "history",
+      "item",
+      "row",
+      "conversation",
+      "thread"
+    ],
+    "related": [
+      "CkHistoryWrapper"
+    ],
+    "props": [],
+    "examples": [
+      "Default",
+      "Active",
+      "AlwaysShowAction",
+      "NoMeta",
+      "WithActionPopover"
+    ],
+    "_autoGenerated": true
+  },
+  "CkHistoryWrapper": {
+    "description": "Vertical stack for chat history rows (`CkHistoryItem`). Sidebar-agnostic: can be used anywhere in the app, not only inside a sidebar.",
+    "category": "Layout",
+    "useCases": [
+      "chat history list",
+      "thread list container",
+      "recent conversations stack"
+    ],
+    "keywords": [
+      "chat",
+      "history",
+      "list",
+      "stack",
+      "container",
+      "wrapper"
+    ],
+    "related": [
+      "CkHistoryItem"
+    ],
+    "props": [
+      "withGap"
+    ],
+    "examples": [
+      "Default",
+      "WithoutGap"
+    ],
+    "_autoGenerated": true
+  },
+  "CkMarkdownRenderer": {
+    "description": "Renders a Markdown string as Vue VNodes with per-tag class overrides and an optional `code-block` slot. Use for assistant messages that contain prose, lists, tables, and code blocks.",
+    "category": "Data Display",
+    "useCases": [
+      "render assistant markdown reply",
+      "syntax-highlighted code blocks",
+      "GFM tables",
+      "chat message body"
+    ],
+    "keywords": [
+      "markdown",
+      "renderer",
+      "gfm",
+      "remark",
+      "code block",
+      "prose"
+    ],
+    "related": [
+      "CkAgentMessage",
+      "CkConversation"
+    ],
+    "props": [
+      "content",
+      "classes",
+      "plugins"
+    ],
+    "examples": [
+      "Default",
+      "WithCodeBlocks",
+      "WithCustomCodeBlockSlot",
+      "ComplexMarkdown",
+      "WithCustomClasses",
+      "GfmFeatures",
+      "WithCustomPlugin"
+    ],
+    "_autoGenerated": true
+  },
+  "CkMessageActionButton": {
+    "description": "Small icon-only action button used in the footer of chat messages. Acts as a ghost-styled wrapper around `UiButton` with consistent chat-kit tokens.",
+    "category": "Actions",
+    "useCases": [
+      "message footer action",
+      "like/dislike reaction",
+      "share button on reply",
+      "secondary message action"
+    ],
+    "keywords": [
+      "icon button",
+      "action",
+      "message",
+      "ghost",
+      "accessible",
+      "aria-label",
+      "button"
+    ],
+    "related": [
+      "CkCopyMessageActionButton",
+      "CkAgentMessage",
+      "CkConversation"
+    ],
+    "props": [
+      "ariaLabel",
+      "disabled"
+    ],
+    "examples": [
+      "Default"
+    ],
+    "_autoGenerated": true
+  },
+  "CkPromptActionButton": {
+    "description": "Icon-only call-to-action button styled for the chat prompt area (brand color). Typically used as the \"send\" button inside a prompt input toolbar, but works for any primary prompt-level action.",
+    "category": "Actions",
+    "useCases": [
+      "send message button",
+      "submit prompt",
+      "primary chat action",
+      "loading send button",
+      "disabled send button"
+    ],
+    "keywords": [
+      "prompt",
+      "send",
+      "action",
+      "button",
+      "icon",
+      "submit",
+      "loading",
+      "brand"
+    ],
+    "related": [
+      "CkPromptInput",
+      "CkInput",
+      "CkMessageActionButton"
+    ],
+    "props": [
+      "ariaLabel",
+      "disabled",
+      "loading",
+      "type"
+    ],
+    "examples": [
+      "Default",
+      "Disabled",
+      "Loading"
+    ],
+    "_autoGenerated": true
+  },
+  "CkPromptInput": {
+    "description": "Low-level prompt input: a single auto-growing textarea with left/right toolbar slots, a footer slot, and keyboard submission (Enter to submit, Shift+Enter for newline). Use when you need full control over the prompt layout; for a turnkey chat input use `CkInput` instead.",
+    "category": "Form Inputs",
+    "useCases": [
+      "raw chat prompt textarea",
+      "custom prompt toolbar",
+      "auto-growing textarea",
+      "compose box",
+      "keyboard submit"
+    ],
+    "keywords": [
+      "prompt",
+      "input",
+      "textarea",
+      "chat",
+      "auto-grow",
+      "compose",
+      "submit",
+      "v-model"
+    ],
+    "related": [
+      "CkInput",
+      "CkPromptActionButton",
+      "CkPromptInputDisclaimer"
+    ],
+    "props": [
+      "modelValue",
+      "placeholder",
+      "disabled",
+      "maxHeight",
+      "ariaLabel"
+    ],
+    "examples": [
+      "Default",
+      "WithToolbarSlots",
+      "WithFooterSlot",
+      "Disabled"
+    ],
+    "_autoGenerated": true
+  },
+  "CkPromptInputDisclaimer": {
+    "description": "Small helper/disclaimer line typically rendered under a chat input (\"AI may produce incorrect answers\"). Renders nothing when there is no text and no default slot content, making it safe to always include.",
+    "category": "Feedback",
+    "useCases": [
+      "chat disclaimer",
+      "ai may make mistakes",
+      "prompt footnote",
+      "small help text under input"
+    ],
+    "keywords": [
+      "disclaimer",
+      "notice",
+      "footer",
+      "help text",
+      "ai",
+      "prompt",
+      "input"
+    ],
+    "related": [
+      "CkInput",
+      "CkPromptInput"
+    ],
+    "props": [
+      "text"
+    ],
+    "examples": [
+      "Default",
+      "WithSlot",
+      "Empty"
+    ],
+    "_autoGenerated": true
+  },
+  "CkPromptStopButton": {
+    "description": "Icon-only button used to stop an in-flight assistant generation. Shares the brand styling of `CkPromptActionButton` but is intended to replace it in the prompt toolbar while a response is streaming.",
+    "category": "Actions",
+    "useCases": [
+      "stop assistant generation",
+      "cancel streaming reply",
+      "abort in-flight request",
+      "halt llm response"
+    ],
+    "keywords": [
+      "stop",
+      "cancel",
+      "abort",
+      "prompt",
+      "action",
+      "button",
+      "icon",
+      "streaming"
+    ],
+    "related": [
+      "CkPromptActionButton",
+      "CkPromptInput",
+      "CkInput"
+    ],
+    "props": [
+      "ariaLabel",
+      "disabled"
+    ],
+    "examples": [
+      "Default",
+      "Disabled"
+    ],
+    "_autoGenerated": true
+  },
+  "CkUserMessage": {
+    "description": "Bubble layout for a single user turn in a conversation. Renders the message text on the right side with a tokenized background and max-width; supports a default slot for custom inline content.",
+    "category": "Messages",
+    "useCases": [
+      "render user message bubble",
+      "conversation turn from user",
+      "chat input preview",
+      "right-aligned message"
+    ],
+    "keywords": [
+      "user",
+      "message",
+      "bubble",
+      "chat",
+      "conversation",
+      "turn"
+    ],
+    "related": [
+      "CkAgentMessage",
+      "CkConversation"
+    ],
+    "props": [
+      "message"
+    ],
+    "examples": [
+      "Default",
+      "LongMessage",
+      "MultilineMessage",
+      "WithSlotContent"
+    ],
+    "_autoGenerated": true
+  },
+  "CkConversation": {
+    "description": "High-level chat conversation: renders user and agent messages, Markdown for assistant replies, an avatar, copy-to-clipboard action, streaming viewport, and slots for overriding any part of the rendering. Use as the drop-in conversation surface for most chat-kit integrations.",
+    "category": "Messages",
+    "useCases": [
+      "complete chat conversation ui",
+      "streaming chat with markdown",
+      "assistant chat view",
+      "llm conversation component",
+      "drop-in chat surface"
+    ],
+    "keywords": [
+      "conversation",
+      "chat",
+      "messages",
+      "assistant",
+      "agent",
+      "user",
+      "markdown",
+      "streaming",
+      "avatar"
+    ],
+    "related": [
+      "CkConversationLayout",
+      "CkAgentMessage",
+      "CkUserMessage",
+      "CkMarkdownRenderer",
+      "CkCopyMessageActionButton",
+      "CkInput"
+    ],
+    "props": [
+      "messages",
+      "agentAvatarImage",
+      "agentAvatarFallback",
+      "agentLoadingImage",
+      "agentMarkdownClasses"
+    ],
+    "examples": [
+      "Default",
+      "WithIcon",
+      "WithCustomAvatarFallback",
+      "NoIcon",
+      "WithCustomIcon",
+      "WithFooterActions",
+      "WithCustomUserContent",
+      "WithCustomAgentContent",
+      "StreamingSimulation",
+      "WithCustomMarkdownClasses",
+      "WithCustomCodeBlock",
+      "Empty"
+    ],
+    "_autoGenerated": true
+  },
+  "CkHistory": {
+    "description": "Composed conversation history list. Renders each conversation as a real `<a href>` row so middle-click, cmd/ctrl-click, and right-click \"Copy link address\" all work natively. Plain left-clicks are intercepted via a RouterLink-style guard and exposed as a `select` event so consumers can call `router.push(...)` (or any other navigation primitive) themselves. Per-row \"Edit\" and \"Delete\" actions are rendered internally; consumers receive `edit` / `delete` events with the corresponding conversation. Use the `#item` scoped slot to fully replace the row rendering — for example to wrap each row in `<RouterLink>` for native vue-router integration. The slot scope exposes the resolved row data (`conversation`, `href`, `isActive`, `title`) plus `select` / `edit` / `delete` helpers that emit the same events as the default rendering.",
+    "category": "Messages",
+    "useCases": [
+      "conversation history list",
+      "recent chats sidebar entry",
+      "thread navigation",
+      "chat history pane"
+    ],
+    "keywords": [
+      "conversation",
+      "history",
+      "list",
+      "navigation",
+      "link",
+      "sidebar",
+      "threads",
+      "routerlink"
+    ],
+    "related": [
+      "CkHistoryWrapper",
+      "CkHistoryItem"
+    ],
+    "props": [
+      "conversations",
+      "hrefResolver",
+      "activeId",
+      "showAction",
+      "showActionOnHover"
+    ],
+    "examples": [
+      "Default",
+      "WithoutActions",
+      "RouterLinkIntegration",
+      "WithCustomItem"
+    ],
+    "_autoGenerated": true
+  },
+  "CkInput": {
+    "description": "Drop-in chat input: combines `CkPromptInput`, a `CkPromptActionButton` send button, and a `CkPromptInputDisclaimer`. Supports `v-model`, loading and disabled states, and slots to customize the toolbar and footer.",
+    "category": "Form Inputs",
+    "useCases": [
+      "chat compose input",
+      "prompt box with send button",
+      "llm input with disclaimer",
+      "quick-start chat input",
+      "turnkey chat input"
+    ],
+    "keywords": [
+      "input",
+      "prompt",
+      "chat",
+      "send",
+      "compose",
+      "disclaimer",
+      "loading",
+      "v-model",
+      "textarea"
+    ],
+    "related": [
+      "CkPromptInput",
+      "CkPromptActionButton",
+      "CkPromptInputDisclaimer",
+      "CkConversation"
+    ],
+    "props": [
+      "modelValue",
+      "placeholder",
+      "disabled",
+      "loading",
+      "maxHeight",
+      "ariaLabel",
+      "stopAriaLabel",
+      "disclaimer"
+    ],
+    "examples": [
+      "Default",
+      "WithModeToggle",
+      "FullExample",
+      "Disabled",
+      "Loading",
+      "WithLongText",
+      "MobileWidth"
+    ],
+    "_autoGenerated": true
+  }
+}