mcp-snomed-ct: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SNOMED CT MCP server — provides LLM-accessible tools for searching, retrieving, and navigating SNOMED CT clinical terminology concepts via FHIR R4 terminology servers. Single-file server (server.py, ~660 lines) built with FastMCP.

Running the Server

# Install dependencies (using venv)
pip install -r requirements.txt

# Run
python server.py

The server reads .env for configuration. Key variables:

• SNOMED_BACKEND — "local" (Snowstorm) or "remote" (hosted FHIR server)
• SNOWSTORM_LOCAL_URL / FHIR_REMOTE_URL — backend endpoint
• SNOMED_DOMAINS — comma-separated list to restrict searchable domains (default: all 19)

Architecture

Everything lives in server.py. The flow:

1. SNOMED_HIERARCHIES dict (single source of truth) maps domain names to SNOMED CT root concept IDs and human-readable labels
2. SNOMED_DOMAINS env var is parsed at startup to filter which domains are active
3. SnomedDomain enum is dynamically generated from active domains — this is what the LLM sees in the tool schema
4. Tool descriptions are dynamically built from the registry so the LLM knows what each domain contains

Request path for lookup: domain name → _domain_to_ecl() builds ECL expression (e.g., <<404684003) → _expand() calls FHIR ValueSet/$expand via httpx → _parse_concept() extracts code, preferred term, FSN, synonyms from response.

Request path for hierarchy navigation: snomed_get_related runs concurrent ECL queries via _expand_ecl() — self ({code}), parents (>!{code}), children (<!{code}), then siblings (children of each parent, minus self). Uses asyncio.gather for concurrency; siblings are computed in a second phase since they depend on the parents result. Nested ECL (e.g., <!( >!{code} )) is avoided because remote FHIR backends don't reliably support it.

MCP Interface