@amedia/brick-mcp 0.0.1-NEW-PATH-1 → 0.0.1-SNAPSHOT-1

package/README.md

@@ -4,38 +4,6 @@
 
 This is a Model Context Protocol (MCP) server for the Brick design system. It enables AI assistants (like Claude Code) to provide accurate, context-aware assistance when developers implement Brick components.
 
-## Prerequisites
-
-Before using the Brick MCP server, you need to set up Claude Code:
-
-> **Note**: This guide assumes that you have pulled the latest changes and installed all dependencies.
-
-### 1. Install Claude CLI
-
-```bash
-curl -fsSL https://claude.ai/install.sh | bash
-```
-
-### 2. Authenticate with Google Cloud
-
-You'll need to authenticate daily to access Amedia's coding agent project:
-
-```bash
-gcloud auth application-default login --project amedia-coding-agent
-```
-
-> **Note**: You will need to re-authenticate once per day.
-
-### 3. Install Claude Code VS Code Extension (Optional)
-
-If you prefer using Claude Code within VS Code:
-
-1. Open VS Code
-2. Go to the Extensions marketplace
-3. Search for "Claude Code"
-4. Install the extension (the one from Anthropic)
-5. Restart VS Code if necessary
-
 ## Usage
 
 The Brick MCP server can be run in two modes:
@@ -45,7 +13,7 @@ The Brick MCP server can be run in two modes:
 To add the Brick MCP server to Claude Code using stdio transport:
 
 ```bash
-claude mcp add --transport stdio Brick -- node /absolute/path/to/brick/packages/brick-mcp/src/index.ts
+claude mcp add --transport stdio Brick -- node /absolute/path/to/brick/mcp-server/src/index.ts
 ```
 
 Replace `/absolute/path/to/brick/` with the actual path to your Brick repository.
@@ -67,7 +35,6 @@ PORT=3001 HOST=localhost npm run start:http
 ```
 
 The HTTP 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
@@ -104,16 +71,13 @@ The Model Context Protocol (MCP) is a standardized way to expose resources, tool
 
 MCP servers can be written in TypeScript using the `@modelcontextprotocol/sdk` package.
 
-## MCP Tools (Actions)
+## Proposed Architecture
 
-Tools are functions that AI assistants can call to actively query and interact with the Brick design system. When you ask Claude about Brick components, it uses these tools behind the scenes to fetch accurate, up-to-date information directly from the codebase.
+### MCP Tools (Actions)
 
-These tools make Claude context-aware about the specific Brick setup, ensuring accurate implementation guidance tailored to the components and design tokens available in the project.
+Tools allow AI assistants to actively query and search the Brick design system.
 
-<details>
-<summary>
-  <strong>1. <code>list-components</code></strong>
-</summary>
+#### 1. `list-components`
 
 **Purpose**: List all available Brick components with metadata
 
@@ -142,10 +106,9 @@ These tools make Claude context-aware about the specific Brick setup, ensuring a
 
 **Use Case**: "What components are available in Brick?"
 
-</details>
+---
 
-<details>
-<summary><strong>2. <code>get-component-docs</code></strong></summary>
+#### 2. `get-component-docs`
 
 **Purpose**: Retrieve detailed documentation for specific component(s)
 
@@ -220,10 +183,9 @@ These tools make Claude context-aware about the specific Brick setup, ensuring a
 
 **Use Case**: "How do I use brick-button? What props does it accept?"
 
-</details>
+---
 
-<details>
-<summary><strong>3. <code>get-design-tokens</code></strong></summary>
+#### 3. `get-design-tokens`
 
 **Purpose**: Access design tokens from brick-tokens
 
@@ -252,10 +214,9 @@ These tools make Claude context-aware about the specific Brick setup, ensuring a
 
 **Use Case**: "What color tokens are available in Brick?"
 
-</details>
+---
 
-<details>
-<summary><strong>4. <code>search-components</code></strong></summary>
+#### 4. `search-components`
 
 **Purpose**: Search components by keyword or functionality
 
@@ -283,10 +244,9 @@ These tools make Claude context-aware about the specific Brick setup, ensuring a
 
 **Use Case**: "Find components related to forms"
 
-</details>
+---
 
-<details>
-<summary><strong>5. <code>get-usage-examples</code> (Optional for v1)</strong></summary>
+#### 5. `get-usage-examples` (Optional for v1)
 
 **Purpose**: Get real-world code examples from Storybook stories
 
@@ -314,13 +274,264 @@ These tools make Claude context-aware about the specific Brick setup, ensuring a
 
 **Use Case**: "Show me examples of brick-button in different states"
 
-</details>
+---
+
+### MCP Resources (Static/Dynamic Data)
+
+Resources provide direct access to structured data without complex queries.
+
+- **`brick://components`**
+  - List of all components (similar to list-components tool)
+
+- **`brick://component/{name}`**
+  - Individual component documentation (e.g., `brick://component/brick-button`)
+
+- **`brick://tokens`**
+  - All design tokens
+
+- **`brick://tokens/{category}`**
+  - Tokens by category (e.g., `brick://tokens/colors`)
+
+- **`brick://getting-started`**
+  - Setup and installation guide
+
+- **`brick://architecture`**
+  - Architecture overview from CLAUDE.md
+
+---
+
+## Implementation Approach
+
+### Package Structure
+
+Create a new package in the monorepo:
+
+```
+packages/brick-mcp-server/
+├── src/
+│   ├── index.ts                 # Main MCP server entry point
+│   ├── server.ts                # MCP server setup and registration
+│   ├── tools/
+│   │   ├── listComponents.ts
+│   │   ├── getComponentDocs.ts
+│   │   ├── getDesignTokens.ts
+│   │   ├── searchComponents.ts
+│   │   └── getUsageExamples.ts
+│   ├── resources/
+│   │   ├── componentResource.ts
+│   │   ├── tokenResource.ts
+│   │   └── docsResource.ts
+│   ├── extractors/
+│   │   ├── packageScanner.ts    # Scan packages/ for components
+│   │   ├── mdxParser.ts         # Parse Storybook MDX files
+│   │   ├── typeExtractor.ts     # Extract TS types from files
+│   │   ├── tokenExtractor.ts    # Extract design tokens
+│   │   └── storyExtractor.ts    # Extract examples from stories
+│   ├── indexer/
+│   │   ├── buildIndex.ts        # Build searchable index
+│   │   └── search.ts            # Search implementation
+│   ├── types.ts                 # TypeScript types
+│   └── utils.ts                 # Helper functions
+├── build.js                     # Build script
+├── package.json
+├── README.md
+└── tsconfig.json
+```
+
+### Documentation Extraction Strategy
+
+The server will extract documentation from various sources in the monorepo:
+
+1. **Component Metadata** (from `package.json`):
+   - Name, version, description
+   - Dependencies
+
+2. **Type Definitions** (from `src/types.ts` or `src/template.ts`):
+   - Props/attributes with types
+   - Event types
+   - Method signatures
+   - Parse TypeScript AST to extract interfaces
+
+3. **Documentation** (from `stories/*.mdx`):
+   - Rich descriptions
+   - Usage guidelines
+   - Accessibility information
+   - Parse MDX frontmatter and content
+
+4. **Examples** (from `stories/*.stories.ts`):
+   - Real code examples from Storybook
+   - Different component states
+   - Parse story definitions
+
+5. **Styles** (from `src/styles.js`):
+   - CSS custom properties
+   - Available variants
+   - Parse Stitches configuration
+
+6. **Design Tokens** (from `packages/brick-tokens`):
+   - Token definitions
+   - Theme variations
+   - Parse token JSON/JS files
+
+7. **Repository Metadata** (from `CLAUDE.md`, `README.md`):
+   - Getting started guide
+   - Architecture overview
+   - Common patterns
+
+### Indexing and Search
+
+To enable fast search:
+
+1. **Build-time indexing**: Create a JSON index of all components with searchable fields
+2. **Fuzzy search**: Use libraries like `fuse.js` for fuzzy text matching
+3. **Semantic categories**: Tag components by purpose (forms, navigation, feedback, etc.)
+4. **Cache**: Cache extracted documentation to avoid repeated parsing
+
+### Technology Stack
+
+- **MCP SDK**: `@modelcontextprotocol/sdk` for server implementation
+- **TypeScript**: Type-safe implementation
+- **AST Parsing**:
+  - `typescript` compiler API for TS parsing
+  - `@mdx-js/mdx` or custom parser for MDX
+  - `@babel/parser` for JS/JSX parsing
+- **Search**: `fuse.js` for fuzzy search
+- **File System**: Node.js `fs` module for scanning packages
+
+### Deployment Options
+
+1. **Local Development** (stdio transport):
+   - Users run the server locally via `npx @amedia/brick-mcp-server`
+   - Configured in Claude Code settings
+
+2. **HTTP Server** (optional):
+   - Deploy as a service for remote access
+   - Use `@modelcontextprotocol/sdk/server/streamableHttp.js`
+
+3. **npm Package**:
+   - Publish as `@amedia/brick-mcp-server`
+   - Users install and configure in their MCP client
+
+### Example Server Setup
+
+```typescript
+import {
+  McpServer,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { listComponents } from './tools/listComponents.js';
+import { getComponentDocs } from './tools/getComponentDocs.js';
+
+// Create MCP server
+const server = new McpServer({
+  name: 'brick-design-system',
+  version: '1.0.0',
+});
+
+// Register tools
+server.registerTool(
+  'list-components',
+  {
+    title: 'List Brick Components',
+    description: 'List all available Brick components with metadata',
+    inputSchema: { filter: z.string().optional() },
+    outputSchema: z.object({
+      components: z.array(
+        z.object({
+          name: z.string(),
+          version: z.string(),
+          selector: z.string(),
+          description: z.string(),
+        })
+      ),
+    }),
+  },
+  async ({ filter }) => {
+    const components = await listComponents(filter);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(components) }],
+      structuredContent: { components },
+    };
+  }
+);
+
+// Register resources
+server.registerResource(
+  'components',
+  new ResourceTemplate('brick://components', { list: undefined }),
+  {
+    title: 'Brick Components',
+    description: 'List of all Brick components',
+  },
+  async (uri) => {
+    const components = await listComponents();
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(components, null, 2),
+          mimeType: 'application/json',
+        },
+      ],
+    };
+  }
+);
+
+// Start server with stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+---
+
+## Development Workflow
+
+### Phase 1: Foundation
+
+1. Set up package structure in `packages/brick-mcp-server/`
+2. Install MCP SDK and dependencies
+3. Create basic server with one tool (list-components)
+4. Implement package scanner to find all brick-\* packages
+
+### Phase 2: Documentation Extraction
+
+1. Build TypeScript type extractor
+2. Build MDX documentation parser
+3. Build Storybook story parser
+4. Build design token extractor
+
+### Phase 3: Core Tools
+
+1. Implement all MCP tools
+2. Implement search functionality
+3. Build documentation index
+
+### Phase 4: Resources
+
+1. Implement MCP resources
+2. Add caching layer
+3. Add error handling
+
+### Phase 5: Testing & Documentation
+
+1. Write unit tests for extractors
+2. Write integration tests for MCP tools
+3. Create comprehensive README
+4. Add usage examples
+
+### Phase 6: Publishing
+
+1. Build and bundle for npm
+2. Publish to npm as `@amedia/brick-mcp-server`
+3. Document installation in Brick docs
+4. Create video/guide for users
 
 ---
 
 ## Usage Example
 
-You can interact with the Brick MCP server in Claude Code:
+Once configured, you can interact with the Brick MCP server in Claude Code:
 
 ```
 User: "I need to add a button to my app using Brick"
@@ -386,6 +597,6 @@ claude mcp add --transport stdio Brick -- npx @amedia/brick-mcp
 
 ## References
 
-- MCP TypeScript SDK: <https://github.com/modelcontextprotocol/typescript-sdk>
-- MCP Example Servers: <https://github.com/modelcontextprotocol/servers>
-- Brick Designsystem: `www.brick.api.no`
+- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
+- MCP Example Servers: https://github.com/modelcontextprotocol/servers
+- Brick Monorepo: `/Users/simonsundstrom/dev/amedia/brick`

package/dist/commands/serve.js

@@ -0,0 +1,42 @@
+/**
+ * HTTP/Fastify transport command
+ * Used for running the MCP server as an HTTP service
+ */
+import Fastify from 'fastify';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createServer } from '../server.ts';
+export async function runServe(options = {}) {
+    const port = options.port ?? 3000;
+    const host = options.host ?? '0.0.0.0';
+    const fastify = Fastify({
+        logger: true,
+    });
+    // Health check endpoint
+    fastify.get('/health', async () => {
+        return { status: 'ok' };
+    });
+    // MCP SSE endpoint
+    fastify.get('/sse', async (request, reply) => {
+        const server = createServer();
+        const transport = new SSEServerTransport('/messages', reply.raw);
+        await server.connect(transport);
+        // Keep connection alive
+        request.raw.on('close', () => {
+            server.close();
+        });
+    });
+    // POST endpoint for messages
+    fastify.post('/messages', async () => {
+        // SSE transport handles this internally
+        return { received: true };
+    });
+    try {
+        await fastify.listen({ port, host });
+        console.log(`Brick MCP server listening on http://${host}:${port}`);
+        console.log(`SSE endpoint: http://${host}:${port}/sse`);
+    }
+    catch (err) {
+        fastify.log.error(err);
+        process.exit(1);
+    }
+}

package/dist/commands/stdio.js

@@ -0,0 +1,11 @@
+/**
+ * stdio transport command
+ * Used by Claude Desktop and other stdio-based MCP clients
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../server.ts';
+export async function runStdio() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/extractors/packageScanner.js

@@ -0,0 +1,150 @@
+/**
+ * Package scanner for discovering Brick components
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PackageJsonSchema, } from '../types.ts';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Get the root directory of the Brick monorepo
+ * Assumes mcp-server is in the root of the brick repository
+ */
+export function getBrickRoot() {
+    // Go up from mcp-server/src to brick root
+    return join(__dirname, '..', '..');
+}
+/**
+ * Extract component selector from package name
+ * e.g., "@amedia/brick-button" -> "brick-button"
+ */
+export function extractSelector(packageName, version) {
+    const componentName = packageName.replace('@amedia/', '');
+    const majorVersion = version.split('.')[0];
+    return `${componentName}-v${majorVersion}`;
+}
+/**
+ * Categorize component based on name or package.json metadata
+ * This is a simple heuristic - can be improved with actual metadata
+ */
+export function categorizeComponent(name) {
+    const categoryMap = {
+        Forms: ['button', 'input', 'checkbox', 'radio', 'select', 'form'],
+        Navigation: ['menu', 'nav', 'breadcrumb', 'tabs', 'link'],
+        Layout: ['grid', 'card', 'container', 'layout', 'section'],
+        Feedback: ['alert', 'toast', 'notification', 'banner', 'dialog', 'modal'],
+        Display: ['avatar', 'badge', 'icon', 'image', 'teaser', 'carousel'],
+        Utilities: ['tokens', 'classnames', 'template', 'fonts'],
+    };
+    const componentName = name.toLowerCase();
+    for (const [category, keywords] of Object.entries(categoryMap)) {
+        if (keywords.some((keyword) => componentName.includes(keyword))) {
+            return category;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract tags from component name
+ */
+export function extractTags(name, category) {
+    const tags = [];
+    if (category) {
+        tags.push(category.toLowerCase());
+    }
+    // Add interactive tag for form/button components
+    if (name.includes('button') ||
+        name.includes('input') ||
+        name.includes('select')) {
+        tags.push('interactive');
+    }
+    return tags;
+}
+/**
+ * Read and parse package.json for a given package path
+ */
+export async function readPackageJson(packagePath) {
+    try {
+        const packageJsonPath = join(packagePath, 'package.json');
+        const content = await readFile(packageJsonPath, 'utf-8');
+        const data = JSON.parse(content);
+        return PackageJsonSchema.parse(data);
+    }
+    catch (error) {
+        console.error(`Error reading package.json at ${packagePath}:`, error);
+        return null;
+    }
+}
+/**
+ * Scan a single package directory and extract component metadata
+ */
+export async function scanPackage(packagePath) {
+    const packageJson = await readPackageJson(packagePath);
+    if (!packageJson) {
+        return null;
+    }
+    // Only include packages that start with @amedia/brick- and exclude utility packages
+    if (!packageJson.name.startsWith('@amedia/brick-')) {
+        return null;
+    }
+    const componentName = packageJson.name.replace('@amedia/', '');
+    const selector = extractSelector(packageJson.name, packageJson.version);
+    const category = categorizeComponent(componentName);
+    const tags = extractTags(componentName, category);
+    return {
+        name: componentName,
+        version: packageJson.version,
+        selector,
+        description: packageJson.description,
+        category,
+        tags: tags.length > 0 ? tags : undefined,
+        packagePath,
+    };
+}
+/**
+ * Scan all packages in the Brick monorepo
+ */
+export async function scanAllPackages() {
+    const brickRoot = getBrickRoot();
+    const packagesDir = join(brickRoot, 'packages');
+    try {
+        const entries = await readdir(packagesDir, { withFileTypes: true });
+        const packageDirs = entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith('brick-'))
+            .map((entry) => join(packagesDir, entry.name));
+        const components = await Promise.all(packageDirs.map((dir) => scanPackage(dir)));
+        // Filter out null results and sort by name
+        return components
+            .filter((component) => component !== null)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (error) {
+        console.error('Error scanning packages:', error);
+        return [];
+    }
+}
+/**
+ * Filter components by category or tag
+ */
+export function filterComponents(components, filter) {
+    if (!filter) {
+        return components;
+    }
+    const filterLower = filter.toLowerCase();
+    return components.filter((component) => {
+        // Match against name
+        if (component.name.toLowerCase().includes(filterLower)) {
+            return true;
+        }
+        // Match against category
+        if (component.category?.toLowerCase().includes(filterLower)) {
+            return true;
+        }
+        // Match against tags
+        if (component.tags?.some((tag) => tag.toLowerCase().includes(filterLower))) {
+            return true;
+        }
+        return false;
+    });
+}