Icd10 MCP

ICD-10-CM MCP服务器

一种模型上下文协议（MCP）服务器，通过3级RAG管道为AI代理提供准确的ICD-10-CM医疗编码能力。

______________________________________________________________________

这个项目是什么？

这是一个 ICD-10-CM MCP（模型上下文协议）服务器 它允许任何AI代理、Claude Desktop、LangGraph代理或web应用程序从纯英语临床记录或医疗查询中查找并分配准确的ICD-10-CM计费代码。

ICD-10-CM代码是医疗保健中用于保险索赔、医疗记录和计费的标准化诊断代码。AI代理可以使用此服务器来执行以下操作，而不是手动搜索大量代码书：

• 搜索代码 使用自然语言医学术语
• 自动对临床记录进行编码 通过提取诊断并将其与具有临床理论基础的最准确的ICD-10代码进行匹配

两种工具

此服务器公开了任何MCP兼容的AI代理都可以调用的两个工具：

l三级RAG管道

它的作用： 记录完整的临床记录（实验室报告、出院总结、病程记录），并返回结构化的ICD-10代码及其基本原理。

何时使用： 您有一份完整的临床文件，需要准确的账单代码。

速度： ~15-30秒（调用LLM两次：计划器+选择器）

例子：

Input: Lab report showing elevated glucose, HbA1c 9.2%, creatinine 2.1, eGFR 38
Output: 
  - E11.22 (Type 2 diabetes mellitus with diabetic chronic kidney disease)
  -ic kidney disease, stage 3)
  - Clinical rationale for each code selection

2. search_icd10 --快速语义向量搜索

它的作用： 接受一个简单的英语医疗查询，并返回最匹配的ICD-10代码。

何时使用： 当您知道条件但需要代码时，可以快速查找。

速度： 约2-3秒

例子：

Query: "type 2 diabetes with chronic kidney disease"
Returns: E11.22, E11.9, N18.3, etc. with descriptions and relevance scores

______________________________________________________________________

lly——RAG管道

这 code_clinical_note 工具使用 3级RAG（检索增强生成）管道 以确保准确、临床合理的ICD-10-CM代码分配。

第一阶段——规划师(planner.py)

目标： 从注释中提取临床问题并生成优化的搜索查询。

它是如何工作的：

1. 将原始临床记录作为输入
2. 通过OpenRouter将其发送到LLM（默认值： openai/gpt-4o-mini)具有详细的系统提示，充当“临床查询计划器”
3. 法学硕士分析笔记并提取一份结构化的临床问题列表

- 示例问题”，“慢性肾病贫血”

1. 对于每个问题，LLM生成2-4个语义搜索查询，这些查询针对匹配向量数据库中的ICD-10-CM代码标题进行了优化

- “2型糖尿病伴慢性肾病”的示例查询： - 2型糖尿病合并糖尿病慢性肾病 - “2型糖尿病合并肾脏并发症” - 2型糖尿病肾病

1. 返回结构化JSON：

   {
     "problems": [
       {
         "problem": "Type 2 diabetes mellitus with chronic kidney disease",
         "confidence": "high",
         "queries": ["...", "...", "..."]
       }
     ]
   }

为什么这很重要： 规划者确保我们寻找正确的东西。一份原始的临床记录可能会说“HbA1c升高9.2%，eGFR降低38”——规划者将其转化为与ICD-10代码描述相匹配的适当医学术语。

第二阶段——寻回犬(retriever.py)

目标： 使用向量搜索和排名融合为每个临床问题找到最佳候选ICD-10代码。

它工作：\*\*

1. 批量嵌入： 接受来自计划器的所有查询（跨越所有问题），并将它们批量嵌入到对OpenRouter的单个API调用中（默认值： openai/text-embedding-3-small)

- 这比逐一嵌入查询快得多

1. 矢量搜索： 对于每个问题，运行多个松果向量查询（计划器生成的每个查询一个）

- 每个查询检索 top_k=16 松果指数的结果 - 松果体指数包含预先嵌入的ICD-10-CM ctadata）

1. 互惠秩融合（RRF）： 使用RRF评分组合多个查询的结果

- RRF公式： score = Σ(1 / (k + rank)) 哪里 k=60 - 这确保了出现在多个查询结果中的代码得到增强

1. 词汇重新排序： 添加词汇相似性得分以捕捉精确的术语匹配

- 标记重叠：测量查询中有多少单词出现在代码标题中 - SequenceMatcher：测量字符级别的相似性 - 最终得分： 75% RRF + 25% lexical

1. 重复数据消除： 每个问题最多返回40个唯一的候选代码，按最终得分排序

为什么这很重要： 单个查询可能会错过相关代码。通过生成多个查询并融合结果，我们可以撒下更广泛的网，同时仍然优先考虑最相关的代码。词汇重新排序确保我们不会错过具有精确术语匹配的代码。

第三阶段——选择器(selector.py)

目标： 使用临床编码规则从候选者中选择最准确的ICD-10编码。

它是如何工作的：

1. 记录原始临床记录+每个问题的所有候选代码
2. 通过OpenRouter将所有内容发送到LLM（默认值： openai/gpt-4o-mini)具有应用ICD-10-CM编码规则的严格系统提示：

- 更喜欢最具体的组合代码 （例如，E11.22超过E11.9+N18.3） - 实施病因表现编码 （首先对根本原因进行编码） - 当存在子代码时，删除父代码 （例如，如果选择E11.22，则不包括E11） 跨问题的代码\*\*（每个代码只出现一次） - 当有特定代码可用时，避免使用“未指定”代码

1. 法学硕士审查每个候选人，并决定是否将其纳入，提供临床理由
2. 返回最终选定的代码以及每个问题的基本原理：

   {
     "results": [
       {
         "problem": "Type 2 diabetes with CKD",
         "selected_codes": [
           {
             "code": "E11.22",
             "title": "Type 2 diabetes mellitus disease",
             "rationale": "Combination code captures both diabetes and CKD relationship"
           }
         ]
       }
     ]
   }

为什么这很重要： 单独的矢量搜索可能会返回太多的代码或错过编码规则。选择器应用临床专业知识来选择正确的代码并解释原因，确保输出是可计费的和临床准确的。

MCP协议层(server.py)

目标： 将管道公开为任何AI代理都可以调用的MCP工具。

它是如何工作的：

• 建立在 mcp 开发包
• 支持 两次运输:

- 标准 --用于本地Claude Desktop使用（无网络，作为子进程运行） - HTTP/SSE --供LangGraph、web应用程序、代理、n8n等远程使用。

• Per-request OpenRouter API密钥注入 通过 X-OpenRouter-API-Key 头球

- 用户携带自己的OpenRouter密钥；服务器从不存储它 - 这允许任何人使用托管服务器，而无需公开API密钥

• 健康检查端点 在 /health 用于监控和正常运行时间检查

架构：

Client (Claude Desktop, LangGraph, etc.)
    │
    ▼
MCP Server (stdio or HTTP/SSE)
    │
    ├─► Planner ──► OpenRouter LLM (extract problems + queries)
    │
    ├─► Retriever ──► OpenRouter Embeddings + Pinecone (vector search + RRF)
    │
    └─► Selector ──► OpenRouter LLM (select codes + rationale)

______________________________________________________________________

先决条件

在使用此MCP服务器之前，您需要：

1. Python 3.10或更高版本 安装在您的系统上

- 索引名称： icd10cm-2026 - 命名空间： icd10cm_2026 - 索引应包含嵌入式ICD-10-CM代码和元数据（代码、标题、父代码、级别）

1. 一个OpenRouter API密钥 --得到一个在 openrouter.ai

1. 环境变量 （供本地/自托管使用）：

- PINECONE_API_KEY -您的Pinecone API密钥 - PINECONE_INDEX_NAME --默认值： icd10cm-2026 - PINECONE_NAMESPACE --默认值： icd10cm_2026 - OPENROUTER_API_KEY -您的OpenRouter API密钥

______________________________________________________________________

集成示例——如何使用此MCP服务器

此服务器可以与任何兼容MCP的AI代理或应用程序集成。以下是常见用例的集成指南。

A.克劳德桌面（远程托管服务器）

将Claude Desktop连接到托管服务器 https://icd10-mcp.onrender.com/sse 使用 supergateway 桥。

第一步： 从以下位置复制配置 claude_desktop_config_example.json:

{
  "mcpServers": {
    "icd10-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://icd10-mcp.onrender.com/sse",
        "--header",
        "X-OpenRouter-API-Key: sk-or-v1-YOUR_OPENROUTER_API_KEY_HERE"
      ]      
    }
  }
}

第二步： 找到您的Claude Desktop配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

步骤3： 将配置添加到Claude Desktop配置文件中（与现有配置合并 mcpServers 如果你有其他人）

步骤4： 替换 sk-or-v1-YOUR_OPENROUTER_API_KEY_HERE 使用实际的OpenRouter API密钥

步骤5： 重新启动克劳德桌面

步骤6： 通过问克劳德来测试它：

“搜索高血压合并心脏病的ICD-10编码”

它是如何工作的：

• supergateway 是一个NPM包，它将SSE（服务器发送事件）桥接到stdio
• 您的OpenRouter API密钥在 X-OpenRouter-API-Key 每个请求的标题
• 托管服务器位于 https://icd10-mcp.onrender.com/sse 处理请求
• 无需在本地运行任何东西——服务器始终可用

B.LangGraph代理

使用将LangGraph代理连接到托管的MCP服务器 langchain-mcp-adapters 包裹。

安装：

pip install langchain-mcp-adapters

示例代码：

from langchain_mcp_adapters.client import MultiServerMCPClient
import asyncio

async def create_icd10_agent():
    """Create a LangGraph agent with ICD-10 MCP tools."""
    
    # Connect to the hosted MCP server
    client = MultiServerMCPClient({
        "icd10-mcp": {
    /sse",
            "transport": "sse",
            "headers": {
                "X-OpenRouter-API-Key": "sk-or-v1-YOUR_OPENROUTER_API_KEY_HERE"
            }
        }
    })
    
    # Get available tools
    tools = await client.get_tools()
    print(f"Available tools: {[t.name for t in tools]}")
    
    # Call a tool
    result = await client.call_tool(
        "search_icd10",
        arguments={"query": "type 2 diabetes", "top_k": 5}
    )
    print(f"Results: {result}")
    
    # Use tools in t
    # ... your LangGraph state machine code here ...
    
    return client

# Run the agent
asyncio.run(create_icd10_agent())

与LangGraph状态机一起使用：

from langgraph.graph import StateGraph, END
from typing import TypedDict

class AgentState(TypedDict):
    clinical_note: str
    icd_codes: list

async def code_note_node(state: AgentState):
    """Node that calls the ICD-10 MCP server."""
    client = MultiServerMCPClient({
        "icd10-mcp": {
            "url": "https://icd10-mcp.onrender.com/sse",
            "transport": "sse",
            "headers": {"X-OpenRouter-API-Key": "sk-or-v1-YOUR_KEY"}
        }
    })
    
    result = await client.call_tool(
        "code_clinical_note",
        arguments={
            "note": state["clinical_note"],
            "max_codes_per_problem": 2
        }
    )
    
    return {"icd_codes": result}

# Build the graph
workflow = StateGraph(AgentState)
workflow.add_node("code_note", code_note_node)
workflow.set_entry_point("code_note")
dd_edge("code_note", END)

app = workflow.compile()

D.直接HTTP/任何Web应用程序或后端

通过HTTP/SSE从任何编程语言直接调用MCP服务器。

服务器详细信息：

• 基本URL: https://icd10-mcp.onrender.com
• SSE端点： GET /sse （用于MCP协议连接）
• 消息终结点： POST /messages/ （用于工具调用）
• 健康检查： GET /health
• 所需标题： X-OpenRouter-API-Key: sk-or-v1-YOUR_OPENROUTER_API_KEY

Python示例（使用 requests):

import requests
import json

MCP_SERVER_URL = "https://icd10-mcp.onrender.com"
OPENROUTER_API_KEY = "sk-or-v1-YOUR_KEY"

# Health check
response = requests.get(f"{MCP_SERVER_URL}/health")
print(response.json())

# Call search_icd10 tool
response = requests.post(
    f"{MCP_SERVER_URL}/messages/",
    json={
        "method": "tools/call",
        "params": {
            "name": "search_icd10",
            "arguments": {"query": "hypertension", "top_k": 5}
        }
    },
    headers={
        "X-OpenRouter-API-Key": OPENROUTER_API_KEY,
        "Content-Type": "application/json"
    }
)

result = response.json()
print(json.dumps(result, indent=2))

# Call code_clinical_note tool
clinical_note = """
Patient presents with elevated blood pressure 158/96 mmHg.
History of type 2 diabetes, HbA1c 9.2%.
Creatinine 2.1 mg/dL, eGFR 38 mL/min.
"""

response = requests.post(
    f"{MCP_SERVER_URL}/messages/",
    json={
        "method": "tools/call",
        "params": {
            "name": "code_clinical_note",
            "arguments": {
                "note": clinical_note,
                "max_codes_per_problem": 2
            }
        }
    },
    headers={
        "X-OpenRouter-API-Key": OPENROUTER_API_KEY,
        "Content-Type": "application/json"
    }
)

result = response.json()
print(json.dumps(result, indent=2))

JavaScript示例（使用 fetch):

const MCP_SERVER_URL = "https://icd10-mcp.onrender.com";
const OPENROUTER_API_KEY = "sk-or-v1-YOUR_KEY";

// Health check
fetch(`${MCP_SERVER_URL}/health`)
  .then(res => res.json())
  .then(data => console.log(data));

// Call search_icd10 tool
fetch(`${MCP_SERVER_URL}/messages/`, {
  method: "POST",
  headers: {
    "X-OpenRouter-API-Key": OPENROUTER_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    method: "tools/call",
    params: {
      name: "search_icd10",
      arguments: { query: "diabetes", top_k: 5 }
    }
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

// Call code_clinical_note tool
const clinicalNote = `
Patient presents with elevated blood pressure 158/96 mmHg.
History of type 2 diabetes, HbA1c 9.2%.
Creatinine 2.1 mg/dL, eGFR 38 mL/min.
`;

fetch(`${MCP_SERVER_URL}/messages/`, {
  method: "POST",
  headers: {
    "X-OpenRouter-API-Key": OPENROUTER_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    method: "tools/call",
    params: {
      name: "code_clinical_note",
      arguments: {
        note: clinicalNote,
        max_codes_per_problem: 2
      }
    }
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

E.任何AI代理（通用MCP客户端）

任何兼容MCP的客户端都可以使用SSE（服务器发送事件）传输连接到此服务器。

连接详细信息：

• 网址： https://icd10-mcp.onrender.com/sse
• 运输： SSE（服务器发送事件）
• 所需标题： X-OpenRouter-API-Key: sk-or-v1-YOUR_OPENROUTER_API_KEY
• 可用工具： code_clinical_note, search_icd10

通用模式：

import requests

# Connect to SSE endpoint
response = requests.get(
    "https://icd10-mcp.onrender.com/sse",
    headers={"X-OpenRouter-API-Key": "sk-or-v1-YOUR_KEY"},
    stream=True
)

# The server will send MCP protocol messages via SSE
# Your client should parse SSE events and handle MCP JSON-RPC messages

______________________________________________________________________

环境变量引用

**\*注：** OPENROUTER_API_KEY HTTP/SSE模式需要。用户通过以下方式提供OpenRouter密钥 X-OpenRouter-API-Key 每个请求的标题。