内容
# OpenRouter Agents MCP Server
[](https://www.npmjs.com/package/@terminals-tech/openrouter-agents)
[](https://spec.modelcontextprotocol.io/specification/2025-11-25/)
[](https://github.com/terminals-tech/openrouter-agents)
Production MCP server for multi-agent AI research. Plan, parallelize, synthesize.
## Install
```bash
npx @terminals-tech/openrouter-agents --stdio
```
**Claude Code one-liner:**
```bash
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](docs/CHANGELOG.md) | [Extensions Guide](docs/EXTENSIONS.md) | [MCP Compliance Report](docs/MCP-COMPLIANCE-REPORT.md)
## 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](docs/ENV-REFERENCE.md)
<details>
<summary><strong>.mcp.json example (team-shareable)</strong></summary>
```json
{
"mcpServers": {
"openrouter-agents": {
"command": "npx",
"args": ["@terminals-tech/openrouter-agents", "--stdio"],
"env": {
"OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
"INDEXER_ENABLED": "true"
}
}
}
}
```
</details>
## 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](https://spec.modelcontextprotocol.io/specification/2025-11-25/basic/transports). Use `--http` explicitly for HTTP mode.
### Client-Specific Setup
<details>
<summary><strong>Jan AI</strong></summary>
1. Enable MCP Servers in Settings → Advanced → Experimental
2. Click + to add server
3. Configure:
- **Name:** `openrouter-agents`
- **Command:** `npx`
- **Arguments:** `@terminals-tech/openrouter-agents`
- **Environment:** `OPENROUTER_API_KEY=sk-or-...`
Note: STDIO is now default - no `--stdio` flag needed.
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"openrouter-agents": {
"command": "npx",
"args": ["@terminals-tech/openrouter-agents"],
"env": {
"OPENROUTER_API_KEY": "sk-or-..."
}
}
}
}
```
</details>
<details>
<summary><strong>Continue / Zed / Other MCP Clients</strong></summary>
Standard MCP config - STDIO is default, no flags needed:
```json
{
"command": "npx",
"args": ["@terminals-tech/openrouter-agents"],
"env": { "OPENROUTER_API_KEY": "..." }
}
```
</details>
### 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
<details>
<summary><strong>Research</strong></summary>
| Tool | Description |
|------|-------------|
| `research` | Async research (returns job_id) |
| `conduct_research` | Sync research with streaming |
| `batch_research` | Parallel batch queries |
| `research_follow_up` | Context-aware follow-up |
| `agent` | Unified entrypoint (auto-routes) |
</details>
<details>
<summary><strong>Knowledge Base</strong></summary>
| Tool | Description |
|------|-------------|
| `search` | Hybrid BM25+vector search |
| `retrieve` | Index or SQL query |
| `query` | SQL SELECT with params |
| `get_report` | Get report by ID |
| `history` | List recent reports |
</details>
<details>
<summary><strong>Session & Graph</strong></summary>
| Tool | Description |
|------|-------------|
| `undo` / `redo` | Session time-travel |
| `checkpoint` | Named save points |
| `fork_session` | Create alternate timeline |
| `graph_traverse` | Explore knowledge graph |
| `graph_clusters` | Find node clusters |
| `graph_pagerank` | Importance rankings |
</details>
<details>
<summary><strong>Rail Protocol</strong></summary>
| Tool | Description |
|------|-------------|
| `list_rails` | List rails, tunnels, routes, consensus |
| `explain_rail` | Detailed rail/tunnel config |
| `list_routes` | All defined routes |
| `list_tunnels` | Active agent-to-agent tunnels |
| `list_consensus` | Streaming consensus sessions |
</details>
<details>
<summary><strong>Utility</strong></summary>
| Tool | Description |
|------|-------------|
| `ping` | Health check |
| `get_server_status` | Full diagnostics |
| `job_status` | Check async job |
| `date_time` | Current timestamp |
| `calc` | Math evaluation |
| `list_tools` | Available tools |
</details>
## MCP Compliance
Compliant with [MCP Specification 2025-11-25](https://spec.modelcontextprotocol.io/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](docs/MCP-COMPLIANCE-REPORT.md)
## 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) |
## Links
- **Homepage:** [terminals.tech](https://terminals.tech)
- **npm:** [@terminals-tech/openrouter-agents](https://www.npmjs.com/package/@terminals-tech/openrouter-agents)
- **GitHub:** [terminals-tech/openrouter-agents](https://github.com/terminals-tech/openrouter-agents)
- **Docs:** [CLAUDE.md](CLAUDE.md) | [Tool Patterns](docs/TOOL-PATTERNS.md) | [Getting Started](docs/GETTING-STARTED.md)
## Releasing
Releases are automated via [release-please](https://github.com/googleapis/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:
```bash
npm test && npm publish --access public
```
---
**Version:** 2.0.0 | **MCP SDK:** 1.27.1 | **MCP Spec:** 2025-11-25 | **Author:** [Tej Desai](https://terminals.tech) | **License:** MIT
连接信息
猜你喜欢
暂无推荐服务器