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