Metadata-Version: 2.3
Name: cdm-mcp-server
Version: 0.4.0
Summary: Develop MCP Servers for automate the work processes of the Clinical Data Manager.
Author: Woohyeon Jeong
Author-email: Woohyeon Jeong <whyeo.nooc@gmail.com>
Requires-Dist: fastmcp>=3.1.0
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: numpy>=2.4.3
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=3.0.1
Requires-Dist: pdfplumber>=0.11.9
Requires-Dist: pymupdf>=1.27.2.2
Requires-Dist: xlsxwriter>=3.2.9
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Clinical Data Management MCP Server

A unified MCP (Model Context Protocol) server for automating Clinical Data Manager (CDM) workflows. Provides Excel comparison, DVS validation, PDF comparison, and more through any MCP-compatible AI agent.

---

## Available Tools

### Excel & DB Spec

- **read_excel_info**: Reads an Excel file and returns its structure — sheet names, column names, row counts, and a preview of the first few rows. Use this first when sheet names or column names are unknown.
- **compare_common_excel**: Compares specific sheets of two Excel files and generates a difference report. Requires specifying the sheet name, header row, and primary key column.
- **compare_db_spec**: Compares full CDM DB Spec workbooks. Automatically detects header positions and updates the Revision History sheet.

### DVS (Data Validation Specifications)

- **download_dvs_grammar**: Copies the bundled DVS Specification Grammar reference file (`DVS_SPEC_GRAMMAR.md`) to a specified directory. Use this when a user needs the grammar definition for writing or reviewing DVS Specifications column entries.
- **validate_dvs_specifications**: Reads a DVS Excel file, validates all Specification entries against the DVS grammar, and generates a detailed validation report. Reports syntax errors and auto-corrected suggestions where possible.
- **check_dvs_consistency** _(requires MCP Sampling)_: Checks whether the natural language Description is logically consistent with the formal Specification for each DVS entry. Results are written to a new Excel report.

### Google Calendar Integration

- **download_timeline_template**: Copies the bundled DM Timeline Excel template to a specified directory. Use this before filling in timeline data and calling `make_google_calendar_csv`.
- **make_google_calendar_csv**: Extracts key schedules from a Timeline Excel file and converts them into a CSV formatted for Google Calendar import.

### Blank eCRF PDF Comparison

- **compare_ecrf_pdf_single**: Compares two Blank eCRF PDF files and produces a single side-by-side comparison PDF. Changed pages are shown with Before (left) and After (right) layouts. Annotation colors: red = deleted, green = added, yellow = modified.

### DB Spec Validation

- **validate_db_spec**: Validates a DB Specification Excel file against CDASH standards (CDASHIG v2.3 / SDTMIG v3.4). Runs three checks: domain validity, ITEM ID suffix vs. DB TYPE consistency, and CODE field duplicate code numbers. Generates an Excel validation report with per-check result sheets and a summary.
- **generate_cdash_variables**: Generates or updates the CDASH variables JSON reference from a CDASH Model Excel file. Use this when a new version of the CDASH Model is released. Supports merge mode to add new entries without replacing existing data.

---

## Installation

> **Windows users:** This server must be run inside **WSL (Windows Subsystem for Linux)**. All commands below should be run in a WSL terminal, not PowerShell or CMD. If WSL is not installed, follow [Microsoft's WSL setup guide](https://learn.microsoft.com/en-us/windows/wsl/install) first.
>
> After installing WSL, open a WSL terminal and execute below commands.

### Step 1. Install uv

`uv` is a fast Python package manager. Installing it also gives you `uvx`, which runs packages without a separate Python installation.

**Mac / Linux / WSL**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Step 2. Set Up Your AI Agent

Follow the section for your AI agent. Each section covers registration, skill installation, and connection verification.

---

#### Claude Code

**Register the MCP server**

```bash
claude mcp add --scope user cdm-server uvx cdm-mcp-server@latest
```

**Install skills** (optional)

```bash
uvx --from cdm-mcp-server cdm-install-skills --tool claude
```

Skills are installed into `.claude/skills/` in your project directory.

**Verify the connection**

```bash
claude mcp list
```

---

#### Gemini CLI

**Prerequisite — Node.js**

Gemini CLI requires Node.js. Install it via nvm if you don't have it.

*Mac / Linux*

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts
```

*Windows* — Download and install [nvm-windows](https://github.com/coreybutler/nvm-windows/releases), then:

```powershell
nvm install lts
nvm use lts
```

**Install Gemini CLI and register the MCP server**

```bash
npm install -g @google/gemini-cli
gemini mcp add cdm-server uvx --args cdm-mcp-server@latest --scope user
```

**Install skills** (optional)

```bash
uvx --from cdm-mcp-server cdm-install-skills --tool gemini
```

Skills are installed into `.gemini/skills/` in your project directory.

**Verify the connection**

```bash
gemini mcp list
```

---

#### Codex CLI

**Register the MCP server**

```bash
codex mcp add cdm-server -- uvx cdm-mcp-server@latest
```

**Install skills** (optional)

```bash
uvx --from cdm-mcp-server cdm-install-skills --tool codex
```

Skills are installed into `.agents/skills/` in your project directory.

**Verify the connection**

```bash
codex mcp list
```

---

You should see `cdm-server` listed as connected.

> **Install skills for all agents at once**
>
> If you use multiple AI tools in the same project directory, run:
>
> ```bash
> uvx --from cdm-mcp-server cdm-install-skills --all
> ```

---

## Usage

Once connected, simply describe what you need in natural language:

> "Compare the previous and current DB Spec files and generate a difference report."

> "Validate the DVS file and report any syntax errors."

> "Download the Timeline template, then convert the completed file into a Google Calendar CSV."

The AI agent will automatically select and call the appropriate tool.

---

## Troubleshooting

### MCP server shows as disconnected

The most common cause is that `uvx` is not in the PATH when the AI tool launches the MCP server process.

**1. Find the `uvx` location**

```bash
which uvx
```

**2. Add its directory to PATH**

Replace `~/.local/bin` with the directory from the output above:

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```

For zsh:

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```

Then restart the AI tool and verify the connection again.

---

## Project Structure

```
src/
└── cdm_mcp_server/
    ├── __init__.py
    ├── server.py                   # MCP server entry point
    ├── templates/
    │   └── DM Timeline 20251120.xlsx  # Bundled Timeline template
    └── modules/
        ├── excel_theme.py          # Shared Excel formatting standards
        ├── excel_compare.py        # Excel & DB Spec comparison engine
        ├── excel_info.py           # Excel structure inspector
        ├── calendar_maker.py       # Timeline parsing & Calendar CSV generator
        ├── dvs_parser.py           # DVS specification grammar parser
        ├── dvs_excel_writer.py     # DVS validation report writer
        ├── dvs_consistency_checker.py  # LLM-powered DVS consistency checker
        └── pdf_ecrf_compare.py     # Blank eCRF PDF comparison engine
```
