Skip to main content
Glama

robins-i-mcp

An MCP server implementing ROBINS-I V2 (Risk Of Bias In Non-randomized Studies – of Interventions, follow-up/cohort variant) as a deterministic, provenanced assessment engine.

Sibling to target-mcp, which scores how completely a target-trial-emulation study reports what the TARGET guideline requires. This one assesses risk of bias in one specific result. The two are complementary on the same paper.

The source is a draft. riskofbias.info presents the 20 November 2025 release of ROBINS-I V2 as still a draft, subject to change. Every report stamps that in its provenance line. See NOTICE and TRANSCRIPTION-NOTES.md.

Follow-up cohort studies. "Follow-up" and "cohort" name one structural property — a defined time zero, individuals followed forward under the contrasted strategies — so read the property, not a design label. Target trial emulations are the central use case and are cohort studies in exactly this sense; both worked examples below are TTEs. Designs with no follow-up structure are out. No variant for other designs is published yet. Note that "Variant A / Variant B" inside the tool means the two forms of Domain 1 selected by C4 — not a study design.

What makes it different from asking a model

The model's contribution is bounded at answering signalling questions from the text. It cannot compute a judgement and it cannot invent evidence.

1  parse_document              PDF + supplement → SectionMap        deterministic
2  cue detection               where to look, per domain            deterministic
3  answer signalling questions quotes copied from the bundle        MODEL
4  evidence binding            quotes → offsets, or REJECT          deterministic
5  algorithms                  answers → domain → overall           deterministic
6  report + render             stamped artifact                     deterministic
7  human ratification          P1, reviewer-prior answers, overrides

Three rules are enforced at submission, and they are the point of the server:

  • Quotes resolve or die. Every quote is matched to character offsets in the ingested bundle through a three-pass ladder (exact → hyphen-relaxed → references-stripped), and the winning pass is recorded so a loose match is never silently equated with an exact one. An unresolvable quote is rejected with the nearest actual text.

  • Absence is searched, not asserted. A manuscript_absent answer names a cue; the server runs the search and attaches the record — terms, sections, hit count. A prose claim that you looked is refused.

  • Judgements are computed. No tool accepts a domain judgement as input. The six domain algorithms and the overall algorithm are explicit edge graphs traced from the published flowcharts. A human may override, with a recorded justification, and the report shows both values.

Related MCP server: LongBook Verifier

Two gates

P1 blocks domain 1. Question 1.1 asks whether all important confounding factors were controlled, and "important" is defined by the reviewer's prespecified list — not by the paper's covariate table. The server refuses to score domain 1 without set_prespecified_confounders rather than silently substituting one for the other. A list you propose is a candidate: it enters the ratification queue until a human accepts it.

C4 selects domain 1's question set. Whether the analysis accounts for protocol deviations picks variant A (intention-to-treat, baseline confounding only) or variant B (per-protocol, baseline and time-varying confounding), so specify_result requires it up front with no default. Judge it on what the analysis does, not on the label the authors give their estimand — on the reference paper, the protocol table says "per-protocol effect" and the analysis is intention-to-treat.

Install

pip install robins-i-mcp

Then register it with your MCP client:

{ "mcpServers": { "robins-i": { "command": "robins-i-mcp" } } }

Or run it with no install at all:

uvx robins-i-mcp

Also on the MCP registry as com.blackswancausallabs/robins-i-mcp.

Develop

python3 -m venv .venv && .venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -q      # 205 passed
.venv/bin/robins-i-mcp                    # stdio MCP server

Tools

Group

Tool

Spec

get_spec

optional introspection; detail='compact'|'full'

Ingest

parse_document

PDF/docx/text + supplements → hash + cue survey

parse_pmcid

Europe PMC retrieval

Setup

set_prespecified_confounders

P1, review-scoped, blocks domain 1

specify_result

A1–A3, B1–B3, C1–C3, D1, and C4

Assess

assess_result

domain=0 overview, domain=1..6 scaffold

submit_answers

per domain; domain=0 finalizes and renders

Render

render_report

re-render of the stamped artifact

Review

export_robvis

many runs' records → one robvis CSV

Scaffolds are per domain, never one flat rubric: most signalling questions are unreachable on any given path, and which of domain 1's two sets exists at all depends on C4.

Pass the supplement. The target-trial specification that settles C1–C4, and the analysis detail domains 1 and 4 turn on, routinely live only in the appendix. Without it, those questions read NI when the answer was merely in a file nobody ingested.

Many studies: the record

A review of N studies is N runs. Each assessment costs a session, and the server keeps no state between them. So each run emits a small portable record — that is the deliverable that crosses the boundary:

session 1..N   assess one result -> save submit_answers(domain=0)['record']
later          export_robvis(records=[...]) -> one figure-ready CSV

A record is ~4 KB of flat JSON and depends on nothing in this codebase, so any later agent can consume it. It carries its own provenance — document hash, algorithm fingerprint, spec version, ratification state — so every row in the resulting figure traces back to a document, and the export can warn when a set mixes algorithm transcriptions.

export_robvis is not a column dump. robvis's ROBINS-I template is V1: seven domains, and V1 orders selection of participants before classification of interventions, which V2 swaps. The default layout places each V2 judgement in its correct V1 slot; a positional dump would parse, plot, and lie. Read the returned losses before publishing — robvis reduces every cell to its first initial over a five-fill palette, so the qualified low collapses to Low there whatever string is written.

See examples/review_from_records.py.

Worked examples

.venv/bin/python examples/dickerman_2022.py out.html          # library level
.venv/bin/python examples/jabagi_2026_server_run.py           # server level
.venv/bin/python examples/review_from_records.py             # across runs
  • Dickerman et al., NEJM 2022 — BNT162b2 vs mRNA-1273 in US veterans. Comes out low, except for concerns about uncontrolled confounding. 24 of 41 questions never reached.

  • Jabagi et al., Lancet Reg Health Eur 2026 — maternal RSVpreF vs infant RSV hospitalisation. Comes out serious, and the route is worth reading: domain 1 fails at 1.3 rather than 1.1, because gestational age at birth and birth weight are matched on despite being realised after the intervention.

The papers themselves are not in this repository — they are published articles and not ours to redistribute. Put your own copies in papers/, or point ROBINS_MCP_PAPERS at the directory holding them; the examples name the files they need and fail with that message if they are absent.

Documentation

  • docs/STATUS.md — current state and handoff. Read this first.

  • docs/DECISIONS.md — why things are the way they are, newest first.

  • docs/SESSION-NOTES-*.md — per-session narrative.

  • TRANSCRIPTION-NOTES.md — how the algorithms were obtained from raster flowcharts, the errata found in the published document, and what still needs external verification.

Licence

Apache-2.0 (LICENSE). The ROBINS-I V2 tool it implements is CC BY-NC-ND 4.0 and no part of it is reproduced here — see NOTICE for why that matters and what the actual constraint is.

Available Tools

9 tools
assess_resultA

Return the assessment scaffold for ONE domain: the questions actually in play, their own-words intent, the response vocabulary each accepts, what evidence each answer must carry, and the cue searches already run against this bundle with their hits.

THE SCAFFOLD IS PER DOMAIN BY DESIGN. Most signalling questions are unreachable on any given path — 24 of 41 were never reached on the reference assessment — and which of domain 1's two question sets exists at all is decided by C4. There is no flat 41-question rubric to fetch, and asking for one would mean answering questions the algorithm discards.

domain=0 (default) returns the overview: the preliminaries, what is settled, which domains are done, and which are outstanding. domain=1..6 returns that domain's scaffold. Domain 1 is refused until P1 is set.

Work a domain at a time: read the cues to find where the evidence is, answer only the questions the algorithm reaches, then submit_answers. You do not state a judgement — the server computes it from your answers.

Inputs: result_id (required), domain. Returns: cues, domain, variant, citation, +25 more

export_robvisA

Combine assessment RECORDS from any number of runs into a CSV for robvis (McGuinness & Higgins), the standard tool for Cochrane-style risk-of-bias figures.

A review of 200 studies is 200 separate runs — each assessment costs a session, and nothing in this server survives between them. So pass records: the record object each submit_answers(domain=0) returns. They are small, flat and JSON-native, so a whole review's worth fits in one context, and they carry their own provenance so every row stays traceable to a document and an algorithm fingerprint. Omit records to use only what was assessed in THIS session (convenient, but session-scoped).

READ THE RETURNED losses BEFORE PUBLISHING THE FIGURE. It reports records that are not yet ratified, mixed C4 variants, equal weighting, and records built under differing algorithm transcriptions — each of which would make the figure claim more than the assessments support.

This is not a column dump, because robvis's ROBINS-I template is ROBINS-I V1 and V2 is not drop-in compatible:

  • V1 has SEVEN domains and orders selection of participants BEFORE classification of interventions. V2 has six and swaps that pair. Writing V2's columns out in order loses no data and raises no error — it just prints your classification judgement under the heading "Bias due to selection of participants". layout='robins_i' (the default) places each V2 judgement into its correct V1 SLOT and marks the dropped deviations domain NA. Upload it with tool='ROBINS-I'.

  • layout='generic' writes six columns headed with V2's own domain names, for tool='Generic'. The headings are then right, but robvis relabels the judgements into ROB1's vocabulary — Moderate becomes "Some concerns", Serious becomes "High". Prefer 'robins_i'.

Neither layout can carry 'Low, except for concerns about uncontrolled confounding': robvis reduces every cell to its first initial over a five-fill palette, so it collapses to Low whatever string is written. Say so in the figure caption.

Inputs: labels, layout, records, weights, +2 more. Returns: csv, rows, usage, header, +10 more

get_specA

Return the encoded ROBINS-I V2 specification: 13 preliminaries, 40 signalling questions across 6 domains (domain 1 in two variants), the response vocabularies, the evidence policy, and the algorithm fingerprint.

OPTIONAL in the assessment flow — introspection only. assess_result already carries the rubric for the domain in hand, so calling both duplicates the payload. detail='compact' (default) gives question ids, own-words labels, response options and evidence modes; detail='full' adds every intent and assessor note.

The descriptions are this implementation's own wording, NOT the published signalling-question text, which is not redistributable. The published question IDs are what make the output interoperable.

Inputs: detail, spec_version. Returns: domains, judgements, attribution, spec_version, +17 more

parse_documentA

PRIMARY entry point: parse a study report into a bundle with character-offset, source-tagged section spans. Every quote you later cite is resolved against THIS text, and every claim of absence is searched in it.

PASS citation=: the full bibliographic reference in APA style. It appears on the rendered assessment so the study being judged is unambiguous.

document is EITHER the raw text OR a file path — but the path must be readable on the SERVER host. If your files live on your own filesystem, paste the TEXT instead, or use parse_pmcid for an open-access PMCID. A path-looking string the server cannot find raises rather than being ingested as its own text.

PASS THE SUPPLEMENT WHEN YOU HAVE IT. supplements is a list of server-readable paths merged as supplementary material. This matters more for ROBINS-I than for a reporting audit: the target-trial specification that settles C1-C4, and the analysis detail domains 1 and 4 turn on, routinely live only in the appendix. Without it those questions read NI when the answer was merely in a file nobody passed. supplement_status defaults to 'user_provided' when supplements are given; pass 'none_exists' to assert the article has none.

Returns the section map, the text hash that keys later calls, and a cue survey — hit counts for the 15 evidence patterns, so you can see before reading where each domain's evidence lives and which absences already look real.

Inputs: document (required), citation, supplements, manuscript_id, +1 more. Returns: source, n_pages, citation, sections, +9 more

parse_pmcidA

CONVENIENCE entry point: retrieve an open-access article from Europe PMC by PMCID and parse it, main text plus PMC-hosted supplements, merged into one source-tagged bundle. Use it when you have no file in hand, or to auto-fetch an open-access paper's supplement; for a manuscript you were given, use parse_document.

supplement_status is 'retrieved' when a supplement was obtained, else 'not_retrieved' — a supplement may still exist on the publisher site, so absence of retrieval is never proof of absence. Raises if no open-access full text is available. An APA-style citation is built from the article's JATS metadata; pass citation= to override it.

Inputs: pmcid (required), citation, include_supplements. Returns: source, n_pages, citation, sections, +9 more

render_reportA

Re-render a finalized assessment as a self-contained HTML page — the meta panel, the six-domain summary strip, the per-domain judgement with its algorithm trail and the evidence behind every answer, styled to the Black Swan Causal Labs identity and carrying the provenance stamp.

Returns the HTML in html (display it inline or publish it as an artifact) and the same bytes base64-encoded in content_base64 (decode and save as .html). This is a pure re-render of the artifact submit_answers already stamped — nothing is re-scored. The assessment must have been finalized this session; the cache does not survive a server restart.

Inputs: result_id (required), title. Returns: html, domains, overall, citation, +8 more

set_prespecified_confoundersA

Supply P1 — the confounding factors this REVIEW judges important for the intervention-outcome relationship, listed before any study is assessed.

THIS IS BLOCKING. Domain 1 will not be scored without it. Question 1.1 asks whether all IMPORTANT confounding factors were controlled for, and 'important' is defined by this list, not by the paper's covariate table. Substituting the paper's own list would let the study grade its own confounding control, which is exactly the judgement ROBINS-I asks the reviewer to make independently.

'Important' means adjustment would be expected to change the estimate meaningfully; factors with only very weak associations are excluded.

You MAY propose a list from domain knowledge or a DAG — that is useful and is what this parameter is for — but a proposed list is not a ratified one. Leave ratified_by empty unless a human in this conversation has actually reviewed and accepted the list; the assessment then carries P1 in its ratification queue and is explicitly not final until they do. Do not sign it off on their behalf.

Scoped by review_id because P1 belongs to the review, not to one study: the same list applies to every result assessed under it.

Inputs: confounders (required), rationale, review_id, ratified_by. Returns: note, ratified, n_factors, rationale, +3 more

specify_resultA

Name the ONE numerical result being assessed, and settle C4. Required before any domain can be scored.

ROBINS-I assesses a single effect estimate, not a paper. A study reporting three outcomes across two analyses yields six assessments; give each its own result_id and run them separately.

accounts_for_deviations IS C4, and it is the highest-leverage input here: it swaps domain 1's entire question set and algorithm, so it cannot be deferred until domain 1 is reached. 'no_itt' — the analysis does NOT account for switches between the compared strategies or other protocol deviations. It targets the effect of assignment. Domain 1 variant A (baseline confounding only). 'yes_pp' — the analysis DOES account for them, by censoring, follow-up partitioning, or a g-method. It targets the effect of sustained receipt. Domain 1 variant B (baseline AND time-varying confounding). Judge this on what the ANALYSIS DOES, not on the label the authors give their estimand. A paper whose protocol table says 'observational analogue of the per-protocol effect' but which never censors at deviation is 'no_itt'. Getting this wrong means answering five questions that do not apply.

result_assessed is A1: the estimate with its precision. outcome is A3. result_location (A2) is where it appears and why it was chosen. target_trial is C1-C3 as a dict of labelled strings — eligible participants, intervention strategy, comparator strategy, and any note on the estimand. information_sources is D1: what you actually read. An NI answer is only defensible relative to what was searched.

b1/b2/b3 are the section B screening answers (Y/PY/PN/N). b1: was any attempt made to control confounding in this result? b2 (asked only if b1 is PN/N): is the potential for confounding great enough that an unadjusted result should not be considered further? b3: is the outcome measurement method unsuitable for the outcome it is meant to capture? Y/PY on b2 or b3 sends the result straight to critical and no domain is scored.

Inputs: outcome (required), result_id (required), text_sha256 (required), result_assessed (required), +11 more. Returns: outcome, citation, estimand, warnings, +14 more

submit_answersA

Submit one domain's signalling-question answers and get back the COMPUTED domain judgement, or (domain=0) finalize the assessment.

Each element of answers is one question: question, response, evidence_mode, rationale, plus the evidence that mode requires — quotes for manuscript_positive, search_cue or search_terms for manuscript_absent, prior_ref for reviewer_prior. Answer only the questions the algorithm reaches; omit the rest rather than answering NA. support is your narrative for the domain as a whole and appears in the report.

Three things are enforced here, and all three are the point of the tool: every quote is resolved to character offsets in the ingested bundle and an unresolvable one is REJECTED with the nearest text found; every claim of absence is backed by a search THE SERVER runs, so it is reproducible; and the judgement is computed by the published algorithm from your answers, never asserted by you. If the traversal reaches a question you did not answer, the call returns status='incomplete' naming it — supply it and call again.

override_judgement sets the domain judgement against the algorithm and REQUIRES override_justification. Overrides cannot hide: the report shows both values and the override enters the ratification queue.

domain=0 finalizes: it computes the overall judgement (worst of the six domains by default), assembles the stamped assessment and returns the rendered report inline. overall_escalate applies the tool's permitted escalation — several moderates to serious, or several seriouses to critical — and requires a justification. The returned report is THE ARTIFACT OF RECORD: present that, not a table of your own, and repeat its ratification queue if it is non-empty, because an assessment with unratified items is not final.

Inputs: domain (required), result_id (required), render, answers, +8 more. Returns: path, notes, domain, record, +23 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool serves a distinct step in the ROBINS-I workflow, but assess_result and get_spec both return specification/rubric information, which could cause an agent to fetch the wrong one. parse_document and parse_pmcid are clearly distinguished by input type.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: parse_document, parse_pmcid, specify_result, submit_answers, render_report, export_robvis. The pattern is uniform and predictable across the entire set.

    Tool Count5/5

    Nine tools is well within the ideal range and each tool covers a necessary step in the assessment lifecycle—parsing, setup, domain work, finalization, and export. No tool feels redundant or extraneous.

    Completeness5/5

    The tool set covers the full ROBINS-I assessment workflow: document ingestion (parse_document/parse_pmcid), protocol setup (set_prespecified_confounders, specify_result), domain assessment (assess_result, submit_answers), and reporting (render_report, export_robvis). There are no obvious dead ends or missing critical operations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that provides tools for deterministic EU AI Act risk classification and documentation generation, enabling human-in-the-loop AI system assessments inside Claude Code.
      22 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that evaluates whether retrieval methods and AI outputs are grounded in long narrative manuscripts by retrieving evidence and scoring coverage deterministically, without external model APIs. It provides tools for chunking, indexing, retrieval, and evaluation.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for agentic systematic literature reviews with citation verification. Enables AI assistants to list reviews, get drafts, retrieve citation audits, and manage discovered papers.
      2
      MIT