Pharmacy MCP Gateway

An MCP server and agent harness that makes pharmaceutical knowledge available through one traceable query contract. It combines public drug APIs, Taiwan TFDA/NHI data, hospital FHIR and inventory, organization databases, vector search, files, fixed web documents, and a trusted PK/DDI simulation catalog.

繁體中文 · Documentation · Architecture

Version 1.0 prerelease. Reference data only; not medical advice or a replacement for a pharmacist, physician, or validated clinical decision-support system.

Why this gateway

• One agent entry point: query_pharmacy routes by capability or explicit source and isolates provider timeouts and failures.

• Stable output: every MCP tool returns QueryResponse v1.0 through a shared JSON Schema. Text is a deterministic json, json_compact, or markdown rendering; MCP structuredContent remains authoritative.

• Agent constraint: every tool carries forwarding rules and clients can load the pharmacy-query-contract MCP prompt.

• Traceable compound results: provider payloads, provenance, warnings, and errors remain distinct. Successful data survives as partial if another source fails.

• Hospital-ready boundaries: FHIR is read-only; file, SQL, vector, and web connectors are configured by operators instead of accepting arbitrary agent paths, SQL, endpoints, or URLs.

• Drift detection: a scheduled health workflow probes 18 official API and dataset surfaces every week without downloading the large Taiwan datasets.

• Deployable FastMCP: use stdio locally or mount the same tool catalog over SSE/Streamable HTTP; service creation and the ASGI export remain lazy.

• Auditable simulation: trusted formulas include units, assumptions, limitations, provenance, fixtures, and fail-closed numerical validation.

Related MCP server: Taiwan Health MCP Server

Quick start

Requires Python 3.11+ and uv.

git clone https://github.com/u9401066/pharmacy-mcp.git
cd pharmacy-mcp
uv sync --all-extras
uv run pharmacy-mcp

Streamable HTTP and ASGI deployments use the same tools and output contract:

uv run pharmacy-mcp --transport streamable-http --host 127.0.0.1 --port 8000
uvicorn pharmacy_mcp.presentation.server:app --host 127.0.0.1 --port 8000

MCP client configuration:

{
  "mcpServers": {
    "pharmacy": {
      "command": "uv",
      "args": ["run", "pharmacy-mcp"],
      "cwd": "/absolute/path/to/pharmacy-mcp"
    }
  }
}

Recommended tool call:

{
  "query": "warfarin",
  "capabilities": ["identity", "label", "reimbursement", "formulary"],
  "sources": ["rxnorm", "dailymed", "tw-tfda", "tw-nhi", "local-formulary"],
  "limit": 10,
  "output_format": "json_compact",
  "locale": "zh-TW"
}

For a shell or non-MCP workflow:

uv run pharmacy-query warfarin \
  --source local-formulary \
  --capability formulary \
  --format json_compact

The Python API exposes the same contract through pharmacy_mcp.application.harness.PharmacyHarness.

Integrated knowledge

Call list_knowledge_sources for the runtime source of truth: capabilities, implementation state, credential needs, and whether an adapter is registered. See the complete data-source catalog.

Taiwan NHI and hospital setup

The NHI provider downloads the official monthly CSV on demand and atomically builds a versioned SQLite index. It can combine reimbursement code, price, ATC, effective dates, TFDA results, and coverage-rule metadata in one query. See Taiwan NHI compound queries.

Set PHARMACY_MCP_FHIR_BASE_URL to register the hospital adapter. Bearer tokens are read from SecretStr settings, and patient resources are queried only when an authorized caller explicitly supplies context.patient_id. Organization connectors use similarly explicit allowlists. Start with .env.example, FHIR and inventory, and organization connectors.

Output and agent rules

The canonical top-level fields are:

schema_version · status · data · sources · warnings · errors · meta

Unknown top-level fields are rejected. All 33 current tools, including calculation and simulation tools, use this envelope. Agents must preserve all seven fields, must not infer absent clinical facts, and must not flatten multiple providers into one implied authority. See the agent harness guide and response contract.

Development

uv sync --all-extras
uv run pytest
uv run ruff check src tests examples scripts
uv run mypy src
uv run mkdocs build --strict
uv run python scripts/check_source_health.py

The repository uses segmented Conventional Commits, an updated Memory Bank, CI across supported Python versions, weekly public-source health checks, and a GitHub Pages documentation workflow. See CONTRIBUTING.md and SECURITY.md.

License

Apache License 2.0. Upstream datasets and commercial knowledge bases retain their own terms, attribution requirements, and clinical-use restrictions.