English | 中文

Harness Research MCP

Give any AI Agent professional-grade deep research capabilities.

An MCP (Model Context Protocol) server that performs real-time deep research across 5 data sources, evaluates source credibility with the CRAAP framework, cross-verifies findings, and generates professional reports — all driven by affordable models like Kimi K2.5.

A full deep research report takes ~10 minutes and can be driven by Kimi K2.5 at ~$0.01/run.

---

For AI Agents: How to install this tool

This is a Node.js MCP server, NOT a Python package. Do NOT git clone or pip install.

Step 1 — One-time setup (run in user's terminal):

npx harness-research-mcp setup

This launches an interactive wizard to configure API keys (stored in ~/.harness-research/.env).

Step 2 — Register as MCP server in your agent's config file:

Claude Desktop / Cursor / Windsurf — edit MCP config JSON:

{
  "mcpServers": {
    "harness-research": {
      "command": "npx",
      "args": ["-y", "harness-research-mcp"]
    }
  }
}

OpenCode — add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "harness-research": {
      "command": "npx",
      "args": ["-y", "harness-research-mcp"]
    }
  }
}

That's it. After registration, the agent gets 3 tools: harness_research (full report), harness_search (quick search), harness_status (progress check).

Do NOT clone this repo, build from source, or run node/python directly. npx handles everything.

Async workflow — no timeout issues: harness_research returns a task_id immediately (< 1 second). The research runs in the background (~10 minutes). You must poll harness_status(task_id) every 30–60 seconds until status is "completed" or "failed". This design means the default 60-second MCP timeout will NOT be a problem.

If your MCP client has a configurable timeout, setting it to 1200 seconds (20 minutes) is still recommended as a safety margin:

{
  "mcpServers": {
    "harness-research": {
      "command": "npx",
      "args": ["-y", "harness-research-mcp"],
      "timeout": 1200
    }
  }
}

---

Why This Tool Exists

The Problem with Current "Deep Research" Tools

Existing deep research tools (Perplexity Deep Research, ChatGPT Research, Gemini Deep Research, etc.) share fundamental flaws:

Problem	Explanation
Rely on stale knowledge	They primarily draw from the LLM's training data, not real-time internet search. You may get data that's months or years out of date.
Opaque sourcing	Most tools don't show where information came from. Some cited URLs are hallucinated.
No source evaluation	A social media post and a government statistical report are treated equally. No mechanism to assess credibility.
Single search source	One search engine, narrow coverage. Academic papers, financial data, and government reports are unreachable.
Not integrable	Locked into specific platforms. Can't plug into your own AI Agent workflow.
Expensive	Require GPT-4, Claude, etc. Each research session costs $1-5+.

How Harness Research Is Different

Feature	Harness Research	Perplexity / ChatGPT / Gemini
Data sources	5 real-time search APIs (Tavily + Brave + arXiv + PubMed + Tushare)	Single search engine or model's internal knowledge
Data freshness	100% real-time search — zero reliance on LLM training data	Mixed stale knowledge + limited search
Source evaluation	CRAAP framework with 5-dimension scoring + T0-T5 tier classification (530+ domain database)	None
Cross-verification	Automatic conflict detection + counterintuitive finding identification	None
Citations	Every reference tagged with source tier, credibility score, publication date	Simple URL list or no citations
LLM requirement	Kimi K2.5 works great (~$0.01/run)	GPT-4 / Claude ($1-5/run)
Output formats	HTML + DOCX + PDF + Markdown	Plain text
Integrability	Standard MCP protocol — works with any Agent	Locked to specific platform
Open source	Apache 2.0	Proprietary

Core principle: The LLM only "thinks" — it never "knows." All factual data comes from real-time search.

---

The 6-Step Research Pipeline

User: "Research the global AI chip market landscape in 2025"
         │
         ▼
Step 1 ── Research Plan (LLM)
         │  Generate chapter structure + search keywords
         ▼
Step 2 ── 5-Source Parallel Search (Code)
         │  Tavily + Brave + arXiv + PubMed + Tushare
         │  Dedup → cap at 50 results
         ▼
Step 3 ── CRAAP Source Evaluation (Code + LLM)
         │  Code pre-filter: T5 eliminated, >3yr eliminated
         │  LLM batch scoring: Relevance + Accuracy + Purpose
         │  Weighted average → filter low-scoring sources
         ▼
Step 4 ── Cross-Verification (LLM)
         │  Data triangulation + conflict detection + counterintuitive findings
         ▼
Step 5 ── Parallel Writing (LLM)
         │  All chapters in parallel + executive summary
         ▼
Step 6 ── Render Output (Code)
         │  HTML + DOCX + PDF (macOS) + Markdown
         ▼
    Professional research report (~10 minutes)

---

Quick Start

1. Setup (one-time)

npx harness-research-mcp setup

The interactive wizard will guide you through:

• Configuring search API keys (Tavily or Brave, at least one)
• Configuring an LLM API key (Kimi K2.5 recommended — cheapest option)
• Optional: Tushare (Chinese financial data), NCBI (PubMed academic search)
• Automatic API connectivity test

2. Register with Your AI Agent

Copy the appropriate config for your Agent framework:

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "harness-research": {
      "command": "npx",
      "args": ["-y", "harness-research-mcp"]
    }
  }
}

OpenClaw:

openclaw mcp set harness-research '{"command":"npx","args":["-y","harness-research-mcp"]}'

OpenCode:

// ~/.config/opencode/opencode.json
{
  "mcp": {
    "harness-research": {
      "command": "npx",
      "args": ["-y", "harness-research-mcp"]
    }
  }
}

3. Use It

Just tell your Agent:

"Do a deep research on the global AI chip market landscape in 2025"

The Agent will automatically call harness_research and return the full report in ~10 minutes.

---

Three MCP Tools

Tool	Description	Duration
harness_research	Full deep research with professional report output	~10 min
harness_search	Quick multi-source search, returns structured results	Seconds
harness_status	Check research task progress	Instant

---

API Keys Explained

Why Do You Need These Keys?

Harness Research does not rely on any LLM's historical knowledge. All information is fetched in real-time from the internet. This requires calling various search and data APIs.

Key	Purpose	Required?	Get it	Cost
TAVILY_API_KEY	Advanced web search (deep scraping support)	Required (pick one)	tavily.com	Free 1000 calls/mo
BRAVE_API_KEY	Privacy-focused web search	Required (pick one)	brave.com/search/api	Free 2000 calls/mo
KIMI_API_KEY	LLM reasoning (planning, evaluation, writing)	Required (pick one)	platform.moonshot.cn	Very low cost
OPENROUTER_API_KEY	LLM reasoning (alternative to Kimi)	Required (pick one)	openrouter.ai	Per-model pricing
TUSHARE_TOKEN	Chinese A-share financial data	Optional	tushare.pro	Free basic tier
NCBI_API_KEY	PubMed academic paper search	Optional	ncbi.nlm.nih.gov	Free

Minimum: 1 search key + 1 LLM key = 2 keys to get started.

Why Kimi K2.5?

• Cost: ~$0.01 per full research session (vs. GPT-4 at $1-5)
• Chinese support: Native Chinese language, no translation layer needed
• Context: 128K token window — handles large volumes of search results
• Reliability: 99.9%+ API availability

---

Output Formats

Format	macOS	Windows / Linux	Notes
HTML	✅	✅	Professional layout, dark theme support
DOCX	✅	✅	Word document, ready to edit and share
PDF	✅	❌	Puppeteer-based, macOS only
Markdown	✅	✅	Plain text, easy to post-process

---

CRAAP Evaluation Framework

Every source is scored across 5 dimensions:

Dimension	Weight	What It Measures
Currency	15%	How recent is the publication?
Authority	25%	Source tier: Government > Academic > Media > Blog
Relevance	25%	How well does it match the research topic?
Accuracy	20%	Is the data verifiable? Does it cite sources?
Purpose	15%	Is the writing objective or biased?

6-Tier Source Classification

Tier	Weight	Source Type	Examples
T0	1.2x	Raw government data APIs	World Bank API, Fed FRED, SEC EDGAR
T1	1.0x	Authoritative institutions	WHO, Nature, Science, government reports
T2	0.8x	Professional organizations	McKinsey, Gartner, Financial Times
T3	0.6x	Mainstream media	Reuters, Bloomberg, TechCrunch
T4	0.3x	General websites	Unclassified domains (default)
T5	0.15x	Social media	Twitter, Reddit (auto-eliminated)

Built-in 530+ domain credibility database covering major governments, academia, media, and professional institutions worldwide.

---

Diagnostics

npx harness-research-mcp doctor

---

Architecture

┌──────────────────────────────────────────┐
│  Claude / Cursor / OpenClaw / OpenCode   │
│            (MCP Client)                  │
└────────────────┬─────────────────────────┘
                 │ stdio (MCP Protocol)
                 ▼
┌──────────────────────────────────────────┐
│      harness-research-mcp (Node.js)      │
│                                          │
│  Tools:                                  │
│    harness_research — full deep research  │
│    harness_search   — quick multi-search  │
│    harness_status   — progress query      │
│                                          │
│  6-Step Pipeline:                         │
│    Plan → Search → CRAAP → Verify →       │
│    Write → Render                         │
│                                          │
│  Pure Node.js. Zero Python dependency.    │
└──────────────────────────────────────────┘

---

Development

git clone https://github.com/Nimo1987/harness-research.git
cd harness-research
npm install
npm run build

---

License

Apache 2.0