Skip to content

Commit 880f372

Browse files
nirmal070125nirmal070125
authored
Merge pull request #6 from VimukthiRajapaksha/main
Tests: Add e2e tests for MCP tools
2 parents ad48eff + 2840dc4 commit 880f372

31 files changed

+1047
-283
lines changed

‎.gitignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,11 @@ wheels/
4141
# Environment variables
4242
.env
4343
*.env
44+
45+
# Ignore OS files
46+
.DS_Store
47+
48+
# Ignore test and coverage outputs
49+
.coverage
50+
htmlcov/
51+
.tox/

‎README.md

Lines changed: 119 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,107 @@ Whether you are building healthcare applications, integrating with AI assistants
4747
cp .env.example .env
4848
```
4949

50+
## Configuration
51+
52+
### CLI Options
53+
54+
You can customize the behavior of the MCP server using the following command-line flags:
55+
56+
- **--transport**
57+
- Description: Specifies the transport protocol used by the MCP server to communicate with clients.
58+
- Accepted values: stdio, sse, streamable-http
59+
- Default: streamable-http
60+
61+
- **--log-level**
62+
- Description: Sets the logging verbosity level for the server.
63+
- Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)
64+
- Default: INFO
65+
66+
- **--disable-mcp-auth**
67+
- Description: Disables OAuth2-based authentication between the MCP client (e.g., Claude Desktop or VSCode) and the MCP server.
68+
- Type: Flag (no value required)
69+
- Default: False (authentication enabled)
70+
71+
- **--disable-fhir-auth**
72+
- Description: Disables OAuth2-based authentication between the MCP server and the FHIR server.
73+
- Type: Flag (no value required)
74+
- Default: False (authentication enabled)
75+
76+
Sample Usages:
77+
78+
```shell
79+
uv run fhir-mcp-server --transport streamable-http --log-level DEBUG --disable-mcp-auth --disable-fhir-auth
80+
```
81+
82+
### Environment Variables
83+
84+
**MCP Server Configurations:**
85+
- `HEALTHCARE_MCP_HOST`: The hostname or IP address the MCP server should bind to (e.g., 0.0.0.0 for all interfaces, or localhost for local-only access).
86+
- `HEALTHCARE_MCP_PORT`: The port on which the MCP server will listen for incoming client requests (e.g., 8000).
87+
88+
**MCP Server OAuth2 Configuration (MCP Client ↔ MCP Server):**
89+
These variables are used when securing communication between an MCP client (like Claude Desktop or VSCode) and the MCP server via OAuth2 Authorization Code Grant flow.
90+
91+
- `HEALTHCARE_MCP_OAUTH__CLIENT_ID`: The OAuth2 client ID registered with your Identity Provider to authenticate MCP clients.
92+
- `HEALTHCARE_MCP_OAUTH__CLIENT_SECRET`: The OAuth2 client secret used to verify the MCP client during the token exchange process.
93+
- `HEALTHCARE_MCP_OAUTH__METADATA_URL`: The URL to the Identity Provider’s OAuth2 discovery document (usually ending in .well-known/openid-configuration). Used to dynamically fetch token and authorization endpoints.
94+
95+
**FHIR Backend Configuration (MCP Server ↔ FHIR Server):**
96+
These variables configure the MCP server’s secure connection with the FHIR backend using authorization code grant flow.
97+
98+
- `HEALTHCARE_MCP_FHIR__CLIENT_ID`: The OAuth2 client ID used by the MCP server to authenticate itself to the FHIR server.
99+
- `HEALTHCARE_MCP_FHIR__CLIENT_SECRET`: The client secret corresponding to the FHIR client ID. Used during token exchange.
100+
- `HEALTHCARE_MCP_FHIR__BASE_URL`: The base URL of the FHIR server (e.g., https://hapi.fhir.org/baseR4). This is used to generate tool URIs and to route FHIR requests.
101+
- `HEALTHCARE_MCP_FHIR__SCOPE`: A space-separated list of OAuth2 scopes to request from the FHIR authorization server (e.g., user/Patient.read user/Observation.read).
102+
103+
104+
## Usage
105+
106+
Run the server:
107+
```bash
108+
uv run fhir-mcp-server
109+
```
110+
111+
You can also run the server directly from the PyPI package (without cloning the repository) using:
112+
113+
```bash
114+
uvx fhir-mcp-server
115+
```
116+
117+
Check available server options:
118+
```bash
119+
uvx run fhir-mcp-server --help
120+
```
121+
122+
## Docker Setup
123+
124+
You can run the MCP server using Docker for a consistent, isolated environment.
125+
126+
### 1. Build the Docker Image
127+
128+
```bash
129+
docker build -t fhir-mcp-server .
130+
```
131+
132+
### 2. Configure Environment Variables
133+
134+
Copy the example environment file and edit as needed:
135+
136+
```bash
137+
cp .env.example .env
138+
# Edit .env to set your FHIR server, client credentials, etc.
139+
```
140+
141+
Alternatively, you can pass environment variables directly with `-e` flags or use Docker secrets for sensitive values.
142+
143+
### 3. Run the Container
144+
145+
```bash
146+
docker run --env-file .env -p 8000:8000 fhir-mcp-server
147+
```
148+
149+
This will start the server and expose it on port 8000. Adjust the port mapping as needed.
150+
50151
## Development & Testing
51152

52153
### Installing Development Dependencies
@@ -56,7 +157,7 @@ To run tests and contribute to development, install the test dependencies:
56157
**Using pip:**
57158
```bash
58159
# Install project in development mode with test dependencies
59-
pip install -e .[test]
160+
pip install -e '.[test]'
60161
61162
# Or install from requirements file
62163
pip install -r requirements-dev.txt
@@ -79,6 +180,12 @@ python run_tests.py
79180
# Or direct pytest usage
80181
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server
81182
```
183+
**Using pytest:**
184+
```bash
185+
pytest tests/
186+
```
187+
This will discover and run all tests in the `tests/` directory.
188+
82189

83190
**Test Features:**
84191
- 🧪 **100+ tests** with comprehensive coverage
@@ -95,25 +202,11 @@ The test suite includes:
95202

96203
Coverage reports are generated in `htmlcov/index.html` for detailed analysis.
97204

98-
## Usage
99-
100-
Run the server:
101-
```bash
102-
uv run fhir-mcp-server
103-
```
104-
105-
You can also run the server directly from the PyPI package (without cloning the repository) using:
106-
107-
```bash
108-
uvx fhir-mcp-server
109-
```
205+
## VS Code Integration
110206

111-
Check available server options:
112-
```bash
113-
uvx run fhir-mcp-server --help
114-
```
207+
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)
208+
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)
115209

116-
## VS Code Integration
117210
Add the following JSON block to your User Settings (JSON) file in VS Code (> V1.101). You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).
118211

119212
<table>
@@ -310,6 +403,14 @@ Once connected, MCP Inspector will allow you to visualize tool invocations, insp
310403
- `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"category":"laboratory","issued:"2025-05-01"}).
311404
- `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$expand").
312405
406+
## Screenshots
407+
408+
### EPIC FHIR Integration
409+
410+
| User Enters a Query | User Authenticates | User Grants Consent | LLM Displays the Response |
411+
|:----------------------:|:-------------------------:|:---------------------------:|:----------------------------:|
412+
| ![User enters a query](docs/images/vscode/epic/user-enters-query.png) | ![User authenticates](docs/images/vscode/epic/user-authenticates.png) | ![User grants consent](docs/images/vscode/epic/user-grants-consent.png) | ![LLM displays the response](docs/images/vscode/epic/llm-displays-response.png) |
413+
313414
## Example Prompts
314415
- Can you create a new record for Homer Simpson? He's male and was born on 12th of May 1956.
315416
- Record Homer's blood pressure as 120 over 80, taken today at 8 AM.

‎docs/images/vscode/epic/llm-displays-response.png

275 KB
Loading

‎docs/images/vscode/epic/user-authenticates.png

378 KB
Loading

‎docs/images/vscode/epic/user-enters-query.png

152 KB
Loading

‎docs/images/vscode/epic/user-grants-consent.png

563 KB
Loading

‎pyproject.toml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,14 @@ url = "https://pypi.org/simple/"
4747

4848
[project.optional-dependencies]
4949
dev = [
50-
"pytest>=8.0.0",
51-
"pytest-asyncio>=0.23.0",
52-
"pytest-cov>=4.0.0",
50+
"pytest==8.4.0",
51+
"pytest-asyncio==1.0.0",
52+
"pytest-cov==6.2.0",
5353
]
5454
test = [
55-
"pytest>=8.0.0",
56-
"pytest-asyncio>=0.23.0",
57-
"pytest-cov>=4.0.0",
55+
"pytest==8.4.0",
56+
"pytest-asyncio==1.0.0",
57+
"pytest-cov==6.2.0",
5858
]
5959

6060
[project.urls]

‎src/fhir_mcp_server/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# WSO2 LLC. licenses this file to you under the Apache License,
44
# Version 2.0 (the "License"); you may not use this file except
55
# in compliance with the License.
6-
# You may obtain postgres_pgvector copy of the License at
6+
# You may obtain a copy of the License at
77

88
# http://www.apache.org/licenses/LICENSE-2.0
99

‎src/fhir_mcp_server/__main__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# WSO2 LLC. licenses this file to you under the Apache License,
44
# Version 2.0 (the "License"); you may not use this file except
55
# in compliance with the License.
6-
# You may obtain postgres_pgvector copy of the License at
6+
# You may obtain a copy of the License at
77

88
# http://www.apache.org/licenses/LICENSE-2.0
99

‎src/fhir_mcp_server/oauth/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# WSO2 LLC. licenses this file to you under the Apache License,
44
# Version 2.0 (the "License"); you may not use this file except
55
# in compliance with the License.
6-
# You may obtain postgres_pgvector copy of the License at
6+
# You may obtain a copy of the License at
77

88
# http://www.apache.org/licenses/LICENSE-2.0
99

0 commit comments

Comments
 (0)