clinical-trial-design

A Claude Code plugin and MCP server for end-to-end clinical trial design.

clinical-trial-design helps biostatisticians and clinical trialists design Phase 2 and Phase 3 confirmatory studies through a conversational interface, backed by validated R packages (gsDesign, gsDesign2, graphicalMCP).

v0.0.13 — pre-beta. Nine MCP tools across single-primary endpoint design (binary, continuous, time-to-event under PH and four NPH frameworks), multi-hypothesis design (co-primary, multi-population, graphical multiplicity / Maurer-Bretz), Monte-Carlo verification, and Word/PDF reporting. Reasoning-chain schema with sponsor-confidential redaction. Operational kernel solves accrual ↔ duration ↔ N, plus optional max_n / max_duration feasibility warnings. 288/288 R tests, 18/18 MCP smoke. Published to npm (clinical-trial-design) and the official MCP registry (io.github.wei-ai-lab/clinical-trial-design). Full change history in CHANGELOG.md; API contract in API_STABILITY.md.

What it is

clinical-trial-design has four layers:

| Layer | Role | |---|---| | R package (r-package/ClinicalTrialDesign) | Pure R statistical computation engine. Wraps and extends established packages (gsDesign, gsDesign2, graphicalMCP, simtrial) behind a unified result schema. | | MCP server (mcp-server/) | Exposes the R functions as typed tools over the Model Context Protocol so Claude Code — or any MCP client — can call them. | | Skill (skills/clinical-trial-design/) | Domain-expert prompt. Translates a user's design brief into the right tool calls and interprets results in clinical-trial terms; includes a 9-step Phase 3 orchestration workflow with waypoints. | | Benchmark corpus (benchmarks/) | 176 curated public-trial designs across 21 family directories. Each case is human-readable Markdown plus machine-readable YAML with expected outputs and tolerances. |

Plus an eval harness under eval/ (11 reproducible scenarios × six scoring dimensions × multi-vendor Claude family) and an examples gallery under examples/ (5 published trials reproduced end-to-end).

What clinical-trial-design actually computes

| Family | Status | |---|---| | Fixed-sample binary | ✅ super / NI / equivalence | | Fixed-sample continuous | ✅ super / NI / equivalence | | Fixed-sample TTE — PH log-rank | ✅ super / NI | | Fixed-sample TTE — NPH MaxCombo / RMST / milestone | ✅ superiority | | Group-sequential binary / continuous | ✅ super / NI; futility via test.type | | Group-sequential TTE — PH | ✅ super / NI; events via Schoenfeld + OBF inflation by default (regulatory-defensible; events_calc selector) | | Group-sequential TTE — NPH (MaxCombo / WLR / AHR) | ✅ superiority | | Multi-hypothesis — co-primary endpoints | ✅ fixed-sequence / alpha-split / Bonferroni | | Multi-hypothesis — multi-population (subgroup + ITT) | ✅ nested or disjoint relations | | Multi-hypothesis — graphical (Maurer-Bretz) | ✅ initial weights + transition matrix + Rule-3 validator | | Adaptive (SSR, enrichment, selection) | ⏳ corpus has cases; wrappers are roadmap | | MAMS / platform / basket / umbrella | ⏳ corpus has cases; wrappers are roadmap |

Status

| Layer | State | |---|---| | R package | ✅ 288/288 testthat | | MCP server | ✅ 9 tools over stdio, esbuild bundle, 18/18 smoke | | Skill | ✅ 9-step Phase 3 orchestration workflow + waypoints | | Benchmark corpus | ✅ 176 curated public-trial cases / 21 families | | Plugin manifest | ✅ .claude-plugin/plugin.json + marketplace.json | | npm package | ✅ clinical-trial-design@0.0.13 published 2026-04-29 | | Official MCP registry | ✅ io.github.wei-ai-lab/clinical-trial-design | | CI release-gate | ✅ .github/workflows/release-gate.yml (R tests + R CMD check + MCP build/smoke + scenario validation) | | LLM benchmark harness | ✅ 11 scenarios × 6-dimension rubric (eval/) | | Pre-beta hand-off | ✅ items tracked in BETA_HANDOFF.md |

Tool surface

Nine MCP tools — three single-primary design tools, three multi-hypothesis design tools, three meta tools. Same unified result schema across families.

Single-primary design tools (3)

| Tool | Endpoint | Selectors | R backend | |---|---|---|---| | design_binary | event / no-event | design_class ∈ {"fixed", "group-sequential"} | gsDesign::nBinomial, gsDesign::gsDesign | | design_continuous | mean difference | design_class ∈ {"fixed", "group-sequential"} | gsDesign::nNormal, gsDesign::gsDesign | | design_survival | time-to-event | design_class × model ∈ {"ph", "maxcombo", "rmst", "milestone", "wlr", "ahr"} | gsDesign::nSurv/gsSurv (PH); gsDesign2::fixed_design_* and gs_design_* (NPH) |

All three accept comparison ∈ {"superiority", "non-inferiority", "equivalence"} (equivalence on fixed-sample binary / continuous only), alpha, power, sided, allocation_ratio, GS parameters (k, timing, sfu, sfl, test.type), an optional operational block, and an optional reasoning_chain array (citation trail with source_type tags).

design_survival adds events_calc ∈ {"schoenfeld" (default), "lachin-foulkes", "freedman"} for PH GS designs and accepts control_hazard_rate (events per patient-year) as an alternative to control_median.

Multi-hypothesis design tools (3)

| Tool | When to use | Strategies | R backend | |---|---|---|---| | design_co_primary | Two or more co-primary endpoints (PFS+OS, CV death+HHF, mixed binary+continuous) | fixed-sequence (hierarchical, default), alpha-split (weighted), bonferroni | Per-endpoint dispatch to single-primary tools at the appropriate effective alpha; total N = max across endpoints | | design_multi_population | Same endpoint tested across multiple populations (biomarker subgroup + ITT, nested PD-L1 strata) | Same three strategies; relation ∈ {"nested", "disjoint"} | Same per-population dispatch; for nested, total N driven by largest implied-enrolled-N (events / prevalence); for disjoint, total N is the sum | | design_graphical_multiplicity | Multi-hypothesis with alpha recycling (Maurer-Bretz) — mixed primary+secondary, dose-response | Graphical procedure with user-supplied initial weights and transition matrix; built-in Rule-3 validator | graphicalMCP::graph_create; per-hypothesis sample-size at worst-case alpha |

Meta tools (3)

| Tool | Purpose | |---|---| | validate_against_benchmark | Replay a benchmark case through its matching design tool and diff against expected values within tolerance. | | verify_design | Monte Carlo cross-check of any result. Closed-form simulation under H0 and H1; ±2 pp power / ±0.5 pp Type I tolerance gate. Supports fixed and GS designs on binary, continuous, and PH-survival endpoints. | | design_report | Render a clinician-readable design summary in markdown (default), Word (format="docx" via officer), or PDF (format="pdf" via rmarkdown + Pandoc). Reasoning chain rendered as a Word table; sponsor-confidential entries surface a redaction warning at the top of the document. |

Operational kernel

Every endpoint design tool accepts an operational block that solves the simple relations accrual_rate × accrual_duration = sample_size_total and total_trial_duration = accrual_duration + follow_up_duration (plus target_events = sample_size_total × cumulative_event_rate(...) for survival, via uniroot over the closed-form pooled exponential-PH event probability — same kernel gsDesign::nSurv uses internally).

Supply any 0–4 of {accrual_rate, accrual_duration, follow_up_duration, total_trial_duration} plus optional caps {max_n, max_duration}. The solver fills in the missing values with an audit trail (given, derived); cap violations surface as structured feasibility_warnings rather than silent over-cap designs.

Quick start

Prerequisites: R ≥ 4.2, Node ≥ 18. No npm install step (the MCP server ships pre-bundled in mcp-server/dist/index.js) and no remotes::install_local step (the launcher sources r-package/ClinicalTrialDesign/R/*.R directly out of the plugin cache).

1. Install CRAN dependencies (one-time)

R -e 'install.packages(c("gsDesign","gsDesign2","graphicalMCP","jsonlite","officer","rmarkdown"))'

The first four are runtime imports; officer and rmarkdown are Suggests: and only needed for design_report(format="docx") / format="pdf".

Tested dependency versions

clinical-trial-design v0.0.13 was developed and tested against the versions below. CRAN's latest is usually fine; pin to these floors only if you hit a version-skew issue.

| Layer | Dependency | Tested version | |---|---|---| | R runtime | R | 4.5.3 (works on R ≥ 4.2) | | R imports | gsDesign | 3.9.0 | | | gsDesign2 | 1.1.8 | | | graphicalMCP | 0.2.9 | | | jsonlite | 2.0.0 | | R suggests | officer | 0.6.x (for design_report(format="docx")) | | | rmarkdown | 2.20+ (for design_report(format="pdf"); Pandoc system dep) | | | simtrial | 1.0.2 (for verify_design Monte Carlo) | | | rpact | 4.4.0 | | | yaml | 2.3.12 | | | testthat | 3.3.2 | | Node runtime | Node | 22.22.1 (works on Node ≥ 18) | | Node bundled | @modelcontextprotocol/sdk | ^1.0.0 (inlined in dist/index.js) | | | zod | ^3.23.0 (inlined) |

2. Install the plugin

Method A — slash commands (recommended, inside Claude Code)

/plugin marketplace add wei-ai-lab/clinical-trial-design
/plugin install clinical-trial-design@wei-ai-lab

After install, restart Claude Code so it loads the bundled MCP server. Confirm with /plugin (clinical-trial-design should be listed and enabled at version 0.0.13).

Method B — host shell (equivalent, scriptable)

claude plugin marketplace add wei-ai-lab/clinical-trial-design
claude plugin install clinical-trial-design@wei-ai-lab
claude plugin list      # confirm: clinical-trial-design@wei-ai-lab, version 0.0.13, enabled

If anything goes wrong, claude plugin validate /full/path/to/clinical-trial-design will tell you whether the marketplace + plugin manifests parse cleanly.

Quick local-dev alternative — skip the marketplace step and load the plugin directly from a checkout:

git clone https://github.com/wei-ai-lab/clinical-trial-design ~/clinical-trial-design
claude --plugin-dir ~/clinical-trial-design

Environment overrides

The MCP server auto-discovers Rscript in the usual locations (/opt/R/<version>/bin/, /usr/local/lib/R/bin, /usr/lib/R/bin, /usr/lib64/R/bin, /usr/local/bin, /usr/bin, /opt/homebrew/bin, /Library/Frameworks/R.framework/Resources/bin). For non-standard installs, override:

• DESIGNR_RSCRIPT=/full/path/to/Rscript — explicit path to your R binary.
• DESIGNR_LAUNCHER=/full/path/to/launcher.R — override the R launcher (rare).

Posit Workbench, RStudio Server, VS Code Remote, and other sandboxed Claude Code hosts

Claude Code in these environments doesn't always inherit your shell's environment when it spawns the MCP server. Set the env var in ~/.claude/settings.json (NOT just ~/.bashrc):

{
  "env": {
    "DESIGNR_RSCRIPT": "/opt/R/4.5.1/bin/Rscript"
  }
}

As of v0.0.14, the auto-discovery walk usually finds Posit Workbench's managed installs at /opt/R/<version>/bin/Rscript automatically, so the env override is only needed for non-standard setups. If you still see rscript_spawn_failed, the error message now reports exactly which paths were checked.

(The DESIGNR_* prefix is preserved as a wire-format contract; see API_STABILITY.md.)

Standalone MCP server (without Claude Code)

The MCP server is published to npm as clinical-trial-design. Any MCP-aware client (Claude Desktop, Cursor, Continue, custom MCP host) can launch it via npx:

npx clinical-trial-design@latest

The package bundles the R sources under r/; the launch