@teamix-evo/mcp

Model Context Protocol server for teamix-evo. Single bin / single process / multiple tool groups. Cursor, Claude Code, Cline, Aider, and any future MCP-aware tool can query teamix-evo's component catalog (and, in future milestones, design tokens / ADRs / scenario packs) as a service instead of grepping 56KB of manifest.json.

Renamed from @teamix-evo/registry-mcp per ADR 0011. Tool names within the registry group (list_components / get_component_meta / find_components) are unchanged.

Why

ADR 0009 (registry MCP rationale) and ADR 0011 (single-package / multi-group consolidation) together explain the design:

• Static manifest.json rots: every consumer pulls a snapshot, drifts from the source.
• AI editors handle 56KB poorly: chunking + RAG is lossy and slow.
• MCP server is single-source: directly reads upstream manifest.json + *.meta.md, returns structured data on demand.
• One process, many groups: registry today; design / adr / scenario in v0.6-v0.8 — without spawning extra processes or .mcp.json entries.

Tool groups

| Group | Status | Tools | Naming | | --- | --- | --- | --- | | registry | ✅ shipping | list_components / get_component_meta / find_components | unprefixed (historical exception, see ADR 0011 §5) | | tokens | ✅ shipping | tokens_get / tokens_list / tokens_search | <group>_<verb>_<noun> | | skills | ✅ shipping | skills_list / skills_get / skills_find | <group>_<verb>_<noun> | | adr | ✅ shipping | adr_list / adr_get / adr_find | <group>_<verb>_<noun> | | scenario | ⏸ v0.8 | scenario_list / scenario_get_pack | <group>_<verb>_<noun> |

Currently shipping — registry group tools

| Tool | Input | Output | | --- | --- | --- | | list_components | status?: 'stable' \| 'experimental' \| 'deprecated' | Array of { id, name, description, status, registryDependencies } | | get_component_meta | id: string | Full UiEntry record + parsed meta.md content (frontmatter + body) | | find_components | query: string, limit?: number | Substring match over id / name / description (semantic search → v0.7) |

Install (consumer side)

# Project-local (recommended)
pnpm add -D @teamix-evo/mcp @teamix-evo/ui

Then wire into your IDE's MCP config:

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "teamix-evo": {
      "command": "npx",
      "args": ["-y", "@teamix-evo/mcp"],
      "env": {
        "TEAMIX_EVO_UI_MANIFEST": "${workspaceFolder}/node_modules/@teamix-evo/ui/manifest.json"
      }
    }
  }
}

Claude Code (.claude/mcp_servers.json)

{
  "teamix-evo": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@teamix-evo/mcp"]
  }
}

Manifest resolution

The server resolves @teamix-evo/ui/manifest.json in this order:

1. TEAMIX_EVO_UI_MANIFEST env var (absolute path)
2. <cwd>/node_modules/@teamix-evo/ui/manifest.json
3. Walking up from <cwd> until a node_modules/@teamix-evo/ui/manifest.json is found
4. Fail with a clear error message

Meta documents (<id>.meta.md) are resolved relative to the manifest's own root.

Run locally (debug)

# From this package directory:
pnpm build
pnpm start

# Or via the bin shortcut after publishing:
npx @teamix-evo/mcp

The server speaks stdio MCP by default. To test interactively, use the MCP Inspector:

npx @modelcontextprotocol/inspector node ./dist/cli.js

Adding a new tool group (for maintainers)

1. Create src/groups/<name>.ts exporting createXxxGroup(opts): ToolGroup
2. Tools must use <group>_<verb>_<noun> naming (registry is the historical exception)
3. Register the group in src/server.ts createServer()
4. Add tests under tests/groups/<name>/
5. Cross-group tool name uniqueness is enforced at startup