Metadata-Version: 2.4
Name: iflow-mcp_amitpuri-fhir-mcp-server
Version: 1.0.3
Summary: FHIR MCP Server - A Model Context Protocol server for interacting with FHIR servers
Author-email: amitpuri <amitpuri@example.com>
License: MIT
Project-URL: Homepage, https://github.com/amitpuri/agentic-healthcare-ai
Project-URL: Repository, https://github.com/amitpuri/agentic-healthcare-ai
Project-URL: Documentation, https://github.com/amitpuri/agentic-healthcare-ai/blob/main/fhir_mcp_server/README.md
Keywords: mcp,fhir,healthcare,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohappyeyeballs>=2.6.1
Requires-Dist: aiohttp>=3.12.14
Requires-Dist: aiosignal>=1.3.2
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: anyio>=4.9.0
Requires-Dist: attrs>=25.3.0
Requires-Dist: certifi>=2025.4.26
Requires-Dist: charset-normalizer>=3.4.2
Requires-Dist: click>=8.2.1
Requires-Dist: fhirpy>=2.0.15
Requires-Dist: frozenlist>=1.6.0
Requires-Dist: h11>=0.16.0
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: idna>=3.10
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: mcp>=1.10.1
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: mdurl>=0.1.2
Requires-Dist: multidict>=6.4.4
Requires-Dist: propcache>=0.3.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: pydantic-core>=2.33.2
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: pygments>=2.19.1
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: pytz>=2025.2
Requires-Dist: requests>=2.32.4
Requires-Dist: rich>=14.0.0
Requires-Dist: shellingham>=1.5.4
Requires-Dist: sniffio>=1.3.1
Requires-Dist: sse-starlette>=2.3.5
Requires-Dist: starlette>=0.49.1
Requires-Dist: typer>=0.16.0
Requires-Dist: typing-extensions>=4.13.2
Requires-Dist: typing-inspection>=0.4.1
Requires-Dist: urllib3>=2.5.0
Requires-Dist: uvicorn>=0.34.2
Requires-Dist: yarl>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# FHIR MCP Server

A Model Context Protocol (MCP) server that provides secure, standardized access to FHIR (Fast Healthcare Interoperability Resources) servers. This server acts as a bridge between MCP clients and FHIR APIs, offering a simplified and secure way to access healthcare data.

## Features

- **MCP Protocol Support**: Full Model Context Protocol implementation
- **FHIR R4 Compatibility**: Works with any FHIR R4-compliant server
- **Simplified Configuration**: Easy setup with environment variables
- **Docker Ready**: Containerized for easy deployment
- **Health Monitoring**: Built-in health check endpoints
- **Security**: Optional OAuth/Bearer token authentication
- **Two Server Modes**: Simple server for development, full server for production

## Supported FHIR Operations

The server provides the following MCP tools for FHIR operations:

- `get_capabilities` - Get FHIR server capabilities for a resource type
- `search` - Search for FHIR resources with parameters
- `read` - Read a specific FHIR resource by ID
- `create` - Create a new FHIR resource
- `update` - Update an existing FHIR resource
- `delete` - Delete a FHIR resource

## Quick Start

### Using Docker Compose (Recommended)

1. Clone the repository and navigate to the project root
2. Copy the environment template:
   ```bash
   cp env.template .env
   ```
3. Edit `.env` with your FHIR server configuration
4. Start the server:
   ```bash
   docker-compose up fhir-mcp-server
   ```

### Manual Installation

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Set environment variables:
   ```bash
   export FHIR_MCP_FHIR__BASE_URL="https://hapi.fhir.org/baseR4"
   export FHIR_MCP_HOST="localhost"
   export FHIR_MCP_PORT="8004"
   ```

3. Run the server:
   ```bash
   python -m fhir_mcp_server
   ```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `FHIR_MCP_HOST` | Server host address | `localhost` |
| `FHIR_MCP_PORT` | Server port | `8004` |
| `FHIR_MCP_FHIR__BASE_URL` | FHIR server base URL | `https://hapi.fhir.org/baseR4` |
| `FHIR_MCP_FHIR__ACCESS_TOKEN` | Bearer token for FHIR server | (empty) |
| `FHIR_MCP_FHIR__TIMEOUT` | Request timeout in seconds | `30` |
| `FHIR_MCP_USE_SIMPLE` | Use simplified server | `true` |

### Server Modes

#### Simple Server (Default)
- Lightweight implementation
- Basic FHIR operations
- Minimal dependencies
- Best for development and testing

#### Full Server
- Complete OAuth2/OIDC support
- Advanced authentication flows
- Production-ready features
- Set `FHIR_MCP_USE_SIMPLE=false` to enable

## Usage Examples

### Using with Healthcare AI UI

The FHIR MCP server integrates seamlessly with the Healthcare AI UI:

1. Enable MCP mode in UI Settings
2. Set MCP server URL to `http://localhost:8004`
3. Configure your FHIR server URL
4. Test the connection

### Direct MCP Protocol Usage

```javascript
// Example MCP request to search for patients
const request = {
  jsonrpc: "2.0",
  id: 1,
  method: "tools/call",
  params: {
    name: "search",
    arguments: {
      type: "Patient",
      searchParam: {
        name: "John"
      }
    }
  }
};

fetch('http://localhost:8004/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
});
```

## API Endpoints

- `POST /mcp` - MCP protocol endpoint
- `GET /health` - Health check endpoint
- `GET /oauth/callback` - OAuth callback (full server only)
- `GET /fhir/callback` - FHIR OAuth callback (full server only)

## Health Check

The server provides a health check endpoint at `/health`:

```bash
curl http://localhost:8004/health
```

Response:
```json
{
  "status": "healthy",
  "service": "FHIR MCP Server",
  "version": "1.0.0",
  "fhir_url": "https://hapi.fhir.org/baseR4"
}
```

## Development

### Running Tests

```bash
# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/
```

### Code Structure

```
fhir_mcp_server/
├── Dockerfile              # Docker configuration for the service
├── README.md               # This README file
├── __init__.py             # Package initialization
├── __main__.py             # Main entry point for the service
├── fhir_mcp_service.py     # Main FHIR MCP service implementing business logic and tool definitions
└── requirements.txt        # Python dependencies
```

## Security Considerations

- Always use HTTPS in production
- Configure proper FHIR server authentication
- Validate all input parameters
- Monitor access logs
- Keep dependencies updated

## Troubleshooting

### Common Issues

1. **Connection Refused**
   - Check if the server is running
   - Verify host and port configuration
   - Ensure firewall allows connections

2. **FHIR Authentication Errors**
   - Verify FHIR server URL is correct
   - Check access token if using authentication
   - Ensure FHIR server is accessible

3. **MCP Protocol Errors**
   - Verify JSON-RPC 2.0 format
   - Check method and parameter names
   - Review server logs for details

### Logs

Enable debug logging for troubleshooting:

```bash
python -m fhir_mcp_server --log-level DEBUG
```

## Contributing

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

## License

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

## Support

For support and questions:
- Open an issue on GitHub
- Check the documentation
- Review the troubleshooting guide

## Related Projects

- [Healthcare AI Agents](../README.md) - Main healthcare AI platform
- [FHIR Proxy](../fhir_proxy/) - Alternative FHIR access method
- [MCP Specification](https://modelcontextprotocol.io/) - Official MCP documentation

## New File Structure

```
fhir_mcp_server/
├── Dockerfile              # Docker configuration for the service
├── README.md               # This README file
├── __init__.py             # Package initialization
├── __main__.py             # Main entry point for the service
├── fhir_mcp_service.py     # Main FHIR MCP service implementing business logic and tool definitions
└── requirements.txt        # Python dependencies
```
