Dietary Exposure MCP

Part of the ToxMCP suite

MCP server for food-mediated oral exposure screening, governed contaminant and pesticide review, and version-pinned dietary evidence handoffs. It turns commodity residue assumptions, governed food-consumption profiles, survey-derived distributions, and monitoring-review evidence into auditable dietary intake summaries, legal-enforcement signals, and PBPK-ready oral dose exports without taking over PBPK execution, final regulatory decisions, or proprietary adapter execution.

Architecture

flowchart LR
    subgraph Clients["Clients and Orchestrators"]
        Codex["Codex CLI / Desktop"]
        Scripts["Scripts / notebooks"]
        Other["Other MCP-aware agents"]
    end

    subgraph MCP["FastMCP Service"]
        Server["Tool and resource surface"]
        Contracts["Schemas, examples,\ncontract manifest"]
        Docs["Operator and\nboundary docs"]
    end

    subgraph Engine["Dietary Engine"]
        Runtime["Deterministic runtime"]
        Survey["Governed raw survey\nand distribution workflows"]
        Monitoring["Contaminant / metals\nmonitoring review"]
        Enforcement["MRL / tolerance\nand trade checks"]
    end

    subgraph Governance["Scientific Control Layer"]
        Defaults["Versioned defaults packs"]
        Provenance["Assumption ledger,\nquality flags, provenance"]
        Validation["Validation dossier,\nrelease metadata, dry runs"]
    end

    subgraph Downstream["Suite Handoffs"]
        PBPK["PBPK MCP oral handoff"]
        Review["Version-pinned review dossiers"]
        FollowUp["Scientific follow-up routing"]
    end

    Clients --> Server
    Server --> Contracts
    Server --> Docs
    Server --> Runtime
    Runtime --> Survey
    Runtime --> Monitoring
    Runtime --> Enforcement
    Runtime --> Defaults
    Runtime --> Provenance
    Server --> Validation
    Server --> PBPK
    Server --> Review
    Server --> FollowUp

The released server is broader than a simple dietary calculator, but the boundary is still strict:

• Dietary Exposure MCP owns food-mediated oral intake, commodity residue inputs, consumption mappings, dietary survey distribution support, contaminant monitoring review, and oral PBPK handoffs.

• Direct-Use Exposure MCP owns direct-use oral regimens, tablets, capsules, tinctures, label-driven serving semantics, and administered-use product scenarios.

• PBPK MCP owns internal dose / toxicokinetic simulation after an external dose is already defined.

• The server is deterministic-first, with a governed survey distribution lane and cohort-bootstrap probabilistic support; it is not a general-purpose probabilistic or final-decision engine.

For the suite-level routing view, see docs/suite_integration.md.

Related MCP server: Wellness Nourish

What's in v0.1.0

• Deterministic point-estimate dietary intake scenarios with acute, chronic, and bounded summary support

• Governed raw-survey ingestion plus survey distribution summaries and cohort-bootstrap probabilistic intake support

• Maximum residue limit / tolerance enforcement records and cross-jurisdiction trade-risk screening

• Governed source, method, legal-authority, reporting-profile, occurrence-evidence, and analytical-method-evidence registries

• Contaminant and metals monitoring import checks, interpretation bundles, signoff packets, and version-pinned review dossiers

• Scientific follow-up queue, review-board, owner handoff, remediation, signoff, and owner-signoff dossier workflows

• PBPK-ready oral dose export and ToxClaw dietary evidence bundle support

• Published JSON schemas, examples, defaults manifests, release metadata, validation dossiers, and packaged mirrors

Release snapshot

The release ships schemas, examples, governed defaults, source records, reference values, consumption profiles, legal and method registries, benchmark fixtures, and validation dossiers. Counts are intentionally not duplicated in this README: the machine-readable source of truth is release metadata, with readiness and validation evidence under docs/releases/.

Why this project exists

Dietary exposure is often still handled through opaque spreadsheets, partial MRL checks, and scattered reference-value notes. That makes internal review slow and makes regulatory challenge harder to answer.

Dietary Exposure MCP gives the suite a dedicated dietary layer that is:

• deterministic-first for auditable Tier 1 and review workflows

• governed through versioned defaults, source registries, quality flags, and explicit limitations

• MCP-native with typed tools, resources, schemas, examples, and packaged validation assets

• bounded so it complements direct-use exposure, PBPK, and review-orchestration services instead of claiming their responsibilities

Feature snapshot

Release verification

Current validation artifacts report:

• draft_ready scientific-review dossier status

• all generated validation suites passing

• scientific-invariant, MCP-conformance, schema-drift, packaging, and security gates

• population coverage for adolescent_11_17, adult_general, child_1_6, older_adult_65_plus, and pregnant_adult

See:

• docs/releases/v0.1.0.release_metadata.json

• docs/releases/v0.1.0.validation_dossier.json

• docs/release_readiness.md

Quick start

Download the complete GitHub release, verify it, and install the wheel:

mkdir dietary-mcp-v0.1.0
cd dietary-mcp-v0.1.0
gh release download v0.1.0 --repo ToxMCP/dietary-exposure-mcp
shasum -a 256 -c SHA256SUMS
uv tool install ./dietary_mcp-0.1.0-py3-none-any.whl
dietary-mcp

The wheel reports package version 0.1.0 and is distributed through this GitHub release. It is not published to PyPI.

Or run from a source checkout:

uv sync --extra dev
uv run dietary-mcp-generate-artifacts
uv run dietary-mcp-validate
uv run dietary-mcp-write-release-reports
uv run pytest
uv run dietary-mcp

Artifact generation is an explicit release-maintenance step; MCP server startup validates and serves the packaged/runtime assets without regenerating checkout files. The HTTP entrypoint remains loopback-only and fail-closed unless an operator deliberately configures an authenticated gateway. v0.1.0 support is centered on local stdio operation.

Optional public-seed generation:

uv run --with xlrd dietary-mcp-generate-public-seeds --workbook /path/to/gems_food_cluster_diets.xls

Repository layout

• src/dietary_mcp/: package code and MCP server surface

• defaults/v1/: curated defaults, taxonomy, legal packs, recipes, reporting profiles, and source databases

• validation/v1/: benchmark fixtures, reference cases, monitoring checks, and governed validation packs

• docs/contracts/schemas/: generated JSON Schema files

• schemas/examples/: generated example payloads

• docs/releases/: generated release metadata, validation dossiers, and dry-run reports

• docs/adr/: architecture decisions

• tests/: runtime, defaults, validation, benchmark, and release regression coverage

Release status and intended use

Use v0.1.0 to build reproducible screening calculations, inspect assumptions, and prepare governed evidence handoffs. Do not use an output by itself to make a legal, clinical, safety, regulatory, or market-access decision. Start with the release notes, limitations and intended use, and release readiness.

Current limitations

Workflow states such as signed_off close a configured review packet; they do not confer regulator acceptance. The canonical explanation is Limitations and Intended Use, with route boundaries in the dietary boundary guide.

Contributing

• CONTRIBUTING.md documents the governed change workflow for collaborators.

• CODE_OF_CONDUCT.md sets expectations for respectful, scientifically honest collaboration.

• Use the scientific-correction issue form for source, unit, population, or interpretation concerns.

• docs/release_checklist.md is the pre-push and pre-release checklist.

Security

Report vulnerabilities through GitHub private vulnerability reporting. Do not put exploit details, credentials, unpublished dossiers, or local paths in a public issue. See SECURITY.md.

Citation

Citation metadata is available in CITATION.cff. Scientific records should also cite the original authority output identified by the record's provenance, because this software is not the primary scientific source.

License

Original project code and documentation are licensed under the Apache License 2.0. Third-party scientific data and vendored materials retain their own terms; see THIRD_PARTY_NOTICES.md.