Metadata-Version: 2.5
Name: forrt-research-mcp
Version: 0.1.2
Summary: MCP server for producing verifiable FORRT nanopublication chains — grounded quote verification and compact Science Live constellation projections, for replications and new research alike.
Project-URL: Homepage, https://github.com/ScienceLiveHub/forrt-research-mcp
Project-URL: Repository, https://github.com/ScienceLiveHub/forrt-research-mcp
Project-URL: Replication template, https://github.com/ScienceLiveHub/forrt-replication-template
Project-URL: Science Live, https://sciencelive4all.org
Author: Anne Fouilloux
License: MIT
License-File: LICENSE
Keywords: FORRT,mcp,nanopublication,open-science,replication,reproducibility,science-live
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pypdf>=4
Requires-Dist: rdflib>=7
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# forrt-research-mcp

<!-- mcp-name: org.sciencelive4all/forrt-research-mcp -->

An MCP server for **producing** verifiable FORRT nanopublication chains — the
tools a researcher needs while doing the work, not while looking for it. It
serves all three shapes of study on the same rails: reproduction, replication,
and research that starts from scratch.

It is the third of three servers that compose:

| Server | Question it answers |
|---|---|
| [OpenAIRE MCP](https://github.com/ScienceLiveHub/replication-radar/blob/main/docs/openaire-mcp.md) | What is in the literature? |
| [`replication-radar`](https://github.com/ScienceLiveHub/replication-radar) | What is worth replicating, and has it been done? |
| **`forrt-research-mcp`** | **How do I produce a chain that is correct and verifiable?** |

Built for the workflow in
[`forrt-replication-template`](https://github.com/ScienceLiveHub/forrt-replication-template),
but it needs nothing from that repo — any agent can call it.

## Scope: reproduction, replication, and research from scratch

All three work here, and they use the same chain:

```
anchor → AIDA → Claim → Study → Outcome → CiTO
```

**Step 01 is one of three anchors, and they are not variants of one form.**
Which anchor fits is independent of whether the study is a reproduction, a
replication or original research:

| Anchor | Required fields | Notes |
|---|---|---|
| `01_quote` Quote-with-comment | `paper`, `quotation`, `comment` | no type, no label. `quotation` is capped at 500 characters and `comment` at 800 — in the template's own regex, not in prose |
| `01_pico` PICO question | `label`, `description`, `type`, + P/I/C/O descriptions | the only anchor with a question-type vocabulary (5 terms) |
| `01_pcc` PCC question | `label`, `description`, + P/C/C descriptions | **no `type` field at all** |

The three share **no field ids whatsoever**, so call `template_fields` on the
anchor you are actually using rather than assuming they match. The
`pico_question_type` vocabulary is named for PICO deliberately: a PCC question
has no type to look up.

`verify_quote` applies to the Quote anchor only — and that is the one anchor
with a dedicated tool, because a quotation is the one field whose correctness
can be *proved* rather than reviewed.

`constellation` and `prior_work` surface a question anchor with its `framework`,
`label`, full question text and its framework's `components` — PICO's
population / intervention / comparator / outcome, PCC's population / concept /
context. Question nodes keep all of that in a `question` object and leave their
top-level `label` empty, so anything reading them like a quote returns nothing.
Tested against two real published question nanopubs.

For a study starting from scratch, the Claim is **your own hypothesis**, derived
from your own question or from the work you are building on. The FORRT Claim
template's `source` is optional, so it needs no external paper — and the
Claim-before-Study order then reads as
**pre-registration**, not as a mismatch. `verify_chain` takes a `mode`
(`auto` / `replication` / `reproduction` / `new_research`) that changes only what
is *required*: from-scratch research has no existing work to cite, so no CiTO
step and no cited DOI are expected.

**The one place the templates still assume an original** is the `study_type`
vocabulary on `04_study`, whose three terms are all replication-flavoured
(Replication Study, Reproduction Study, or both). There is no term for *an
original study testing its own claim*. Three field prompts read oddly too —
`scope` and `methodology` say "is reproduced/replicated", and the Outcome's
`conclusion` says "about the original claim" — but they are only wording;
`validationStatus` (validated / partially supported / contradicted /
inconclusive / not tested) describes testing your own hypothesis perfectly well.

So closing the gap is plausibly **one added vocabulary term and three reworded
prompts**, not a new template family. When that lands, this server picks it up
with no code change: `template_fields` and `vocabulary` fetch live, and
`driftedFromSnapshot` flags the supersession so the vendored copy gets re-cut.

> **A note on using "Reproduction Study" for from-scratch work.** It is a
> reasonable workaround while the vocabulary lacks a better term, but the
> template means the replication-science sense — *"direct reproduction: same
> methodology, same tools"*, i.e. re-running someone else's analysis — not the
> RSE sense of "my work is reproducible". Downstream consumers read it the first
> way: `replication-radar`'s verdict overlay and `verified_claims` will present
> the study as verification of an existing claim.

## Why a server and not a prompt

Two jobs here look like reasoning but are not, and doing them in an agent loop
makes them unreproducible and expensive:

**1. Reading a published chain.** `/np/constellation` walks the FORRT citation
graph bidirectionally and returns everything it reaches. For a single
marine-heatwave chain that is **330 KB, 98 nodes and 1012 edges — of which 64
nodes are AIDA statements belonging to entirely different studies**. Handing
that to an agent burns its context and invites it to reason over another paper's
claims. `constellation` returns the same chain in ~16 KB (4.7 %).

**2. Checking a quotation is real.** A FORRT Quote nanopub must be verbatim. That
is a string search, not a judgement — so it should be a tool that cannot be
talked out of its answer, and that anyone can re-run to get the same result.

## What it does not do

It does not search papers (that is the OpenAIRE MCP), rank replication targets
(that is `replication-radar`), or write nanopub content. It also does not
*extract* claims: choosing which sentence carries a paper's headline claim is a
judgement, and wrapping a judgement in a tool would not make it reproducible — a
model behind a tool boundary is exactly as non-deterministic as one in the agent
loop. The division this server is built around:

| The model proposes | This server disposes |
|---|---|
| Which sentence is the claim | Whether that sentence is in the PDF, where, under what SHA-256 |
| How to phrase the AIDA | What fields the template actually has, and their caps |
| Which claim type or CiTO relation applies | Which values the form will actually accept |
| Which Wikidata topic is meant | Whether that QID exists and is of the right type |
| Which paper to cite | Whether that DOI resolves, and to what |
| Whether to extend or dispute prior work | What prior chains already claimed |

## Install

```bash
pipx install forrt-research-mcp
claude mcp add forrt-research -s user -- forrt-research-mcp
```

User-scoped (`-s user`) so it is available in every session and folder, and does
not clash with a per-repo config. For other agents, the stdio command is
`forrt-research-mcp`.

```bash
# optional
export SCIENCELIVE_API_BASE="https://api.sciencelive4all.org"  # default (production)
export SCIENCELIVE_API_KEY="sl_…"   # /np/constellation is a public read
```

> The default base is **production**. To test against the dev deployment, set
> `SCIENCELIVE_API_BASE=https://api-dev.sciencelive4all.org`. A constellation
> that nobody has requested recently can take ~60 s to build; after that it is
> cached for 4 h and returns in well under a second.

## Tools

### `verify_quote(pdf_path, quotation)`

Proves a candidate quotation is in a source PDF before it is published as
verbatim. Returns a graded verdict with page, character offsets and the file's
SHA-256:

| Verdict | Meaning |
|---|---|
| `exact` | byte-identical to the extracted page text |
| `normalized` | matched after whitespace / ligature / typographic punctuation / line-break-hyphen repair |
| `extraction_tolerant` | additionally ignored hyphens and punctuation spacing |
| `whitespace_insensitive` | additionally deleted every space — for text layers that break words apart |
| `not_found` | **not in this PDF — do not publish it** |

Every tier canonicalises *formatting only* — never words, digits or order. A
quotation with one digit changed scores ~0.91 similarity against the source and
is still `not_found`; on a miss, `closest.text_in_pdf` shows what the paper
actually says there.

A tier below `exact` is normal. PDF extraction inserts line breaks, loses
hyphens, and sometimes breaks words apart entirely:

- the quotation published in the real marine-heatwave chain matches only at
  `extraction_tolerant`, because `pypdf` reads the paper's `35-year` as `35year`
  and `(p <` as `( p <`;
- Hundhausen et al. 2024 renders its own abstract as `CP en semble`, `largest c
  hanges`, `prec ipitation` — spaces *inside* words, which no punctuation rule
  can undo. That needs `whitespace_insensitive`, which deletes every space and
  therefore does not verify word boundaries; it declines to run below 40
  characters, where two short texts could collide.

**"Character-for-character" is not literally achievable against extracted PDF
text**, which is why the result is graded rather than boolean.

Words split across a line break (`convection-\npermitting`) are rejoined at the
`normalized` tier. A *suspended* hyphen (`15- and 30-minute`) is deliberately
NOT rejoined — the rule requires a line break, because joining those would
corrupt the text.

### `constellation(uri, depth=5, max_nodes=80)`

The FORRT chain(s) reachable from a published nanopub URI, projected to
agent-size: chains with their steps in chain order, the apex CiTO, any Research
Synthesis, and the Quote/Question anchors attributable to this paper.

Read `citedPaper`, not the API's top-level `paperDoi` — see *Upstream
quirks* below.

`stepsPresent` legitimately omits steps: a CiTO at the apex of a constellation
is hoisted out of its chain, and Quote/AIDA anchors are often not enumerated.
Missing does not mean unpublished.

### `prior_work(uri)`

What has already been claimed about a paper — the starting point for new work,
replication or otherwise. Per completed chain: claim type, `scope`, `method`,
`deviations`, verdict, confidence, repository, and `limitations`.

`limitations` is the field to read most carefully. It is where previous authors
stated, in signed and immutable words, what their study did *not* cover — which
is often exactly where the next study begins. In the marine-heatwave chain it
records that the paper's better-known 54 % headline describes a different
analysis over a different period and was not tested.

### `constellation_raw(uri, …)`

The unprojected response, for debugging the graph or an upstream data problem.
Large; prefer `constellation`.

### `template_fields(step, live=True)` · `vocabulary(name, live=True)` · `list_schemas()`

A nanopub template **is** the schema for its chain step, so these turn "never
invent a field name" and "never invent a claim type" from rules an agent has to
remember into a lookup that can only return real values.

`template_fields` returns the real field ids, prompts, required/repeatable
flags, and the `regex` / `prefix` / `datatype` constraints — which is where the
Quote template's character cap actually lives, rather than in a hand-written
doc that drifts. `step` accepts `05_outcome`, `05`, or `outcome`.

`vocabulary` returns the allowed values of a controlled vocabulary, taken from
the real restricted-choice field:

| Name | From | Terms |
|---|---|---|
| `claim_type` | `03_claim.forrtType` | 7 |
| `study_type` | `04_study.type` | 3 — the Reproduction vs Replication distinction |
| `validation_status` | `05_outcome.validationStatus` | 5 |
| `confidence_level` | `05_outcome.confidenceLevel` | 5 |
| `cito_relation` | `06_citation.cites` | 43, via a separate value-list nanopub |
| `question_type` | `01_pico.type` | 5 |

Both fetch live by default and fall back to a **bundled snapshot** when the
network is unavailable — always reporting which was used, and setting
`driftedFromSnapshot` when the upstream template has been superseded. A drifted
result means the live values win and this package needs re-vendoring; it is a
loud, reviewable event rather than slow silent divergence.

`cito_relation` is the one vocabulary that cannot be resolved offline: it lives
in a separate value-list nanopub. Offline it returns `source:
"unavailable-offline"` with a warning rather than an empty list, because an
empty list reads as "no valid values."

### `verify_chain(published_path, repo_url="")`

The final check before announcing a chain. Point it at a `nanopubs/PUBLISHED.md`
ledger; `green` is true only when nothing failed. Read-only — it never edits,
retracts or supersedes.

| Check | What it means |
|---|---|
| ledger | every required step (01–06) has a URI |
| reachable | every URI is really published |
| repository | the Outcome's archived version DOI resolves |
| cited-doi | every DOI the chain cites resolves |
| verdict-relation | **the CiTO relation agrees with the Outcome's verdict** |

That last one is the failure most worth catching: `Validated` implies
`confirms`, `PartiallySupported` implies `qualifies`, `Contradicted` implies
`disputes`. A mismatch means the Outcome and the Citation disagree about what
the replication actually found — a chain that cites `confirms` for a paper it
contradicted is worse than no chain at all.

**A constellation alone cannot verify a chain**, which is why this does not try.
On both real chains the walk stops short of the upstream anchors, so anything it
does not enumerate is checked by fetching its TriG from the bare
`w3id.org/np/` resolver — the `/sciencelive/np/` form serves an HTML viewer that
answers 200 and would pass a status-only check while serving no nanopub. A row
reading *"not enumerated by the walk but its TriG resolves"* is a pass, not a
warning.

The Outcome's repository is expected to be a **Zenodo version DOI**, not a
GitHub URL: a version DOI pins the archived state the outcome was computed
from, where `github.com/ORG/REPO` is a moving target. Both are accepted; a DOI
is checked by resolving it, a URL by comparing it to `repo_url`.

Both published chains verify green, matching the hand-run verification recorded
in marine-heatwave's ledger.

### `validate_chain_draft(path)`

Checks `nanopubs/chain-draft.json` — **the artifact that actually gets
published** — before it is handed to the Science Live chain wizard. Run it at the
end of Phase 5b, after `pixi run build-chain-draft` and before pushing the file
and opening the wizard URL.

The markdown drafts are the authoring format; `build_chain_draft.py` turns them
plus `CITATION.cff` and the templates into this file, which the wizard pre-fills
each step from and a human reviews and signs. `validate_draft` checks the input;
this checks the artifact.

What it catches that reading the file cannot:

- a **superseded `template_uri`** — invisible in the JSON, but it makes the
  wizard pre-fill the old form;
- a `prefill` key that is neither a template field nor a known platform
  form-field, which the wizard silently drops;
- a complex field in the wrong shape — `06_citation.st02` must be
  `[{cites, cited}]` with at least one entry, and `04_study.disciplineSelection`
  is a **single object, not an array** (the one asymmetry in the contract);
- a required field neither prefilled nor carried forward;
- a value over the template's own cap, an invalid vocabulary term, a malformed
  date, an unresolved `{{TOKEN}}`, or a DOI that does not resolve;
- a `carry_forward` edge running backwards through the chain.

Fields the wizard fills itself are exempt rather than reported missing:
`02_aida` has no `project`, `03_claim` no `aida`, `04_study` no `claim`.

Both of this project's real chain drafts validate clean, and 13 deliberate
mutations of one are each caught.

### `validate_draft(path)` · `validate_drafts(directory)`

The pre-flight checklist in `docs/forrt-form-fields.md`, actually executed. One
call checks a drafted nanopub end to end: field ids against the live template,
choice values against its enumeration, length caps against its regex, DOIs
against the registry, QIDs against Wikidata. `publishable` is true only when
nothing came back as an error.

This is the composition the other tools exist for — individually they answer
"is this value real?", together they answer "is this draft publishable, and if
not, exactly where is it wrong?"

**Three placeholder conventions, and only one is a problem.** Getting this wrong
made the checker useless on real drafts, so each is handled explicitly:

| In a draft | Meaning | Severity |
|---|---|---|
| `«URI of step 05 …»` | back-reference; the chain wizard fills it from the published step | info |
| `{{ZENODO_VERSION_DOI}}` | release-time token; the release workflow substitutes it | warning |
| anything else standing in for a value | genuinely unfilled | **error** |

A draft whose required fields are nearly all empty is reported once as an
unfilled skeleton — "it has not been drafted yet" — rather than as a wall of
per-field errors.

**What it cannot see.** Values a draft puts in prose or a markdown table rather
than behind a `<!-- field: … -->` marker are reported as `coverage` warnings,
never as missing. The CiTO step's citation list is the known case: `cites` and
`cited` live in a table in both repos checked.

Validated against two real published chains (marine-heatwave and Sado estuary):
all six published steps pass in both, with the only remaining flags being an
unpublished step 07 and the release tokens above.

### `resolve_doi(doi)`

Does this DOI resolve, and to what? `resolves: false` means it is not
registered — **a well-formed DOI is not a real one**, and a fabricated one is
indistinguishable from a genuine one until something asks the registry. Returns
the registered title, authors, year and container so you can confirm it is the
paper you meant, not merely a paper that exists. Accepts bare, URL, and `doi:`
forms. A 5xx is reported as transient rather than as a bad DOI.

### `wikidata_lookup(query, expected_type="", limit=5)`

Real Wikidata candidates for a term, with their actual P31/P279 types. Pass
`expected_type` as a QID and each candidate is marked `typeMatches`.

Checked against the ten Wikidata terms in this project's published chains — the
QIDs `build_chain_draft.py` resolved and signed — it returns the published QID
at rank 1 for all ten (marine heatwave, sea surface temperature, climate change,
time series analysis, chlorophyll a, remote sensing, estuary, Sentinel-2, water
quality, atmospheric correction).

It deliberately **does not choose** — picking the right sense of an ambiguous
label is a judgement. Searching `Bombus` with `Q16521` (taxon) returns the
insect genus as a match and *the album of the same name* as not, which is
exactly the failure worth catching before a QID gets signed into a nanopub.
Candidates are annotated, never filtered: a near miss is often the informative
result. Zero candidates means leave the field empty — never fall back to a QID
from memory.

## Upstream quirks this handles

Found by probing live data rather than reading the API contract, and each one is
pinned by a test against a real recorded payload (two constellations, from
unrelated studies):

1. **Cloudflare rejects urllib's default User-Agent.** The API runs on
   Cloudflare Workers, whose bot protection answers `Python-urllib/3.x` with
   HTTP 403 — same URI, same key, 200 under any normal agent. Every request this
   client makes sets an explicit `User-Agent`. Do the same in your own client;
   no hermetic test can catch it.
2. **`paperDoi` can name the wrong paper.** It is chosen by frequency across the
   whole walk, so a neighbouring study's Quote nanopubs can outvote the chain's
   own citation. On the marine-heatwave chain it reports the LifeWatch ERIC
   paper (4 unrelated quotes) instead of Oliver et al. 2018, which the chain's
   CiTO actually cites — and it names **the same wrong paper** from the
   unrelated Sado-estuary entry point, so this is systemic, not one bad record.
   `citedPaper` derives the paper from the CiTO and sets
   `disagreesWithReported` when the two differ.
3. **The walk stops short, and missing does not mean unpublished.** Two real
   chains enumerated `[Claim, Study, Outcome]` and `[Study, Outcome, CiTO]`,
   while the Quote, AIDA and Claim nanopubs listed in those repos'
   `PUBLISHED.md` were published and merely unreachable. `stepsNotEnumerated`
   reports the gap. **A constellation alone cannot verify a complete chain** —
   fetch those URIs' TriG directly.
4. **`quote.quotedText` comes back empty** on nanopubs using the current quote
   template. The text survives in `label` and in two untagged excerpts — the
   quotation and the annotator's comment, in no guaranteed order. We match them
   against the label stem rather than assuming a position, and report the
   recovery in `text_source`.
5. **The apex CiTO is hoisted** out of `chains[].steps[]` to top level.
6. **The `/sciencelive/np/` URI form serves an HTML viewer** that answers 200, so
   a status-only reachability check passes even when no nanopub is served. We
   normalise to the bare `w3id.org/np/` resolver and assert the body is RDF.

## Checking against every real artefact

The test suite is hermetic: it pins behaviour against recorded data, which
prevents regressions but **cannot discover a wrong premise**. Every serious bug
in this server was a wrong premise, and each surfaced only when the tools met
real data they had not seen. So "have we tested comprehensively?" is not a
judgement call here — it is a computation with a visible denominator:

```bash
python scripts/check_corpus.py /path/to/your/study/repos
```

It discovers every repository with a `nanopubs/` directory, runs the applicable
tools against each artefact, and prints what passed out of what was found.
Findings are *not* automatically failures — an empty required field is a true
statement about a draft. What it exits non-zero for is a **crash or a parse
failure**, because those mean a tool could not read a real artefact at all.

The denominator is only as good as what is on disk. A chain that is not under
that root is not covered, and a green run does not say otherwise.

## Development

```bash
pip install -e '.[dev]'
pytest
```

All 287 tests are hermetic and need no network, no API key, and no live
service: the constellation fixtures are real recorded `/np/constellation`
responses, quote tests build minimal PDFs in-process that reproduce the
extraction artifacts deliberately, and the template/DOI/Wikidata tests stub HTTP
with recorded payloads. The suite stays green through an upstream outage.

The bundled template snapshot under `src/forrt_research_mcp/data/` is vendored
from `ScienceLiveHub/forrt-replication-template`, as is `template_spec.py`.
Re-vendor when `template_fields` reports `driftedFromSnapshot`.

## License

MIT — see [LICENSE](LICENSE).
