@iflow-mcp/openrouter-deep-research-mcp

v1.8.1

Published

2 months ago

OpenRouter MCP server for research agents

0High
0Medium
0Low

chatflowdev

qystart

mcp model context protocol openrouter agents research pglite pgvector

OpenRouter Agents MCP Server

Overview

Production-ready MCP server for multi-agent AI research with OpenRouter integration. Fully compliant with MCP Specification 2025-06-18 and prepared for November 2025 spec updates.

Key Features

Multi-Agent Orchestration: Plan → parallelize → synthesize workflow with adaptive concurrency
Async Operations: Job system with SSE streaming for long-running research tasks
Knowledge Base: Hybrid BM25+vector search with PGlite + pgvector
Model Support: Dynamic catalog supporting Anthropic Sonnet-4, OpenAI GPT-5, Google Gemini, and more
Production Hardened: Rate limiting, request size limits, multi-tier auth (JWT/API key)
MCP Compliant: 100% spec compliance with server discovery and extension metadata
Three Modes: AGENT (simple), MANUAL (granular), or ALL (both)

Install / Run

Install (project dependency)

npm install @terminals-tech/openrouter-agents

Global install (optional)

npm install -g @terminals-tech/openrouter-agents

Run with npx (no install)

npx @terminals-tech/openrouter-agents --stdio
# or daemon
SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

What's New (v1.8.0 - December 5, 2025)

MCP Apps (SEP-1865): UI resources for autonomous interface surfacing (ui://research/viewer, ui://knowledge/graph)
Knowledge Graph: New tools for graph exploration - graph_traverse, graph_path, graph_clusters, graph_pagerank
Session Time-Travel: Undo/redo, fork sessions, checkpoints, and time navigation via @terminals-tech/core
Error Visibility: Structured error handling with cause chains, pre-flight validation, and detailed diagnostics
Package Ecosystem: Integrated @terminals-tech/embeddings, @terminals-tech/graph, @terminals-tech/core

Changelog → | Compliance Report →

Quick start

Prereqs

Node 18+ (20 LTS recommended), npm, Git, OpenRouter API key

Install

npm install

Verify installation (optional but recommended)

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

Configuration: .env vs .mcp.json

Choose your configuration method based on your use case:

Are you working alone or with a team?
│
├─ ALONE (local development)
│   │
│   └─► Use .env file
│       • Keeps secrets out of version control
│       • Personal API keys stay private
│       • Add .env to .gitignore
│
└─ TEAM (shared project)
    │
    └─► Use .mcp.json file
        • Commit to version control
        • Use ${VAR} syntax for secrets
        • Team shares same configuration
        • Each member sets own env vars

Quick Decision:

.env → Solo developer, local machine, prototype
.mcp.json → Team project, CI/CD, shareable config

Configure (.env)

OPENROUTER_API_KEY=your_openrouter_key
SERVER_API_KEY=your_http_transport_key
SERVER_PORT=3002

# Modes (pick one; default ALL)
# AGENT  = agent-only + always-on ops (ping/status/jobs)
# MANUAL = individual tools + always-on ops
# ALL    = agent + individual tools + always-on ops
MODE=ALL

# Orchestration
ENSEMBLE_SIZE=2
PARALLELISM=4

# Models (override as needed) - Updated with state-of-the-art cost-effective models
PLANNING_MODEL=openai/gpt-5-chat
PLANNING_CANDIDATES=openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4
HIGH_COST_MODELS=x-ai/grok-4,openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4,morph/morph-v3-large
LOW_COST_MODELS=deepseek/deepseek-chat-v3.1,z-ai/glm-4.5v,qwen/qwen3-coder,openai/gpt-5-mini,google/gemini-2.5-flash
VERY_LOW_COST_MODELS=openai/gpt-5-nano,deepseek/deepseek-chat-v3.1

# Storage
PGLITE_DATA_DIR=./researchAgentDB
PGLITE_RELAXED_DURABILITY=true
REPORT_OUTPUT_PATH=./research_outputs/

# Indexer
INDEXER_ENABLED=true
INDEXER_AUTO_INDEX_REPORTS=true
INDEXER_AUTO_INDEX_FETCHED=true

# MCP features
MCP_ENABLE_PROMPTS=true
MCP_ENABLE_RESOURCES=true

# Prompt strategy
PROMPTS_COMPACT=true
PROMPTS_REQUIRE_URLS=true
PROMPTS_CONFIDENCE=true

STDIO (for Cursor/VS Code MCP):

node src/server/mcpServer.js --stdio

HTTP/SSE (local daemon):

SERVER_API_KEY=$SERVER_API_KEY node src/server/mcpServer.js

Windows PowerShell examples

STDIO

$env:OPENROUTER_API_KEY='your_key'
$env:INDEXER_ENABLED='true'
node src/server/mcpServer.js --stdio

HTTP/SSE

$env:OPENROUTER_API_KEY='your_key'
$env:SERVER_API_KEY='devkey'
$env:SERVER_PORT='3002'
node src/server/mcpServer.js

One-liner demo scripts

Dev (HTTP/SSE):

SERVER_API_KEY=devkey INDEXER_ENABLED=true node src/server/mcpServer.js

STDIO (Cursor/VS Code):

OPENROUTER_API_KEY=your_key INDEXER_ENABLED=true node src/server/mcpServer.js --stdio

MCP client JSON configuration (no manual start required)

You can register this server directly in MCP clients that support JSON server manifests.

Minimal examples:

STDIO transport (recommended for IDEs)

{
  "servers": {
    "openrouter-agents": {
      "command": "npx",
      "args": ["@terminals-tech/openrouter-agents", "--stdio"],
      "env": {
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "SERVER_API_KEY": "${SERVER_API_KEY}",
        "PGLITE_DATA_DIR": "./researchAgentDB",
        "INDEXER_ENABLED": "true"
      }
    }
  }
}

HTTP/SSE transport (daemon mode)

{
  "servers": {
    "openrouter-agents": {
      "url": "http://127.0.0.1:3002",
      "sse": "/sse",
      "messages": "/messages",
      "headers": {
        "Authorization": "Bearer ${SERVER_API_KEY}"
      }
    }
  }
}

With the package installed globally (or via npx), MCP clients can spawn the server automatically. See your client's docs for where to place this JSON (e.g., ~/.config/client/mcp.json).

Claude Code Integration

One-liner setup for Claude Code:

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

Or interactive setup with slash commands and hooks:

npx @terminals-tech/openrouter-agents --setup-claude

Included Slash Commands

| Command | Description | |---------|-------------| | /mcp-status | Check server health and recent activity | | /mcp-research | Run synchronous research query | | /mcp-async-research | Run async research (returns job_id) | | /mcp-search | Search the knowledge base | | /mcp-query | Execute SQL query |

Environment Setup

Set your API key before using:

export OPENROUTER_API_KEY="sk-or-..."

Portable Project Configuration

The setup creates a .mcp.json file for team-shareable configuration:

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

Verification

After setup, verify the connection:

/mcp-status

Or use the tools directly:

ping {}                    // → {"pong":true}
get_server_status {}       // → Full health check
list_tools {}              // → Available tools

See .claude/README.md for detailed configuration options.

Tools (high‑value)

Always‑on (all modes): ping, get_server_status, job_status, get_job_status, cancel_job
AGENT: agent (single entrypoint for research / follow_up / retrieve / query)
MANUAL/ALL toolset: submit_research (async), conduct_research (sync/stream), research_follow_up, search (hybrid), retrieve (index/sql), query (SELECT), get_report_content, list_research_history
Jobs: get_job_status, cancel_job
Retrieval: search (hybrid BM25+vector with optional LLM rerank), retrieve (index/sql wrapper)
SQL: query (SELECT‑only, optional explain)
Knowledge base: get_past_research, list_research_history, get_report_content
DB ops: backup_db (tar.gz), export_reports, import_reports, db_health, reindex_vectors
Models: list_models
Web: search_web, fetch_url
Indexer: index_texts, index_url, search_index, index_status

Tool usage patterns (for LLMs)

Use tool_patterns resource to view JSON recipes describing effective chaining, e.g.:

Search → Fetch → Research
Async research: submit, stream via SSE /jobs/:id/events, then get report content

Notes

Data lives locally under PGLITE_DATA_DIR (default ./researchAgentDB). Backups are tarballs in ./backups.
Use list_models to discover current provider capabilities and ids.

Architecture at a glance

See docs/diagram-architecture.mmd (Mermaid). Render to SVG with Mermaid CLI if installed:

npx @mermaid-js/mermaid-cli -i docs/diagram-architecture.mmd -o docs/diagram-architecture.svg

Or use the script:

npm run gen:diagram

Architecture Diagram (branded)

If the image doesn’t render in your viewer, open docs/diagram-architecture-branded.svg directly.

Answer crystallization view

Answer Crystallization Diagram

How it differs from typical “agent chains”:

Not just hardcoded handoffs; the plan is computed, then parallel agents search, then a synthesis step reasons over consensus, contradictions, and gaps.
The system indexes what it reads during research, so subsequent queries get faster/smarter.
Guardrails shape attention: explicit URL citations, [Unverified] labelling, and confidence scoring.

Minimal‑token prompt strategy

Compact mode strips preambles to essential constraints; everything else is inferred.
Enforced rules: explicit URL citations, no guessing IDs/URLs, confidence labels.
Short tool specs: use concise param names and rely on server defaults.

Common user journeys

“Give me an executive briefing on MCP status as of July 2025.”
- Server plans sub‑queries, fetches authoritative sources, synthesizes with citations.
- Indexed outputs make related follow‑ups faster.
“Find vision‑capable models and route images gracefully.”
- /models discovered and filtered, router template generated, fallback to text models.
“Compare orchestration patterns for bounded parallelism.”
- Pulls OTel/Airflow/Temporal docs, produces a MECE synthesis and code pointers.

Cursor IDE usage

Add this server in Cursor MCP settings pointing to node src/server/mcpServer.js --stdio.
Use the new prompts (planning_prompt, synthesis_prompt) directly in Cursor to scaffold tasks.

FAQ (quick glance)

How does it avoid hallucinations?
- Strict citation rules, [Unverified] labels, retrieval of past work, on‑the‑fly indexing.
Can I disable features?
- Yes, via env flags listed above.
Does it support streaming?
- Yes, SSE for HTTP; stdio for MCP.

Command Map (quick reference)

Start (stdio): npm run stdio
Start (HTTP/SSE): npm start
Run via npx (scoped): npx @terminals-tech/openrouter-agents --stdio
Generate examples: npm run gen:examples
List models: MCP list_models { refresh:false }
Submit research (async): submit_research { q:"<query>", cost:"low", aud:"intermediate", fmt:"report", src:true }
Track job: get_job_status { job_id:"..." }, cancel: cancel_job { job_id:"..." }
Unified search: search { q:"<query>", k:10, scope:"both" }
SQL (read‑only): query { sql:"SELECT ... WHERE id = $1", params:[1], explain:true }
Get past research: get_past_research { query:"<query>", limit:5 }
Index URL (if enabled): index_url { url:"https://..." }
Micro UI (ghost): visit http://localhost:3002/ui to stream job events (SSE).

Package publishing

Name: @terminals-tech/openrouter-agents
Version: 1.8.0
Bin: openrouter-agents
Author: Tej Desai [email protected]
Homepage: https://terminals.tech

Install and run without cloning:

npx @terminals-tech/openrouter-agents --stdio
# or daemon
SERVER_API_KEY=your_key npx @terminals-tech/openrouter-agents

Publish (scoped)

npm login
npm version patch -m "chore(release): %s"
git push --follow-tags
npm publish --access public --provenance

Validation – MSeeP (Multi‑Source Evidence & Evaluation Protocol)

Citations enforced: explicit URLs, confidence tags; unknowns marked [Unverified].
Cross‑model triangulation: plan fans out to multiple models; synthesis scores consensus vs contradictions.
KB grounding: local hybrid index (BM25+vector) retrieves past work for cross‑checking.
Human feedback: rate_research_report { rating, comment } stored to DB; drives follow‑ups.
Reproducibility: export_reports + backup_db capture artifacts for audit.

Quality feedback loop

Run examples: npm run gen:examples
Review: list_research_history, get_report_content {reportId}
Rate: rate_research_report { reportId, rating:1..5, comment }
Improve retrieval: reindex_vectors, index_status, search_index { query }

Architecture diagram (branded)

See docs/diagram-architecture-branded.svg (logo links to https://terminals.tech).