MMCPMarkets
WO

wheattoast11/openrouter-deep-research-mcp

开发工具
55 stars 0 forks 质量 55 趋势 55
Repository Install

Production MCP server for multi-agent AI research. Plan, parallelize, synthesize.

概览

Production MCP server for multi-agent AI research. Plan, parallelize, synthesize.

README

OpenRouter Agents MCP Server

Production MCP server for multi-agent AI research. Plan, parallelize, synthesize.

Install

npx @terminals-tech/openrouter-agents --stdio

Claude Code one-liner:

claude mcp add openrouter-agents -- npx @terminals-tech/openrouter-agents --stdio

What’s New (v2.0.0)

  • MCP SDK 1.27.1 — registerTool/registerPrompt/registerResource APIs, security fixes
  • Zod 4 — Upgraded from Zod 3; z.record() syntax, config schema fixes
  • Express 5 — Upgraded from Express 4; modern path patterns, req.query handling
  • Streamable HTTP — Primary transport (SSE deprecated as legacy fallback)
  • Circuit breaker — Model API fault tolerance with configurable thresholds
  • Embedding-based model routing — Local vector similarity for model selection (no LLM call)
  • Persistent storage — Reports, jobs, knowledge graph persist across sessions by default

macOS/Node 25 Note: A cosmetic libc++abi: mutex lock failed message may appear on shutdown. This is harmless — data is checkpointed before shutdown. Set DB_AUTO_HEAL=true for in-memory mode (no persistence, no message).

Full Changelog | Extensions Guide | MCP Compliance Report

Configuration

Set OPENROUTER_API_KEY in your environment, then configure via .env or .mcp.json:

Variable Default Description
OPENROUTER_API_KEY required OpenRouter API key
OPENROUTER_API_KEYS (optional) Comma-separated OpenRouter keys for rotation
OPENROUTER_KEY_COOLDOWN_MS 5000 Base cooldown per key after failures
SERVER_PORT 3002 HTTP server port
MODE ALL AGENT, MANUAL, or ALL
EMBEDDING_ROUTING_ENABLED true Enable embedding-based model routing
INDEXER_ENABLED true Enable knowledge indexing

Full ENV Reference

Multi-Client Setup

Transport Modes

Transport Flag Use Case
STDIO (default) MCP clients (Claude, Jan AI, Continue)
HTTP --http Web apps, shared server

STDIO is the default transport per MCP spec. Use --http explicitly for HTTP mode.

Client-Specific Setup

Feature Matrix

Feature All MCP Clients Claude Code Only
Core Research Tools ✓ ✓
Knowledge Base ✓ ✓
Session/Graph Tools ✓ ✓
Rail Protocol Tools ✓ ✓
Slash Commands - ✓

Models (v2.0.0)

High-Cost Tier

Model Domains
anthropic/claude-sonnet-4.5 reasoning, technical, general, creative
anthropic/claude-opus-4.6 reasoning, technical, general, creative
openai/gpt-5.2-chat reasoning, technical, general
openai/gpt-5.3-codex coding, technical, reasoning
google/gemini-3-pro-preview reasoning, technical, general
qwen/qwen3-coder coding, editing, technical

Low-Cost Tier

Model Domains
google/gemini-3-flash-preview coding, editing, technical
anthropic/claude-haiku-4.5 general, technical, reasoning
deepseek/deepseek-chat-v3.1 general, reasoning, technical, coding
deepseek/deepseek-v3.2 general, reasoning, technical, coding
openai/gpt-oss-120b general, reasoning, search

Models are selected via embedding-based routing — query embeddings are matched to model domain profiles without an LLM call.

Tools

MCP Compliance

Compliant with MCP Specification 2025-11-25 (stable, AAIF/Linux Foundation governance).

Feature SEP Status
JSON-RPC 2.0 Core Compliant
Tools/Resources/Prompts Core Compliant
Task Protocol SEP-1686 Compliant
Sampling with Tools SEP-1577 Compliant
Elicitation SEP-1036 Compliant
MCP Apps SEP-1865 Compliant
Enterprise Auth SEP-990 Compliant
Client Metadata SEP-991 Compliant

Full Compliance Report

Architecture

User Query
    │
    ▼
┌─────────────────┐
│  Planning Agent  │ ─── Decomposes into sub-queries
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Agent 1│ │Agent N│ ─── Parallel research (embedding-routed models)
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌─────────────────┐
│   Synthesizer   │ ─── Consensus + citations (Signal protocol)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Knowledge Base  │ ─── PGlite + pgvector (persistent)
└─────────────────┘

Core Abstractions

Module Purpose
Signal Protocol Inter-agent communication with confidence scoring and consensus
Rail Protocol Bidirectional channels with backpressure, provenance, tunnels
Error Taxonomy Deterministic classification with auto-learning and circuit breakers
Circuit Breaker Model API fault tolerance with configurable thresholds and auto-recovery
Parameter Normalization Declarative alias system (q→query, cost→costPreference)
RoleShift Protocol Bidirectional server↔client via MCP sampling/elicitation
Embedding Router Local vector-based model selection via @terminals-tech/embeddings

Circuit Breaker

Protects against cascading model API failures. Configurable via environment:

Variable Default Description
RAIL_CIRCUIT_BREAKER true Enable circuit breaker
RAIL_CIRCUIT_THRESHOLD 5 Failures before tripping
RAIL_CIRCUIT_RESET_MS 120000 Recovery timeout (ms)

States: closed (normal) -> open (failing, requests rejected) -> half-open (testing recovery).

Transport (v2.0.0)

Transport Status Use Case
Streamable HTTP Primary All new integrations
SSE Deprecated Legacy compatibility only
STDIO Default MCP clients (Claude, Jan AI, Continue)

Releasing

Releases are automated via release-please:

  1. Push conventional commits to main (e.g. feat:, fix:, chore:)
  2. release-please opens a version-bump PR
  3. Merge the PR → GitHub Release created automatically
  4. npm publish triggers on release via CI

Manual publish:

npm test && npm publish --access public

Version: 2.0.0 | MCP SDK: 1.27.1 | MCP Spec: 2025-11-25 | Author: Tej Desai | License: MIT

View this README on GitHub

安装

npx @terminals-tech/openrouter-agents --stdio

配置

{ "mcpServers": { "openrouter-agents": { "command": "npx", "args": ["@terminals-tech/openrouter-agents", "--stdio"], "env": { "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}", "INDEXER_ENABLED": "true" } } } }