jev-router-mcp

An MCP server that lets an agent decide which tool should answer a question using a Jev System-1 decision engine instead of guessing. It speaks the Jev /v1/systemone wire protocol, so it works with any Jev-compatible server — Laya is the reference implementation.

Give it a question, it returns the best tool pick with a confidence score, and the agent calls that tool.

What it does

• route_code(question) — preset that picks between codegraph (exact symbols, signatures, call paths, blast radius, source), graft (repo overview, module wiring, related files), both, or neither (not a code-structure question).
• route_query(question, options) — generic: you pass the tool ids and when-to-use descriptions, the decision engine picks the winner.

Both return { choice, confidence, probabilities, advice } so the agent knows what to call — and when the server is unreachable it says so and tells the agent to fall back to its own judgment.

$ jev-router-mcp
→ { "choice": "graft", "confidence": 0.39,
    "probabilities": { codegraph: 0.29, graft: 0.39, both: 0.23, neither: 0.09 },
    "advice": "Call the \"graft\" tool." }

Requirements

• Node.js >= 20 (global fetch)
• A running Jev-compatible server exposing POST /v1/systemone (e.g. Laya — see its self-host docs)
• The tools you route to (e.g. graft, codegraph) configured as MCP servers in your client, so the agent can act on the verdict

Install

# run directly
npx -y @humayunkabir/jev-router-mcp

# install globally
npm install -g @humayunkabir/jev-router-mcp

Quick setup (interactive)

npx -y @humayunkabir/jev-router-mcp init
# answers two prompts (server URL, API key), offers to write your config,
# then wires the code-routing instruction below into an existing AGENTS.md
# (or prints exactly what to add where none exists)

Answers two prompts (server URL, API key), then asks "Write to ~/.config/opencode/opencode.jsonc?" — answering y merges the server into your opencode config automatically (it respects an existing mcp.servers shape; refuses and prints a snippet if your config is JSONC-with-comments it can't safely parse). Use init --write to skip the confirmation. Either way it then wires the code-routing instruction below into an existing AGENTS.md, or prints exactly what to add and where. Restart opencode afterwards.

OpenCode (manual)

Add to your opencode.json / opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jev-router": {
      "type": "local",
      "command": ["npx", "-y", "@humayunkabir/jev-router-mcp"],
      "environment": {
        "JEV_URL": "http://localhost:8000",
        "JEV_API_KEY": "your-bearer-token"
      },
      "enabled": true
    }
  }
}

Any MCP client works the same way (Claude Desktop, Cursor, ...): configure a stdio server with the npx command and the env vars below.

Local checkout

git clone https://github.com/humayunkabir/jev-router-mcp
cd jev-router-mcp
npm install
node src/index.js        # speaks MCP over stdio; for config use:
# "command": ["node", "/path/to/jev-router-mcp/src/index.js"]

Configuration

| env var | default | description | | --- | --- | --- | | JEV_URL | http://localhost:8000 | Base URL of the decision server (trailing /v1/systemone is normalized). | | JEV_API_KEY | (none) | Bearer token for POST /v1/systemone. Omit for servers without auth. | | JEV_ROUTER_INSTRUCTIONS | built-in | Instructions for the route_query choice question. |

LAYA_URL / LAYA_API_KEY are accepted as aliases for JEV_URL / JEV_API_KEY, so existing Laya deployments keep working unchanged.

Using it

Tell the agent to consult the router before answering code-intelligence questions, e.g. in your AGENTS.md (jev-router-mcp init adds this for you when an AGENTS.md exists):

## Code routing

When a question needs code structure or repo context, call `route_code`
first, then the MCP tool it picks (or both when the verdict says `both`).

Example session:

1. “Why is MAX_BODY_BYTES enforced in two places in serve.py?” → route_code → codegraph (symbols & call paths) → agent calls codegraph_explore.
2. “How do the onboarding modules fit together?” → route_code → graft → agent calls graft_trace_calls / graft_repo_map.
3. “Explain how JWT refresh tokens work” → route_code → neither → agent answers from reasoning, no code tool needed.

Development

npm test

Unit tests cover URL normalization, body building, verdict parsing, advice, env aliasing, opencode config merge/write, init's interactive and AGENTS.md-wiring behavior. Set TEST_JEV_URL (and optionally TEST_JEV_API_KEY) to also run a live routing test against your server.

License

MIT