@amedia/brick-mcp 0.1.3 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Brick MCP Server is a Model Context Protocol (MCP) server that provides AI assistants (like Claude Code) with direct access to the Brick design system. It enables accurate, context-aware assistance when developers implement Brick components by exposing component documentation, design tokens, and usage examples through standardized MCP tools.
+The Brick MCP Server is a Model Context Protocol (MCP) server that provides AI assistants (like Claude Code or Copilot) with direct access to the Brick design system. It enables accurate, context-aware assistance when developers implement Brick components by exposing component documentation, design tokens, and usage examples through standardized MCP tools.
 
 ## Prerequisites
 
@@ -206,6 +206,55 @@ Claude: [Calls list-components with filter: "button"]
 
 ---
 
+## Maintaining Component Documentation
+
+The MCP server includes prompts to help maintain component documentation as components evolve.
+
+### Updating Component Docs
+
+Use [prompts/update-component-docs.md](prompts/update-component-docs.md) to check if component documentation needs updating based on version changes.
+
+**When to use:**
+
+- After component versions have been updated
+- To audit which components have outdated documentation
+- Before publishing a new version of the MCP server
+
+**What it does:**
+
+1. Compares versions in `data/components/*.md` frontmatter against `packages/*/package.json`
+2. Identifies components with major or minor version changes (patch changes are skipped)
+3. Generates updated documentation for components that need it
+4. Provides a summary of what was updated
+
+**Example usage with Claude Code:**
+
+```
+User: "Check if any component docs need updating using prompts/update-component-docs.md"
+
+Claude: [Reads the prompt file and follows the instructions]
+        [Checks all components in data/components/]
+        [Identifies version mismatches]
+        [Updates documentation for components with major/minor changes]
+
+        ## Documentation Update Summary
+
+        ### Components Checked: 45
+
+        ### Updates Required:
+        - brick-modal: 3.2.1 → 4.0.0 (major change)
+        - brick-image: 6.0.5 → 6.1.0 (minor change)
+
+        ### Up to Date: 42 components
+
+        ### Skipped (patch changes only):
+        - brick-button: 9.0.2 → 9.0.5
+```
+
+The prompt references [prompts/generate-llm-docs.md](prompts/generate-llm-docs.md) for the documentation generation process.
+
+---
+
 ### Adding New Tools
 
 To add a new MCP tool:

package/data/components/brick-mcp.md

@@ -0,0 +1,259 @@
+---
+name: brick-mcp
+version: 0.1.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]
+---
+
+# Brick MCP
+
+A Model Context Protocol (MCP) server that provides AI assistants with direct access to the Brick design system through standardized tools for component documentation, design tokens, and usage examples.
+
+## Key Capabilities
+
+- Exposes three MCP tools for AI assistants to query Brick components and design tokens
+- 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
+
+## MCP Tools
+
+The server provides three tools that AI assistants can call:
+
+### list-components
+
+Lists all available Brick components with optional filtering.
+
+**Input Schema:**
+```typescript
+{
+  filter?: string;  // Filter by name, category, or tag
+}
+```
+
+**Returns:**
+```typescript
+{
+  components: Array<{
+    name: string;        // e.g., "brick-button"
+    version: string;     // e.g., "9.0.0"
+    selector: string;    // e.g., "brick-button-v9"
+    description?: string;
+    category?: string;   // Forms, Navigation, Layout, Feedback, Display, Utilities
+    tags?: string[];
+  }>;
+}
+```
+
+### get-component-docs
+
+Retrieves detailed documentation for one or more components.
+
+**Input Schema:**
+```typescript
+{
+  components: string[];  // e.g., ["brick-button", "brick-modal"]
+}
+```
+
+**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
+  }>;
+}
+```
+
+### get-design-tokens
+
+Accesses design tokens from brick-tokens with filtering options.
+
+**Input Schema:**
+```typescript
+{
+  category?: 'colors' | 'spacing' | 'typography' | 'shadows' | 'borders';
+  theme?: string;  // e.g., "bergen", "alfa", "bt"
+}
+```
+
+**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;
+  };
+}
+```
+
+## Examples
+
+### Installation via npx (Recommended)
+
+Add the Brick MCP server to Claude Code using npx:
+
+```bash
+claude mcp add --transport stdio Brick -- npx -y @amedia/brick-mcp@latest
+```
+
+### Install as Package Dependency
+
+```bash
+npm install @amedia/brick-mcp
+```
+
+### Running in HTTP Mode
+
+For local development with HTTP transport:
+
+```bash
+# Install and build
+npm install
+npm run build
+
+# Start HTTP server (default: http://localhost:3000)
+npm run dev:http
+
+# Add to Claude Code
+claude mcp add Brick-http --transport sse --scope user -- http://0.0.0.0:3000/sse
+```
+
+### Environment Variables
+
+```bash
+PORT=3000  # Server port (default: 3000)
+HOST=0.0.0.0  # Server host (default: 0.0.0.0)
+```
+
+## Usage Workflow
+
+Once configured, AI assistants can use the MCP tools:
+
+```
+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' };
+  },
+};
+```
+
+## 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
+- **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`
+
+## Publishing
+
+### Standard Release
+
+```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
+```
+
+### 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
+
+## 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

package/data/components/brick-pill.md

@@ -0,0 +1,362 @@
+---
+name: brick-pill
+version: 9.0.9
+selector: brick-pill-v9
+category: Data Display
+tags: [pill, label, badge, status, meta, countdown, icon, vignette]
+use_cases:
+  [
+    article-metadata,
+    content-labels,
+    status-indicators,
+    countdown-timers,
+    breaking-news,
+    content-categorization,
+  ]
+related: [brick-pillbox, brick-icon, brick-tokens]
+---
+
+# Brick Pill
+
+A read-only status indicator or label component that displays small pieces of meta information with optional icons and background fills.
+
+## Key Capabilities
+
+- Multiple visual versions: vignette, video, gallery, breaking, plus, alt, plusall, icon, countdown
+- Customizable skins for different content categories (sport, opinion, highlight, commercial, shopping, betting)
+- Optional filled or outlined styles
+- Icon support with configurable size
+- Live countdown timer functionality with automatic toggle to fallback version
+- Locale support for countdown text (Norwegian Bokmal and Nynorsk)
+- Can be used standalone or wrapped in brick-pillbox container
+- CSS custom properties for advanced styling
+
+## Props/Attributes
+
+| Attribute                        | Type                                                                                   | Default     | Required | Description                                                    |
+| -------------------------------- | -------------------------------------------------------------------------------------- | ----------- | -------- | -------------------------------------------------------------- |
+| `data-text`                      | string                                                                                 | -           | no       | Text content to display in the pill                            |
+| `data-version`                   | `'vignette' \| 'video' \| 'gallery' \| 'breaking' \| 'untold' \| 'icon' \| 'plus' \| 'alt' \| 'plusall' \| 'countdown'` | `'vignette'` | no       | Visual style variant of the pill                               |
+| `data-filled`                    | boolean                                                                                | `false`     | no       | When true, pill has background color fill                      |
+| `data-skin`                      | `'none' \| 'black' \| 'custom-one' \| 'custom-two' \| 'custom-three' \| 'sport' \| 'highlight' \| 'commercial' \| 'shopping' \| 'betting' \| 'opinion'` | `'none'`    | no       | Predefined color theme for the pill                            |
+| `data-icon-id`                   | string                                                                                 | -           | no       | ID of icon from brick-icon to display                          |
+| `data-icon-text`                 | string                                                                                 | -           | no       | Alternative text for the icon                                  |
+| `data-icon-size`                 | string                                                                                 | `'small'`   | no       | Size of the icon                                               |
+| `data-countdown-date`            | EpochTimeStamp                                                                         | -           | no       | Unix timestamp for countdown end time (required for countdown) |
+| `data-countdown-toggle-version`  | `'vignette' \| 'video' \| 'gallery' \| 'breaking' \| 'untold'`                         | `'vignette'` | no       | Version to display after countdown ends                        |
+| `data-countdown-toggle-text`     | string                                                                                 | -           | no       | Text to display after countdown ends                           |
+| `data-locale`                    | `'nb_NO' \| 'nn_NO'`                                                                   | `'nb_NO'`   | no       | Locale for countdown text (day/days translation)               |
+
+## Examples
+
+### Basic Pill
+
+```html
+<brick-pill-v9 data-text="News" data-version="vignette"> </brick-pill-v9>
+```
+
+### Filled Pill with Skin
+
+```html
+<brick-pill-v9
+  data-text="Sport"
+  data-version="vignette"
+  data-filled="true"
+  data-skin="sport"
+>
+</brick-pill-v9>
+```
+
+### Breaking News Pill
+
+```html
+<brick-pill-v9
+  data-text="Breaking"
+  data-version="breaking"
+  data-filled="true"
+>
+</brick-pill-v9>
+```
+
+### Pill with Icon
+
+```html
+<brick-pill-v9
+  data-text="1t 10m"
+  data-version="vignette"
+  data-icon-id="pill-podcast"
+  data-icon-size="small"
+>
+</brick-pill-v9>
+```
+
+### Countdown Pill
+
+Displays a live countdown timer that automatically switches to a different pill when time expires:
+
+```html
+<brick-pill-v9
+  data-version="countdown"
+  data-countdown-date="1676460023618"
+  data-countdown-toggle-text="Direkte"
+  data-countdown-toggle-version="breaking"
+  data-filled="true"
+>
+</brick-pill-v9>
+```
+
+Note: The countdown date should be a Unix epoch timestamp in milliseconds.
+
+### Content Category Pills
+
+```html
+<!-- Opinion content -->
+<brick-pill-v9
+  data-text="Opinion"
+  data-version="vignette"
+  data-skin="opinion"
+  data-filled="true"
+>
+</brick-pill-v9>
+
+<!-- Commercial content -->
+<brick-pill-v9
+  data-text="Commercial"
+  data-version="vignette"
+  data-skin="commercial"
+  data-filled="true"
+>
+</brick-pill-v9>
+
+<!-- Highlight -->
+<brick-pill-v9
+  data-text="Recommended"
+  data-version="vignette"
+  data-skin="highlight"
+  data-filled="true"
+>
+</brick-pill-v9>
+```
+
+### Using with brick-pillbox
+
+When wrapping multiple pills in brick-pillbox, the container manages spacing and styling:
+
+```html
+<brick-pillbox-v0 data-filled="true">
+  <brick-pill-v9
+    data-text="Breaking"
+    data-version="breaking"
+    data-filled="true"
+  >
+  </brick-pill-v9>
+  <brick-pill-v9 data-text="Politics" data-version="vignette" data-filled="true">
+  </brick-pill-v9>
+</brick-pillbox-v0>
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  import '@amedia/brick-pill';
+</script>
+
+<brick-pill-v9
+  data-text="News"
+  data-version="vignette"
+  data-filled="true"
+/>
+```
+
+See this REPL for full example: https://svelte.dev/repl/b124e26657b944908566c8c21f985415
+
+### React/Vue
+
+```javascript
+import '@amedia/brick-pill';
+
+// React
+function ArticleMeta() {
+  return (
+    <brick-pill-v9
+      data-text="Breaking"
+      data-version="breaking"
+      data-filled="true"
+    />
+  );
+}
+
+// Vue
+<template>
+  <brick-pill-v9
+    data-text="Breaking"
+    data-version="breaking"
+    data-filled="true"
+  />
+</template>
+```
+
+## Programmatic Usage
+
+```javascript
+import { BrickPill } from '@amedia/brick-pill';
+
+const pill = document.createElement('brick-pill-v9');
+pill.dataset.version = 'vignette';
+pill.dataset.text = 'Latest';
+pill.dataset.filled = 'true';
+pill.dataset.skin = 'sport';
+
+document.body.appendChild(pill);
+```
+
+### Creating Countdown with JavaScript
+
+```javascript
+const timestamp = new Date('2024-12-31T23:59:59').getTime();
+// or: const timestamp = +new Date('2024-12-31T23:59:59');
+
+const countdownPill = document.createElement('brick-pill-v9');
+countdownPill.dataset.version = 'countdown';
+countdownPill.dataset.countdownDate = timestamp.toString();
+countdownPill.dataset.countdownToggleText = 'Live Now';
+countdownPill.dataset.countdownToggleVersion = 'breaking';
+countdownPill.dataset.filled = 'true';
+
+document.body.appendChild(countdownPill);
+```
+
+## Server-Side Rendering
+
+```javascript
+import { renderBrickPill } from '@amedia/brick-pill/template';
+
+const pillHTML = renderBrickPill({
+  dataText: 'Breaking',
+  dataVersion: 'breaking',
+  dataFilled: true,
+  dataSkin: 'none',
+});
+
+// Include CSS file
+// <link rel="stylesheet" href="https://assets.acdn.no/pkg/@amedia/brick-pill/v9/css/styles.css">
+```
+
+## Accessibility
+
+- Color contrasts adhere to WCAG 2.1 AA guidelines
+- Icons are decorative and hidden from screen readers (aria-hidden)
+- Text content is accessible to assistive technologies
+- Countdown updates are announced to screen readers using aria-live regions
+
+## Common Patterns
+
+### Article Teaser Metadata
+
+```html
+<brick-pillbox-v0 data-filled="true">
+  <brick-pill-v9 data-text="Breaking" data-version="breaking" data-filled="true">
+  </brick-pill-v9>
+  <brick-pill-v9 data-text="Politics" data-version="vignette" data-filled="true">
+  </brick-pill-v9>
+  <brick-pill-v9 data-text="5 min read" data-version="vignette" data-filled="true">
+  </brick-pill-v9>
+</brick-pillbox-v0>
+```
+
+### Live Event Countdown
+
+```html
+<brick-pill-v9
+  data-version="countdown"
+  data-countdown-date="1703001600000"
+  data-countdown-toggle-text="Live"
+  data-countdown-toggle-version="breaking"
+  data-filled="true"
+  data-locale="nb_NO"
+>
+</brick-pill-v9>
+```
+
+### Custom Publication Logo Pill
+
+```html
+<brick-pill-v9
+  data-text="Laagendalsposten"
+  data-version="alt"
+  data-filled="true"
+  style="--b-pill-svg: url('https://r.acdn.no/local/v3/publications/www.ao.no/gfx/square.svg')"
+>
+</brick-pill-v9>
+```
+
+## Styling and CSS Properties
+
+Customize pill appearance using CSS custom properties:
+
+```css
+brick-pill-v9 {
+  /* Background color for filled pills */
+  --b-pill-color-bg: var(--brick-colors-surfaceBrand);
+
+  /* Text color */
+  --b-pill-color-fg: var(--brick-colors-textOnBrand);
+
+  /* Breaking version background color */
+  --b-pill-color-breakingBg: var(--brick-colors-utilityDangerBg);
+
+  /* Breaking version text color */
+  --b-pill-color-breakingFg: var(--brick-colors-utilityDangerFg);
+
+  /* Custom SVG icon for "icon" version */
+  --b-pill-svg: url('path/to/icon.svg');
+
+  /* SVG icon dimensions */
+  --b-pill-svg-width: 11px;
+  --b-pill-svg-height: 11px;
+}
+```
+
+### Opinion Skin Custom Colors
+
+When using `data-skin="opinion"` with `data-filled="true"`:
+
+```css
+brick-pill-v9 {
+  --opinion-background-color: #yourcolor;
+  --opinion-color-text: #yourtextcolor;
+}
+```
+
+**Note:** When overriding colors, ensure your customizations adhere to WCAG 2.1 AA contrast requirements.
+
+## Technical Details
+
+- **Custom Element**: `brick-pill-v9`
+- **Base Class**: BrickElement
+- **Dependencies**:
+  - @amedia/brick-tokens (design tokens)
+  - @amedia/brick-icon (icon support)
+  - @amedia/brick-template (base class)
+- **Renders as**: `<span>` element with shadow DOM
+- **SSR Compatible**: Yes, with client-side hydration for countdown version
+- **Framework**: Framework-agnostic web component
+
+## Important Notes
+
+- Pills are read-only status indicators and are not interactive
+- The countdown version always renders its inner markup (icon and clock) client-side
+- When the countdown expires, it automatically switches to the version specified in `data-countdown-toggle-version`
+- When used inside `brick-pillbox`, the container affects pill styling:
+  - Removes individual pill border radius
+  - Truncates text on the last pill
+  - Adds dividers between eligible pills
+- The breaking version has special animation that requires overflow to be visible, so it will not get text ellipsis
+- Version 9.0.0 uses the `brick-pill-v9` selector
+
+## Version
+
+Current version: 9.0.9