# SNOMED CT MCP Server

A Model Context Protocol (MCP) server that provides access to SNOMED CT terminology services. This server can be deployed on Cloudflare Workers for scalable, serverless access to SNOMED CT data.

## Features

- **Search Concepts**: Search for SNOMED CT concepts by term
- **Concept Details**: Get detailed information about specific concepts
- **Descriptions**: Retrieve all descriptions for a concept
- **Relationships**: Get concept relationships and hierarchy
- **Navigation**: Browse concept children and parents
- **ECL Support**: Search using Expression Constraint Language

## Available Tools

1. `search_concepts` - Search for concepts by term
2. `get_concept` - Get concept details by ID
3. `get_concept_descriptions` - Get all descriptions for a concept
4. `get_concept_relationships` - Get concept relationships
5. `get_concept_children` - Get child concepts
6. `get_concept_parents` - Get parent concepts
7. `search_by_ecl` - Search using ECL expressions

## Installation

### Prerequisites

- Node.js 20 or later
- npm or yarn
- Claude Desktop app

### Install from GitHub

1. Clone the repository:
```bash
git clone https://github.com/yourusername/snomed-mcp-server.git
cd snomed-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

### Configure Claude Desktop

1. Open your Claude Desktop configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add the SNOMED MCP server to your configuration:
```json
{
  "mcpServers": {
    "snomed-mcp-server": {
      "command": "node",
      "args": ["path/to/snomed-mcp-server/dist/index.js"]
    }
  }
}
```

**Important**: Replace `path/to/snomed-mcp-server` with the actual path to your cloned repository.

3. **Restart Claude Desktop** for the changes to take effect.

### Verify Installation

After restarting Claude Desktop, you should see the following SNOMED CT tools available:
- `search_concepts` - Search for SNOMED CT concepts
- `get_concept` - Get detailed concept information
- `get_concept_descriptions` - Get concept descriptions
- `get_concept_relationships` - Get concept relationships
- `get_concept_children` - Get child concepts
- `get_concept_parents` - Get parent concepts
- `search_by_ecl` - Search using ECL expressions

## Development

Run locally:
```bash
npm run dev
```

Build:
```bash
npm run build
```

## Deployment to Cloudflare Workers

1. Install Wrangler CLI:
```bash
npm install -g wrangler
```

2. Login to Cloudflare:
```bash
wrangler auth login
```

3. Deploy:
```bash
npm run deploy
```

## Usage Examples

### Screenshot
<img width="794" height="885" alt="Screenshot 2025-09-16 at 1 56 11 PM" src="https://github.com/user-attachments/assets/96f5d7a9-8918-4db8-97c2-cba5dabd057d" />

<img width="1643" height="988" alt="Screenshot 2025-09-16 at 2 06 43 PM" src="https://github.com/user-attachments/assets/4c1c52e9-0044-42de-8f10-da0ecf919804" />


### Search for concepts
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_concepts",
    "arguments": {
      "term": "heart attack",
      "limit": 10
    }
  }
}
```

### Get concept details
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_concept",
    "arguments": {
      "conceptId": "22298006"
    }
  }
}
```

### Search using ECL
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_by_ecl",
    "arguments": {
      "ecl": "< 404684003",
      "limit": 20
    }
  }
}
```

## API Endpoints

The server uses the SNOMED International public terminology server:
- Base URL: `https://browser.ihtsdotools.org/snowstorm/snomed-ct/MAIN`
- FHIR URL: `https://snowstorm.ihtsdotools.org/fhir`

## Troubleshooting

### MCP Server Not Appearing in Claude Desktop

1. **Check Configuration File Path**: Ensure you're editing the correct config file for your OS
2. **Verify JSON Syntax**: Make sure your `claude_desktop_config.json` has valid JSON syntax
3. **Check File Paths**: Ensure the path to `dist/index.js` is correct and absolute
4. **Restart Required**: Always restart Claude Desktop after configuration changes
5. **Build First**: Run `npm run build` before configuring Claude Desktop

### Connection Issues

1. **Check Build Output**: Ensure `dist/index.js` exists after running `npm run build`
2. **Test Locally**: Run `npm run dev` to test the server locally
3. **Node.js Version**: Ensure you're using Node.js 20 or later
4. **Permissions**: Make sure Claude Desktop can access the file path

### Common Configuration Mistakes

- Using relative paths instead of absolute paths in the configuration
- Forgetting to restart Claude Desktop after changes
- Missing the build step (`npm run build`)
- JSON syntax errors in the configuration file

### Getting Help

If you continue to experience issues:
1. Check the Claude Desktop logs
2. Verify the server runs with `npm run dev`
3. Ensure all file paths are correct and accessible

## License

MIT

## Contributing

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

## Disclaimer

This server uses the SNOMED International public terminology server for reference purposes. It is not intended for production healthcare systems. Please refer to SNOMED International licensing terms for commercial use.