jev-mcp-router

Selects the MCP tools that fit the query, inside a context budget.

Author: Pinuts. MIT license.

Part of JEV Labs.

Stack: Python 3.10+, HTTP, MCP stdio, Docker, HTML demo.

After jev-mcp serve: demo

Local, no keys

git clone https://github.com/Pinutss/jev-mcp-router
cd jev-mcp-router
uv sync
uv run jev-mcp demo
uv run jev-mcp serve

No agent and no LLM are required. JEV_PROVIDER=auto (the default) stays on the local heuristic. If JEV and a gateway are configured, they are used as the judge. Docker:

docker compose up

What the prototype does

The selector chooses tools from a catalog, under a token budget. It explains the choice, abstains if no candidate is safe, and allows only one fallback hop.

It does not run tools and does not ship them.

Selection is not authorization. Permissions come only from the catalog and the caller constraints. The task, a tool, or a model cannot add them.

Cursor and Hermes plugin

This repository is an Agent Plugin. Cursor and Hermes can install it directly.

Hermes

hermes plugins install Pinutss/jev-mcp-router --enable

Cursor

Install from the JEV plugins marketplace, or copy this folder to ~/.cursor/plugins/local/jev-mcp-router.

One tool: mcp_select. Pass query + tools. Keys stay in the process environment, not in the call.

Requires uv. JEV_PROVIDER defaults to local.

Hermes and OpenClaw

Yes, locally. The MCP process does not need JEV or a gateway:

uv run jev-mcp mcp

One tool: mcp_select. Pass query + tools. Keys stay in the process environment, not in the call.

Hermes (~/.hermes/config.yaml):

mcp_servers:
  jev-mcp:
    command: uv
    args: ["run", "--directory", "/path/to/jev-mcp-router", "jev-mcp", "mcp"]
    env:
      JEV_PROVIDER: local

OpenClaw (~/.openclaw/openclaw.json, or Settings > MCP > Stdio):

{
  "mcp": {
    "servers": {
      "jev-mcp": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/jev-mcp-router", "jev-mcp", "mcp"],
        "env": { "JEV_PROVIDER": "local" }
      }
    }
  }
}

Python

from jev_mcp_router import McpSelector, DEFAULT_TOOLS

result = McpSelector(provider="local").select(
    query="Read a local file, then search GitHub issues",
    tools=DEFAULT_TOOLS,
    max_tools=2,
    budget_tokens=250,
    scope="demo",
)
print(result.decision, [item.id for item in result.selected])

JEV + gateway (optional)

If you wire the cloud later, two keys are enough: JEV_API_KEY / JEV_BASE_URL, and your gateway. If GATEWAY_* is incomplete, the multi-LLM catalog resolves the judge. Vendor keys stay in the environment and each is sent only to its own vendor (OPENROUTER_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, and the other catalog presets). A custom judge endpoint is discovered by scanning env for JEV_LLM_<NAME>_BASE_URL (plus JEV_LLM_<NAME>_API_KEY / JEV_LLM_<NAME>_MODELS); that key is used only against that base URL.

No key in the HTTP or MCP body.

cp .env.example .env

JEV_PROVIDER=jev will not start if JEV or the resolved gateway is missing. With auto, missing keys just keep the local heuristic.

Public catalog: GET /v1/llms. You can also point JEV_MODELS_FILE at a JSON catalog.

HTTP

uv run jev-mcp serve

GET /, /demo, /healthz, /v1/llms. POST /v1/select. Binds 127.0.0.1. The body must not contain keys. It may contain gateway_provider, gateway_model, llm_prefer.

Local validation

uv run jev-mcp benchmark

Annotated set in benchmarks/annotated_tasks.json. This is a local baseline, not a live JEV trial.

Limits

Local ranking is lexical and deterministic. Scope isolates lists, it is not auth. One fallback hop. No tool execution. No store, no PyPI yet.

docs/vision.md is a long-term target, not the current contract.