Compass MCP (compass-mcp)

Purpose

Pick the model that fits the task — not always the cheapest, not locked to one vendor.

Read the task sentence (intent · scope · difficulty) — not keyword spam.

Lightest is per host — not always Haiku:

Haiku = Claude light example. Cursor light = Composer. GPT light = Mini/Nano.

Scoring uses logical role Composer 2.5 for the lightest tier; primary_id is host-mapped via list_hosts.

Philosophy: best fit for the job → if unavailable on your host, use the next id in candidates / fallback_chain.

Saving means avoiding overspend (Codex on a one-liner), not under-spending on design.

Local MCP recommends a catalog model. It does not auto-switch the chat UI dropdown.

SSOT for scoring: this MCP. Cursor rules only call tools — they must not paste full MCP dumps into chat (2-line summary).

Related MCP server: MCP Router

Install

Easiest: one command

Clone once, then register MCP for your host — no manual mcp.json paste:

git clone https://github.com/JakeLim17/compass-mcp.git
cd compass-mcp
npm run connect -- cursor    # Cursor
npm run connect -- claude    # Claude Code (or Claude Desktop fallback)
npm run connect -- codex     # OpenAI Codex CLI

Each command runs npm install + build, sets COMPASS_MCP_HOST automatically, and writes the server entry (node …/dist/server.js). Existing config is backed up before merge.

Then: restart or refresh MCP in that app (Cursor: Cmd/Ctrl+Shift+J → Tools & MCP → toggle OFF/ON).

Aliases: npm run install:cursor · install:claude · install:codex

Not on npm — clone from GitHub only.

Update later: npm run sync (pull + build + smoke + refresh reminder).

Manual setup (fallback)

git clone https://github.com/JakeLim17/compass-mcp.git
cd compass-mcp
npm run setup

Paste into ~/.cursor/mcp.json, then refresh MCP (how_to_refresh_mcp).

Prefer npm run connect -- cursor — avoids copy/paste errors.

Remote HTTP MCP (Claude.ai / ChatGPT / web)

Same tools as stdio — exposed over MCP Streamable HTTP (GET/POST/DELETE on /mcp).

1. Start locally

cp .env.example .env   # optional
export COMPASS_MCP_API_KEY="$(openssl rand -hex 32)"   # required before tunneling
npm run start:http
# → http://127.0.0.1:3920/mcp
# → http://127.0.0.1:3920/health

Production / VPS: set NODE_ENV=production and COMPASS_MCP_API_KEY (server exits without it).

2. HTTPS tunnel (for Claude.ai / ChatGPT connectors)

Connectors require a public HTTPS URL. Use a tunnel to your local port:

# cloudflared (example)
cloudflared tunnel --url http://127.0.0.1:3920

# ngrok (example)
ngrok http 3920

Your MCP URL becomes: https://<tunnel-host>/mcp
Auth header: Authorization: Bearer <COMPASS_MCP_API_KEY>

3. Connect clients

Env reference

Without COMPASS_MCP_API_KEY, only localhost requests are accepted (console warning).

OAuth full spec is not included in v0.9.1 — API key + HTTPS URL is the supported path.

Agents: recommend → execute (critical)

1. Call recommend_model or start_session with task_description

2. Read run_hint.ko: 다음 Task model=<primary_id> …

3. Read must_do.ko checklist (4 lines)

4. Launch Task/subagent with model: primary_id

5. If host says unavailable → candidates[1].id, then next in fallback_chain

6. log_model_usage → set_sticky

7. Tell the user via model_persistence — never say “sticky”

8. Optional: verify_run_compliance after deploy/update

The agent calling this MCP (e.g. Composer) may differ from the task recommendation (primary_id). That is intentional.

Verbal override: 페이블로 / 코덱스로 / use fable in task_description → that model wins over scoring; if blocked → next candidate + 말 지정 but unavailable in reason.

Cursor catalog (Task-enabled)

We only recommend slugs Cursor can run as Task model. Gray UI models → blocked_models.

How to add a model

1. Add slug to CURSOR_AGENT_CATALOG and CURSOR_TASK_SLUG in src/recommend.ts

2. Add ModelId, BASE, COST_TIER, MODEL_TIER, keyword/tag boosts as needed

3. Mirror slug in CURSOR_IDS in src/hosts.ts (cursor profile)

4. Add smoke case + example prompt if user-facing

5. Bump version, npm test, refresh MCP

Fallback chain (candidates)

recommend_model returns compact JSON including:

{
  "primary_id": "composer-2.5-fast",
  "candidates": [ … ],
  "fallback_chain": ["composer-2.5-fast", "claude-sonnet-5-thinking-high", "…"],
  "run_hint": {
    "ko": "다음 Task model=… (불가 시 …) → log_model_usage → set_sticky"
  }
}

On host=claude, copy/i18n tasks still score logical Composer 2.5 but primary_id maps to Haiku.

Tools (complete)

Pass verbose: true only when debugging.

Project config (.compass-mcp.json)

Walk up from cwd for .compass-mcp.json. Copy from .compass-mcp.json.example.

Example blocked list matches Cursor gray models: GPT-5.5, Sonnet 4.6, Opus 4.7, …

Verify: get_project_config then recommend with cwd set to project root.

Behavior cheatsheet

Scripts

npm run connect -- cursor   # one-command MCP register (recommended)
npm run connect -- claude
npm run connect -- codex
npm run setup               # install + print manual snippets
npm run sync                # git pull + build + smoke + refresh reminder
npm start                   # stdio (Cursor local)
npm run start:http          # Streamable HTTP (remote connectors)
npm test                    # smoke + smoke:http + connect merge tests
npm run smoke:connect       # connect merge helpers only
npm run typecheck
npm run build

Practical 10/10 checklist

Verified by npm test (smoke) + verify_run_compliance:

• npm run setup prints version

• MCP tools include start_session, check_update, verify_run_compliance, recommend_model, get_project_config

• recommend_model returns run_hint.ko + must_do.ko with primary_id

• Every compact recommend includes mcp_version

• candidates.length >= 2 and catalog slugs only (cursor host)

• Agent compliance: Task model=must_do.task_model (not just MCP caller)

• log_model_usage + set_sticky after adoption

• User never sees the word “sticky” — model_persistence instead

• .compass-mcp.json enabled_models / blocked_models affect scoring

• list_hosts exposes per-host lightest + Cursor enabled/blocked/chat-only

• get_usage_summary alerts when high-tier overused

• feedback_recommendation nudges next recommend (±3, recency ×1.5)

• Stale tools → check_update / how_to_refresh_mcp / npm run sync

• npm test all green

Self-score (v0.9.1): usefulness 10 / 10 · completeness 10 / 10 for agents that follow must_do.

Limits

• Chat UI dropdown does not auto-switch — intentional ceiling; agents must pass primary_id to Task/subagent

• primary / for_task ≠ the model running the MCP call

• Haiku/Gemini chat models are not Cursor Task slugs unless Cursor adds them — use host mapping

• Cost/token_risk are relative, not dollars

• Claude/OpenAI host ids are approximate (src/hosts.ts)

License

MIT

한국어: 명령을 정독해 작업에 맞는 모델을 고르는 로컬 MCP. lightest는 호스트마다 다름(Cursor=Composer, Claude=Haiku 예시, GPT=Mini). 추천 후 run_hint.ko대로 Task model=primary_id. compact 응답. 에이전트는 MCP 덤프·「sticky」단어 금지.