Cheap Research

A bounded evidence review engine. Give it a claim and a document corpus - it extracts relevant evidence, detects contradictions, and produces auditable evidence packets. No hallucinations, no global truth claims, no open-web research.

What it does

1. Ingest PDF, TXT, MD, DOCX, DOC, HTML, RTF, EPUB documents
2. Extract evidence spans relevant to your claim
3. Detect contradictions between claim and corpus
4. Render markdown evidence packets with caveats
5. Audit immutable hash-chained audit trail

Trust posture

• Fails closed - enforcement engine blocks invalid authority transitions
• Bounded corpus - cannot make claims outside provided documents
• Explicit caveats - every packet states limitations
• No global truth - "not established in corpus" not "false"
• Human review required - claims need explicit reviewer sign-off

MCP Tools

Tool	Description
research_start	Ingest corpus, assess claim, produce evidence packet
research_status	Get run state and evidence summary
research_getEvidence	Get top relevant spans + contradictions
research_getPacket	Get full markdown assessment report
research_audit	Run compliance integrity audit
corpus_topics	List available paper topics for download
corpus_list	List all papers in curated library (filterable)
corpus_load	Download seminal ML papers to corpus directory

Quick Start: Download Papers

Use corpus_load to download a curated set of foundational ML papers:

// Download ALL papers to your corpus
corpus_load({ corpus_path: "/path/to/cheap-research/corpus" })

// Or download specific topics
corpus_load({
  corpus_path: "/path/to/corpus",
  topics: ["transformers", "optimization"]
})

// Or specific papers by ID
corpus_load({
  corpus_path: "/path/to/corpus",
  paper_ids: ["attention", "bert", "resnet"]
})

Available topics: transformers, foundations, optimization, reinforcement, generative, representations, efficiency

Papers included: Attention Is All You Need, BERT, GPT, GPT-3, ResNet, AlexNet, LSTM, Adam, Batch Norm, Dropout, GANs, VAE, Diffusion Models, Vision Transformer, Word2Vec, DQN, Knowledge Distillation, and more (22 papers total).

Install

git clone https://github.com/your-org/cheap-research.git
cd cheap-research
npm install
npm run build

Adding to Your AI Assistant

This server uses the Model Context Protocol (MCP). Here's how to connect it to your AI:

Claude (Claude Code CLI / Claude Desktop)

1. Open your MCP config file:

   • Claude Code: ~/.claude.json
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

2. Add the server to mcpServers:

{
  "mcpServers": {
    "cheap-research": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/cheap-research/node_modules/.bin/tsx",
        "--tsconfig",
        "/ABSOLUTE/PATH/TO/cheap-research/tsconfig.base.json",
        "/ABSOLUTE/PATH/TO/cheap-research/apps/mcp-server/src/index.ts"
      ]
    }
  }
}

3. Replace /ABSOLUTE/PATH/TO/ with the actual path where you cloned the repo.

4. Restart Claude Code or Claude Desktop.

5. Type /mcp in Claude Code to verify the server is connected.

Other MCP-compatible AI Tools

Any AI tool that supports MCP can use this server. Point it to run the npm run mcp command or use the config format above. Check your tool's documentation for MCP server configuration.

Run as MCP Server (manual)

npm run mcp

This starts the server in stdio mode, ready for MCP clients.

Example

// Start research on a claim
research_start({
  task_type: "bounded_doc_claim_assessment",
  target_claim: "Attention mechanisms enable Transformers to model long-range dependencies",
  entity: "Transformer architecture",
  feature: "attention mechanism",
  scope: "Assess based on provided neural network papers",
  corpus_path: "/path/to/corpus"
})

// Returns: { run_id, status: "completed", assessment: "qualified", ... }

Supported Formats

Format	Extension	Parser
PDF	.pdf	pdf-parse
Text	.txt	native
Markdown	.md	native
Word	.docx	mammoth
Word (legacy)	.doc	mammoth + fallback
HTML	.html, .htm	cheerio
RTF	.rtf	rtf-parser
EPUB	.epub	epub2

What's NOT included (intentional)

• Open-web research
• Autonomous recommendations
• Confidence scores
• Free-form LLM synthesis
• Automatic operational acceptance
• Vector embeddings / semantic search

Architecture

corpus/           → ingestCorpus() → MemoryStore
                                  ↓
claim + evidence  → findRelevantSpans() → scored spans
                                  ↓
                  → detectContradictions() → flagged spans
                                  ↓
                  → createClaimCandidate() → enforcement check
                                  ↓
                  → renderPacketMarkdown() → evidence packet
                                  ↓
                  → publishPacket() → audit log

State Machines

Claims, findings, packets all have strict state transitions enforced by the enforcement engine. Illegal transitions are blocked with explicit blockers.

Audit Trail

Hash-chained immutable audit log. Every action recorded with:

• Actor context (who)
• Object reference (what)
• Event type (action)
• Payload (details)
• Chain hash (integrity)

License

MIT