research_mcp
Rust deep research engine with multi-agent debate — a Feynman-style deepresearch pipeline with an SQLite-backed queue, MCP server, and five source types.
Features
- 8-phase pipeline: planning → searching → fetching → drafting → citing → debating → reviewing → delivering
- 5 source types: web (TinyFish optional + DuckDuckGo → Bing → Brave, bot-gating detection + retry), arXiv (HTML abs page, immune to export API rate limits), PubMed (E-utilities), Scopus (Elsevier, metadata + CrossRef abstract fallback)
- Multi-agent debate: 5 agents with distinct beliefs critique the brief's content AND references, converge over rounds (spread/convergence measured), then answer targeted follow-up interviews on open questions
- SQLite state machine: every phase commits to
research.db— crash recovery, resume (--resume <id>), audit trail (research_phase_log) - Resilient worker: max 1 concurrent run, batch coherence, unlimited retry with backoff, auth errors (401/403) fail fast
- MCP server (
--mcp): 8 tools over stdio for OpenCode/Claude/etc. - Language-aware: Hungarian topics produce Hungarian reports and debates
- CLI: run research,
--list,--status <id>,--resume <id>
Pipeline
topic → planning → searching → fetching → drafting → citing
→ debating (5 agents, belief update, consensus) → reviewing → delivering
Install
Download (prebuilt binaries)
Grab the package for your platform from the latest release:
# Linux / macOS
tar xzf research_mcp-<ver>-<platform>.tar.gz
cd research_mcp-<ver>
cp config.example.toml config.toml # fill in your API keys
./research_mcp "your research topic"
No Rust toolchain needed — the binaries are self-contained (only system libc).
From source
cargo build --release
cp config.example.toml config.toml # fill in your API keys
Configuration (config.toml)
LLM backend & pro-class gate
llm_backend (config.toml) or --llm-backend (CLI) selects the LLM API:
opencode (default: OpenCode Go) or openrouter (OpenRouter, OpenAI-compatible
chat completions at https://openrouter.ai/api/v1). Each backend uses its own
key/model (openrouter_api_key + openrouter_model for OpenRouter); OpenRouter
model IDs are vendor/model (e.g. deepseek/deepseek-v4-flash).
A pro-class gate (mirroring Feynman) refuses premium "pro" models at
startup regardless of backend — e.g. gpt-5.6-pro, o1-pro — so the pipeline
never silently runs on a paid premium tier. Open-weight models that merely
contain "pro" in the name (deepseek-v4-pro and its routing aliases) are
explicitly allowed.
Adaptive coverage (LLM-driven)
The research planner is an LLM that sizes the search based on topic scale
(Feynman-style "Scale decision"). Two extra plan fields are emitted at planning
time and are not in config.toml:
download_budget is combined with the config max_sources via a double cap:
the actual download count is min(max_sources, download_budget), so you keep a
hard upper bound on cost/context while coverage expands for news-heavy topics.
Plans that omit either field fall back to defaults (6 / 8), keeping old
plans and saved sessions compatible.
Web search resilience: the keyless backend chain is DuckDuckGo → Bing → Brave, each with bot-gating detection (real challenge markers, checked after parsing so genuine results are never discarded) and the whole sweep retries before giving up. When all three are empty/gated, a "0 web results" warning is surfaced in the run log instead of silently producing an empty brief.
TinyFish backend (optional, recommended): set tinyfish_api_key in
config.toml (free key from https://agent.tinyfish.ai/api-keys — Search never
draws from the wallet) and web search gains a first-tier backend served by a
real browser: live, never-cached results as structured JSON, immune to the
bot-gating that intermittently blocks the keyless scrapers. Without the key
the tier is skipped silently and the keyless chain handles everything.
Usage
CLI
# Run a research (synchronous)
research_mcp "What are the tradeoffs of the ketogenic diet?"
# Query the queue
research_mcp --list
research_mcp --list --list-status complete
research_mcp --status <run_id>
# Resume an interrupted run (crash recovery)
research_mcp --resume <run_id>
# Re-run a job with the same topic and fresh session (test fixes)
research_mcp --rerun <run_id>
# Raise the hard cap on full-text downloads (news/current-events topics)
research_mcp --max-sources 20 "your topic"
# Run as MCP server (stdio)
research_mcp --mcp
MCP (OpenCode)
See docs/opencode.md for the full setup guide (config, troubleshooting, tool usage). Short version:
"research_mcp": {
"type": "local",
"command": ["/absolute/path/to/research_mcp", "--mcp"],
"enabled": true
}
A ready-made OpenCode skill ships in .opencode/skills/research-deepresearch/
— it teaches the agent the recommended submit → poll → read flow.
MCP tools
Output
Each run produces (in out_dir):
<slug>.md— the research brief with inline citations, Sources, and an Agent Debate Summary (positions, consensus, dissensus, interviews)<slug>.provenance.md— source tracking (date, accepted/rejected, plan paths).drafts/— intermediate artifacts (plan, research notes, draft, cited, verification)
License
MIT.
Inspired by:
- companion-inc/feynman (MIT) — deepresearch workflow pattern
- MiroShark/MiroShark (AGPL-3.0) — multi-agent belief state + debate pattern (reimplemented, LLM-based)
Disclaimer
Use at your own risk. The software is provided "as is", without warranty of any kind (see LICENSE.md). Generated research briefs are AI-assisted and may contain errors, omissions, or hallucinations. Always verify claims against the cited primary sources. This tool does not provide professional, medical, financial, or legal advice.
Contributing
See CONTRIBUTING.md. Changes are tracked in CHANGELOG.md.