target-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@target-mcp Assess this manuscript against the TARGET reporting guideline."
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.
TARGET Checklist MCP Server
An MCP server that operationalizes the TARGET reporting guideline (TrAnsparent ReportinG of observational studies Emulating a Target trial; Cashin et al., JAMA/BMJ, September 2025) as a deterministic, provenanced scoring engine for target trial emulation (TTE) studies.
This is the executable TARGET: not a manuscript auditor that renders an opinion, but a measurement instrument that produces a structured, item-by-item, evidence-linked matrix with fixed model provenance, so a corpus-scale result is reproducible.
See ../target-mcp-server-design.md for the full design rationale.
Status — vertical slice
Built and proven end-to-end:
Spec layer — the 21 published items decomposed into 39 scoreable leaf subitems, encoded as versioned YAML (
target_mcp/specs/target-0.1.0.yaml) with own-words intent, verdict boundaries, signal terms, the 6x↔7x specification/emulation pairing, and applicability rules. Structurally validated on load (spec.py).Ingestion layer — PDF/text/docx →
SectionMapwith character-offset, source-tagged section spans (main vssupplement:<file>), protocol-table and flow-diagram detection, extractor version + text hash stamps, and whitespace-insensitive quote→span resolution. Supports multi-document bundles (main text + supplements) viabuild_bundle(ingest.py).Retrieval layer — the corpus/batch and convenience path: fetch open-access articles by PMCID from Europe PMC (JATS main text plus PMC-hosted supplementary files, merged into one bundle). Use this when there is no file in hand or to auto-fetch an OA paper's supplement; for a manuscript you were given, ingest the file directly (
retrieve.py).Assessment layer — batched, single-pass scoring of all applicable leaves. Scaffold mode (default) is the path for reviewing a publication: the agent already in the loop is the scorer, so the server returns the exact prompt + schema for it to run, then validates the verdicts it submits. Judge mode is for the headless/batch case (no LLM in the loop) — the server makes its own pinned model call so a corpus run is reproducible and caller-independent. Both share one validation path that enforces leaf coverage, verdict vocabulary, and mandatory verbatim evidence resolved to spans with a
source_documenttag (assess.py).Rendering layer —
render_checklistprojects a finalized assessment onto the published TARGET checklist form (all 39 rows, verbatim item wording under CC BY-ND, a Location-reported column from the resolved evidence spans; the enriched view adds verdict + evidence).render_checklist_docxwrites the same as a submission-ready Word file (render.py,render_docx.py).Corpus & validation layers —
aggregate_corpusrolls many assessments into per-item completeness rates with coverage denominators (corpus.py);validate.pyprovides blind human coding-sheet generation and per-leaf agreement (raw, Cohen's κ, Gwet's AC1, sensitivity/specificity) against a gold standard.Composition layer — FastMCP server (
server.py) exposing eleven tools. The primary manuscript flow isparse_manuscript(parse the file you were given, withsupplements=when available) →assess_manuscript→submit_scaffold_verdicts→render_checklist(orrender_checklist_docx). Supporting tools:parse_pmcid(corpus/batch or OA-supplement fetch),get_checklist(introspect the spec),aggregate_corpus,build_coding_sheet, andvalidate_against_gold.
Not yet built (see design doc): assess_item, check_emulation_coherence,
export_identifiability_spec, publisher-site supplement retrieval (beyond the
PMC-OA tier), better table extraction, and the separate materiality/design-risk
layer.
Provenance stamped on every assessment
spec_version, resolved model id, temperature, prompt_hash,
prompt_template_version, extractor_version, text_sha256, assessed_at,
full_text_available, supplement_status, and a per-source documents list;
each evidence item carries its resolved span, section, and source_document.
A span is only meaningful alongside the extractor version and text hash, so
they travel together.
Related MCP server: robins-i-mcp
Reporting completeness, not a pass/fail verdict
The instrument scores how completely a manuscript reports what the checklist
requires — not study quality, and it issues no pass/fail judgment. TARGET
presents all 21 items as essential minimum items with no tiering, and this
tool follows suit: the output is the 39 per-leaf verdicts with evidence and a
completeness tally. (An earlier "critical floor" — a BSCL pass/fail overlay over
six leaves — was removed in 2026-07-19 as off-message and confusing; see
docs/DECISIONS.md.) Do not present a verdict matrix as TARGET compliance.
Install
The server and the optional orchestration skill ship together in this repo, but they activate through two separate mechanisms — installing one does not enable the other. Getting the files (clone/download) gives you both; then do the two activation steps below.
1. Install the server
git clone https://github.com/Black-Swan-Causal-Labs/target-mcp.git
cd target-mcp
python3 -m venv .venv
.venv/bin/pip install -e .(Once published to PyPI: pip install target-mcp.)
Run it standalone (stdio transport) to smoke-test:
.venv/bin/target-mcp2. Register the server with your MCP client
Add it to the client's MCP config with an absolute path. For Claude Desktop
that file is ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS); for a Claude Code project use .mcp.json:
{
"mcpServers": {
"target-checklist": {
"command": "/ABSOLUTE/PATH/TO/target-mcp/.venv/bin/python",
"args": ["-m", "target_mcp.server"]
}
}
}Restart / reconnect the client. Confirm it exposes 11 tools (a stale process may show fewer — respawn it). The server is now fully usable on its own: any MCP client can run parse → assess → submit → render in a single scaffold pass.
3. (Optional, Claude Code only) Activate the fan-out skill
.claude/skills/target-checklist-fanout/ encodes the parallel-subagent
orchestration that scores the 39 leaves concurrently (~2 min vs ~20 min). It is
an accelerator, not a dependency — it only works in clients that can spawn
subagents (the Claude Code CLI, or the Claude Desktop Code/Cowork tabs; the
plain Chat tab cannot, and non-Claude clients like Codex ignore it). Without
it, everything still works via the single-pass fallback.
A Claude Code session discovers the skill when its working directory is this repo. To make it available in every session regardless of directory, copy it to the user scope:
mkdir -p ~/.claude/skills
cp -R .claude/skills/target-checklist-fanout ~/.claude/skills/For the skill to actually run, all three must be present: the server (step 2), the skill (this step), and a subagent-capable client.
Judge mode (headless/batch, optional)
Judge mode needs ANTHROPIC_API_KEY in the environment. The pinned model is
claude-sonnet-5 by default; override with TARGET_JUDGE_MODEL.
Batch / corpus runs
Scoring hundreds of papers is a headless job, not an interactive MCP call (a
multi-hour tool call would blow the client's request timeout). Use the
target-mcp-corpus CLI: it fetches + judges a list of PMCIDs concurrently,
isolates per-paper failures, retries transient errors, and rolls up the
aggregate.
# ids.txt: one PMCID per line (#-comments and blanks ignored)
ANTHROPIC_API_KEY=sk-... target-mcp-corpus ids.txt -o out/ -j 12-j/--workersbounds concurrency (default 8; raise toward your API rate limit). Judge is ~a few minutes/paper, so wall-clock ≈papers / workers × per-paper— e.g. 300 papers at 12 concurrent ≈ 1–1.5h, versus ~10–20h serial.-o/--out-dirwrites one JSON per assessment plusaggregate.jsonandsummary.json(with per-paper stamps, verdict tallies, and any failures). Without-o, the aggregate prints to stdout.--modeloverrides the pinned judge model;--no-supplementsskips supplement retrieval.
Judge mode records the resolved model id per paper, so a corpus aggregate is
truthfully provenanced and caller-independent. Re-roll-up saved assessments any
time with the aggregate_corpus MCP tool.
Tests
.venv/bin/python -m pytest tests/ -qCovers spec validation, section mapping and quote resolution, the finalize + evidence-resolution path, evidence-required and coverage-mismatch guards, applicability rules, abstract-only full-text gating, corpus aggregation, the validation harness, checklist rendering (Markdown + .docx), and prompt-hash stability.
Licensing / commons hygiene
The encoded checklist is a re-encoding of item intent in own words plus
assessor notes; it does not reproduce the TARGET checklist wording verbatim.
The original checklist is © the TARGET group under CC BY-ND 4.0. When the
Explanation & Elaboration document is released, leaves flagged
e_e_pending: true should be re-checked and the spec bumped to a clean minor
release. Do not copy E&E text verbatim.
Available Tools
11 toolsaggregate_corpusA
Roll up many assessments into per-item completeness rates plus coverage
denominators (supplement-retrieval status, full-text availability, evidence-
resolution rate). Pass an array of assessment objects as assessments, or
use_session=true to aggregate every assessment produced this session. The
completeness rates are only as valid as the sample and are not yet
gold-standard calibrated.
Inputs: assessments, use_session. Returns: note, coverage, n_papers, per_leaf, +2 more
assess_manuscriptA
Assess a manuscript against all applicable TARGET leaves in one batched
pass. document is a path, raw text, or a text_sha256 returned by
parse_manuscript.
mode='scaffold' (default) is the path for reviewing a publication: you are the LLM in the loop, so the server returns the exact assessment prompt, the tool schema, and a prompt hash for YOU to execute — read the manuscript against the rubric, produce the verdicts, then call submit_scaffold_verdicts to validate them and get the stamped result (evidence resolved to spans, provenance, ready for render_checklist).
mode='judge' is for the headless/batch case where no LLM is in the loop (e.g. a corpus run). The server makes its own pinned-model API call (requires ANTHROPIC_API_KEY) so scoring is reproducible and caller- independent, and returns the full verdict matrix directly. Overkill when an agent is already reviewing the paper interactively.
Inputs: document (required), mode, model, spec_version, +1 more. Returns: object
build_coding_sheetA
Emit blank per-paper coding sheets for human gold-standard coding: one
row per applicable leaf with its intent and verdict boundaries and empty
verdict/evidence/note fields. blind=true (default) withholds the
instrument's verdict so coders are not anchored — use blind coding for the
primary reference standard. Pass assessments or use_session=true.
Inputs: blind, assessments, use_session. Returns: result
get_checklistA
Return the encoded TARGET checklist spec: 39 scoreable leaf subitems (grouped into the 21 published items) with intent, assessor notes, signal terms, pairing links, and applicability rules. Pass a version id to pin; omit for the current default.
OPTIONAL in the review flow — introspection only. assess_manuscript already embeds the full per-leaf rubric (intents + verdict boundaries) in the prompt it returns, so calling both get_checklist and assess_manuscript for the same review duplicates the rubric payload. Use this when you want to inspect the spec on its own, not as a required step before assessing.
Inputs: version. Returns: items, e_e_status, leaf_count, spec_version, +4 more
parse_manuscriptA
PRIMARY entry point: parse a manuscript into a SectionMap with character-offset, source-tagged section spans.
PASS citation=: the manuscript's full bibliographic reference in APA style
(authors, year, title, journal, volume(issue), pages, DOI). It is carried
into the assessment and displayed on every rendered checklist so the
assessed publication is unambiguous — without it, renders can only show the
short manuscript_id. You have the paper in hand; format the reference from
its title page.
document is EITHER the raw manuscript text OR a file path — but the path
must be readable on the SERVER host. If you are an agent whose uploaded files
live on your own filesystem (a mounted upload dir, a sandbox), the server
cannot see them: paste the manuscript TEXT instead, or use parse_pmcid for an
open-access PMCID. Reach for a file path only when the file is on the same
host as this server (server-local/batch use). A path-looking string that the
server can't find raises rather than being silently ingested as its own text.
supplements is a list of server-readable file paths (PDF/docx/text) to
merge as supplementary material — PASS IT WHEN YOU HAVE IT: TTE methods
(estimand, identifying assumptions) frequently live in a supplementary
protocol table, and without a supplement the verdicts on those leaves come
back not_reported when the content was merely in an un-ingested appendix.
When supplements are provided, supplement_status defaults to 'user_provided'.
Pass supplement_status='none_exists' to assert the article has no supplement.
section_hints is a LAST RESORT for a section the detector cannot find:
{'introduction': 6543} splits whatever section contains that character
offset. Some journals print no heading for a section (an introduction that
simply follows the abstract) and interpose prose — a lay-summary box — that
no structural rule can tell apart from the section itself; check the
warnings for 'may have swallowed an unheaded introduction'. A hint never
edits the text, so text_sha256 is unchanged and a hinted parse is the same
document; the hinted section carries an empty heading because the paper
prints none. Only supply an offset you established by READING the paper, and
expect an error rather than silence if the hint cannot be applied.
Returns source-tagged section boundaries, protocol-table and flow-diagram detection over the combined text, supplement_status, and the text hash used to key later calls.
Inputs: document (required), citation, supplements, manuscript_id, +2 more. Returns: source, n_pages, citation, sections, +9 more
parse_pmcidA
CONVENIENCE / BATCH entry point: retrieve an open-access article from
Europe PMC by PMCID and parse it. Reach for this in the corpus/batch case
(no file in hand) or to auto-fetch an open-access paper's supplement; for a
single manuscript you were given, use parse_manuscript instead. Fetches JATS
main text plus (if available) PMC-hosted supplementary files, merged into
one source-tagged SectionMap. supplement_status is 'retrieved' when a
supplement was obtained, else 'not_retrieved' (a supplement may still exist
on the publisher site; absence of retrieval is not proof of absence).
Raises if no open-access full text is available. Returns the same summary
as parse_manuscript, including the text hash for assess_manuscript.
An APA-style citation is auto-built from the article's JATS metadata and
displayed on every rendered checklist; pass citation= to override it (e.g.
when the auto-built reference is incomplete).
Inputs: pmcid (required), citation, include_supplements. Returns: source, n_pages, citation, sections, +9 more
render_checklistA
Render a finalized assessment as the completed TARGET checklist form: the
21 published items (39 leaf rows, in checklist order) with the published
item wording and a Location-reported column derived from the resolved
evidence spans. The default enriched view adds, per leaf, the instrument's
verdict and the verbatim evidence quote that justifies the location;
view='official' strips to the published form's columns (Item / Checklist
item / Location reported). Returns structured rows, a completeness tally, and
a ready-to-display Markdown table. Pass either a full assessment object or
the manuscript_id of one assessed earlier this session. This is a pure
projection — no re-scoring.
Inputs: view, assessment, manuscript_id. Returns: html, rows, view, citation, +8 more
render_checklist_docxA
Write the completed TARGET checklist to a Word (.docx) file and return it.
Same content as render_checklist (published item wording + a Location-reported
column from the resolved evidence spans; enriched view adds verdict and
evidence), serialized as a submission-ready landscape table, one per
manuscript section. Pass a full assessment object or the manuscript_id of
one assessed this session. view='official' strips to the published form's
three columns.
RETRIEVING THE FILE: the return carries the document bytes as base64 in
content_base64 (with content_type and filename) — decode and save these
to get the deliverable. The file is ALSO written to path on the server host,
but that filesystem is not the caller's: if you are an agent whose files live
elsewhere, use content_base64, not path. path defaults to a writable
temp dir and is only directly useful for server-local/batch runs.
logo=True heads the document with the published TARGET banner, but ONLY on
view='official' (the author's self-report form); on the enriched view it is
ignored and the returned logo_applied is False, because the official mark on
a machine-generated assessment would imply an endorsement the instrument does
not carry. Default off.
Inputs: logo, path, view, assessment, +1 more. Returns: path, view, bytes, n_rows, +4 more
render_checklist_htmlA
Render the completed TARGET checklist as a self-contained HTML page —
same content as render_checklist, styled to the Black Swan Causal Labs
identity (canvas ground, one aligned table, verdict pills), viewable in any
browser on any host. Returns the HTML string in html (show it inline or
publish it as an artifact) and the same bytes as base64 in content_base64
(decode and save as an .html file). Carries the provenance stamp. Pass a
full assessment object or the manuscript_id of one assessed this session;
view='official' strips to the published form's three columns.
Inputs: view, assessment, manuscript_id. Returns: html, view, filename, provenance, +3 more
submit_scaffold_verdictsA
Scaffold-mode completion: validate verdicts produced by the calling
agent (leaf coverage, verdict vocabulary, mandatory verbatim evidence quotes
resolved to spans) and return the stamped assessment TOGETHER WITH the
finished, rendered deliverable. items is the verdict array from the forced
tool call — one object per leaf with id, verdict, confidence,
rationale, and (for reported/partial) evidence_quotes.
THE ARTIFACT OF RECORD is in the returned report (by default the HTML
form), carrying a provenance stamp bound to the ingested text and prompt.
That stamped render is the ONLY canonical output — present it as the
completed checklist. Need another format? Do NOT hand-assemble one: call
render_checklist (markdown) or render_checklist_docx (.docx bytes) to
re-render the same stamped artifact, or pass report_formats (any of
'html', 'markdown', 'docx') to include them here. The default is HTML only
because every extra format flows through your context window. The items
verdicts are an intermediate object; do NOT hand-assemble your own checklist
document and present it as the assessment, because it will lack the stamp
and cannot be verified. You MAY additionally write an analytic memo
(prioritized gaps, an estimand-first reading), but label it as commentary
and cite the stamp — never let it stand in for, or inherit the authority
of, the stamped form.
Set render=false to skip rendering (verdicts only). The parse cache does not
survive a server restart; if text_sha256 is no longer cached, pass
document (the same path or text) to re-parse transparently.
Inputs: items (required), text_sha256 (required), model, render, +3 more. Returns: mode, items, model, usage, +16 more
validate_against_goldA
Compute per-leaf agreement between instrument assessments and human gold-standard codings: raw agreement, Cohen's kappa, Gwet's AC1, and binary (reported-vs-rest) sensitivity/specificity with the human coding as the reference standard, plus a span-keyed disagreement list for adjudication. Agreement is reported PER LEAF; the pooled figure is orientation only. Both arguments are arrays of assessment/coding objects sharing manuscript ids and spec version.
Inputs: instrument (required), human_codings (required). Returns: n_papers, per_leaf, spec_version, disagreements, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool maps to a distinct stage of the TARGET review pipeline: ingest, assessment, rendering, and corpus validation. The only real overlap is the three render_checklist variants, but their output-format suffixes make selection unambiguous.
All names use snake_case and start with a verb, mostly following a verb_noun pattern like parse_manuscript and render_checklist. Minor deviations such as validate_against_gold and render_checklist_docx/html add modifiers or suffixes, but the overall convention remains readable and predictable.
Eleven tools is well-scoped for a complete assessment pipeline: parsing, assessing, stamping, rendering in three formats, and corpus-level aggregation/validation. Every tool has a distinct role, and none feels redundant or missing.
The tool surface covers the full TARGET workflow from manuscript ingestion through canonical stamped rendering and gold-standard validation, with no dead ends in the primary path. Minor gaps exist around session-scoped data and the lack of an explicit amendment workflow, but agents can work around these.
Maintenance
Related MCP Connectors
Traceable scientific novelty and evidence assessment with source-linked results and a human gate.
Check if references exist or were retracted, look up journal AI policies, and preview manuscripts.
ArXiv to code, replication audits, paper contradictions, citation audit, prose forensics.
Deterministic eligibility scoring for AI agents: CLEAR/HOLD/FAIL verdicts, published weights.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables scientific due diligence by grading claims against public literature, clinical trials, and filings, with explicit citations and optional attestation.4MIT
- AlicenseAqualityDmaintenanceAn MCP server implementing the ROBINS-I V2 framework for risk-of-bias assessment in non-randomized studies, with deterministic algorithms and full provenance. It enables users to parse study documents, specify target trial results, answer signalling questions with evidence-bound quotes, and compute or override domain judgements.9Apache 2.0
- AlicenseBqualityDmaintenanceEnables revision-bound source audits with exact article fingerprinting, claim-to-source mapping, quotation verification, and immutable JSON evidence reports for prepublication review.9MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables auditing scientific papers for methodological biases such as selection bias and p-hacking, and assessing citation credibility and research consensus.-