# CogStack MCP Wrapper

An MCP (Model Context Protocol) server that provides programmatic access to [CogStackCohort](https://github.com/CogStack/CogStackCohort) for querying and analyzing medical cohorts through a standardized interface.

## What This Is

**A bridge layer** that:
- Makes CogStackCohort accessible via the Model Context Protocol (MCP)
- Automatically manages the CogStack server lifecycle
- Translates between user-friendly and internal data formats
- Provides a simplified API for complex medical queries
- Works with any MCP-compatible client (Claude Desktop, VS Code, custom clients)

## What This Is NOT

- NOT a replacement for CogStackCohort
- NOT adding new medical logic or algorithms
- NOT modifying how cohorts are calculated
- NOT a visualization tool (returns data, not charts)

## Key Features

The wrapper exposes CogStackCohort's functionality through MCP tools:
- **Search SNOMED-CT concepts** - Find medical conditions by keyword
- **Create patient cohorts** - Filter patients by conditions and demographics
- **Temporal queries** - Support for longitudinal studies (last 5/10 years, custom ranges)
- **Analyze cohort statistics** - Age distribution, top conditions, demographics

## Prerequisites

- Node.js 14+ 
- npm or yarn
- [CogStackCohort](https://github.com/CogStack/CogStackCohort) server
- An MCP-compatible client (e.g., Claude Desktop, VS Code with MCP extension, or custom implementation)

## Installation

1. Clone both repositories:
```bash
# Clone the MCP wrapper
git clone https://github.com/YOUR_USERNAME/cogstack-mcp-wrapper.git
cd cogstack-mcp-wrapper

# Clone CogStackCohort (in parent directory)
cd ..
git clone https://github.com/CogStack/CogStackCohort.git
cd cogstack-mcp-wrapper

# Install dependencies
npm install
```

2. Prepare data files in `../CogStackCohort/server/data/`:
   - Extract SNOMED terms: `cd ../CogStackCohort/server/data && tar xzvf snomed_terms_data.tar.gz`
   - Either provide real data files or generate random test data (automatic if files missing)

3. Build the MCP server:
```bash
npm run build
```

## Usage

### Running the MCP Server

The server runs on stdio and automatically starts the CogStackCohort server:

```bash
node dist/index.js
```

### Available Tools

#### 1. `cogstack_search_snomed`
Search for SNOMED-CT concepts by keyword.

**Parameters:**
- `query` (string, required): Search terms
- `limit` (number, optional): Maximum results (default: 20)

**Example:**
```json
{
  "tool": "cogstack_search_snomed",
  "parameters": {
    "query": "diabetes type 2",
    "limit": 10
  }
}
```

#### 2. `cogstack_create_cohort`
Create a patient cohort based on SNOMED terms and filters.

**Parameters:**
- `queries` (array, required): SNOMED queries with:
  - `cui`: SNOMED concept ID
  - `include`: Include (true) or exclude (false) patients
  - `includeChildren`: Include child concepts
  - `operator`: "AND" or "OR" for combining queries
- `filters` (object, optional): Demographic filters:
  - `ageMin`, `ageMax`: Age range
  - `gender`: {male, female, unknown}
  - `ethnicity`: {asian, black, white, mixed, other, unknown}
  - `vitalStatus`: {alive, deceased}
  - `timeFilter`: Time-based filtering

**Example:**
```json
{
  "tool": "cogstack_create_cohort",
  "parameters": {
    "queries": [
      {
        "cui": "44054006",
        "include": true,
        "includeChildren": true,
        "operator": "AND"
      },
      {
        "cui": "38341003",
        "include": false
      }
    ],
    "filters": {
      "ageMin": 50,
      "ageMax": 70,
      "gender": {
        "male": true,
        "female": true
      }
    }
  }
}
```

#### 3. `cogstack_analyze_cohort`
Analyze a previously created cohort.

**Parameters:**
- `cohortId` (string, required): ID from create_cohort
- `analysisType` (string, required): One of:
  - `age_distribution`: Age breakdown
  - `top_conditions`: Most common conditions
  - `demographics`: Full demographic analysis

#### 4. `cogstack_get_stats`
Get statistics about the loaded data.

## Configuration

Environment variables:
- `COGSTACK_PATH`: Path to CogStackCohort directory (default: `../CogStackCohort`)
- `COGSTACK_DATA_PATH`: Path to data files (default: `../CogStackCohort/server/data`)
- `PORT`: Port for CogStack server (default: 3000)

## Integration with MCP Clients

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "cogstack": {
      "command": "node",
      "args": ["/path/to/cogstack-mcp-wrapper/dist/index.js"],
      "env": {
        "COGSTACK_PATH": "/path/to/CogStackCohort"
      }
    }
  }
}
```

### Other MCP Clients

For other MCP clients, configure with:
- **Command**: `node /path/to/cogstack-mcp-wrapper/dist/index.js`
- **Transport**: stdio
- **Environment**: `COGSTACK_PATH` pointing to CogStackCohort directory

## Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   MCP Client    │────►│  MCP Wrapper     │────►│ CogStack Server  │
│  (Any MCP App)  │◄────│  (Node.js)       │◄────│  (Express.js)    │
└─────────────────┘     └──────────────────┘     └──────────────────┘
         ↑                       │                            │
         └───────────────────────┴────────────────────────────┘
                    stdio (standard input/output)
```

The wrapper:
1. Starts CogStack server as a subprocess
2. Translates MCP tool calls to HTTP requests
3. Returns formatted results to the MCP client

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build
```

## Troubleshooting

1. **Missing data files**: The server will automatically generate random test data if required files are missing.

2. **Port conflicts**: Set `PORT` environment variable to use a different port.

3. **Memory issues**: The CogStack server runs with `--max-old-space-size=32768`. Adjust in `src/index.ts` if needed.

4. **Server startup**: The wrapper waits up to 30 seconds for CogStack to start. Check console output for errors.

## Documentation

- [COMPARISON.md](./COMPARISON.md) - Detailed comparison between the MCP wrapper and original CogStackCohort
- [CogStackCohort Documentation](https://github.com/CogStack/CogStackCohort) - Original project documentation

## How It Works

The wrapper acts as a translation layer:
1. **Receives** MCP commands from any MCP client
2. **Starts** the CogStackCohort server (if not running)
3. **Translates** commands to HTTP requests
4. **Formats** responses for the MCP client

All medical logic, data processing, and cohort calculations remain in the original CogStackCohort server.

## License

This wrapper follows the same license as CogStackCohort.