@amedia/brick-mcp 0.0.0-vCLR-20260313124546

package/README.md

@@ -0,0 +1,297 @@
+# Brick MCP Server
+
+## Overview
+
+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
+
+Follow the Amedia CLI guide available [here](https://amedia.slite.com/app/docs/6GMS-ASZ1r2rWM)
+
+## Usage
+
+The Brick MCP server can be run in two modes:
+
+### Stdio Mode (for Claude Code)
+
+The recommended way to use the MCP server with Claude Code is via npx:
+
+```bash
+# Add to Claude Code
+claude mcp add --transport stdio Brick -- npx -y @amedia/brick-mcp@latest
+```
+
+### HTTP Mode (for local development)
+
+To run the MCP server as an HTTP service:
+
+```bash
+# Fetch data folder
+npm run build
+# Development with watch mode
+npm run dev: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
+
+To add to Claude run
+
+```bash
+claude mcp add Brick-http --transport sse --scope user -- http://0.0.0.0:3000/sse
+```
+
+#### Environment Variables
+
+- `PORT` - Server port (default: 3000)
+- `HOST` - Server host (default: 0.0.0.0)
+
+### What the MCP Server Provides
+
+Once configured, you can ask Claude about Brick components, design tokens, and implementation patterns. The MCP server provides three main tools:
+
+1. **`list-components`**: Discover all available Brick components with filtering by name, category, or tags
+2. **`get-component-docs`**: Retrieve detailed documentation including MDX content, llm.txt summaries, examples, and Storybook links
+3. **`get-design-tokens`**: Access design tokens filtered by category (colors, spacing, typography, shadows, borders) or theme, with available themes list and comprehensive documentation about the token system
+
+## Goals
+
+1. **Easy Discovery**: Enable AI to quickly list and search available Brick components
+2. **Accurate Implementation**: Provide detailed component documentation including props, events, and accessibility guidelines
+3. **Design Consistency**: Make design tokens easily accessible for consistent styling
+4. **Best Practices**: Include usage examples and patterns from Storybook
+5. **Developer Experience**: Reduce friction when implementing Brick components through AI-assisted development
+
+## MCP Tools (Actions)
+
+The MCP server exposes three tools that AI assistants can call to fetch information about the Brick design system. All data is pre-generated during the build process and bundled as JSON files, making the server fast and suitable for use as a standalone npm package.
+
+### 1. `list-components`
+
+List all available Brick components with optional filtering.
+
+**Input**:
+
+```typescript
+{
+  filter?: string;  // Filter by name, category, or tag
+}
+```
+
+**Output**:
+
+```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; // Auto-categorized: Forms, Navigation, Layout, Feedback, Display, Utilities
+    tags?: string[]; // Auto-generated tags
+  }>;
+}
+```
+
+**Example**: `{ "filter": "button" }` returns all button-related components.
+
+---
+
+### 2. `get-component-docs`
+
+Retrieve detailed documentation for one or more components.
+
+**Input**:
+
+```typescript
+{
+  components: string[];  // e.g., ["brick-button", "brick-modal"]
+}
+```
+
+**Output**:
+
+```typescript
+{
+  docs: Array<{
+    name: string;
+    version: string;
+    selector: string;
+    description?: string; // From llm.txt or MDX content
+    examples: {
+      webComponent?: string; // Extracted from MDX or auto-generated
+      storybook?: string; // Link to Chromatic Storybook
+    };
+    cdnPath?: string; // Eik CDN URL for the component
+  }>;
+}
+```
+
+**Data Sources**:
+
+- `llm.txt`: AI-friendly component summaries (if available)
+- `.mdx` files: Full documentation from Storybook
+- `package.json`: Version and description
+
+---
+
+### 3. `get-design-tokens`
+
+Access design tokens from brick-tokens with filtering options.
+
+**Input**:
+
+```typescript
+{
+  category?: 'colors' | 'spacing' | 'typography' | 'shadows' | 'borders';
+  theme?: string;  // e.g., "bergen", "alfa", "bt"
+}
+```
+
+**Output**:
+
+```typescript
+{
+  tokens: Array<{
+    name: string;        // e.g., "color-primary"
+    value: string;       // e.g., "#0066CC"
+    type: string;        // Token type from Design Tokens spec
+    description?: string;
+    category?: string;
+    theme?: string;
+  }>;
+  themes: string[];      // Available theme names (e.g., ["alfa", "bergen", "bt"])
+  documentation: {
+    anOverview?: string;  // Overview of the design token system
+    formats?: string;     // Information about token formats
+    naming?: string;      // Token naming conventions
+    themes?: string;      // Theme documentation
+    usage?: string;       // Usage guidelines
+  };
+}
+```
+
+**Data Sources**:
+
+- Pre-built tokens from `brick-tokens/publications/publication/*.json`
+- Documentation from `tokens-documentation.json`
+
+---
+
+## Usage Example
+
+Once configured, Claude Code can use the MCP tools to answer questions about Brick:
+
+```
+User: "I need to add a button to my app using Brick"
+
+Claude: [Calls list-components with filter: "button"]
+        [Calls get-component-docs with components: ["brick-button"]]
+
+        "I can help you add a Brick button. Here's the brick-button-v9 component:
+
+        <brick-button-v9>Click me</brick-button-v9>
+
+        You can load it from the Eik CDN:
+        https://assets.acdn.no/pkg/@amedia/brick-button/9.0.0/brick-button.js
+
+        For detailed examples and variants, check the Storybook documentation:
+        https://master--60060c41f82e040021133482.chromatic.com/?path=/docs/bricks-brick-button
+
+        Would you like me to implement this in your file?"
+```
+
+---
+
+## 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:
+
+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()`
+4. Update this README with tool documentation
+
+### Publishing
+
+The package is configured to publish to npm:
+
+```bash
+# From the Brick root
+# 1. Make your changes and create a changeset
+npx changeset
+# 2. Create a PR - merging will trigger a "Version Packages" PR
+# 3. Merge the "Version Packages" PR to publish to npm
+```
+
+For snapshot releases (testing pre-release versions):
+
+1. Create a changeset and then run the [snapshot GitHub action](https://github.com/amedia/brick/actions/workflows/snapshotRelease.yml) for your branch and this package.
+
+After publishing, the package can be used via:
+
+```bash
+npx @amedia/brick-mcp           # Run the latest version
+npm install @amedia/brick-mcp   # Install in your project
+```
+
+---
+
+## References
+
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [Brick Design System](https://www.brick.api.no)
+- [Chromatic Storybook](https://master--60060c41f82e040021133482.chromatic.com/)

package/data/components/brick-actions.md

@@ -0,0 +1,59 @@
+---
+name: brick-actions
+version: 0.1.5
+category: Tooling
+tags: [github-actions, automation, eik, publishing, ci-cd]
+use_cases: [ci-cd, automated-publishing, eik-deployment]
+related: []
+---
+
+# Brick Actions
+
+Custom JavaScript GitHub Actions used to automate packaging and publishing to Eik when packages are published to NPM.
+
+## Key Capabilities
+
+- Automatically publishes packages to Eik CDN after NPM publication
+- Filters packages based on Eik configuration in package.json
+- Integrates with Changesets workflow for version management
+- Validates required secrets/tokens before execution
+
+## Technical Details
+
+- **Type**: GitHub Action (JavaScript)
+- **Main**: dist/index.js
+- **Build Tool**: @vercel/ncc
+- **Dependencies**: @actions/core, @actions/exec, @actions/github, @eik/cli, @manypkg/get-packages
+
+## How It Works
+
+1. Triggered when Changesets publishes packages to NPM
+2. Receives `publishedPackages` as input
+3. Filters packages that have `eik` configuration in package.json
+4. Runs `eik package` command with proper credentials
+5. Publishes to Eik CDN at https://assets.acdn.no
+
+## Development
+
+### Building
+
+```bash
+npm run build-index
+```
+
+This uses @vercel/ncc to compile code and modules into a single distribution file.
+
+### Testing
+
+Can be tested locally using [Act](https://github.com/nektos/act) with environment variables via dotenv.
+
+## Important Notes
+
+- Not a Brick web component - this is tooling for CI/CD
+- Changesets handles versioning and CHANGELOG updates
+- Does not commit `.eik/integrity.json` files
+- Requires proper Eik credentials in GitHub secrets
+
+## Version
+
+Current version: 0.1.5

package/data/components/brick-alt-teaser.md

@@ -0,0 +1,264 @@
+---
+name: brick-alt-teaser
+version: 8.0.65
+selector: brick-alt-teaser-v8
+category: Media
+tags: [teaser, article, news, card, content-preview, media, alt-theme]
+use_cases:
+  [
+    news-listing,
+    content-cards,
+    article-preview,
+    editorial-content,
+    opinion-pieces,
+    video-teasers,
+    photo-galleries,
+    reviews,
+    featured-content,
+  ]
+related: [brick-image, brick-player, brick-pill, brick-icon]
+---
+
+# Brick Alt Teaser
+
+A flexible article teaser component designed for the Alt theme, supporting multiple content types including standard articles, features, opinions, videos, galleries, and reviews.
+
+## Key Capabilities
+
+- Multiple layout variants: standard article, feature, opinion, video, gallery, and review
+- Responsive image handling with srcset and custom aspect ratios
+- Video playback integration via brick-player
+- Photo gallery support with image count indicator
+- Review ratings displayed as dice icons
+- Opinion pieces with author bylines and profile images
+- Countdown timer support for time-sensitive content
+- Analytics integration with ADP (Amedia Data Platform)
+- Customizable background colors for visual categorization
+- Accessibility features including ARIA labels and screen reader support
+
+## Props/Attributes
+
+| Attribute                     | Type    | Default   | Required | Description                                                        |
+| ----------------------------- | ------- | --------- | -------- | ------------------------------------------------------------------ |
+| `title`                       | string  | ''        | yes      | Main headline of the article                                       |
+| `link`                        | string  | ''        | yes      | URL to the full article                                            |
+| `publication`                 | string  | ''        | no       | Publication domain (e.g., "www.tb.no")                             |
+| `name`                        | string  | ''        | no       | Publication name (e.g., "Tønsbergs Blad")                          |
+| `articleId`                   | string  | ''        | no       | Unique article identifier for tracking                             |
+| `published`                   | string  | ''        | no       | Publication date/time (supports ISO 8601 or human-readable format) |
+| `readEstimate`                | string  | ''        | no       | Estimated reading time (e.g., "Lesetid 4 min")                     |
+| `image`                       | string  | ''        | no       | Primary image URL                                                  |
+| `srcset`                      | string  | ''        | no       | Responsive image srcset for different screen sizes                 |
+| `imagesizes`                  | string  | ''        | no       | Image sizes attribute for responsive images                        |
+| `imageRatio`                  | string  | ''        | no       | Custom aspect ratio (e.g., "16/9", "4/3", "1.33")                  |
+| `aoi`                         | number  | -         | no       | Area of interest width for image cropping                          |
+| `altText`                     | string  | ''        | no       | Alternative text for images                                        |
+| `tags`                        | string  | ''        | no       | Comma-separated content tags                                       |
+| `pretitle`                    | string  | ''        | no       | Text displayed above the main title (for features)                 |
+| `feature`                     | boolean | false     | no       | Enables feature layout variant                                     |
+| `opinion`                     | boolean | false     | no       | Enables opinion layout variant                                     |
+| `review`                      | number  | -         | no       | Review rating (1-6, displayed as dice icons)                       |
+| `gallery`                     | string  | ''        | no       | Comma-separated list of gallery image URLs                         |
+| `isVideo`                     | boolean | false     | no       | Enables video teaser mode                                          |
+| `videoId`                     | string  | ''        | no       | Video identifier for brick-player                                  |
+| `playerId`                    | string  | ''        | no       | Flowplayer player ID                                               |
+| `authorName`                  | string  | ''        | no       | Author name(s) for opinion pieces (comma-separated for multiple)   |
+| `authorRole`                  | string  | ''        | no       | Author role/title for opinion pieces                               |
+| `authorImage`                 | string  | ''        | no       | Author profile image URL                                           |
+| `backgroundColor`             | string  | '#d3d9de' | no       | Background color for the teaser card                               |
+| `countdown`                   | string  | ''        | no       | ISO 8601 date for countdown timer                                  |
+| `menuOnClickEventName`        | string  | ''        | no       | Custom event name dispatched when menu is clicked                  |
+| `publicationOnHoverEventName` | string  | ''        | no       | Custom event name dispatched on publication logo hover             |
+| `siteId`                      | string  | ''        | no       | Site identifier for analytics                                      |
+| `small`                       | boolean | false     | no       | Enables compact layout variant                                     |
+
+## Examples
+
+### Basic Article Teaser
+
+```html
+<brick-alt-teaser-v8
+  title="Harvard: Fem av de beste treningsøvelsene du noensinne kan gjøre"
+  link="https://example.com/article/123"
+  publication="www.tb.no"
+  name="Tønsbergs Blad"
+  published="i dag 13:37"
+  readEstimate="Lesetid 4 min"
+  image="https://g.acdn.no/api/reflex/v1/image/resize/480/example.jpg"
+  srcset="https://g.acdn.no/api/reflex/v1/image/resize/480/example.jpg 880w, https://g.acdn.no/api/reflex/v1/image/resize/1280/example.jpg 1280w"
+  articleId="5-95-91371"
+  tags="Utvikling"
+  backgroundColor="#D3D9DE"
+>
+</brick-alt-teaser-v8>
+```
+
+### Feature Teaser
+
+```html
+<brick-alt-teaser-v8
+  feature="true"
+  pretitle="Stikktittel for feature"
+  title="Tittel for feature teaser"
+  publication="www.akersposten.no"
+  name="Akersposten"
+  image="https://g.acdn.no/api/reflex/v1/image/resize/480/example.jpg"
+  altText="Beskrivende alt-tekst"
+  link="https://example.com/feature/456"
+  backgroundColor="#DEDCD3"
+>
+</brick-alt-teaser-v8>
+```
+
+### Video Teaser
+
+```html
+<brick-alt-teaser-v8
+  title="Tittel for video teaser"
+  isVideo="true"
+  videoId="ea507f6b-ca59-4ae6-a5fa-942fd02b458a"
+  playerId="3689c16b-4cb9-4a36-baf4-2c3aa7fcc811"
+  publication="www.tb.no"
+  name="Tønsbergs Blad"
+  published="i dag 13:37"
+  readEstimate="Spilletid 13:37 min"
+  link="https://example.com/video/789"
+  backgroundColor="#D3DED6"
+>
+</brick-alt-teaser-v8>
+```
+
+### Opinion Teaser
+
+```html
+<brick-alt-teaser-v8
+  opinion="true"
+  title="Mening om viktig samfunnsspørsmål"
+  authorName="Hege Breen Bakken"
+  authorRole="Politisk redaktør i Drammens Tidende"
+  authorImage="https://image.journalisten.no/357695.jpg"
+  publication="www.dt.no"
+  name="Drammens Tidende"
+  published="i dag 13:37"
+  image="https://g.acdn.no/api/reflex/v1/image/resize/480/example.jpg"
+  link="https://example.com/opinion/101"
+>
+</brick-alt-teaser-v8>
+```
+
+### Gallery Teaser
+
+```html
+<brick-alt-teaser-v8
+  title="Bildegalleri fra årets arrangement"
+  gallery="https://example.com/img1.jpg, https://example.com/img2.jpg, https://example.com/img3.jpg"
+  image="https://example.com/img1.jpg"
+  readEstimate="3 bilder"
+  publication="www.tb.no"
+  name="Tønsbergs Blad"
+  published="i dag 13:37"
+  link="https://example.com/gallery/202"
+  altText="Bilder fra arrangementet"
+>
+</brick-alt-teaser-v8>
+```
+
+### Review Teaser
+
+```html
+<brick-alt-teaser-v8
+  title="Anmeldelse: Årets beste film"
+  review="5"
+  image="https://g.acdn.no/api/reflex/v1/image/resize/480/example.jpg"
+  publication="www.tb.no"
+  name="Tønsbergs Blad"
+  published="i dag 13:37"
+  readEstimate="Lesetid 6 min"
+  link="https://example.com/review/303"
+  altText="Filmplakat"
+>
+</brick-alt-teaser-v8>
+```
+
+## Programmatic Usage
+
+```javascript
+import { BrickAltTeaser } from '@amedia/brick-alt-teaser';
+
+// The component auto-registers as brick-alt-teaser-v8
+// You can also manually define it:
+if (!customElements.get('brick-alt-teaser-v8')) {
+  customElements.define('brick-alt-teaser-v8', BrickAltTeaser);
+}
+
+// Create and append programmatically
+const teaser = document.createElement('brick-alt-teaser-v8');
+teaser.setAttribute('title', 'My Article Title');
+teaser.setAttribute('link', 'https://example.com/article');
+teaser.setAttribute('image', 'https://example.com/image.jpg');
+document.querySelector('#container').appendChild(teaser);
+
+// Listen to custom events
+teaser.addEventListener('my-menu-event', (event) => {
+  console.log('Menu clicked');
+});
+```
+
+## Accessibility
+
+- **ARIA Labels**: Each teaser includes a comprehensive screen reader label combining title, publication, and date
+- **Keyboard Navigation**: Single tab stop per teaser (title link only) to avoid redundant navigation
+- **Focus Indicators**: Clear 2px outline on all focusable elements
+- **Semantic HTML**: Uses `<article>` with Schema.org NewsArticle markup
+- **Alt Text Support**: Images can include descriptive alternative text via `altText` attribute
+- **Skip Decorative Images**: Image links are `aria-hidden` to prevent duplicate announcements
+- **Menu Button**: Options menu includes proper `aria-expanded` state management
+
+## Analytics Integration
+
+The component includes built-in ADP (Amedia Data Platform) tracking:
+
+- **Teaser Clicks**: Automatically tagged with `data-adp-clickLabel="teaser"` and `data-adp-clickValue="read-article"`
+- **Menu Interactions**: Menu button tagged with `data-adp-clickvalue="open-menu"`
+- **Publication Tracking**: Publication logo includes hover tracking
+- **Custom Events**: Dispatches custom events via `menuOnClickEventName` and `publicationOnHoverEventName`
+- **Article Metadata**: Includes Schema.org itemprops for structured data tracking
+
+## Layout Variants
+
+The component automatically selects layout based on attributes:
+
+- **Opinion Layout**: Triggered by `opinion="true"` - Image above title with author byline
+- **Video/Gallery Layout**: Triggered by `isVideo="true"` or `gallery` attribute - Media at top
+- **Feature Layout**: Triggered by `feature="true"` - Enhanced styling with optional pretitle
+- **Standard Layout**: Default layout with image below title
+- **Small Layout**: Triggered by `small="true"` - Compact horizontal layout
+
+## Technical Details
+
+- **Custom Element**: `brick-alt-teaser-v8`
+- **Base Class**: HTMLElement (vanilla web component)
+- **Dependencies**:
+  - `@amedia/brick-tokens` - Design tokens and styling
+  - `@amedia/brick-image` - Image rendering
+  - `@amedia/brick-player` - Video playback
+  - `@amedia/brick-pill` - Tag/pill components
+  - `@amedia/brick-icon` - Icon rendering
+- **Renders as**: `<article>` with nested semantic HTML
+- **Styling**: CSS-in-JS via Stitches with design tokens
+- **Schema.org**: Implements NewsArticle microdata
+
+## Important Notes
+
+- **Alt Team Component**: Built and maintained by the Alt theme team. Consult with them before using in other contexts.
+- **Image Srcset**: As of v8.0.0, image srcset must be provided externally with correct sizes and encoding - it is no longer auto-generated
+- **Date Formats**: The `published` attribute accepts both human-readable strings ("i dag 13:37") and ISO 8601 timestamps
+- **Multiple Authors**: Opinion pieces support multiple comma-separated authors, which will display with ellipsis overflow
+- **Background Colors**: Common background colors follow design token patterns for subject categorization (default, nature, sport, health, culture, economy)
+- **Review Ratings**: Review attribute accepts values 1-6, displayed as dice icons
+- **Video Player**: Requires valid Flowplayer player ID and video ID for video teasers
+- **Countdown**: Countdown attribute expects ISO 8601 date format for time-sensitive content
+
+## Version
+
+Current version: 8.0.65