cdisc-mcp

CDISC Library MCP Server — Query clinical data standards (SDTM, ADaM, CDASH, CT) directly from AI assistants.

🌐 Translations: 中文 README · 日本語 README

What is This?

The CDISC MCP Server connects AI assistants (Claude, VS Code Copilot, Cursor, etc.) to the CDISC Library REST API, exposing 11 structured tools for querying clinical trial data standards. Ask your AI assistant questions like:

"What variables are in the SDTM AE domain?" "Show me the ADSL variables in ADaM IG 1.3" "List all available Controlled Terminology packages"

For full setup instructions, see the User Manual →

Quick Start

1 · Get a CDISC Library API Key

Register at https://library.cdisc.org and obtain a personal API key.

2 · Install

# Runtime only
pip install -e .

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

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

3 · Set API Key

# 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 · Run

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

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

Web Explorer — Quick Interactive Testing

The fastest way to verify your setup and explore tools without any AI client.

# 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

The explorer provides:

• Sidebar navigation — all 11 tools organized by standard (SDTM / ADaM / CDASH / Terminology)
• Auto-generated forms — dropdowns for versions and domains, text inputs for variables
• Live JSON responses — syntax-highlighted, copyable output with response time
• Bridge status indicator — confirms your API key and connectivity

Tip: Use version strings with dashes — 3-4 not 3.4, 1-3 not 1.3. Example: SDTM-IG 3-4, ADaM-IG 1-3, CDASH-IG 2-0

Available Tools

Version Reference

Connect to an AI Assistant

Claude Desktop

Add to claude_desktop_config.json:

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

VS Code / Cursor

Add to .vscode/mcp.json or equivalent MCP config:

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

Architecture

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

Key design decisions:

• CDISCClient is a singleton async HTTP client with 1-hour TTL in-memory cache
• Only 429 and 5xx responses are retried; 4xx raise immediately
• Tool functions are pure async — independently testable without patching
• format_response() strips HAL _links metadata, extracts structured data for LLM consumption

Development

Running Tests

# 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

Code Quality

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

Project Structure

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

License

MIT — see LICENSE