research.md

The decision forge. An MCP server that enforces evidence-graded, phase-gated, peer-reviewed research workflows so AI agents cannot skip rigor under time pressure.

What it enforces

Evidence gates (upstream)

Process gates (downstream)

Install

pip install research-md

Or install from source:

pip install -e ".[dev]"

MCP configuration

Add to your Claude Code config:

claude mcp add research-md --scope user -- research-md

Or add to .mcp.json:

{
  "mcpServers": {
    "research-md": {
      "command": "research-md"
    }
  }
}

Agent workflow

A typical research session follows this path:

project_set          Register project, get research_id
    |
finding_create       Record claims with evidence grades (UNVERIFIED -> LOW -> REASONED -> CONFIRMED)
    |                Tool nudges: "Use WebSearch to find sources"
finding_update       Add sources, disconfirmation search, upgrade evidence grade
    |                Gate: CONFIRMED requires 2+ sources + disconfirmation
candidate_create     Define options to evaluate
    |                Advisory: "Document the full landscape before narrowing"
criteria_lock        Freeze decision criteria weights
    |
peer_review_log      Log reviewer assessment
    |
candidate_score      Score candidates (gated on criteria + peer review + no TBD)
    |
project_decide       Record the decision with rationale

Evidence grade ladder

Source quality tiers

Each source is tagged with a tier for awareness (no hard gate):

Trilogy conventions

research.md follows shared conventions with ike.md and visionlog. See CONVENTIONS.md for the full standard.

• research.md -- decide with evidence (this tool)
• visionlog -- record the decision as a contract
• ike.md -- execute tasks within those contracts

Config lives at .research/research.json (committed to git).

Targeting pattern: project_set + research_id

Every tool call requires a research_id -- the GUID from .research/research.json. This is an in-memory mapping that does not persist across MCP server restarts.

1. Call project_set with the project's absolute path
2. It returns the project's research_id (a UUID)
3. Pass that research_id on every subsequent tool call

If you call a tool without a valid research_id, the server tells you exactly how to fix it.

Project structure

Single project

my-research/
  .research/
    research.json              <- config with project GUID (commit this)
    findings/                  <- NNNN-slug.md
    candidates/                <- slug.md
    evaluations/
      decision-criteria.md     <- criteria table (lock before scoring)
      peer-review.md           <- reviewer log (required before scoring)
      scoring-matrix.md        <- generated from locked criteria + candidates

Multi-project root

research-root/
  .research/
    research.json              <- root config (lists subprojects)
  vendor-selection/
    .research/
      research.json            <- subproject GUID
      findings/
      candidates/
      evaluations/

Initialize: project_init { path, root: true } then project_init { path, subproject: "name" }. When you project_set a root, all subprojects are registered automatically.

Tools (20)

Session

Project

Findings

Candidates

Scoring

Peer Review

Decision

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT -- see LICENSE.