# research-dispatcher-mcp

A Model Context Protocol (MCP) server that lets any MCP-capable AI agent run **one research query across multiple public sources** (Hacker News, Reddit, GitHub, Brave Web Search) in parallel, with source-specific query tuning baked in.

[![PyPI](https://img.shields.io/pypi/v/canola-research-dispatcher-mcp)](https://pypi.org/project/canola-research-dispatcher-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## What it does

Exposes 5 MCP tools:

| Tool | Source | Auth |
|---|---|---|
| `research_hn` | Hacker News (Algolia) | none |
| `research_reddit` | Reddit site-wide search | none (User-Agent only) |
| `research_github` | GitHub repositories | optional `GITHUB_TOKEN` for higher rate limit |
| `research_brave` | Brave Web Search | requires `BRAVE_API_KEY` |
| `research_all` | All of the above in parallel | per-source rules apply |

Each tool returns JSON: a list of normalized hits with `title`, `url`, `score`/`stars`, `created_at`, and source-specific metadata. `research_all` aggregates into `{source: {status, count, items}}`.

## Why

AI agents that handle "what's the latest on X" tasks need to consult multiple sources but each has its own API, rate limit, and pitfalls. This server encodes those once so the agent calls one tool and gets normalized results.

## Install

Requires Python 3.10+.

```bash
pip install canola-research-dispatcher-mcp
```

## Configure your agent

### Claude Code

Add to your `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "research-dispatcher": {
      "command": "research-dispatcher-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_... (optional)",
        "BRAVE_API_KEY": "... (optional)"
      }
    }
  }
}
```

Restart Claude Code and the 5 `research_*` tools become available.

### Codex CLI / Cursor / other MCP runtimes

Each runtime has its own MCP server registration. The command is always `research-dispatcher-mcp`.

## Quickstart

```
"What's the latest on MCP server marketplaces?"
→ agent calls research_all(query="MCP server marketplace", limit=10, since_days=30)
→ HN + Reddit + GitHub returned in parallel, agent synthesizes
```

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `GITHUB_TOKEN` | unset | Raises GitHub rate limit from 60/hr to 5000/hr |
| `BRAVE_API_KEY` | unset | Required to enable `research_brave`; without it the tool returns a "skipped" notice |

## Limitations

- No paywall / logged-in content (X/Twitter, LinkedIn, private subreddits).
- Reddit site-wide search has noticeably weaker recall than subreddit-specific browsing.
- Brave's free tier is 2000 calls/month; this server does not currently track quota.
- Source list is fixed in v0.1; add new sources in `src/research_dispatcher_mcp/sources.py`.

## Development

```bash
git clone https://github.com/0x67108864/research-dispatcher-mcp.git
cd research-dispatcher-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Related

- The original SKILL.md format version: [`canola_oil/skills/research-dispatcher`](https://github.com/0x67108864/skills/tree/main/research-dispatcher) — instruction-based, drop-in folder for agentskills.io runtimes
- Agent Skills standard: [agentskills.io](https://agentskills.io)
- Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)

## License

MIT — see [LICENSE](LICENSE).

## Author

canola_oil — https://0x67108864.github.io/