jonw2000/digiclinic-mcp-server

DigiCare MCP Server

A medical systems MCP (Model Context Protocol) server designed for experimental healthcare AI research. Built with Python 3.11+ and FastAPI, providing HTTP and Server-Sent Events (SSE) support for LLM integration with mock medical systems.

Overview

This experimental platform provides medical AI research capabilities with:

• Modern Python: Uses Python 3.11+ with type hints and async/await
• FastAPI: High-performance web framework with automatic API documentation
• MCP Protocol: Full compliance with the Model Context Protocol specification
• HTTP + SSE: Dual transport support for maximum compatibility
• Medical Tool System: Mock medical data access tools for experimental research
• Development Ready: Configured with linting, formatting, and testing tools

Quick Start

Installation

# Clone the DigiCare MCP server
cd digicare-mcp-server

# Install dependencies
pip install -e .

# For development
pip install -e ".[dev]"

Running the Server

# Start the server
digicare-mcp-server

# Or using Python module
python -m digicare_mcp_server.server

# Or using uvicorn directly
uvicorn digicare_mcp_server.server:create_app --host 0.0.0.0 --port 8000

The server will start on http://localhost:8000 with:

• API documentation at http://localhost:8000/docs
• Health check at http://localhost:8000/health
• Tools listing at http://localhost:8000/tools

API Endpoints

HTTP Endpoints

• GET / - Server information and available endpoints
• GET /health - Health check endpoint
• GET /tools - List available tools
• POST /tools/{tool_name} - Execute a specific tool
• POST /mcp - MCP protocol messages over HTTP
• GET /mcp/sse - Server-Sent Events endpoint for real-time communication

Available Medical Tools

The DigiCare MCP Server provides the following medical research tools:

1. Patient Database Tool (patient-db)

Look up detailed patient information including medical history, visits, and prescriptions.

Parameters:

• patient_name (string, required): Full name of the patient
• national_insurance (string, required): National Insurance number

2. Patient List Tool (patient-list)

Get a list of all patients in the database with their names and National Insurance numbers.

Parameters: None required

Example Usage

# List available tools
curl http://localhost:8000/tools

# Get list of all patients
curl -X POST http://localhost:8000/tools/patient-list \
  -H "Content-Type: application/json" \
  -d '{}'

# Look up specific patient information
curl -X POST http://localhost:8000/tools/patient-db \
  -H "Content-Type: application/json" \
  -d '{
    "patient_name": "Sarah Johnson",
    "national_insurance": "AB123456C"
  }'

# MCP protocol call for patient lookup
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "patient-db",
      "arguments": {
        "patient_name": "Sarah Johnson",
        "national_insurance": "AB123456C"
      }
    }
  }'

Project Structure

digicare-mcp-server/
├── digicare_mcp_server/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main server implementation
│   └── tools.py             # Medical tool definitions and handlers
├── dat/
│   └── patient-db.json      # Mock patient database (fictional data)
├── tests/                   # Test files (create as needed)
├── pyproject.toml          # Modern Python project configuration
├── README.md               # This file
├── role-intern.md          # Medical intern role definition
└── run.sh                  # Setup and run script

Adding New Tools

1. Define the tool in digicare_mcp_server/tools.py:

def get_my_tool() -> Tool:
    return Tool(
        name="my_tool",
        description="Description of what this tool does",
        inputSchema={
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    )

async def handle_my_tool(arguments: Dict[str, Any]) -> list[TextContent]:
    param1 = arguments.get("param1")
    # Tool logic here
    return [TextContent(type="text", text=f"Result: {param1}")]

2. Register the tool in digicare_mcp_server/server.py:

# In _setup_mcp_handlers method
@self.mcp_server.list_tools()
async def list_tools() -> List[Tool]:
    return [get_random_string_tool(), get_my_tool()]  # Add your tool

@self.mcp_server.call_tool()
async def call_tool(name: str, arguments: Dict[str, Any]):
    if name == "random_string":
        return await handle_random_string(arguments)
    elif name == "my_tool":  # Add your tool handler
        return await handle_my_tool(arguments)
    else:
        raise ValueError(f"Unknown tool: {name}")

Development

Code Quality

# Format code
black digicare_mcp_server/

# Lint code
ruff check digicare_mcp_server/

# Type checking
mypy digicare_mcp_server/

# Run tests
pytest

Configuration

The project uses:

• Black for code formatting
• Ruff for linting and import sorting
• MyPy for static type checking
• Pytest for testing

All tools are configured in pyproject.toml.

MCP Protocol Support

This server implements the MCP (Model Context Protocol) specification:

• Tools: Executable functions that can be called by clients
• Resources: Static or dynamic content (extend as needed)
• Prompts: Reusable prompt templates (extend as needed)
• Initialization: Proper capability negotiation
• Error Handling: Comprehensive error responses

Transport Methods

HTTP

Standard REST API endpoints for synchronous communication.

Server-Sent Events (SSE)

Real-time communication channel for:

• Live updates
• Streaming responses
• Connection monitoring

Customization

Medical Research Purpose

⚠️ EXPERIMENTAL USE ONLY ⚠️

This server is designed exclusively for:

• Medical AI Research: Testing LLM capabilities in healthcare scenarios
• Clinical Decision Support Research: Simulating interactions with medical databases
• Healthcare Tool Integration: Providing mock access to patient records, lab results, imaging data
• Diagnostic Assistance Studies: Enabling LLMs to gather and analyze medical data

Important: All medical data is fictional and generated for testing purposes only. Never use with real patient data or in clinical settings.

Customization for Medical Research

1. Add medical tools: Implement healthcare-specific functionality in tools.py
2. Simulate medical systems: Create mock databases for patient records, lab results, etc.
3. Extend data types: Add medical data schemas and validation
4. Implement medical workflows: Create realistic healthcare system interactions
5. Add authentication: Implement security appropriate for medical research environments

Dependencies

Core Dependencies

• mcp>=1.0.0 - Model Context Protocol implementation
• fastapi>=0.110.0 - Modern web framework
• uvicorn[standard]>=0.27.0 - ASGI server
• sse-starlette>=2.0.0 - Server-Sent Events support
• pydantic>=2.6.0 - Data validation and settings
• httpx>=0.27.0 - HTTP client library
• anyio>=4.3.0 - Async networking library

Development Dependencies

• pytest>=8.0.0 - Testing framework
• pytest-asyncio>=0.23.0 - Async testing support
• black>=24.0.0 - Code formatter
• ruff>=0.2.0 - Linter and import sorter
• mypy>=1.8.0 - Static type checker

License

MIT License - for medical AI research and experimentation only.

Medical Data Disclaimer

This software generates simulated medical data for experimental purposes only:

• Fictional Data: All patient records, lab results, and medical information are computer-generated
• Non-Clinical Use: Not intended for real medical decision-making or patient care
• Research Focus: Designed to test LLM capabilities in healthcare scenarios
• Privacy Safe: Contains no real patient information or PHI (Protected Health Information)