ModelRouter MCP

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 — stub only in v0.1)

• Cursor.models.list() or any IDE runtime model API

• Product HTTP/REST API (stdio MCP only)

Related MCP server: code-review-mcp

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"]
    }
  }
}

Efficient usage

1. Write a plan file (or pass planText inline)

2. Call recommend_model with planPath or planText (+ optional repoPath)

3. Manually select the recommended model in the Cursor picker

4. Call sync_metadata when pricing/models look stale (or wait for 24h background sync)

Tools (10)

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

Sync source matrix

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)

• MODELROUTER_PRIVACY_MODE=1 — startup privacy (blocks outbound sync)

Optional file: ~/.modelrouter/config.json (same schema). Precedence: env → file → defaults.

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 MODELROUTER_PRIVACY_MODE=1 or privacyMode: true to block 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

Cursor model IDs in the seed registry are documented, not runtime-verified. Calibration is provisional.

See CONTRIBUTING.md for maintainer workflows.

License

MIT — see LICENSE