Eddie Brain

The agentic intelligence layer for the Eddie Design System. Exposes an MCP server so AI coding tools (Claude Code, Cursor, etc.) can query component metadata, validate token usage, check design system health, and compose canonical UI patterns.

What It Does

• eddie_get_component — Full component docs: props, slots, events, guidelines
• eddie_search — Search across components, tokens, and recipes
• eddie_get_token — Token value, tier, intent, and which components use it
• eddie_compose_recipe — Canonical composition patterns for a given UI intent (e.g. "login form", "destructive confirmation dialog")
• eddie_check_health — Health scores across tokens, naming, docs, coverage, accessibility, and consistency
• eddie_validate_file — Validate a file against Eddie conventions
• eddie_suggest_fix — Suggest fixes for detected violations
• eddie_get_relationships — Component composition relationships

Setup

Prerequisites

• Node.js (same version as the monorepo)
• The eddie-design-system repo cloned locally

1. Install dependencies

From the repo root:

npm install

2. Build the package

cd packages/eddie-brain
npm run build

This runs tsc and copies the static knowledge base files (components.json, tokens.json, etc.) into dist/.

Verify the output:

ls dist/mcp/server.js

3. MCP registration is automatic

The repo's .mcp.json at the root handles registration for Claude Code:

{
  "mcpServers": {
    "eddie-brain": {
      "command": "node",
      "args": ["packages/eddie-brain/dist/mcp/server.js"],
      "env": {
        "EDDIE_ROOT": "."
      }
    }
  }
}

Claude Code reads .mcp.json on startup when your working directory is inside eddie-design-system. The EDDIE_ROOT: "." env var tells the server where to find the design system files. No additional configuration needed.

Rebuilding After Changes

Whenever src/ or data/ files change, rebuild and restart your editor session:

cd packages/eddie-brain
npm run build

CLI

The package also ships a standalone CLI:

# Health report for the whole system
node packages/eddie-brain/dist/cli/brain.js health

# Full scan (monitor + analyze)
node packages/eddie-brain/dist/cli/brain.js scan
node packages/eddie-brain/dist/cli/brain.js scan --component ed-button

# Validate tokens and naming in source files
node packages/eddie-brain/dist/cli/brain.js validate src/
node packages/eddie-brain/dist/cli/brain.js validate --fix

# Compose a pattern from components
node packages/eddie-brain/dist/cli/brain.js compose "destructive confirmation dialog"

# View audit log
node packages/eddie-brain/dist/cli/brain.js audit
node packages/eddie-brain/dist/cli/brain.js audit --since 2026-03-01

Development

npm run dev      # TypeScript watch mode
npm test         # Run tests
npm run health   # Quick health check

Architecture

See SPEC.md for the full technical specification, including the knowledge graph schema, trust level model, health scoring categories, and implementation phases.