Openehr MCP Server

🚀 openEHR MCP Server

An openEHR MCP Server based on the Model Context Protocol (MCP) for interacting with the openEHR REST API (specifically the EHRbase implementation). This server enables MCP clients (such as Claude Desktop) to create compositions for openEHR templates and submit them to the server.

For production-level EHR integration, an AI model that ensures data privacy must be used.

For more information about MCP, please visit https://modelcontextprotocol.io/introduction

🚀 Quick Start

Using the pre-built Docker image (available on Docker Hub) is the simplest way to get started.

1. Prerequisites

Ensure you have a running EHRbase server. If needed, refer to the setup guide in the documentation.

2. Install Docker

Install and configure the Docker environment according to the official documentation: https://docs.docker.com/get-docker/

3. Pull the Docker Image

Download the openEHR MCP Server image from Docker Hub:

docker pull openehr-mcp-server:latest

4. Run the Docker Container

Run the container in interactive mode and connect it to the host network:

docker run -it --network host openehr-mcp-server:latest

This will start the MCP server, and you can see the log output in the terminal. By default, the server will run on http://localhost:8080.

5. Verify the Installation

Open a browser or use a command-line tool to access http://localhost:8080. You should see the welcome page or API documentation of the MCP server.

✨ Features

MCP Tools

• openehr_template_list: List all available openEHR templates on the EHRbase server.
• openehr_template_get: Retrieve a specific openEHR template by its unique identifier.
• openehr_template_example_composition: Generate an example openEHR composition based on a specific template.
• openehr_ehr_create: Create a new EHR.
• openehr_ehr_get: Get an EHR by its ID.
• openehr_ehr_list: List all available EHRs in the system.
• openehr_ehr_get_by_subject: Get an EHR by the subject ID and namespace.
• openehr_composition_create: Create a new openEHR composition in the electronic health record.
• openehr_composition_get: Retrieve an existing openEHR composition by its unique identifier.
• openehr_composition_update: Update an existing openEHR composition.
• openehr_composition_delete: Delete an existing openEHR composition from the electronic health record.
• openehr_query_adhoc: Execute an ad-hoc AQL query on the openEHR server.

MCP Prompts

• vital_signs_capture: Capture vital signs for a specific EHR ID.

📦 Installation

Install Dependencies

Before you start, make sure the following software is installed on your system:

• Python 3.6 or higher
• pip (Python package manager)
• Docker (if you need to use containerized deployment)

Clone the Repository

Clone this repository from GitHub:

git clone https://github.com/yourusername/openehr-mcp-server.git
cd openehr-mcp-server

Install Python Packages

In the project root directory, install the required Python packages:

pip install -r requirements.txt

Configure Settings

Create a config.py file (or copy an existing example configuration file) and adjust it as needed.

# Example of config.py
DEBUG = True
PORT = 8080
HOST = 'localhost'

Start the Server

Run the following command to start the MCP server:

python app.py

The server will start on the specified port and be ready to handle requests.

💻 Usage Examples

Command-Line Tools

All MCP tools can be used via the command line. For example:

List All Templates

openehr_template_list --server http://localhost:8080

Create a New EHR

openehr_ehr_create --subject-id "patient_1234" --server http://localhost:8080

API Documentation

The full API documentation can be accessed via Swagger UI: http://localhost:8080/swagger

📚 Documentation

Testing

Unit Tests

Run the following command to execute unit tests:

pytest tests/test_*.py -v

This will run all test cases and output detailed results.

Integration Tests

Run more comprehensive tests in the integration environment:

pytest integration_tests/ --cov=openehr_mcp_server

Troubleshooting

If you encounter problems, check the following:

1. Ensure Docker is correctly installed and running.
2. Check the container's log output for possible error messages:

   docker logs <container-id>
   

3. View the server log file (usually located in the logs/ directory).

Contribution Guidelines

If you wish to contribute to the project, please follow these steps:

1. Fork the repository.
2. Create a new feature branch:

   git checkout -b feature/<your-feature>
   

3. Commit your changes and create a Pull Request to the main branch.
4. Provide detailed descriptions of your changes in the Pull Request.

📄 License

This project is licensed under the MIT License. For more details, please refer to the LICENSE file.

If you have any questions or need further assistance, please feel free to contact us!