mcp-mozart

Status: V1 ready except HTTP transport (deferred). 101 tests, ~83% statement coverage. Working: discovery, capability index, local embeddings, recommender, MCP stdio server, CLI (init, status, rescan, eval [--bootstrap], serve), chokidar watcher, optional Claude-powered description augmentation and CLAUDE.md routing-hint mining (both behind --augment and ANTHROPIC_API_KEY), gold-set eval scoring. Not yet implemented: HTTP transport for non-Claude-Code MCP clients (planned for V1.1). See MCP-MOZART-PLAN.md for the full plan.

A unified retrieval recommender MCP server. Auto-discovers other MCPs registered in your Claude Code project (or user-global config), embeds their tool descriptions locally, and recommends which tools to consult for any given query — with cosine-ranked scores and short reasons.

mcp-mozart does not call the recommended tools. It returns a ranked list; the consumer LLM (e.g. Claude Code) invokes them with proper typed parameters.

Why a recommender, not a router?

MCP tools have typed parameters (bug_fix_history(component, include_security), commits_touching_file(filename, limit)) that can't be derived from a raw user query without an LLM call. A recommender:

• Keeps the contract honest — it doesn't pretend to call tools it can't parameterize
• Latency stays at ~100ms (embedding only)
• Cost stays at $0/query after setup
• Matches how routing tables in CLAUDE.md files are already written: "use this tool for that question"

Install

As a Claude Code plugin (recommended)

claude plugin add gunesbizim/mcp-mozart

This clones the repo into ~/.claude/plugins/cache/, runs npm install (which builds dist/ via the prepare script), registers the mozart MCP server, and exposes the /mozart-init, /mozart-status, and /mozart-recommend slash commands. Update later with /plugin update mozart.

After install, run once to build the capability index:

/mozart-init

As a standalone npm package

npm install -g mcp-mozart
mozart init

Then register it manually in any project's .mcp.json:

{
  "mcpServers": {
    "mozart": {
      "command": "mozart",
      "args": ["serve"],
      "env": { "MOZART_SELF": "1" }
    }
  }
}

From source (development)

git clone https://github.com/gunesbizim/mcp-mozart.git
cd mcp-mozart
npm install     # runs `prepare` → builds dist/
node dist/cli/index.js init

CLI

mozart init                       # discover MCPs, embed tool descriptions, persist index
mozart init --augment             # also call Claude to enrich thin descriptions + mine CLAUDE.md
mozart status                     # print current state
mozart rescan                     # re-discover, only re-embed changed tools
mozart eval                       # replay gold set, report routing accuracy
mozart eval --bootstrap           # interactively build gold set (requires ANTHROPIC_API_KEY)
mozart serve                      # start the MCP server over stdio

mozart init flags:

• --config <path> — explicit .mcp.json path instead of probing ./.mcp.json, ~/.claude.json, ~/.mcp.json.
• --verbose — debug-level logging.
• --augment — call Claude (requires ANTHROPIC_API_KEY) to expand thin tool descriptions and parse CLAUDE.md routing hints. Improves recommendation quality but costs API credits.

Tool surface

Once mozart is installed and mozart init has been run, any MCP client can call:

// tools/call mozart_recommend
{
  "query": "how does auth work?",
  "topK": 3,         // optional, default 3
  "threshold": 0.5   // optional, default 0.5
}

Response shape:

{
  "query": "how does auth work?",
  "recommendations": [
    {
      "server": "gitnexus",
      "tool": "query",
      "score": 0.84,
      "reason": "GitNexus tool answers 'how does X work' — code structure + call chains"
    }
  ],
  "meta": {
    "indexed_tools": 23,
    "considered": 23,
    "above_threshold": 1,
    "threshold": 0.5,
    "embedding_ms": 42,
    "scoring_ms": 3
  }
}

Architecture

┌──────────────────────────────────────────────────────────────┐
│ Claude Code (or any MCP client)                               │
│   1. calls mozart_recommend("…")                              │
│   2. receives ranked tool list                                │
│   3. invokes top tool(s) itself with proper params            │
└────────────────────────┬─────────────────────────────────────┘
                         │
            ┌────────────▼────────────┐
            │   mcp-mozart (stdio)    │
            │   • embed(query)        │
            │   • cosine top-k        │
            │   • threshold ≥ 0.5     │
            │   • attach reasons      │
            └─────────────────────────┘
                         ▲
                         │ load capability index
            ┌────────────┴────────────┐
            │  ~/.mozart/index.json   │
            └─────────────────────────┘
                         ▲
            ┌────────────┴────────────┐
            │  Discovery on init      │
            │  + chokidar watcher     │
            └─────────────────────────┘

Development

npm test                   # run vitest
npm run test:coverage      # with coverage gate (lines/branches/funcs ≥ 70%)
npm run typecheck          # tsc --noEmit
npm run build              # tsc → dist/

Test approach:

• Unit tests use a deterministic stub embedder (sha256-derived) — no model load.
• One integration test (tests/integration/stdio-server.test.ts) exercises the full path through the MCP SDK with InMemoryTransport.
• Discovery is tested against in-process fake MCP servers; no real subprocess spawning.

License

MIT — see LICENSE.