How do I use research.md?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@research.md Set up a research project on cloud database options" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

research.md

by eidos-agi

Overview Schema Source Related Servers Discussions Admin

Python

Local

research.md

PyPI License: MIT Python 3.11+

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)

Gate	Trigger
2+ sources for CONFIRMED evidence	`finding_create` / `finding_update` fail if upgrading to CONFIRMED with < 2 sources
Disconfirmation search required	`finding_create` / `finding_update` fail if upgrading to CONFIRMED without documenting what you searched to disprove the claim
Content hash for REASONED+	Source must include `content_hash:` proving the agent fetched and read the material
Web research nudge	Tool returns advisory when findings have no sources
Vendor-only warning	Advisory when all sources are VENDOR tier
Landscape scan advisory	Nudge on first candidate to document the full option landscape

Process gates (downstream)

Gate	Trigger
Criteria locked before scoring	`candidate_score` fails if `decision-criteria.md` not locked
No TBD on scored candidates	`candidate_score` fails if candidate has `_TBD_` claims
Peer review before scoring	`candidate_score` fails if no `evaluations/peer-review.md`

Related MCP server: agent-gate

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

Grade	Meaning	Requirements
`UNVERIFIED`	Claim recorded, not yet investigated	None -- tool nudges toward web research
`LOW`	Single source or anecdotal	At least a coherent argument
`REASONED`	Credible source, verified consultation	1+ source with `content_hash:` proof
`CONFIRMED`	Confirmed -- validated by evidence	2+ independent sources + disconfirmation search

Source quality tiers

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

Tier	Examples
`PRIMARY`	Census data, RFC specs, user study results
`EXPERT`	PMC papers, RAND reports, Thoughtworks Radar
`SECONDARY`	Blog roundups, tutorials, comparison guides
`VENDOR`	Company blog comparing itself to competitors

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.

Call project_set with the project's absolute path
It returns the project's research_id (a UUID)
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

Tool	Description
`project_set`	Register a project path, returns its GUID. Also registers subprojects if root.
`project_get`	List all registered projects and their GUIDs for this session.

Project

Tool	Description
`project_init`	Initialize project structure (single, root, or subproject).
`status`	Project health: evidence gate status, criteria locked, peer review, TBD count, finding/candidate totals.

Findings

Tool	Description
`finding_create`	Create finding with evidence grade, sources array, and disconfirmation. Nudges toward web research.
`finding_list`	List all findings with status and evidence grade.
`finding_update`	Update status, evidence grade, sources, disconfirmation, or claim. Gates CONFIRMED evidence.

Candidates

Tool	Description
`candidate_create`	Create candidate for evaluation. Landscape advisory on first candidate.
`candidate_list`	List all candidates with verdict status.
`candidate_update`	Update verdict (provisional/recommended/eliminated) or description.
`candidate_add_claim`	Add binary testable claim to validation checklist.
`candidate_resolve_claim`	Mark a claim Y or N (clears `_TBD_`).

Scoring

Tool	Description
`criteria_lock`	Lock decision criteria weights. Required before scoring.
`candidate_score`	Score a candidate against locked criteria. Gated on criteria lock + peer review + no TBD.
`scoring_matrix_generate`	Generate comparison table from locked criteria + scored candidates.

Peer Review

Tool	Description
`peer_review_log`	Log reviewer name and findings. Required before scoring.

Decision

Tool	Description
`project_decide`	Record the final decision with rationale.
`project_supersede`	Mark a decided project as superseded by new research.
`research_brief`	Generate a layered research brief from a completed project.
`research_report`	Generate a full untruncated research report.

Development

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

License

MIT -- see LICENSE.

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

FlowraOAuth
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
Agenda Intelligence MD A
io.github.vassiliylakhonin
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
Legal & Compliance Research & Data
118
mcp-agentcore A
com.geiant
AI governance MCP server for EU AI Act compliance and jurisdiction verification
Legal & Compliance AI & Machine Learning Government Data
32

Related MCP Servers

p2pclaw-mcp-server
Research & Data Web3 & Decentralized Tech Autonomous Agents
Agnuxo1
F
license
Not graded
quality
B
maintenance
A backend MCP server that enables AI agents to publish, validate, and search research papers, submit swarm-compute jobs, and invoke formal proof checking on the P2PCLAW decentralized network.
Updated 19 days ago (2026-09-24 18:51 UTC)
15
-
agent-gate
Autonomous Agents Agent Orchestration
Jott2121
A
license
B
quality
B
maintenance
An MCP server that enforces fail-closed deterministic checks, independent refute-first review, and tamper-evident hash-chained receipts for AI agent outputs before claiming completion.
Updated a month ago (2026-09-15 03:54 UTC)
4
3
MIT
governed-mcp
Security Autonomous Agents Agent Orchestration
rsiraj0
F
license
Not graded
quality
D
maintenance
MCP server that enforces governance on agentic decisions with auditable evidence records, providing tools for understanding, calibrating confidence, and navigating handoffs based on policy.
Updated 3 months ago (2026-07-07 21:40 UTC)
-
MLLoop
AI & Machine Learning Research & Data Autonomous Agents
Sin991114
A
license
Not graded
quality
C
maintenance
An MCP server that enforces a scientific-method loop for AI-driven machine learning experiments, with hypothesis gating, diagnostics, and data forensics.
Updated 3 months ago (2026-07-25 04:16 UTC)
Apache 2.0

research.md

What it enforces

Evidence gates (upstream)

Process gates (downstream)

Install

MCP configuration

Agent workflow

Evidence grade ladder

Source quality tiers

Trilogy conventions

Targeting pattern: project_set + research_id

Project structure

Single project

Multi-project root

Tools (20)

Session

Project

Findings

Candidates

Scoring

Peer Review

Decision

Development

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

p2pclaw-mcp-server

agent-gate

governed-mcp

MLLoop