使用说明

CDISC库MCP服务器 --直接从AI助手查询临床数据标准（SDTM、ADaM、CDASH、CT）。

🌐 翻译： 中文 README · 日本语README

这是什么？

这 CDISC MCP服务器 将AI助手（Claude、VS Code Copilot、Cursor等）连接到 CDISC库REST API，公开了11个用于查询临床试验数据标准的结构化工具。问你的AI助手一些问题，比如：

“SDTM AE域中有哪些变量？”/m “显示ADaM IG 1.3中的ADSL变量” “列出所有可用的受控术语包”

有关完整的设置说明，请参阅 用户手册→。参见 例子→ 以获取真实的对话样本。

快速开始

0·一线AI安装

让AI助手为您安装一切：

curl -fsSL https://raw.githubusercontent.com/Teninq/cdisc-mcp/main/install.md

将输出粘贴到Claude、Copilot或任何AI聊天中——它将阅读指南并交互式地引导您完成整个设置。

1·获取CDISC库API密钥

注册地址： https://library.cdisc.org 并获得个人API密钥。

2·安装

# Runtime only
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

# With web explorer
pip install -e ".[web]"

3·设置API密钥

# Linux / macOS
export CDISC_API_KEY=your_key_here

# Windows — Command Prompt
set CDISC_API_KEY=your_key_here

# Windows — PowerShell
$env:CDISC_API_KEY = "your_key_here"

4·跑步

# Start MCP server (for AI assistant integration)
cdisc-mcp

# OR: Start Web Explorer (quick interactive testing)
python web/app.py

Web Explorer——快速交互式测试

验证设置和探索工具的最快方法 没有任何AI客户端.

# 1. Install web dependencies
pip install -e ".[web]"

# 2. Set your API key
export CDISC_API_KEY=your_key_here   # Linux/macOS
set CDISC_API_KEY=your_key_here      # Windows CMD
$env:CDISC_API_KEY = "your_key_here" # Windows PowerShell

# 3. Start the bridge server
python web/app.py

# 4. Open in browser
#    → http://localhost:8080

资源管理器提供：

侧边栏导航 --按标准（SDTM/ADaM/CDASH/术语）组织的所有11个工具
自动生成的表单 --版本和域的下拉菜单，变量的文本输入
实时JSON响应 --语法突出显示，可复制输出，具有响应时间
网桥状态指示器 -确认您的API密钥和连接

提示： 使用带破折号的版本字符串-- 3-4 不 3.4, 1-3 不 1.3. 示例：SDTM-IG 3-4，ADaM IG 1-3，CDASH-IG 2-0

可用工具

#	工具	标准	说明
1	`list_products`	--	列出所有可用的CDISC标准和已发布版本
2	`get_sdtm_domains`	SDTM	列出SDTM-IG版本中的所有数据集
3	`get_sdtm_domain_variables`	SDTM	列出SDTM域/数据集中的所有变量
4	`get_sdtm_variable`	SDTM	获取特定SDTM变量的完整定义
5	`get_adam_datastructures`	ADaM	列出ADaM IG版本中的所有数据结构
6	`get_adam_variable`	ADaM	获取特定ADaM变量的定义
7	`get_cdash_domains`	CDASH	列出CDASH-IG版本中的所有域
8	`get_cdash_domain_fields`	CDASH	获取CDASH域的所有数据收集字段
9	`list_ct_packages`	CT	列出所有可用的受控术语包
10	`get_codelist`	CT	获取CT代码表的定义和元数据
11	`get_codelist_terms`	CT	列出CT代码列表中的所有有效术语

版本参考

标准	可用版本（使用破折号）
SDTM-IG	`3-4` · `3-3` · `3-2` · `3-1-3`
ADaM IG	`1-3` · `1-2` · `1-1` · `1-0`
CDASH-IG	`2-1` · `2-0` · `1-1-1`

连接到AI助手

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "cdisc": {
      "command": "cdisc-mcp",
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

VS代码/光标

添加 .vscode/mcp.json 或等效的MCP配置：

{
  "servers": {
    "cdisc": {
      "command": "cdisc-mcp",
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

克劳德代码（CLI）

Claude Code在两个范围内支持MCP服务器：用户（全球，所有项目）和项目（仅限本地当前项目）。

选项A--CLI命令（推荐）

# Add globally (available in all projects)
claude mcp add cdisc-mcp -e CDISC_API_KEY=your_key_here -- python -m cdisc_mcp.server

# Add for the current project only
claude mcp add cdisc-mcp --scope project -e CDISC_API_KEY=your_key_here -- python -m cdisc_mcp.server

# Verify the server was registered
claude mcp list

选项B——编辑 ~/.claude.json 直接

{
  "mcpServers": {
    "cdisc-mcp": {
      "command": "python",
      "args": ["-m", "cdisc_mcp.server"],
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

提示： 如果 CDISC_API_KEY 已在您的系统环境中，省略 env 完全阻塞——Claude Code会自动继承它。

注册后，请确认 /mcp 在任何Claude Code会话中，然后以对话方式使用这些工具：

User: What SDTM domains are defined in version 3.4?
Claude: [calls get_sdtm_domains with version="3-4"] ...

在自己的Python工具中使用

您可以使用官方的MCP客户端SDK从任何Python脚本以编程方式调用CDISC MCP工具。

安装客户端

pip install mcp

最小示例

import asyncio
import os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

SERVER = StdioServerParameters(
    command="python",
    args=["-m", "cdisc_mcp.server"],
    env={"CDISC_API_KEY": os.environ["CDISC_API_KEY"]},
)

async def main():
    async with stdio_client(SERVER) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List all available tools
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Call a tool
            result = await session.call_tool(
                "get_sdtm_domains",
                arguments={"version": "3-4"},
            )
            print(result.content[0].text)

asyncio.run(main())

可重复使用的助手

import asyncio, os, json
from contextlib import asynccontextmanager
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

_SERVER = StdioServerParameters(
    command="python",
    args=["-m", "cdisc_mcp.server"],
    env={"CDISC_API_KEY": os.environ["CDISC_API_KEY"]},
)

@asynccontextmanager
async def cdisc_session():
    """Async context manager that yields an initialised MCP session."""
    async with stdio_client(_SERVER) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            yield session

async def call(tool: str, **kwargs) -> dict:
    async with cdisc_session() as s:
        result = await s.call_tool(tool, arguments=kwargs)
        return json.loads(result.content[0].text)

# --- Usage examples ---
async def demo():
    # Fetch SDTM domains
    domains = await call("get_sdtm_domains", version="3-4")

    # Fetch all variables in the AE domain
    variables = await call("get_sdtm_domain_variables", version="3-4", domain="AE")

    # Look up a single variable
    aeterm = await call("get_sdtm_variable", version="3-4", domain="AE", variable="AETERM")

    print(aeterm)

asyncio.run(demo())

可用工具签名（快速参考）

# Products / versions
await session.call_tool("list_products", {})

# SDTM
await session.call_tool("get_sdtm_domains",          {"version": "3-4"})
await session.call_tool("get_sdtm_domain_variables", {"version": "3-4", "domain": "AE"})
await session.call_tool("get_sdtm_variable",         {"version": "3-4", "domain": "AE", "variable": "AETERM"})

# ADaM
await session.call_tool("get_adam_datastructures",   {"version": "1-3"})
await session.call_tool("get_adam_variable",         {"version": "1-3", "data_structure": "ADSL", "variable": "USUBJID"})

# CDASH
await session.call_tool("get_cdash_domains",         {"version": "2-0"})
await session.call_tool("get_cdash_domain_fields",   {"version": "2-0", "domain": "AE"})

# Controlled Terminology
await session.call_tool("list_ct_packages",          {})
await session.call_tool("get_codelist",              {"package_id": "sdtmct-2024-03-29", "codelist_id": "C66781"})
await session.call_tool("get_codelist_terms",        {"package_id": "sdtmct-2024-03-29", "codelist_id": "AGEU"})

版本格式： 始终使用破折号，而不是点-- "3-4" 不 "3.4".

建筑

MCP Client (Claude / VS Code / Cursor)
        │
        │  MCP protocol (stdio)
        ▼
   server.py  ──── FastMCP tool registration
        │
        ▼
   tools/  ──────── domain functions (sdtm, adam, cdash, terminology, search)
        │
        ▼
   client.py  ───── CDISCClient (async HTTP · TTL cache · retry)
        │
        │  HTTPS
        ▼
   library.cdisc.org/api  ──── CDISC Library REST API

关键设计决策：

CDISCClient 是一个具有1小时TTL内存缓存的单例异步HTTP客户端
仅 429 和 5xx 重新尝试响应； 4xx 立即提高
工具函数是纯异步的——无需打补丁即可独立测试
format_response() HAL条 _links 元数据，提取用于LLM消费的结构化数据

发展

开发工作流程（先开发，分支合并SOP）： 看贡献指南.

运行测试

# Full suite with coverage (≥80% required)
pytest

# Specific modules
pytest tests/test_tools.py tests/test_client.py -v

# Single test
pytest tests/test_tools.py::test_list_products -v

代码质量

ruff check src/ tests/    # Linting
mypy src/                 # Type checking

GitHub分支保护（必需检查）

配置 main 分支保护要求：

CI Tests / tests
CI Lint / lint
CI Types / types

项目结构

src/cdisc_mcp/
├── server.py              # FastMCP server + tool registration
├── client.py              # Async HTTP client (cache, retry)
├── config.py              # Config dataclass + env loader
├── errors.py              # AuthenticationError, ResourceNotFoundError, RateLimitError
├── response_formatter.py  # HAL response normalization
└── tools/
    ├── search.py          # list_products (product catalog)
    ├── sdtm.py            # SDTM domain/variable tools
    ├── adam.py            # ADaM datastructure/variable tools
    ├── cdash.py           # CDASH domain/field tools
    ├── terminology.py     # CT package/codelist tools
    └── _validators.py     # Path traversal guards
web/
├── app.py                 # FastAPI bridge server
└── index.html             # Single-file browser explorer
tests/
├── test_config.py
├── test_client.py
├── test_response_formatter.py
├── test_tools.py
├── test_errors.py
└── test_server.py

许可证

MIT许可证。

专为使用CDISC标准的临床数据专业人员而设计。

用户手册 · 例子 · CDISC图书馆 · API文件