Metadata-Version: 2.3
Name: cdm-mcp-server
Version: 0.2.1
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)

- **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.

---

## Installation

### 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**

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

**Windows**

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### Step 2. Register the MCP Server

Choose the AI client you use and run the corresponding command once. This registers the server globally so it's available from any directory.

**Claude Code**

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

**Claude Desktop**

Add the following to your Claude Desktop config file:

- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "cdm-server": {
      "command": "uvx",
      "args": ["cdm-mcp-server"]
    }
  }
}
```

Then restart Claude Desktop.

**Gemini CLI**

```bash
gemini mcp add cdm-server "uvx cdm-mcp-server" --scope user
```

**Codex CLI**

Add the following to `~/.codex/config.toml`:

```toml
[[mcp_servers]]
name = "cdm-server"
command = "uvx"
args = ["cdm-mcp-server"]
```

### Step 3. Verify the Connection

**Claude Code**

```bash
claude mcp list
```

**Gemini CLI**

```bash
gemini mcp list
```

You should see `cdm-server: ✓ Connected`.

---

## 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.

---

## 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
```
