PBPK MCP Server
by ToxMCP
README.md
# PBPK MCP Server
[](https://github.com/ToxMCP/pbpk-mcp/actions/workflows/ci.yml)
[](https://doi.org/10.64898/2026.02.06.703989)
[](./LICENSE)
[](https://github.com/ToxMCP/pbpk-mcp/releases)
[](https://www.python.org/)
> Part of **ToxMCP** Suite → https://github.com/ToxMCP/toxmcp
**Public MCP endpoint for physiologically based pharmacokinetic (PBPK) simulation, qualification, and dossier export.**
Expose PK-Sim / MoBi `.pkml`, MCP-ready `rxode2` `.R`, deterministic and population runs, and OECD-oriented validation/reporting to any MCP-aware agent (Codex CLI, Gemini CLI, Claude Code, etc.).
## Architecture
```mermaid
flowchart LR
subgraph Clients["Clients and Agents"]
Codex["Codex CLI / Desktop"]
Gemini["Gemini CLI"]
Claude["Claude Code"]
Scripts["Scripts / notebooks"]
end
subgraph API["FastAPI MCP Service"]
Router["HTTP entrypoints\n/health and /mcp"]
Registry["Tool registry\npbpk-mcp.v1 contracts"]
Tools["Tool handlers\ndiscovery, validation,\nexecution, reporting"]
end
subgraph Contracts["Discovery and Qualification Layer"]
Catalog["Filesystem model catalog\nADAPTER_MODEL_PATHS"]
Manifest["Static manifest validation\nvalidate_model_manifest"]
Qualification["Qualification metadata\ncapabilities, profile,\nvalidation, qualificationState"]
Verification["Executable verification\nrun_verification_checks"]
Reports["OECD dossier export\nexport_oecd_report"]
end
subgraph Backends["Execution Backends"]
OSPSuite["OSPSuite backend\nPK-Sim / MoBi (.pkml)"]
Rxode2["rxode2 backend\nMCP-ready R (.R)"]
Convert["Conversion-only inputs\n.pksim5 and .mmd -> .pkml or .R"]
end
subgraph Runtime["Runtime and QA Path"]
Jobs["Celery + Redis jobs\nasync runs and result handles"]
Overlay["Source-overlay runtime\nbind mounts + worker image"]
Tests["Unit + live smoke tests\nrelease readiness checks"]
end
Clients --> Router
Router --> Registry
Registry --> Tools
Tools --> Catalog
Tools --> Manifest
Tools --> Qualification
Qualification --> Verification
Qualification --> Reports
Tools --> OSPSuite
Tools --> Rxode2
Convert --> OSPSuite
Convert --> Rxode2
Tools --> Jobs
Overlay --> Tools
Qualification --> Tests
Overlay --> Tests
```
The current implementation follows a layered model:
- `FastAPI + JSON-RPC` expose `/mcp` and `/health`, and keep transport concerns separate from PBPK model logic.
- `Tool handlers` are the agent-facing API. They validate inputs, call adapters, and emit structured responses with normalized `pbpk-mcp.v1` payloads.
- `Discovery and manifest validation` make model files visible before load, and keep curation checks separate from runtime execution.
- `Execution backends` route `.pkml` files to `ospsuite` and MCP-ready `.R` modules to `rxode2`, while treating `.pksim5` and `.mmd` as conversion-only inputs.
- `Qualification metadata` keeps `capabilities`, `profile`, `validation`, and `qualificationState` separate so runnable does not get conflated with scientifically qualified.
- `Executable verification` adds lightweight but structured runtime checks on top of qualification metadata, including parameter-unit consistency, structural flow/volume consistency, deterministic smoke, result-integrity, and repeat-run reproducibility checks without conflating them with formal qualification evidence.
- `Packaged-default runtime + overlay smoke tests` keep the documented tool surface synchronized with the live API while still leaving an explicit maintainer override path for workspace iteration.
- `Release metadata checks` now verify that package version markers, compose/env `SERVICE_VERSION`, README release markers, the top changelog entry, and the matching `docs/releases/` note stay aligned.
- `Release artifact evidence` now retains a machine-readable report with `sdist`/wheel hashes and the linked contract-manifest identity during tag builds.
See `docs/architecture/dual_backend_pbpk_mcp.md` for the fuller architecture narrative, `docs/architecture/capability_matrix.md` for the published support matrix, `docs/architecture/mcp_payload_conventions.md` for the response contract, `docs/deployment/runtime_patch_flow.md` for the operator path behind the current local deployment model, and `docs/pbpk_model_onboarding_checklist.md` for the recommended trust pipeline when onboarding another chemical model.
See `docs/architecture/exposure_led_ngra_role.md` for the explicit boundary statement on what PBPK MCP does and does not own inside exposure-led NGRA workflows.
See `docs/architecture/toxmcp_suite_index.md` for the shortest cross-service routing guide inside the ToxMCP suite.
See `benchmarks/regulatory_goldset/regulatory_goldset_summary.md` for the current gold-set documentation benchmark summary derived from the fetched public-code PBPK corpus. Internal examples such as the bundled synthetic reference model remain bounded MCP rehearsal models, not benchmark exemplars.
## What's new in v0.5.0
- Enforced single-use replay rejection for bearer tokens that carry `jti` claims, so repeated presentation of the same token identifier is now treated as an auth failure instead of silently succeeding.
- Upgraded `/mcp` to the MCP `2025-11-25` JSON-RPC behavior, including clean success/error response shapes, standard tool schemas, structured tool results, and standard MCP resources exposed through `pbpk://` URIs.
- Moved canonical PBPK tool modules to `mcp_bridge.pbpk_tools` while keeping a temporary deprecated `mcp.*` compatibility shim for existing internal scripts.
- Aligned REST and MCP parameter writes on one governance path, so snapshots, audit-backed sweep detection, and the returned `governance` payload now behave consistently across both transports.
- Fixed `set_parameter_value(updateMode="relative")` so relative deltas are applied against the current parameter value before validation, audit, and persistence.
- Completed the `v0.5.0` release alignment across package metadata, compose/runtime version markers, the README, and the dedicated release-note entry, while moving the remaining legacy env-alias removal target to `v0.6.0`.
## Why this project exists
PBPK workflows often juggle PK-Sim or MoBi transfer files, R-authored mechanistic models, runtime-specific scripts, and incomplete qualification notes. That makes them difficult for coding agents to automate safely and difficult for reviewers to inspect consistently.
The PBPK MCP server wraps those workflows in a **single, programmable interface**:
- **Unified MCP surface** – discovery, manifest checks, load, validation, execution, results, and dossier export share one tool catalog.
- **Dual-backend execution** – `.pkml` models run on `ospsuite`; MCP-ready `.R` models run on `rxode2`.
- **Qualification-aware workflows** – runtime capability, scientific profile, preflight validation, and derived `qualificationState` stay separate.
- **NGRA-ready PBPK objects** – validation and dossier export expose PBPK-side typed objects such as `assessmentContext`, `pbpkQualificationSummary`, `uncertaintySummary`, `uncertaintyHandoff`, `internalExposureEstimate`, a typed external uncertainty-register reference, and a typed external PoD reference handoff, now with explicit boundary/support metadata plus additive `semanticCoverage` for PBPK-side uncertainty semantics, without collapsing PBPK MCP into a full decision engine.
- **Exposure-led boundary clarity** – `assessmentContext.workflowRole`, `assessmentContext.populationSupport`, `pbpkQualificationSummary.evidenceBasis`, `pbpkQualificationSummary.workflowClaimBoundaries`, and `pbpkQualificationSummary.reviewStatus` now make IVIVE/exposure dependencies, supported population contexts, no-direct-in-vivo status, reviewer-attention requirements, and claim boundaries explicit.
- **Static curation feedback for NGRA gaps** – `validate_model_manifest` now exposes `manifest.ngraCoverage` plus a compact `curationSummary`, so missing workflow-role, population-support, evidence-basis, and claim-boundary declarations are visible before load in both machine-readable and reviewer-facing form; that summary now also carries an anti-misread block, explicit summary-transport risk for thin/forwarded views, a normalized `cautionSummary` with advisory-versus-blocking handling, a machine-readable `exportBlockPolicy`, and rendering guardrails for analyst-facing clients.
- **Regulatory benchmark bar** – the workspace now also ships a gold-set benchmark dossier under `benchmarks/regulatory_goldset/` plus an advisory `curationSummary.regulatoryBenchmarkReadiness` block, so MCP reviewers can compare a model dossier to public regulatory-grade PBPK packaging without promoting research models to regulatory-ready status. That advisory block now also carries per-dimension evaluation paths, benchmark examples, and concrete next-artifact guidance for closing documentation gaps.
- **Reviewer-friendly discovery summaries** – `discover_models` and `/mcp/resources/models` now surface `manifestStatus`, `qualificationState`, and a compact `curationSummary` so curated illustrative examples can be distinguished from exploratory or partially declared models at discovery time, with explicit anti-misread guidance and no official “bare label only” rendering path.
- **Human-review summary** – OECD report export now includes a compact `humanReviewSummary` block that pulls those boundary fields into one reviewer-facing surface, including reviewer-status, unresolved-dissent context, normalized `cautionSummary`, summary-transport risk, `exportBlockPolicy`, and rendering guardrails, without creating a second hidden score or decision engine.
- **Anti-misread report section** – OECD report export now also includes a mandatory `misreadRiskSummary` block so common over-interpretations are stated explicitly next to the primary report summary instead of being left implicit.
- **Audit-backed operator sign-off** – trust-bearing outputs now surface an additive `operatorReviewSignoff` summary plus an explicit `operatorReviewGovernance` block derived from the real workflow contract, and the REST surface now exposes viewer-readable `/review_signoff/history` so recorded acknowledgement, bounded-use sign-off, rejection, and revocation remain auditable without being mistaken for a second qualification score, override path, or decision authority.
- **Explicit audit-storage boundary** – the default local stack keeps reviewer-readable hash-chained audit history on the local filesystem, while stronger off-host immutability depends on the S3/Object-Lock backend and external retention discipline documented for operators.
- **Conservative PK/NCA output surface** – `calculate_pk_parameters` and the internal deterministic-result summaries now expose additive `auc0Inf`, `lambdaZ`, `halfLife`, extrapolated-AUC share, terminal-phase point counts, and screening-oriented `ncaStatus`/`ncaWarnings`, while clearance and volume distribution remain withheld unless explicit dose context is declared.
- **No bundled analyst UI in the current release** – trust-bearing review remains on the MCP and REST surfaces for now; `/console` and `/console/api/*` are intentionally absent until a stronger reviewer-facing client exists.
- **Thin-client trust-surface contract** – trust-bearing MCP tool results now also expose a top-level `trustSurfaceContract` so thin clients can find the nested summary surfaces, required adjacent caveats, and primary block reasons they must carry together instead of rediscovering those paths tool by tool.
- **Traceable predictive evidence** – performance bundles can now carry traceability supplements, and the report path now warns when bundled benchmark rows do not actually line up with the declared datasets, target outputs, or acceptance criteria.
- **Objective performance-evidence metrics** – observed-versus-predicted rows now retain additive `objectiveEvidence` metrics such as fold error, row-level RMSE, and simple acceptance-criterion evaluation when the criterion is machine-interpretable, without replacing the original evidence row semantics.
- **Reviewer-facing dossier improvement signals** – verification and OECD report export now attach an advisory `dossierImprovementSignals` block sourced from the regulatory benchmark comparison so maintainers can see the highest-leverage dossier/documentation gaps without changing qualification state.
- **Discovery before execution** – models are discoverable from disk before they are loaded into a live session.
- **Release-tested local deployment** – the packaged local runtime and the explicit source-overlay maintainer profile are both exercised with unit tests, live-stack tests, and a readiness check.
- **Model-specific executable qualification checks** – MCP-ready models can add runtime verification hooks for checks such as flow/volume consistency, mass balance, or numerical stability without overstating regulatory qualification.
> `rxode2` is a native PBPK execution engine in this project. It is not limited to Berkeley Madonna conversion workflows.
---
## Feature snapshot
| Capability | Description |
| --- | --- |
| 🧬 **Dual-backend PBPK execution** | Route `.pkml` models to `ospsuite` and MCP-ready `.R` models to `rxode2` through one MCP surface. |
| 🗂️ **Model discovery and curation** | Discover supported model files from `ADAPTER_MODEL_PATHS`, inspect unloaded models, and run static manifest checks before load. |
| 🛡️ **OECD-oriented qualification** | Keep `capabilities`, `profile`, `validation`, and `qualificationState` explicit; expose applicability, provenance, uncertainty, implementation verification, software-platform qualification, and qualification gaps. |
| 🧱 **NGRA-ready PBPK objects** | Emit typed PBPK-side objects such as `assessmentContext`, `pbpkQualificationSummary`, `uncertaintySummary`, `uncertaintyHandoff`, `internalExposureEstimate`, a typed `uncertaintyRegisterReference`, a typed `pointOfDepartureReference`, and a thin BER-ready reference bundle in dossier export, with explicit boundary/support flags plus additive uncertainty `semanticCoverage` for downstream NGRA orchestration and without embedding BER decision logic in PBPK MCP. |
| 📐 **Published object schemas** | Publish machine-readable JSON Schemas and example payloads for the PBPK-side NGRA handoff object family under `schemas/` so downstream tooling can validate the public object layer directly. |
| 🔌 **External PBPK normalization** | Normalize externally generated PBPK outputs, qualification metadata, and optional PoD references through `ingest_external_pbpk_bundle` without pretending PBPK MCP executed the upstream engine. |
| ✅ **Executable verification** | Run `run_verification_checks` to capture preflight validation, parameter coverage, parameter-unit consistency, structural flow/volume consistency, deterministic smoke, deterministic result integrity, repeat-run reproducibility, optional population smoke, and verification-evidence summaries in one payload. |
| 📈 **Deterministic and population jobs** | Submit asynchronous deterministic and population simulations, then retrieve result handles, stored results, and PK summaries. |
| 🧾 **Dossier export** | Export a structured OECD-style report with model metadata, validation context, checklist state, parameter provenance, performance evidence, uncertainty evidence, verification evidence, and software-platform qualification evidence when declared. |
| ⚙️ **Source-overlay deployment hygiene** | Recreate the local stack through the documented compose entrypoints and validate the live contract with readiness and smoke gates. |
| 🤖 **Agent friendly** | Verified through MCP HTTP surfaces such as `/mcp/list_tools`, `/mcp/call_tool`, and `/mcp/resources/models`, with live-stack regression checks. |
---
## Table of contents
1. [Architecture](#architecture)
2. [Published schemas](#published-schemas)
3. [Capability matrix](#capability-matrix)
4. [Quick start](#quick-start)
5. [Configuration](#configuration)
6. [Tool catalog](#tool-catalog)
7. [Running the server](#running-the-server)
8. [Integrating with coding agents](#integrating-with-coding-agents)
9. [Output artifacts](#output-artifacts)
10. [Security checklist](#security-checklist)
11. [Current limitations](#current-limitations)
12. [Development notes](#development-notes)
13. [Contributing](#contributing)
14. [Security policy](#security-policy)
15. [Code of conduct](#code-of-conduct)
16. [Citation](#citation)
17. [Roadmap](#roadmap)
18. [License](#license)
---
## Quickstart TL;DR
```bash
# 1) build the worker image
git clone https://github.com/ToxMCP/pbpk-mcp.git
cd pbpk-mcp
# 2) start the local stack
./scripts/build_rxode2_worker_image.sh
./scripts/deploy_rxode2_stack.sh
# 3) verify
curl -s http://localhost:8000/health | jq .
curl -s http://localhost:8000/mcp/list_tools | jq '.tools[].name'
```
## Published schemas
The PBPK-side NGRA handoff objects are now published as machine-readable JSON Schemas under `schemas/`, with matching examples under `schemas/examples/`.
Published object family:
- `schemas/assessmentContext.v1.json`
- `schemas/pbpkQualificationSummary.v1.json`
- `schemas/uncertaintySummary.v1.json`
- `schemas/uncertaintyHandoff.v1.json`
- `schemas/uncertaintyRegisterReference.v1.json`
- `schemas/internalExposureEstimate.v1.json`
- `schemas/pointOfDepartureReference.v1.json`
- `schemas/berInputBundle.v1.json`
Design intent:
- require the stable core fields only
- allow additive convenience fields
- keep BER calculation and final decision policy outside PBPK MCP
- keep exposure assessment, IVIVE policy, reverse dosimetry, and direct regulatory dose derivation outside PBPK MCP
- make the PBPK-side handoff layer consumable by downstream validators and orchestrators without scraping examples out of tests
See `schemas/README.md` for the short schema guide and `tests/test_ngra_object_schemas.py` for the validation gate that keeps the published schemas aligned with live payload generation. The same schema family is also exposed through the live MCP resource surface at `/mcp/resources/schemas`. In the current local packaged runtime, the live schema/capability/contract-manifest resources treat the packaged `mcp_bridge.contract` content as authoritative rather than depending on copied JSON under `/app/var/contract`. `scripts/check_installed_package_contract.py` is the maintainer gate that proves the generated package fallback still matches the published JSON artifacts after a non-editable local install. When you explicitly opt into the workspace source-overlay profile, `scripts/runtime_src_overlay.pth` promotes `/app/src` ahead of the installed package.
PBPK MCP now also publishes a machine-readable contract manifest in:
- `docs/architecture/contract_manifest.json`
- `/mcp/resources/contract-manifest`
That manifest inventories the published PBPK-side schema family, the capability matrix, the legacy artifacts intentionally excluded from the PBPK-side object family, and the stable resource endpoints that expose the contract.
The live schema, capability-matrix, and contract-manifest resources now also expose SHA-256 values so downstream clients can verify that the running API matches the published artifact inventory.
The shared schema/capability/contract-manifest route logic now lives in packaged `src/mcp_bridge/routes/resources_base.py`, and packaged `src/mcp_bridge/routes/resources.py` now owns the full generic `/mcp/resources` surface including `/mcp/resources/models`.
The same is now true for tools as well: packaged `src/mcp_bridge/tools/registry_base.py` and `src/mcp_bridge/tools/registry.py` now own the generic discovery/static-manifest/result/import descriptors alongside the rest of the documented PBPK workflow surface.
The next `0.4.x` debt-reduction slices are now live too: generic discovery, manifest, load/session-status, preflight validation, executable verification, dossier export, deterministic-result retrieval, external-import normalization, population workflow tools, the shared `model_catalog` / `model_manifest` helpers, the top-level `mcp` namespace, and the generic adapter contract/runtime now live in packaged `src/`. The default local runtime no longer needs a patch-copy step or a source overlay for code: the worker image bakes `scripts/ospsuite_bridge.R` and the bundled reference `.R` model into their runtime locations, `docker-compose.celery.yml` runs the packaged baseline, and `docker-compose.overlay.yml` is now the explicit maintainer profile when workspace `src/` and `scripts/` should override the image.
## Capability matrix
PBPK MCP now publishes a dedicated capability matrix for adopters in:
- `docs/architecture/capability_matrix.md`
- `docs/architecture/capability_matrix.json`
The machine-readable matrix is also exposed from the running server at `/mcp/resources/capability-matrix`.
For the cross-service routing view rather than the per-input capability boundary, read `docs/architecture/toxmcp_suite_index.md`.
This matrix is the crisp public answer to:
- what is discoverable
- what is statically validatable
- what is loadable
- what is deterministic-run capable
- what is population-run capable
- what is dossier-capable
Current headline boundaries:
- `.pkml` is discoverable, loadable, validatable, verification-capable, deterministic-run capable, and dossier-capable through `ospsuite`
- contract-complete MCP-ready `.R` is discoverable, loadable, validatable, verification-capable, deterministic-run capable, and dossier-capable through `rxode2`
- population execution is currently `rxode2`-only and remains conditional on model capability
- incomplete `.R` files may still be discoverable before they are runnable
- `.pksim5` and `.mmd` are conversion-only and do not appear as runtime-supported catalog entries
The machine-readable JSON file is intentionally small and stable so downstream tooling can consume it directly without scraping prose from the README.
`scripts/generate_contract_artifacts.py --check` is the maintainer gate that keeps the contract manifest and generated packaged fallback aligned with the published JSON artifacts.
## Quick start
```bash
git clone https://github.com/ToxMCP/pbpk-mcp.git
cd pbpk-mcp
./scripts/build_rxode2_worker_image.sh
./scripts/deploy_rxode2_stack.sh
```
When you only need to refresh the packaged runtime image from the current workspace contents, without recompiling `rxode2`, use:
```bash
./scripts/refresh_rxode2_worker_image.sh
```
> **Heads-up:** `./scripts/deploy_rxode2_stack.sh` now runs the packaged local runtime by default and waits for stable `/health` and `/mcp/list_tools` responses before returning. The deploy helpers use a longer readiness window than before because the packaged import path is heavy on some machines. When you need workspace `src/` and `scripts/` to override the image for active development, use `./scripts/deploy_source_overlay_stack.sh`.
Once the server is running:
- HTTP MCP endpoint: `http://localhost:8000/mcp`
- Health check: `http://localhost:8000/health`
- Model discovery resource: `http://localhost:8000/mcp/resources/models`
- Architecture docs: `docs/architecture/dual_backend_pbpk_mcp.md`
- Runtime operator docs: `docs/deployment/runtime_patch_flow.md`
- New-model trust pipeline: `docs/pbpk_model_onboarding_checklist.md`
## Verification (smoke test)
Once the server is running:
```bash
# health
curl -s http://localhost:8000/health | jq .
# list MCP tools
curl -s http://localhost:8000/mcp/list_tools | jq .
# discover reference_compound
curl -s -X POST http://localhost:8000/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{"tool":"discover_models","arguments":{"search":"reference_compound","limit":10}}' | jq .
# static manifest validation
curl -s -X POST http://localhost:8000/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{"tool":"validate_model_manifest","arguments":{"filePath":"/app/var/models/rxode2/reference_compound/reference_compound_population_rxode2_model.R"}}' | jq .
```
For the full live-stack gate, run:
```bash
python3 scripts/release_readiness_check.py
```
That live readiness gate now also reruns the curated manifest publication check for the bundled synthetic reference model and pregnancy examples, and it fails if those examples regress to implicit NGRA workflow-role, population-support, evidence-basis, or claim-boundary declarations.
For the standalone static gate on that same curated publication set, run:
```bash
python3 scripts/validate_model_manifests.py --strict --require-explicit-ngra --curated-publication-set
```
To smoke-test the actual discovered model inventory in the current workspace, run:
```bash
python3 scripts/workspace_model_smoke.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long
python3 scripts/workspace_model_smoke.py --include-population --auth-dev-secret pbpk-local-dev-secret-32bytes-long
```
The script discovers runtime-supported models through `/mcp/resources/models`, runs static manifest validation, loads each model, submits a deterministic simulation, retrieves stored results, and optionally runs a small population smoke for `rxode2` models that declare population support. It writes a JSON report to `var/workspace_model_smoke_report.json`. On hardened local stacks, the load/run operations require operator or admin access, so pass `--auth-dev-secret pbpk-local-dev-secret-32bytes-long` for the default development profile or provide a real bearer token.
For the GitHub-hosted verification path, the repository also carries:
- a lightweight `CI` workflow for patch/runtime contract checks on pushes and pull requests, now retaining a validated `sdist`, wheel, and runtime-contract report as artifacts
- a heavier `Model Smoke` workflow that builds the Docker-backed stack, runs the live readiness gate, executes `workspace_model_smoke.py --include-population --auth-dev-secret pbpk-local-dev-secret-32bytes-long`, and uploads the resulting JSON reports as workflow artifacts
---
## Configuration
The default local packaged stack is defined in `docker-compose.celery.yml`. An explicit source-overlay development profile is available in `docker-compose.overlay.yml`, and a stricter operator overlay is available in `docker-compose.hardened.yml` for deployments that should disable anonymous access and require explicit auth configuration. The source-overlay profile now bind-mounts `src/`, `scripts/`, `docs/`, `schemas/`, and `var/` so the running server stays aligned with regenerated contract artifacts during release-prep. Key environment variables currently shaping the runtime are:
| Variable | Default | Description |
| --- | --- | --- |
| `ADAPTER_MODEL_PATHS` | `/app/var` | Filesystem roots scanned by `discover_models` and `/mcp/resources/models`. |
| `ADAPTER_BACKEND` | `subprocess` | Uses the R / OSPSuite subprocess bridge instead of an in-memory mock path. |
| `JOB_BACKEND` | `celery` | Enables asynchronous job submission through Redis-backed Celery workers. |
| `CELERY_BROKER_URL` | `redis://redis:6379/0` | Queue broker for asynchronous jobs. |
| `CELERY_RESULT_BACKEND` | `redis://redis:6379/1` | Result storage for job handles and async result chaining. |
| `ADAPTER_R_PATH` / `ADAPTER_R_HOME` | container defaults | Point the bridge to the R runtime used by `rxode2` and OSPSuite tooling. |
| `ADAPTER_TIMEOUT_MS` | `30000` | Default adapter timeout in milliseconds. |
| `AUDIT_ENABLED` | `true` in local compose | Enables audit-backed sign-off, verification traceability, and readable history surfaces. |
| `R_MAX_VSIZE` | `2G` | Caps R virtual memory use inside the current local worker setup. |
| `DOTNET_GCHeapLimitPercent` | `60` | Constrains the .NET heap used by the OSPSuite runtime. |
| `PBPK_ENABLE_SRC_OVERLAY` | `false` | Keeps `/app/src` out of import precedence by default; `docker-compose.overlay.yml` sets it to `true` for workspace-override development. |
| `SERVICE_VERSION` | `0.5.0` | Exposed through `/health` and compose-level runtime metadata. |
| `AUTH_ALLOW_ANONYMOUS` | `true` | Development-friendly local default; do not expose beyond localhost without hardening. |
| `PBPK_BIND_HOST` | `127.0.0.1` | Host/interface used by the hardened overlay when publishing the API port. |
| `PBPK_BIND_PORT` | `8000` | Host port used by the hardened overlay when publishing the API port. |
| `AUTH_ISSUER_URL` | unset | Required by the hardened overlay. OIDC issuer used for token validation. |
| `AUTH_AUDIENCE` | unset | Required by the hardened overlay. Audience expected in bearer tokens. |
| `AUTH_JWKS_URL` | unset | Required by the hardened overlay. JWKS endpoint used to validate bearer tokens. |
| `AUTH_REPLAY_WINDOW_SECONDS` | `300` | Rejects replay of already-seen `jti` token identifiers; callers must mint fresh jti-bearing tokens when this is enabled. |
| `MCP_ALLOWED_ORIGINS` | unset | Optional comma-separated allow-list for browser-originated MCP streamable HTTP requests. CLI clients without an `Origin` header remain valid. |
| `MCP_STRICT_TRANSPORT` | `false` | When `true`, requires MCP streamable HTTP `Accept` and `MCP-Protocol-Version` headers for hardened deployments. |
For the default packaged local runtime, use `docker-compose.celery.yml` through `./scripts/deploy_rxode2_stack.sh`. When you need workspace overrides, use `./scripts/deploy_source_overlay_stack.sh`, which layers `docker-compose.overlay.yml` over the same local stack and enables `/app/src` precedence. For a more production-like local or operator-managed deployment, use `./scripts/deploy_hardened_stack.sh`, which layers `docker-compose.hardened.yml` over the packaged local runtime, forwards the hardened auth plus optional S3/Object-Lock audit env contract, and waits for stable readiness before returning. For a local S3-compatible smoke run, `./scripts/deploy_s3_audit_smoke_stack.sh` layers a MinIO-backed audit overlay over the same packaged runtime.
Legacy aliases such as `R_PATH`, `R_HOME`, `R_LIBS`, `MCP_MODEL_SEARCH_PATHS`, `ADAPTER_TIMEOUT_SECONDS`, and `AUDIT_TRAIL_ENABLED` are still accepted for compatibility, but startup now warns that they are scheduled for removal in `v0.6.0`.
See `docker-compose.celery.yml`, `docker-compose.overlay.yml`, `docker-compose.hardened.yml`, `docker-compose.s3-audit-smoke.yml`, `docs/deployment/runtime_patch_flow.md`, and `docs/deployment/rxode2_worker_image.md` for the current operator-facing deployment surface. For the current audit-storage guarantees and limits, see `docs/hardening_migration_notes.md`, `docs/adr/0001-audit-storage-boundary.md`, and `docs/deployment/s3_object_lock_audit.md`.
---
## Tool catalog
| Category | Highlight tools | Notes |
| --- | --- | --- |
| Discovery and curation | `discover_models`, `validate_model_manifest`, `load_simulation` | Discover models before load, inspect static manifest state, and load supported `.pkml` or MCP-ready `.R` files into the live session registry. |
| Qualification and reporting | `validate_simulation_request`, `run_verification_checks`, `export_oecd_report`, `ingest_external_pbpk_bundle` | Run OECD-oriented preflight checks, executable verification with unit/integrity/reproducibility checks, structured dossier export with `profile`, `validation`, `qualificationState`, evidence sections, and a descriptive `oecdCoverage` map to OECD Tables 3.1/3.2, and normalize externally generated PBPK outputs into the same typed PBPK-side objects. |
| Simulation control | `list_parameters`, `get_parameter_value`, `set_parameter_value`, `run_simulation` | Inspect and modify simulation parameters, then submit deterministic runs asynchronously. |
| Async status and results | `get_job_status`, `get_results`, `calculate_pk_parameters`, `cancel_job` | Track async jobs, retrieve stored deterministic results, compute PK summaries, and cancel queued/running jobs. |
| Population and exploration | `run_population_simulation`, `get_population_results`, `run_sensitivity_analysis` | Run population workflows and sensitivity analyses on the backends that declare those capabilities. |
The normalized `pbpk-mcp.v1` contract currently applies to:
- `load_simulation`
- `validate_model_manifest`
- `validate_simulation_request`
- `run_verification_checks`
- `export_oecd_report`
- `get_job_status`
- `get_results`
### Example workflow
For the current public workflow:
1. Call `discover_models` or inspect `/mcp/resources/models`.
2. Call `validate_model_manifest` before loading a new model.
3. Call `load_simulation`.
4. Call `validate_simulation_request` for the intended context of use.
5. Call `run_verification_checks` when you want a lightweight executable verification summary before broader use or release.
6. Submit `run_simulation` or `run_population_simulation`.
7. Poll `get_job_status`, then fetch `get_results` or `get_population_results`.
8. Call `export_oecd_report` when you need a dossier/report package.
### Supported model policy
Supported runtime inputs:
- `.pkml` via `ospsuite`
- MCP-ready `.R` via `rxode2`
Conversion-only inputs:
- `.pksim5` PK-Sim project files
- Berkeley Madonna `.mmd`
Both conversion-only formats are rejected early with explicit guidance to export to `.pkml` or convert to an MCP-ready `.R` model.
Qualification model:
PBPK MCP keeps these concepts separate:
- `capabilities` for operational/runtime support
- `profile` for declared scientific metadata
- `validation` for preflight applicability and guardrail assessment
- `qualificationState` for the derived summary label
- `ngraObjects` for PBPK-side typed NGRA-ready objects such as `assessmentContext`, `pbpkQualificationSummary`, `uncertaintySummary`, `uncertaintyHandoff`, `internalExposureEstimate`, and `uncertaintyRegisterReference`
- `uncertaintySummary` now also carries additive `semanticCoverage` so downstream consumers can distinguish declared-only versus quantified PBPK-side variability, sensitivity, and residual uncertainty without inferring that from raw evidence rows alone; it now includes `quantifiedRowCount`, `declaredOnlyRowCount`, and a stricter `variabilityQuantificationStatus`
- `oecdCoverage` for a descriptive mapping from exported dossier fields onto OECD reporting-template and evaluation-checklist sections; it does not modify `oecdChecklistScore` or qualification state
Current derived qualification states include:
- `exploratory`
- `illustrative-example`
- `research-use`
- `regulatory-candidate`
- `qualified-within-context`
This is the core policy boundary for the server:
- executable does not mean qualified
- in-bounds does not mean suitable for regulatory use
For `.R` models, richer OECD-oriented reporting is enabled by hooks such as:
- `pbpk_model_profile()`
- `pbpk_validate_request(...)`
- `pbpk_parameter_table(...)`
- `pbpk_performance_evidence(...)`
- `pbpk_uncertainty_evidence(...)`
- `pbpk_verification_evidence(...)`
- `pbpk_run_verification_checks(...)`
- `pbpk_platform_qualification_evidence(...)`
For example, the reference_compound `rxode2` model now exports bounded local sensitivity evidence and a compact variability-propagation summary through `uncertaintyEvidence`, using the currently loaded parameter state rather than a hard-coded placeholder row. Its `performanceEvidence` is also explicitly classified as runtime-only/internal evidence so executable smoke checks cannot be mistaken for predictive validation.
`export_oecd_report` now also adds `oecdCoverage`, an additive coverage map aligned to OECD PBK Guidance Tables 3.1 and 3.2. It is intentionally descriptive: it shows which dossier sections/questions are covered by the current report payload and which remain incomplete, but it does not alter `oecdChecklistScore`, `qualificationState`, or any downstream decision boundary.
Researchers can also attach generic companion performance bundles next to either `.pkml` or `.R` models without modifying the bridge code. See [performance_evidence_bundles.md](docs/integration_guides/performance_evidence_bundles.md) and the starter template at [performance_evidence_bundle.template.json](examples/performance_evidence_bundle.template.json). Those bundles can now carry both row-level evidence and a traceability-only `profileSupplement` for predictive dataset records, acceptance criteria, and target outputs. The MCP validates row-level claims conservatively and keeps the supplement descriptive rather than silently upgrading the qualification boundary.
`modelPerformance` can now also declare structured `datasetRecords` and `acceptanceCriteria` inside `goodnessOfFit`, `predictiveChecks`, or `evaluationData`. The bridge normalizes those fields and exposes additive traceability counts so predictive support is not reduced to a single status token.
The same pattern now exists for uncertainty evidence. See [uncertainty_evidence_bundles.md](docs/integration_guides/uncertainty_evidence_bundles.md) and [uncertainty_evidence_bundle.template.json](examples/uncertainty_evidence_bundle.template.json). The MCP surfaces warnings when uncertainty rows are missing method/summary or scope information, and `variability-propagation` rows are only treated as quantified propagation evidence when they actually include quantitative outputs such as `value`, `lowerBound`, `upperBound`, `mean`, or `sd`.
The same companion-bundle pattern now exists for richer parameter tables. See [parameter_table_bundles.md](docs/integration_guides/parameter_table_bundles.md) and [parameter_table_bundle.template.json](examples/parameter_table_bundle.template.json). `export_oecd_report` and `validate_model_manifest` now surface row-level coverage for sources, citations, distributions, study conditions, and rationale so dossier gaps are visible without custom bridge code.
Structured peer-engagement traceability can now stay inside the existing `peerReview` profile section. If a model declares `reviewRecords`, `priorRegulatoryUse`, `revisionStatus`, or `revisionHistory`, the bridge now normalizes those fields and exposes dossier-ready coverage counts instead of treating peer review as a single free-text status flag.
For `.pkml` models, richer qualification metadata can be supplied with sidecars such as:
- `model.profile.json`
- `model.pbpk.json`
---
## Running the server
The default local stack is:
- `pbpk_mcp-api-1` on `http://127.0.0.1:8000`
- `pbpk_mcp-worker-1` on the same `pbpk_mcp-worker-rxode2:latest` image for execution
- `pbpk_mcp-redis-1` for job brokering and result storage
The preferred local operator entrypoint is:
```bash
./scripts/deploy_rxode2_stack.sh
```
That command recreates the packaged local runtime so the live tool catalog remains aligned with the documented contract.
When you want to iterate against the current workspace source tree instead of the baked image baseline, use:
```bash
./scripts/deploy_source_overlay_stack.sh
```
That profile layers `docker-compose.overlay.yml` on top of the packaged stack, bind-mounts `src/`, `scripts/`, `docs/`, `schemas/`, and `var/`, enables `PBPK_ENABLE_SRC_OVERLAY=true`, and then waits for stable `/health` and `/mcp/list_tools` responses before returning.
When you want the same runtime contract with stricter deployment defaults, use:
```bash
AUTH_ISSUER_URL="https://issuer.example" \
AUTH_AUDIENCE="pbpk-mcp" \
AUTH_JWKS_URL="https://issuer.example/.well-known/jwks.json" \
./scripts/deploy_hardened_stack.sh
```
That overlay disables anonymous access, switches the stack to `ENVIRONMENT=production`, binds the published API port through `PBPK_BIND_HOST` / `PBPK_BIND_PORT`, and still waits for stable `/health` and `/mcp/list_tools` responses before returning.
---
## Integrating with coding agents
Add `http://localhost:8000/mcp` as the standards-compliant MCP provider in Codex CLI/Desktop, Gemini CLI, Claude Code, or other MCP-aware hosts. The endpoint negotiates MCP `2025-11-25` by default while accepting `2025-03-26` clients during the compatibility window.
Standard MCP methods on `/mcp` include:
- `initialize`
- `tools/list`
- `tools/call`
- `resources/list`
- `resources/read`
- `resources/templates/list`
Compatibility REST helper surfaces remain available for scripts and notebooks:
- `/mcp/list_tools` for the live tool catalog
- `/mcp/call_tool` for direct HTTP tool execution
- `/mcp/resources/models` for discoverable model files
- `/mcp/resources/simulations` for already-loaded live sessions
- `/mcp/resources/schemas` for the published PBPK-side object schemas and example payloads
- `/mcp/resources/capability-matrix` for the live machine-readable runtime-support matrix
Critical tools declare standard MCP annotations such as `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`; PBPK-specific role and confirmation metadata remains in annotation extensions. The current live regression suite checks both the standard `/mcp` JSON-RPC surface and the compatibility REST helpers.
Python import note: new internal code must import PBPK tools from `mcp_bridge.pbpk_tools`. The top-level `mcp.*` package is a deprecated transitional shim and can shadow the official MCP Python SDK when this package is installed in the same environment; only the canonical `mcp_bridge.*` imports are guaranteed during the shim window.
---
## Output artifacts
### Third-party model release boundary
The public repository does **not** bundle the reviewed third-party esqLABS PKML models, their model-specific sidecars, or their smoke outputs. `var/models/esqlabs/index.json` retains a machine-neutral inventory with pinned source commits and content hashes, while `sources.json` records the current license evidence and review status. `python3 scripts/esqlabs_models.py check-public-tree` verifies that those assets remain absent. The separate `write-index --public-release` redistribution gate still fails until every source is explicitly approved and its required notices are packaged. Authorized private operators can supply a separate model root with `PBPK_ESQLABS_MODELS_ROOT`; this is a release-control boundary, not a legal conclusion.
The server currently produces and exposes:
- discovered model inventories with loaded/unloaded state
- static manifest validation reports
- load-time model metadata with `backend`, `capabilities`, `profile`, `validation`, and `qualificationState`
- validation/report payloads with typed PBPK-side NGRA-ready objects such as `assessmentContext`, `pbpkQualificationSummary`, `uncertaintySummary`, `uncertaintyHandoff`, `internalExposureEstimate`, `uncertaintyRegisterReference`, and `pointOfDepartureReference`
- uncertainty objects now include machine-readable PBPK-side uncertainty semantics for quantified variability, declared-only residual uncertainty, and still-missing components
- a BER-ready reference bundle in dossier export that can become `ready-for-external-ber-calculation` when an external `podRef` and a resolved PBPK exposure target are both available
- imported external PBPK run records and NGRA-ready object bundles from `ingest_external_pbpk_bundle`
- executable verification summaries with structured check results, smoke-run artifact handles, parameter-unit consistency, result-integrity/reproducibility checks, and verification-evidence snapshots
- deterministic result handles and stored deterministic result payloads
- population summary payloads and chunk handles
- PK metric outputs from `calculate_pk_parameters`
- OECD-style dossier/report exports with checklist state, missing-evidence hints, performance evidence, uncertainty evidence, verification evidence, software-platform qualification evidence, and parameter provenance when declared
- local/internal audit generators can produce verifiable evidence packs for bounded rehearsal models, but those study-specific outputs are not part of the public release surface and should not be treated as benchmark or distribution artifacts
---
## Security checklist
- ✅ Dual-backend runtime policy is explicit: `.pkml` and MCP-ready `.R` are supported; `.pksim5` and `.mmd` are conversion-only.
- ✅ Discovery, manifest validation, runtime validation, and OECD dossier export are exposed as separate tool surfaces.
- ✅ `capabilities`, `profile`, `validation`, and `qualificationState` remain distinct, so runtime support is not mislabeled as scientific qualification.
- ✅ The default local deployment path is now packaged by default, and the source-overlay maintainer path is explicit and opt-in.
- ✅ Live readiness checks verify `/mcp/list_tools`, `/mcp/resources/models`, discovery parity, and conversion-only rejection behavior.
- ✅ A documented hardened overlay now disables anonymous access by default and requires explicit auth settings before the stack will start.
- 🔲 The default compose file is still development-oriented; keep it on localhost and use the hardened overlay plus environment-specific ingress controls when moving beyond local development.
- 🔲 Qualification evidence completeness still depends on the model or sidecar; executable does not imply regulatory readiness.
## Current limitations
### Format and backend limitations
- Raw Berkeley Madonna `.mmd` files are not directly executable.
- Only `.pkml` and MCP-ready `.R` are supported runtime formats.
- PK-Sim / MoBi project files such as `.pksim5` are not loaded directly and must be exported to `.pkml`.
- An `.R` file can be discoverable without being runnable if it does not implement the required contract.
- Backend capabilities are intentionally not identical across `ospsuite` and `rxode2`.
- Population simulation is currently implemented for `rxode2` models, not as a generic OSPSuite `.pkml` capability.
### Qualification limitations
- `validate_model_manifest` is a static pre-load check; it does not by itself prove executable correctness or scientific validity.
- Runtime guardrails are not the same as external scientific validation.
- `ingest_external_pbpk_bundle` is a normalization/import path for externally generated PBPK outputs. It does not execute vendor engines such as GastroPlus or Simcyp, and it does not parse proprietary project files directly.
- `run_verification_checks` is intentionally lightweight implementation verification; it now includes parameter-unit consistency, structural flow/volume consistency, deterministic integrity, and reproducibility checks, but it still does not replace formal dimensional analysis, full unit-consistency proof across equations, solver qualification, software-platform qualification, or external qualification evidence.
- `export_oecd_report` now carries the latest stored `run_verification_checks` snapshot as `executableVerification` when one has been run for that loaded simulation. The report does not silently rerun verification during export.
- Model-specific hooks can add executable qualification checks such as flow/volume consistency, mass balance, or solver-stability comparisons, but those checks should still be interpreted as implementation evidence within the declared context, not as blanket regulatory qualification.
- Bundled `uncertaintyEvidence` can now include bounded local sensitivity screens and compact variability-propagation summaries for specific models, but those rows are still internal quantitative evidence. They are not the same thing as variance-based global sensitivity analysis, posterior uncertainty propagation, or externally reviewed qualification studies.
- `research-use` or `illustrative-example` models should not be represented as regulatory-ready.
- OECD-style metadata completeness can be high while scientific evidence remains incomplete.
- Exported `performanceEvidence` is now explicitly classified and bounded, but many models will still only carry runtime/internal evidence rather than observed-versus-predicted datasets, predictive evaluation sets, or external qualification studies.
- Parameter provenance may be structured and exportable while still lacking full per-parameter citations, study conditions, or identifiability evidence.
### Operational limitations
- `rxode2` image builds are heavy and should be prebuilt rather than compiled inside a capped runtime worker.
- Runtime workers should stay conservatively capped, such as `4 GiB`.
- Durable `rxode2` image builds can take a long time on laptop hardware because of C/C++ compilation.
- The default local deployment now runs the packaged baseline, but active workspace development should still go through the documented deploy entrypoints so the intended runtime mode is explicit.
- The hardened overlay improves auth defaults and bind behavior, but it is still an operator-side compose profile rather than a full production deployment package with ingress, secret rotation, or managed identity infrastructure.
---
## Development notes
Recommended checks:
```bash
python3 scripts/check_runtime_contract_env.py
python3 scripts/public_release_preflight.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long
python3 -m unittest -v tests/test_load_simulation_contract.py
python3 -m unittest -v tests/test_model_manifest.py
python3 -m unittest -v tests/test_oecd_bridge.py
python3 -m unittest -v tests/test_model_discovery_live_stack.py
python3 -m unittest -v tests/test_oecd_live_stack.py
python3 scripts/release_readiness_check.py
python3 scripts/workspace_model_smoke.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long
```
`make runtime-contract-test` in the public repository now runs the same dependency preflight first, runs the named misuse-prevention gate, reruns the strict curated-manifest NGRA gate for the bundled example models, builds a temporary `sdist` and `wheel` outside the repo worktree, validates that the normative contract files survive source distribution packaging, and performs an installed-package check of `mcp_bridge.contract` against the built wheel so the published contract artifacts are validated across both source and distribution boundaries.
The same strict curated-manifest NGRA gate is now part of `make runtime-contract-test`, `scripts/release_readiness_check.py`, and the `Release Artifacts` workflow, so bundled example models cannot quietly regress to implicit NGRA workflow role, population support, evidence basis, or claim-boundary declarations on the normal release-prep path.
That gate is now selected through `--curated-publication-set`, so the Makefile, workflow, and manual release checklist all use one curated model inventory instead of duplicating path lists.
Human-process release artifacts now live alongside the runtime gates:
- `docs/release_readiness.md`
- `docs/github_branch_protection.md`
- `docs/hardening_migration_notes.md`
- `docs/pbpk_model_onboarding_checklist.md`
- `docs/pbk_reviewer_signoff_checklist.md`
- `docs/post_release_audit_plan.md`
Repository automation is split intentionally:
- normal CI should catch contract drift in the local runtime layer quickly
- the dedicated `Release Artifacts` workflow should be used on tags or release-prep runs to validate and retain the exact published `sdist` and wheel
- the heavier catalog-wide model smoke should run as a dedicated workflow or release gate because it builds the full worker image and executes the live stack
The published `pbpk-mcp.v1` contract manifest now distinguishes:
- `normative` artifacts that define the machine-readable contract
- `supporting` artifacts that help users adopt and publish the contract correctly
- `legacy-excluded` artifacts that remain in the repo but are intentionally outside the PBPK-side object family
### Maintainer workflow
If you are maintaining the local stack in the current convergence stage:
1. Change the authoritative runtime files in the packaged modules under `src/`, the local runtime helpers under `scripts/`, `scripts/ospsuite_bridge.R`, or the bundled `.R` model modules.
- generic MCP namespaces, tool modules, and adapter/runtime files now live under `src/`
- the local operator/runtime helper surface now lives in the deploy scripts, worker Dockerfile, and overlay hook rather than a tracked `patches/` implementation layer
2. If the worker image baseline should change, rebuild it with `./scripts/build_rxode2_worker_image.sh`. If you only need to sync the packaged runtime contents to the current workspace, use `./scripts/refresh_rxode2_worker_image.sh`.
3. Recreate the packaged local stack with `./scripts/deploy_rxode2_stack.sh`.
- When you need workspace overrides for active development, use `./scripts/deploy_source_overlay_stack.sh`.
- When you need stricter auth defaults, use `./scripts/deploy_hardened_stack.sh` with `AUTH_ISSUER_URL`, `AUTH_AUDIENCE`, and `AUTH_JWKS_URL` set. If you want the off-host audit path, also set the `AUDIT_STORAGE_BACKEND` / `AUDIT_S3_*` variables documented in `docs/deployment/s3_object_lock_audit.md`.
- When you want a packaged local proof of the S3 backend without real AWS infrastructure, use `./scripts/deploy_s3_audit_smoke_stack.sh` and then `python3 scripts/s3_audit_smoke.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long`.
4. Verify the live API with:
- `curl -s http://localhost:8000/health`
- `curl -s http://localhost:8000/mcp/list_tools`
- `python3 scripts/public_release_preflight.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long`
- retain `var/public_release_preflight_summary.json` and require `overallStatus = passed` before public release
- `python3 scripts/release_readiness_check.py`
- `python3 scripts/workspace_model_smoke.py --auth-dev-secret pbpk-local-dev-secret-32bytes-long`
- `python3 scripts/workspace_model_smoke.py --include-population --auth-dev-secret pbpk-local-dev-secret-32bytes-long`
The GitHub `Model Smoke` workflow now retains the same preflight summary alongside the live release-readiness and smoke JSON outputs, so release evidence from local runs and workflow runs stays aligned.
Important boundaries:
- `scripts/deploy_rxode2_stack.sh` is the preferred packaged local operator entrypoint.
- `scripts/deploy_source_overlay_stack.sh` is the explicit maintainer entrypoint when workspace `src/` and `scripts/` should override the image.
- `scripts/deploy_hardened_stack.sh` is the stricter operator entrypoint when you need non-anonymous auth defaults on the same packaged local stack.
- `scripts/deploy_s3_audit_smoke_stack.sh` is the packaged local entrypoint for MinIO-backed audit smoke checks.
- `docker/rxode2-worker.Dockerfile` now owns the baked baseline worker assets directly, including `scripts/ospsuite_bridge.R` and the bundled reference `.R` model.
- the local stack now defaults to the packaged runtime, while the overlay `.pth` remains only for the explicit source-overlay maintainer profile.
### Useful repository guideposts
- `scripts/ospsuite_bridge.R`
- `scripts/runtime_src_overlay.pth`
- `docker/rxode2-worker.Dockerfile`
- `scripts/workspace_model_smoke.py`
- `src/mcp_bridge/model_catalog.py`
- `src/mcp_bridge/model_manifest.py`
- `src/mcp_bridge/pbpk_tools/`
- `src/mcp/__init__.py` and `src/mcp/tools/` as deprecated compatibility shims only
- `src/mcp_bridge/adapter/__init__.py`
- `src/mcp_bridge/adapter/interface.py`
- `src/mcp_bridge/adapter/ospsuite.py`
- `docs/architecture/dual_backend_pbpk_mcp.md`
- `docs/deployment/runtime_patch_flow.md`
- `docs/integration_guides/rxode2_adapter.md`
- `docs/integration_guides/ospsuite_profile_sidecars.md`
- `docs/github_publication_checklist.md`
- `docs/hardening_migration_notes.md`
- `docs/pbpk_model_onboarding_checklist.md`
- `docs/pbk_reviewer_signoff_checklist.md`
- `docs/post_release_audit_plan.md`
---
## Contributing
Use the clean GitHub clone as the release source of truth when publishing. Before proposing a release or publication update, run the readiness checks above and review the publication checklist in `docs/github_publication_checklist.md`, the migration notes in `docs/hardening_migration_notes.md`, the model-onboarding checklist in `docs/pbpk_model_onboarding_checklist.md`, the reviewer checklist in `docs/pbk_reviewer_signoff_checklist.md`, and the post-release audit plan in `docs/post_release_audit_plan.md`.
For the published repo, follow `CONTRIBUTING.md` and use the GitHub issue and pull-request templates for normal contributions.
Maintainers should also keep `docs/github_branch_protection.md`, `docs/deployment/s3_object_lock_audit.md`, `docs/architecture/sensitivity_v2.md`, and `docs/architecture/ospsuite_population_feasibility.md` aligned with the actual runtime and governance posture.
---
## Security policy
The default local compose stack is development-oriented and currently allows anonymous local use. Do not expose it beyond localhost without hardening authentication, ingress, and runtime resource limits.
For the published repo, follow `SECURITY.md`.
---
## Code of conduct
Community interactions for the published repo should follow `CODE_OF_CONDUCT.md`.
---
## Citation
If you use PBPK MCP in your work, please cite the BioRxiv preprint:
Djidrovski, I. **ToxMCP: Guardrailed, Auditable Agentic Workflows for Computational Toxicology via the Model Context Protocol.** bioRxiv (2026). https://doi.org/10.64898/2026.02.06.703989
```bibtex
@article{djidrovski2026toxmcp,
title = {ToxMCP: Guardrailed, Auditable Agentic Workflows for Computational Toxicology via the Model Context Protocol},
author = {Djidrovski, Ivo},
journal = {bioRxiv},
year = {2026},
doi = {10.64898/2026.02.06.703989},
url = {https://doi.org/10.64898/2026.02.06.703989}
}
```
Citation metadata: `CITATION.cff`
---
## Roadmap
- Keep reducing the remaining source-overlay-specific maintainer surface now that the default local runtime is packaged by default.
- Add richer quantitative uncertainty, sensitivity, and implementation-verification evidence to strengthen regulatory-facing qualification.
- Expand dossier-grade parameter provenance and model-performance evidence across curated example and production models.
- Keep improving release automation so image build, hot patching, docs, and version markers stay aligned.
---
## License
Apache-2.0
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues