mcp-terminology

mcp-terminology

统一的 LOINC / SNOMED CT / RxNorm / ICD-10 MCP 服务 — v1.0.0 属于 fhir-mcp-suite 单体代码库。

通过单个 MCP 服务查询四大临床术语系统，该服务由免费的公共 FHIR R4 术语服务（tx.fhir.org/r4）提供支持。

---

工具

工具	描述	后端操作
lookup_code	查找单个代码 — 返回显示名称、定义和名称	CodeSystem/$lookup
search_codes	在 LOINC、SNOMED CT 或 RxNorm 中进行自由文本搜索	ValueSet/$expand?filter=
translate_code	跨系统转换代码（如 SNOMED ↔ ICD-10-CM）	ConceptMap/$translate
expand_valueset	按 URL 展开任意规范 FHIR ValueSet	ValueSet/$expand

lookup_code 支持的系统

别名	URI
loinc	http://loinc.org
snomed / snomed-ct	http://snomed.info/sct
rxnorm	http://www.nlm.nih.gov/research/umls/rxnorm
icd-10-cm	http://hl7.org/fhir/sid/icd-10-cm
icd-10	http://hl7.org/fhir/sid/icd-10
cvx	http://hl7.org/fhir/sid/cvx
cpt	http://www.ama-assn.org/go/cpt
ndc	http://hl7.org/fhir/sid/ndc
ucum	http://unitsofmeasure.org

---

快速开始

# Install into the monorepo workspace
uv sync --all-packages

# Run (stdio mode — for Claude Desktop)
uv run mcp-terminology

# Run with SSE transport (port 8001)
MCP_TRANSPORT=sse uv run mcp-terminology

---

Claude Desktop 配置

{
  "mcpServers": {
    "terminology": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fhir-mcp-suite",
        "run",
        "mcp-terminology"
      ],
      "env": {
        "TERMINOLOGY_BASE_URL": "https://tx.fhir.org/r4",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

---

工具调用示例

查找 LOINC 代码

{ "system": "loinc", "code": "8302-2" }

{
  "system_url": "http://loinc.org",
  "system_name": "LOINC",
  "code": "8302-2",
  "display": "Body height",
  "definition": "...",
  "designations": [...],
  "version": "2.78"
}

将 SNOMED 转换为 ICD-10-CM

{
  "code": "73211009",
  "source_system": "snomed",
  "target_system": "icd-10-cm"
}

展开 ValueSet

{ "url": "http://hl7.org/fhir/ValueSet/administrative-gender" }

---

架构

Claude Desktop / LangGraph agent
         │  MCP stdio
    mcp-terminology (this package)
         │  HTTPS
    tx.fhir.org/r4  (free public FHIR R4 terminology server)
         └── CodeSystem/$lookup
         └── ValueSet/$expand
         └── ConceptMap/$translate

可观测性：每次工具调用都会记录到 LangFuse 中（输入、输出、延迟、响应字节数）。 设置 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST 即可启用。

---

评估结果

mcp-terminology eval — 21 golden cases
  Error/security cases: 6/6   100%  (network-independent)
  Integration cases:    run with `--tags lookup search translate expand`
  CI threshold:         85% pass rate

本地运行：

# Error cases only (no network needed):
uv run python evals/mcp-terminology/run_eval.py --tags error

# Full suite (requires tx.fhir.org):
uv run python evals/mcp-terminology/run_eval.py

# CI gate:
uv run python evals/mcp-terminology/run_eval.py --ci --threshold 0.85

---

安全

• 输入清理：适用于所有参数（对代码使用正则表达式允许列表、仅允许 http/https URL、过滤器会剔除控制字符）
• 结果数量上限：每次查询最多返回 100 条结果
• 无 PHI — 仅使用合成/公开代码查询
• 完整允许列表请参阅 validation.py

---

许可证

Apache-2.0 — 详见 LICENSE。