@amedia/brick-mcp 1.0.3 → 1.0.5

package/dist/data/components/brick-mcp.md

@@ -1,11 +1,11 @@
 ---
 name: brick-mcp
-version: 0.1.3
+version: 1.0.3
 selector: N/A
 category: Utilities
-tags: [mcp, model-context-protocol, ai, llm, development-tools, cli, design-system]
-use_cases: [ai-assisted-development, component-discovery, design-tokens-access, code-generation]
-related: [brick-tokens, brick-template]
+tags: [mcp, model-context-protocol, ai, llm, development-tools, cli, design-system, server]
+use_cases: [ai-assisted-development, component-discovery, design-tokens-access, code-generation, ssr-guidance]
+related: [brick-tokens, brick-template, brick-themes]
 ---
 
 # Brick MCP
@@ -14,106 +14,94 @@ A Model Context Protocol (MCP) server that provides AI assistants with direct ac
 
 ## Key Capabilities
 
-- Exposes three MCP tools for AI assistants to query Brick components and design tokens
+- Exposes three MCP tools (`list-components`, `get-component-docs`, `get-design-tokens`) for AI assistants to query the Brick design system
 - Provides component discovery with filtering by name, category, or tags
-- Delivers detailed component documentation including props, examples, and Storybook links
-- Gives access to design tokens filtered by category or theme
-- Runs in stdio mode (for Claude Code) or HTTP mode (for local development)
-- Pre-generates and bundles all data as JSON for fast, standalone operation
-- Enables accurate, context-aware AI assistance when implementing Brick components
+- Delivers detailed, LLM-optimized component documentation including props, examples, and CDN paths
+- Gives access to design tokens filtered by category, with compact text output to minimize context window usage
+- Runs in stdio mode (recommended for Claude Code) or HTTP/SSE mode (for local development)
+- Pre-generates and bundles all data as JSON at build time for fast, standalone operation without needing the Brick monorepo at runtime
 
 ## MCP Tools
 
-The server provides three tools that AI assistants can call:
+The server registers three tools that AI assistants can call.
 
 ### list-components
 
-Lists all available Brick components with optional filtering.
+Lists all available Brick components with optional filtering by name, category, or tag.
 
-**Input Schema:**
-```typescript
-{
-  filter?: string;  // Filter by name, category, or tag
-}
-```
+| Parameter | Type | Default | Required | Description |
+| --------- | ---- | ------- | -------- | ----------- |
+| filter | string | undefined | No | Filter components by name, category, or tag (case-insensitive substring match) |
+
+**Returns:** JSON object with a `components` array. Each entry contains:
 
-**Returns:**
 ```typescript
 {
   components: Array<{
     name: string;        // e.g., "brick-button"
-    version: string;     // e.g., "9.0.0"
+    version: string;     // e.g., "9.4.20"
     selector: string;    // e.g., "brick-button-v9"
     description?: string;
-    category?: string;   // Forms, Navigation, Layout, Feedback, Display, Utilities
+    category?: string;   // Forms, Navigation, Layout, Feedback, Display, or Utilities
     tags?: string[];
+    assetUrl?: string;   // CDN base URL, e.g., "https://assets.acdn.no/pkg/@amedia/brick-button"
+    mainJsFile?: string; // Main JS filename, e.g., "brick-button.js"
   }>;
 }
 ```
 
+**Example call:** `{ "filter": "button" }` returns all button-related components.
+
 ### get-component-docs
 
-Retrieves detailed documentation for one or more components.
+Retrieves detailed LLM-optimized documentation for one or more components. First looks for a markdown file in `data/components/{name}.md`, falling back to JSON component data if no markdown exists.
 
-**Input Schema:**
-```typescript
-{
-  components: string[];  // e.g., ["brick-button", "brick-modal"]
-}
-```
+| Parameter | Type | Default | Required | Description |
+| --------- | ---- | ------- | -------- | ----------- |
+| components | string[] | - | Yes | Array of component names (e.g., `["brick-button", "brick-card"]`) |
 
-**Returns:**
-```typescript
-{
-  docs: Array<{
-    name: string;
-    version: string;
-    selector: string;
-    description?: string;
-    examples: {
-      webComponent?: string;
-      storybook?: string;  // Link to Chromatic Storybook
-    };
-    cdnPath?: string;      // Eik CDN URL
-  }>;
-}
-```
+**Returns:** JSON object with a `docs` array of strings. Each string is either the full markdown documentation content for that component or a JSON-serialized component data object as fallback.
+
+**Example call:** `{ "components": ["brick-button", "brick-teaser"] }`
 
 ### get-design-tokens
 
-Accesses design tokens from brick-tokens with filtering options.
+Accesses design tokens from brick-tokens. Behavior differs based on whether a category is provided.
+
+| Parameter | Type | Default | Required | Description |
+| --------- | ---- | ------- | -------- | ----------- |
+| category | `"colors"` \| `"spacing"` \| `"typography"` \| `"shadows"` \| `"borders"` | undefined | No | Filter tokens by category |
+
+**Without category:** Returns a compact summary listing available categories with token counts and example paths. This avoids dumping all tokens into the context window.
 
-**Input Schema:**
-```typescript
-{
-  category?: 'colors' | 'spacing' | 'typography' | 'shadows' | 'borders';
-  theme?: string;  // e.g., "bergen", "alfa", "bt"
-}
+```
+Available token categories:
+- colors: 142 tokens (color.background.default, color.text.default, color.primary, ...)
+- spacing: 24 tokens (spacing.1, spacing.2, spacing.3, ...)
+- typography: 38 tokens (typography.heading.1, typography.body.default, ...)
+- shadows: 6 tokens (box-shadow.small, box-shadow.medium, ...)
+- borders: 12 tokens (border-width.thin, border-radius.small, ...)
+
+Call with a specific category to see tokens.
 ```
 
-**Returns:**
-```typescript
-{
-  tokens: Array<{
-    name: string;
-    value: string;
-    type: string;
-    description?: string;
-    category?: string;
-    theme?: string;
-  }>;
-  themes: string[];
-  documentation: {
-    anOverview?: string;
-    formats?: string;
-    naming?: string;
-    themes?: string;
-    usage?: string;
-  };
-}
+**With category:** Returns a compact text listing where each line is `cssVariable: value -- description`.
+
 ```
+--brick-color-background-default: #ffffff  -- Default background color
+--brick-color-text-default: #1a1a1a  -- Default text color
+```
+
+Note: Values shown are examples from one theme. Actual values vary across themes. Use the CSS variable for theme-aware styling.
 
-## Examples
+**Category-to-path-prefix mapping:**
+- `colors` matches tokens with path starting with `color.`
+- `spacing` matches `spacing.`
+- `typography` matches `typography.`
+- `shadows` matches `box-shadow.`
+- `borders` matches `border-width.`, `border-radius.`, `border.`
+
+## Usage
 
 ### Installation via npx (Recommended)
 
@@ -139,6 +127,9 @@ npm install
 npm run build
 
 # Start HTTP server (default: http://localhost:3000)
+npm run start:http
+
+# Or with watch mode for development
 npm run dev:http
 
 # Add to Claude Code
@@ -147,14 +138,20 @@ claude mcp add Brick-http --transport sse --scope user -- http://0.0.0.0:3000/ss
 
 ### Environment Variables
 
-```bash
-PORT=3000  # Server port (default: 3000)
-HOST=0.0.0.0  # Server host (default: 0.0.0.0)
-```
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| PORT | 3000 | Server port (HTTP mode only) |
+| HOST | localhost | Server host (HTTP mode only) |
+
+### HTTP Endpoints (HTTP Mode Only)
 
-## Usage Workflow
+| Endpoint | Method | Description |
+| -------- | ------ | ----------- |
+| `/health` | GET | Health check, returns `{ "status": "ok" }` |
+| `/sse` | GET | SSE endpoint for MCP protocol communication |
+| `/message?sessionId=X` | POST | Message endpoint for client-to-server communication |
 
-Once configured, AI assistants can use the MCP tools:
+### Workflow Example
 
 ```
 User: "I need to add a button to my app using Brick"
@@ -162,98 +159,44 @@ User: "I need to add a button to my app using Brick"
 AI Assistant:
 1. Calls list-components with filter: "button"
 2. Calls get-component-docs with components: ["brick-button"]
-3. Provides implementation guidance with examples and CDN links
-```
-
-## HTTP Endpoints (HTTP Mode Only)
-
-When running in HTTP mode, the server exposes:
-
-- `http://localhost:3000/health` - Health check endpoint
-- `http://localhost:3000/sse` - SSE endpoint for MCP protocol communication
-- `http://localhost:3000/message` - Message endpoint for client-to-server communication
-
-## Programmatic Usage
-
-### Extending with Custom Tools
-
-To add a new MCP tool:
-
-1. Create a new file in `src/tools/yourTool.ts`
-2. Implement the tool function with input/output types using Zod
-3. Register the tool in `src/server.ts` using `server.registerTool()`
-
-Example tool structure:
-
-```typescript
-import { z } from 'zod';
-
-const InputSchema = z.object({
-  parameter: z.string().optional(),
-});
-
-const OutputSchema = z.object({
-  result: z.string(),
-});
-
-export const yourTool = {
-  name: 'your-tool',
-  description: 'Description of what your tool does',
-  inputSchema: InputSchema,
-  handler: async (input: z.infer<typeof InputSchema>) => {
-    // Tool implementation
-    return { result: 'output' };
-  },
-};
+3. Provides implementation guidance with correct selector, CDN URL, and examples
 ```
 
-## Data Sources
-
-The MCP server aggregates data from multiple sources during build:
-
-- **Component Metadata**: `data/components-metadata.json` (auto-generated)
-- **Component Documentation**: `data/components/*.md` (LLM-optimized docs)
-- **Design Tokens**: `brick-tokens/publications/publication/*.json`
-- **Token Documentation**: `data/tokens-documentation.json`
-- **Package Information**: Each component's `package.json`
-
 ## Technical Details
 
-- **Runtime**: Node.js
-- **Protocol**: Model Context Protocol (MCP) 1.25.2+
-- **Transport Modes**: stdio (recommended for Claude Code) or HTTP/SSE
+- **Package version**: 1.0.3
+- **Runtime**: Node.js (target: node22)
+- **Protocol**: Model Context Protocol (MCP) via `@modelcontextprotocol/sdk` 1.27.1
+- **Transport modes**: stdio (recommended for Claude Code) or HTTP/SSE (via Fastify 5.8.5)
 - **Dependencies**:
-  - @modelcontextprotocol/sdk (MCP implementation)
-  - fastify (HTTP server)
-  - zod (schema validation)
-- **Build System**: Custom build script that pre-generates all JSON data
-- **Distribution**: Published to npm as `@amedia/brick-mcp`
+  - `@modelcontextprotocol/sdk` 1.27.1 (MCP implementation)
+  - `fastify` 5.8.5 (HTTP server)
+  - `@fastify/cors` 11.1.0 (CORS support for HTTP mode)
+  - `zod` 3.25.76 (schema validation)
+  - `zod-to-json-schema` 3.24.6 (JSON schema generation)
+- **Build system**: esbuild (ESM bundle, platform: node)
+- **Distribution**: Published to npm as `@amedia/brick-mcp`; executable via `npx @amedia/brick-mcp`
+- **Binary**: `brick-mcp` (CLI entry point at `dist/index.js` with shebang)
 
-## Publishing
+## Data Sources
 
-### Standard Release
+All data is pre-generated at build time by `scripts/generate-data.js` and bundled into the `data/` directory:
 
-```bash
-# From Brick monorepo root
-npx changeset              # Create a changeset
-# Create PR → merge → "Version Packages" PR created automatically
-# Merge "Version Packages" PR to publish to npm
-```
+- **`data/components-metadata.json`**: Lightweight metadata for all Brick components (auto-generated from each package's `package.json`)
+- **`data/components/*.md`**: LLM-optimized markdown documentation per component
+- **`data/components/*.json`**: Structured component data (fallback when no `.md` exists)
+- **`data/tokens.json`**: Design tokens sourced from `brick-tokens/tokens-viewer/tokens-viewer.json`
+- **`data/tokens-documentation.json`**: Token system documentation extracted from Storybook MDX files
 
-### Snapshot Release (Testing)
-
-1. Create a changeset
-2. Run the [snapshot GitHub action](https://github.com/amedia/brick/actions/workflows/snapshotRelease.yml) for your branch and this package
+Build also runs `scripts/check-docs-versions.js` which compares documentation versions against current package versions and warns about stale docs.
 
 ## Important Notes
 
-- The MCP server is designed to be run as a standalone npm package via npx
-- All data is pre-generated during build time for optimal performance
-- The server does not require access to the Brick monorepo at runtime
-- stdio mode is recommended for Claude Code integration
-- HTTP mode is useful for local development and testing
-- The server provides read-only access to Brick design system information
-
-## Version
-
-Current version: 0.1.3
+- **Version 1.0.0 breaking change**: The package was made public on npm. No API changes, but the package is now accessible to all consumers via `npx @amedia/brick-mcp`.
+- The `get-design-tokens` tool no longer accepts a `theme` parameter (removed in 0.1.8). It returns compact text instead of structured JSON objects to minimize context window usage.
+- Without a `category` argument, `get-design-tokens` returns only a summary of available categories rather than all tokens.
+- The server does not require access to the Brick monorepo at runtime; all data is bundled at build time.
+- stdio mode is recommended for Claude Code integration. HTTP mode is intended for local development and testing only.
+- The server provides read-only access to Brick design system information.
+- Excluded from metadata generation: `brick-actions`, `brick-icons`, `brick-template`, and `brick-mcp` itself.
+- Component categories are inferred from the component name using keyword matching, not manually assigned.