Fhir MCP Server Medagentbench

🚀 fhir-mcp-server-medagentbench

A Python-based MCP (MedAgentBench Communication Protocol) server designed for the MedAgentBench environment. This server simulates interactions with the FHIR (Fast Healthcare Interoperability Resources) API.

Instead of sending actual HTTP requests to a FHIR server, it intercepts FHIR operations in MCP requests and returns a textual representation of the request (e.g., GET https://fhir.example.com/Patient/123 or POST https://fhir.example.com/Observation\n{...}). This allows testing MedAgentBench agents without a live FHIR endpoint.

🚀 Quick Start

Installation

Make sure Python >= 3.10 and Poetry are installed.

poetry install

Configuration

Before running the server, you must set the environment variable FHIR_BASE_URL. This URL is used to build the simulated request string.

export FHIR_BASE_URL="https://your-fhir-server-base.com/fhir"
# Or for local testing:
# export FHIR_BASE_URL="http://localhost:8080/fhir"

Usage

After configuration, run the server using the installed script:

fhir-mcp-server-medagentbench

The server will start listening for MCP requests on standard input/output.

✨ Features

• Implement MCP processors:
  • list_resources: List available simulated resources (currently CapabilityStatement).
  • read_resource: Simulate reading a FHIR resource via URI.
  • list_tools: List available FHIR simulation tools.
  • call_tool: Simulate executing FHIR operations:
    • search_fhir: Simulate searching for FHIR resources.
    • read_fhir: Simulate reading a specific FHIR resource via URI.
    • create_fhir_resource: Simulate creating a new FHIR resource.
• Use the mcp-server library for MCP communication.
• Use Poetry for configuration and packaging.
• Include asynchronous unit tests using pytest and pytest-asyncio.

📦 Installation

Ensure Python >= 3.10 and Poetry are installed, then run:

poetry install

📚 Documentation

Configuration

Set the FHIR_BASE_URL environment variable before running the server:

export FHIR_BASE_URL="https://your-fhir-server-base.com/fhir"
# Or for local testing:
# export FHIR_BASE_URL="http://localhost:8080/fhir"

Usage

Run the server using the installed script:

fhir-mcp-server-medagentbench

The server will listen for MCP requests on standard input/output.

Development

Setup

Clone the repository and install dependencies (including development tools):

git clone https://github.com/MikeHolcomb/mcp-fhir-python-medagentbench.git
cd mcp-fhir-python-medagentbench
poetry install --with dev

Format Checking and Code Style

This project uses pre-commit to perform code style (black, isort) and issue checks (flake8, mypy).

# Run all checks on commit (usually runs automatically)
poetry run pre-commit run

# Run checks on all files
poetry run pre-commit run --all-files

# Or run tools separately
poetry run black .
poetry run isort .
poetry run flake8 src tests
poetry run mypy src

Testing

Tests are located in the tests/ directory and use pytest.

poetry run pytest

# Run tests with coverage report
poetry run pytest --cov=src

Tests require pytest-asyncio to support asynchronous features.

🤝 Contribution

We welcome contributions from the community! Please refer to the CONTRIBUTING.md file in the project repository to learn how to contribute.

📄 License

This project is licensed under the MIT License.