prospero-mcp

MCP server, machine-readable CLI, and installable agent skill for querying PROSPERO registered protocols and preparing guarded registration drafts.

Non-negotiable safety boundary

The prospero CLI and $prospero-research Skill deliberately do not provide Submit, Mark complete, Delete, Withdraw, Release, author-approval, or browser-writing capabilities. They stop at public discovery, evidence extraction, draft generation, validation, read-only inspection, and reviewed manual-paste assistance.

This boundary is defined by execution surface:

Surface	May read PROSPERO	May prepare local drafts	May write into the PROSPERO browser	May submit or change record lifecycle
prospero CLI	Yes	Yes	No	No
$prospero-research Skill	Yes, through MCP/CLI	Yes	No direct write capability	No
MCP core profile	Yes	Yes	No	No
MCP authoring profile (default)	Yes	Yes	No	No
MCP full profile	Yes	Yes	Only the separately guarded Save for later tool, disabled by default	No

Permanent prohibitions apply to every profile and cannot be enabled by an environment variable, confirmation hash, Skill instruction, or agent request:

• No Submit or final registration submission.
• No Mark complete or section-completion action.
• No Delete, Withdraw, or Release action.
• No author invitation, author approval, ownership change, or declaration on a person's behalf.
• No password collection, CAPTCHA handling, or authentication bypass.

The only browser-writing exception anywhere in the codebase is the MCP full-profile prospero_apply_registration_patch tool. It can only use Save for later; it is unavailable from the CLI, excluded from the default MCP profile, disabled unless PROSPERO_ENABLE_WRITES=true, and additionally requires an exact single-use dry-run receipt, confirmation hash, field allowlist, unchanged draft state, per-draft lock, and sanitized audit record. See docs/SAFETY_MODEL.md.

Quick start

npm install
npm run build
npm run setup:prospero

The guided setup finds Chrome/Edge, opens PROSPERO for website login, verifies public and authenticated access, and generates a local MCP configuration example. See FIRST_RUN.md for the complete first-time flow.

Released packages also provide prospero-mcp-setup and prospero-mcp-login executables.

The package has three coordinated entry points backed by the same safety model:

• prospero-mcp — stdio MCP server for agent tool calls.
• prospero — JSON CLI for terminal agents, scripts and CI.
• prospero-research — installable Codex skill that teaches an agent when and how to use the MCP/CLI safely.

Install the bundled skill after installing the npm package:

prospero-mcp-install-skill

Restart Codex after installation. The installer refuses to overwrite an existing skill unless --force is explicitly supplied.

CLI

prospero health
prospero search "breast cancer" --status Ongoing --year 2025,2026 --type Clinical
prospero get CRD420251181863
prospero protocol D:/research/protocol.docx --output D:/research/workbook.md
prospero protocol D:/research/protocol.docx --search
prospero protocol D:/research/protocol.docx --search --confirm <confirmation_hash>
prospero validate D:/research/answers.json --complete
prospero template --output D:/research/protocol-template.md
prospero list-drafts
prospero schema --record-version-id <uuid> --details

Successful operations emit { "ok": true, "data": ... }. Failures emit a structured error on stderr with a stable nonzero exit code. The CLI intentionally exposes no registration submission or browser-write command, including Save for later.

Tools

Public discovery:

• prospero_health
• prospero_search_protocols
• prospero_get_protocol
• prospero_similar_reviews
• prospero_build_query
• prospero_bulk_export
• prospero_compare_similar_reviews

Authenticated read-only registration support:

• prospero_record_workflow
• prospero_list_drafts
• prospero_get_registration_schema

Preparation and validation:

• prospero_generate_workbook
• prospero_protocol_to_registration — protocol → workbook → PROSPERO + optional PubMed similar-review report
• prospero_validate_registration
• prospero_prepare_registration_patch
• prospero_analyze_protocol — provenance, field states, confidence and missing-information interview
• prospero_validate_search_strategy
• prospero_compare_protocol_versions
• prospero_generate_local_preview
• prospero_monitor_similar_reviews
• prospero_protect_local_artifact / prospero_read_protected_artifact

Human-confirmed clipboard assistance:

• prospero_prepare_clipboard_queue
• prospero_copy_confirmed_field — copies one confirmed non-declaration field once; never touches the browser

Disabled-by-default write assistance:

• prospero_apply_registration_patch — saves explicitly approved fields with Save for later only.

prospero_record_workflow supports four modes:

• view_record — fetch and parse the full public PROSPERO record page by accession number.
• myprospero — open the signed-in dashboard page and report whether login is required.
• start_registration — open the registration coversheet page and report whether login is required.
• register_checklist — open the register page and extract the checklist sections when a logged-in session is available.

Environment

• PROSPERO_TOOL_PROFILE - core, authoring (default), or full; smaller profiles publish fewer MCP tools
• PROSPERO_RESPONSE_MODE - summary, standard (default), or full; controls large response fields and truncation
• PROSPERO_BASE_URL - defaults to https://www.crd.york.ac.uk/PROSPERO/api/
• PROSPERO_ACCESS_TOKEN - optional; defaults to empty string
• PROSPERO_AUTH_TOKEN - optional; defaults to a timestamp-based token per request
• PROSPERO_TIMEOUT_MS - defaults to 10000
• PROSPERO_BROWSER_PATH - optional; path to Chrome/Edge for page scraping
• CHROME_PATH / PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH - fallback browser locations
• PROSPERO_USER_DATA_DIR - optional; persistent Chrome/Edge profile used for PROSPERO login
• PROSPERO_ENABLE_WRITES - must equal true before guarded Save-for-later assistance can run; defaults to disabled
• PROSPERO_AUDIT_DIR - optional local directory for sanitized write audit records
• PROSPERO_PATCH_DIR - optional local directory for single-use dry-run receipts
• PROSPERO_NETWORK_MODE - online or offline; offline fails closed before any PROSPERO/PubMed/browser request
• PROSPERO_ALLOWED_PROTOCOL_DIRS - trusted input roots; defaults to the server working directory
• PROSPERO_ALLOWED_OUTPUT_DIRS - trusted output roots; defaults to the server working directory
• PROSPERO_CLIPBOARD_DIR - local single-use clipboard queue receipts
• PROSPERO_ENABLE_CLIPBOARD - must equal true before a reviewed field can be copied; defaults to disabled
• PROSPERO_CLIPBOARD_CLEAR_MS - clears unchanged copied text after 60 seconds by default
• PROSPERO_CACHE_DIR / PROSPERO_CACHE_TTL_MS - ignored local cache for public PROSPERO/PubMed metadata; default TTL is 6 hours and stale entries are usable only offline
• PROSPERO_PARSER_TIMEOUT_MS / PROSPERO_PARSER_MAX_OLD_SPACE_MB - isolated PDF/DOCX parser limits; defaults are 60 seconds and 256 MB
• PROSPERO_MAX_EXTRACTED_CHARACTERS / PROSPERO_MAX_PDF_PAGES - extraction ceilings; defaults are 2,000,000 characters and 1,000 PDF pages
• PROSPERO_LOCK_DIR - per-draft locks that prevent concurrent Save-for-later operations
• PROSPERO_ARTIFACT_KEY - non-Windows AES key for optional protected artifacts; Windows uses current-user DPAPI
• PUBMED_ENABLED - defaults to true; set false for PROSPERO-only operation
• PUBMED_TIMEOUT_MS - defaults to 15000
• NCBI_EUTILS_BASE_URL - defaults to the official HTTPS E-utilities endpoint
• NCBI_API_KEY - optional; PubMed works without it at NCBI's lower public rate limit
• NCBI_TOOL / NCBI_EMAIL - optional NCBI client identification; tool defaults to prospero-mcp

Login bootstrap

Run:

npm run login:prospero

This opens a browser on the PROSPERO login page using a dedicated local profile directory. Log in and the browser will close automatically after PROSPERO's sessionStorage login state is captured. The state is stored in .prospero-profile/prospero-session.json and restored for later myprospero, register, and reviewcoversheet access. On Windows the session payload is protected with current-user DPAPI. The entire profile directory is ignored by Git; do not share it.

For a complete first-time setup with checks and a generated MCP configuration, prefer:

npm run setup:prospero

Registration workbook

PROSPERO_REGISTRATION_WORKBOOK.md mirrors the 12 registration sections and 39 fields. It is intended for drafting and confirming answers outside PROSPERO before manually pasting them into the website. The MCP does not automatically submit registrations.

For a new review, start with the blank English templates/PROSPERO_PROTOCOL_TEMPLATE.md. Its headings are machine-aligned with all 39 registration fields. The Chinese docs/PROSPERO_PROTOCOL_WRITING_GUIDE.md explains what to write, current required/word constraints, automation confidence, common errors, similar-review wording and final quality checks.

prospero_generate_workbook can extract candidate content from TXT, Markdown, PDF and DOCX protocols. Extracted content is a draft and must be reviewed before use.

For the complete workflow, call prospero_protocol_to_registration. It generates the workbook first and returns the exact planned PROSPERO/PubMed queries plus a confirmation hash without sending them. Return external_query_confirmation_hash on the second call to authorize public-database searching. PubMed is optional: disabled access, no results, timeout, rate limiting or service failure produces a source status instead of failing the workbook or PROSPERO results. An NCBI API key is not required for low-rate use. See the NCBI E-utilities documentation and NCBI disclaimer.

Example with a local protocol:

{
  "protocol_path": "D:/research/protocol.docx",
  "include_pubmed": true,
  "max_prospero": 25,
  "max_pubmed": 25,
  "write_workbook": true
}

Use "include_pubmed": false or PUBMED_ENABLED=false for PROSPERO-only discovery. Set PROSPERO_NETWORK_MODE=offline for a fully local run that blocks PROSPERO, PubMed and browser access.

Safe automation workflow

1. prospero_analyze_protocol produces source quotes/page or line locations, confidence, missing/extracted/generated/needs_confirmation/confirmed/stale/blocked states and only the unresolved interview questions.
2. prospero_validate_search_strategy and consistency checks detect method conflicts without inventing corrections.
3. prospero_protocol_to_registration previews outbound queries; the reviewed hash is required before protocol-derived terms leave the machine.
4. prospero_generate_local_preview creates an escaped local HTML review page.
5. prospero_prepare_clipboard_queue accepts only explicitly confirmed non-declaration fields; copying is opt-in, single-use, hash-audited and auto-cleared.
6. prospero_compare_protocol_versions and prospero_monitor_similar_reviews identify stale confirmations, method changes and new candidate reviews.

Protocol and output paths are resolved through real paths and must remain inside configured roots. Outbound queries are blocked if they appear to contain email addresses, phone numbers, tokens or clinical identifiers.

Protected artifacts also use two steps: the first read returns metadata and a SHA-256 confirmation hash; plaintext is released only when that exact hash is returned. PDF and DOCX extraction runs in a bounded child process. Public search caching never stores login state or protocol text.

Write safety

CLI, Skill, MCP core, and the default MCP authoring profile are read-only with respect to the PROSPERO browser. They generate local drafts and support manual paste but cannot save browser fields.

The MCP full profile contains one separately guarded exception. When explicitly enabled, it requires a selected draft, a local single-use dry-run receipt and confirmation hash, the tested field-route allowlist, unchanged draft timestamp, unchanged old values, and a per-draft lock. It can only click Save for later and creates a sanitized audit record.

Automation for Mark complete, Submit, Delete, Withdraw, Release and author approval is intentionally unsupported. See docs/SAFETY_MODEL.md.

Release safety

Authentication profiles, sessions, environment files, logs, downloaded PDFs/ZIPs, and generated local configuration are excluded from Git. The npm package uses an explicit public-file allowlist.

Before publishing, run:

npm run release:check

The release build omits TypeScript declarations and source maps; the development build retains them for local debugging.

Review SECURITY.md for the exact local credential path and release checklist.

Development contracts and roadmap are in docs/TOOL_CONTRACTS.md and docs/DEVELOPMENT_PLAN.md.

Example

Search by keyword:

{
  "query": "covid",
  "page": 1,
  "page_size": 20
}

Search by exact accession:

{
  "accession_number": "CRD420251016642"
}

Fetch a public record page:

{
  "mode": "view_record",
  "accession_number": "CRD420251007996"
}

Open the registration flow:

{
  "mode": "start_registration"
}

Extract the registration checklist:

{
  "mode": "register_checklist"
}