berkdurmus/eps-mcp

EPS MCP Server

A Model Context Protocol (MCP) server for the NHS Electronic Prescription Service (EPS) FHIR API. This server provides tools, resources, and prompts for interacting with electronic prescriptions, enabling seamless integration with LLM applications.

Overview

The EPS MCP Server implements the Model Context Protocol to provide standardized access to the NHS Electronic Prescription Service FHIR API. It enables LLM applications to:

• Search for prescriptions and medication data
• Track prescription status and dispensing history
• Find nearby pharmacies and dispensing sites
• Validate FHIR resources against EPS profiles
• Access comprehensive documentation and examples

Features

Tools

• search_prescriptions: Search for prescriptions using FHIR Bundle endpoint
• get_prescription_details: Get detailed information about specific prescriptions
• track_prescription_status: Track prescription dispensing status and history
• find_dispensing_sites: Find pharmacies and dispensing locations
• validate_fhir_resource: Validate FHIR resources against EPS profiles

Resources

• API Specification: Complete OpenAPI specification for EPS FHIR API
• Example Resources: Sample FHIR Bundles and MedicationRequest resources
• Documentation: EPS-specific FHIR profiles and extensions
• Error Reference: Comprehensive error codes and troubleshooting guide

Prompts

• analyze_prescription_data: Generate insights and analysis from prescription data
• explain_fhir_structure: Explain FHIR resource structures and usage
• prescription_workflow_guide: Generate workflow guides for different user roles

Installation

Prerequisites

• Node.js 18+
• npm or yarn package manager

Setup

1. Clone or download this repository:

git clone <repository-url>
cd EPS-MCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Running the Server

The server runs using the stdio transport for MCP communication:

npm start

For development with automatic rebuilding:

npm run dev

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

{
  "mcpServers": {
    "eps-fhir": {
      "command": "node",
      "args": ["/path/to/EPS-MCP/dist/index.js"],
      "env": {}
    }
  }
}

Authentication

The server uses the NHS Digital sandbox environment by default. For production use:

1. Obtain API credentials from NHS Digital Developer Portal
2. Configure authentication headers in the service
3. Update the service constructor to use production endpoints

Tools Reference

search_prescriptions

Search for prescriptions using patient identifier and optional filters.

Parameters:

• patient_identifier (required): NHS number or patient identifier
• status (optional): Prescription status (active, completed, cancelled, draft)
• date_from (optional): Start date for search (YYYY-MM-DD)
• date_to (optional): End date for search (YYYY-MM-DD)

Example:

{
  "patient_identifier": "9446041481",
  "status": "active",
  "date_from": "2024-01-01"
}

get_prescription_details

Get comprehensive details for a specific prescription.

Parameters:

• prescription_id (required): Unique prescription identifier

Example:

{
  "prescription_id": "prescription-12345"
}

track_prescription_status

Track dispensing status and history for a prescription.

Parameters:

• prescription_id (required): Prescription ID to track

find_dispensing_sites

Find pharmacies and dispensing locations near a postcode.

Parameters:

• postcode (required): UK postcode to search near
• radius (optional): Search radius in miles (default: 5)
• service_type (optional): Type of service (community, distance_selling, appliance_contractor)

Example:

{
  "postcode": "SW1A 1AA",
  "radius": 10,
  "service_type": "community"
}

validate_fhir_resource

Validate FHIR resources against EPS profiles.

Parameters:

• resource_type (required): FHIR resource type (Bundle, MedicationRequest, Patient, Practitioner, Organization)
• resource_data (required): FHIR resource JSON data

Resources Reference

API Specification

URI: eps://api/specification Complete OpenAPI 3.0 specification for the EPS FHIR API.

Example Resources

URI: eps://examples/{resource-name}

• prescription-bundle: Sample prescription search results
• medication-request: Example MedicationRequest resource

Documentation

URI: eps://documentation/{doc-name}

• profiles: EPS FHIR profiles and extensions documentation

Reference Materials

URI: eps://reference/{ref-name}

• error-codes: Complete error codes reference

Prompts Reference

analyze_prescription_data

Generate detailed analysis and insights from prescription data.

Arguments:

• prescription_data (required): FHIR Bundle or MedicationRequest data
• focus_area (optional): Specific analysis focus area

explain_fhir_structure

Explain FHIR resource structures and their usage in EPS context.

Arguments:

• resource_type (required): FHIR resource type to explain
• detail_level (optional): Explanation detail level (basic, intermediate, advanced)

prescription_workflow_guide

Generate workflow guides for prescription processes.

Arguments:

• workflow_type (required): Workflow type (prescribing, dispensing, tracking)
• user_role (optional): Target user role (prescriber, pharmacist, patient, developer)

Development

Project Structure

EPS-MCP/
├── src/
│   ├── index.ts              # Main server entry point
│   └── services/
│       └── eps.fhir.service.ts  # EPS FHIR API service
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Development Mode

npm run dev

This runs TypeScript in watch mode, automatically recompiling on changes.

Code Organization

• Server: Main MCP server implementation with protocol handlers
• Service: EPS FHIR API integration and business logic
• Validation: Zod schemas for request validation
• Error Handling: Comprehensive error handling with proper MCP error codes

API Integration

NHS Digital EPS FHIR API

This server integrates with the NHS Digital Electronic Prescription Service FHIR API:

• Production: https://api.service.nhs.uk/electronic-prescriptions
• Sandbox: https://sandbox.api.service.nhs.uk/electronic-prescriptions

Supported Endpoints

• GET /Bundle - Search prescriptions
• GET /MedicationRequest/{id} - Get prescription details
• GET /MedicationDispense - Get dispensing information
• GET /Organization - Find pharmacies and dispensing sites

Error Handling

The server implements comprehensive error handling:

• Validation Errors: Invalid request parameters
• API Errors: NHS Digital API response errors
• Network Errors: Connection and timeout issues
• Resource Errors: Missing or invalid resources

All errors are properly formatted as MCP errors with appropriate error codes.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the NHS Digital Developer Hub documentation
2. Review the EPS FHIR API specification
3. Create an issue in this repository

Related Resources

• NHS Digital Developer Hub
• EPS FHIR API Documentation
• Model Context Protocol
• FHIR R4 Specification