sthio90/cogstack-mcp-wrapper

CogStack MCP Wrapper

An MCP (Model Context Protocol) server that provides programmatic access to 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 server
• An MCP-compatible client (e.g., Claude Desktop, VS Code with MCP extension, or custom implementation)

Installation

1. Clone both repositories:

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

npm run build

Usage

Running the MCP Server

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

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:

{
  "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:

{
  "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:

{
  "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

# 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

• - Detailed comparison between the MCP wrapper and original CogStackCohort
• CogStackCohort Documentation - 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.