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

Remote (hosted) MCP over HTTP

The same server can run as a remote, Streamable HTTP MCP so projects can connect over a URL — no local install or repo checkout. The tool implementations are shared via createEddieBrainServer(); the transports differ:

• src/mcp/server.ts — stdio entrypoint (local; used by .mcp.json) + the shared createEddieBrainServer() factory and loadBrainContext().
• src/mcp/http.ts — Streamable HTTP entrypoint. handleNodeMcpRequest (Node http.Server, for local testing) and handleWebMcpRequest (Fetch API, for Netlify/Workers/Deno/Bun). Both run stateless.
• src/mcp/serverless.ts + scripts/bundle-serverless.js — the Fetch handler, pre-bundled by esbuild into one self-contained file at dist/serverless/mcp.mjs and copied to netlify/functions/mcp.mjs. Netlify deploys it with node_bundler = "none" (ships it verbatim); its own bundler otherwise scans the monorepo's .ts/.d.ts and fails.

The knowledge graph is bundled into dist/graph/ at build (scripts/copy-graph.js) so a disk-less deployment loads it via the EDDIE_ROOT-unset fallback in loadBrainContext().

Test the HTTP server locally before deploying:

npm run build          # compiles + bundles the graph into dist/graph/
npm run mcp:http       # serves http://localhost:3939/mcp (uses the bundled dist/graph)

# List tools over HTTP:
curl -sS http://localhost:3939/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

See docs/ECOSYSTEM.md → "Connect to Eddie's Brain (MCP)" for how consumer projects wire up the remote URL.

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.