ModelRouter

Advisory MCP server for intelligent LLM model recommendations in Cursor.

v1 Capability Statement

Ships:

• Advisory recommend_model with schema-validated JSON
• Heuristic task analysis (Layer A) + metadata scoring (Layer B)
• Static seed registry with user-writable cache (~/.modelrouter)
• Live metadata sync by default (Class D inbound fetch when privacyMode: false)
• Guidance snippets for Cursor — user manually picks model

Does NOT ship:

• Force Composer/Auto model selection
• Continuous validation against engineering tasks (Phase 8 opt-in only)
• Cursor.models.list() or any IDE runtime model API

Quick Start

npm install
npm run build
MODELROUTER_USE_FIXTURES=1 npm test
npm run validate-schemas
npm run smoke

Cursor MCP Configuration

npm (after publish):

{
  "mcpServers": {
    "modelrouter": {
      "command": "npx",
      "args": ["-y", "modelrouter-mcp"]
    }
  }
}

Local development:

{
  "mcpServers": {
    "modelrouter": {
      "command": "node",
      "args": ["/absolute/path/to/ModelRouter_MCP/dist/index.js"]
    }
  }
}

Tools (10)

Benchmark ingest is internal-only (via SweBenchAdapter), not exposed as an MCP tool.

Configuration

See schemas/modelrouter-config.schema.json.

Environment variables (not in JSON schema):

• MODELROUTER_DATA_DIR — override user cache directory (default ~/.modelrouter)
• MODELROUTER_USE_FIXTURES=1 — fixtures only, no live HTTP (CI/dev offline)

Privacy

See PRIVACY.md. User plan and repository data are never sent outbound. Optional public model metadata fetch (Class D) occurs when privacyMode: false.

Data directories

Single-instance assumption: concurrent writes are not supported.

Troubleshooting

• Build errors: Run npm run build before starting MCP
• Stale metadata: Call sync_metadata or wait for background TTL sync (24h)
• Offline dev: Set MODELROUTER_USE_FIXTURES=1
• Privacy: Set privacyMode: true in config to block all outbound HTTP

Maintainer Scripts

# Optional — requires CURSOR_API_KEY
npm run verify-cursor-ids

# CI denylist check
npm run lint:cursor-denylist

# Record live sync fixtures (network required)
npx tsx scripts/record-sync-fixtures.ts

Implementation status

See CONTRIBUTING.md for maintainer workflows.

License

MIT — see LICENSE