@uh-joan/cortellis-mcp-server/README.md

MCP server for Cortellis drug database search and ontology exploration

# Cortellis MCP Server

MCP Server for searching drugs and exploring ontology terms in the Cortellis database.

## Installation

```bash
# Using npm
npm install @uh-joan/cortellis-mcp-server
```

## Quick Start

1. Set up your environment variables:
```env
CORTELLIS_USERNAME=your_username
CORTELLIS_PASSWORD=your_password
USE_HTTP=true  # Optional: run as HTTP server
PORT=3000      # Optional: specify port for HTTP server
```

2. Run the server:
```bash
# As MCP server
npx cortellis-mcp-server

# As HTTP server
USE_HTTP=true PORT=3000 npx cortellis-mcp-server
```

## Tools

1. `ci_search_drugs`
   - Search for drugs in the Cortellis database
   - Optional Inputs:
     - `query` (string) - Raw search query
     - `company` (string) - Company ID for the developing company (e.g., "18614")
     - `indication` (string) - Indication ID (numeric ID only, e.g., "238" for Obesity). Use ci_explore_ontology to find the correct ID.
     - `action` (string) - Target specific action (e.g., glucagon)
     - `phase` (string) - Development status:
       - Uses LINKED format with short codes: S, DR, CU, C1-C3, PR, R, L, OL, NDR, DX, W
       - **Important:** only a single phase value is supported for the `phase` parameter; do not use OR/AND. If you need to search for multiple phases, run separate queries for each phase.
       - Examples:
         - phase: "L"
         - phase: "C1"
         - phase: "C2"
         - phase: "C3"
       - Status codes:
         - S: Suspended
         - DR: Discovery/Preclinical
         - CU: Clinical (unknown phase)
         - C1-C3: Phase 1-3 Clinical
         - PR: Pre-registration
         - R: Registered
         - L: Launched
         - OL: Outlicensed
         - NDR: No Development Reported
         - DX: Discontinued
         - W: Withdrawn
     - `phase_terminated` (string) - Last phase before NDR/DX
       - Uses short format with double colon: S, DR, CU, C1-C3, PR, R, L, OL, NDR, DX, W
       - Supports AND/OR operators
       - Examples:
         - `phase_terminated: "C2"`
         - `phase_terminated: "C2 OR C3"`
     - `technology` (string) - Drug technology (e.g., small molecule)
     - `drug_name` (string) - Name of the drug
     - `country` (string) - Country ID (e.g., "US")
     - `offset` (number) - For pagination
     - `hits` (number) - Number of results per page (default: 100)
     - `company_size` (string) - The size of a company based on market capitalization in billions USD
       - Format: '<X' for less than $XB, 'X' for greater than $XB
     - `developmentStatusDate` (string) - Date of change in status (only possible within LINKED queries). Use RANGE(>=YYYY-MM-DD;<=YYYY-MM-DD) for ranges. Example: `RANGE(>=2023-01-01;<=2023-12-31)`
     - `historic` (boolean) - **Set to true to search using the historic development status fields. This is required for questions about the status of a drug at a specific point in the past (e.g., 'What drugs were in phase 3 in 2019?'). If you want to know the status as it was at a particular date or within a date range, always set historic: true and use the developmentStatusDate parameter.**
   - Returns: JSON response with drug information and development status

2. `ci_explore_ontology`
   - Explore taxonomy terms in the Cortellis database
   - Optional Inputs (at least one required):
     - `term` (string) - Generic search term
     - `category` (string) - Category to search within
     - `action` (string) - Target specific action
     - `indication` (string) - Disease/condition
     - `company` (string) - Company name
     - `drug_name` (string) - Drug name
     - `target` (string) - Drug target
     - `technology` (string) - Drug technology
   - Returns: JSON response with matching taxonomy terms

3. `ci_get_drug`
   - Return the entire drug record with all available fields for a given identifier
   - Required Input:
     - `id` (string) - Numeric Drug Identifier (e.g. "101964" for tirzepatide, not the drug name)
   - Example:
     {
       "tool-name": "ci_get_drug",
       "arguments": {
         "id": "101964",
         "category": "report" // Optional. Values: "report" (default), "swot", "financial"
       }
     }
   - Returns: JSON response with complete drug record

4. `ci_get_company`
   - Return the entire company record with all available fields for a given identifier
   - Required Input:
     - `id` (string) - Numeric Company Identifier (not the company name)
   - Example:
     {
       "tool-name": "ci_get_company",
       "arguments": {
         "id": "18614"
       }
     }
   - Returns: JSON response with complete company record

5. `ci_search_companies`
   - Search for companies in the Cortellis database
   - Optional Inputs:
     - `query` (string) - Raw search query
     - `company_name` (string) - Company name to search for
     - `hq_country` (string) - Company headquarters country
     - `deals_count` (string) - Count for all distinct deals where company is principal/partner
       - Format: '<20' for less than 20 deals
       - Format: '20' or '>20' for greater than 20 deals (default behavior)
     - `indications` (string) - Top 10 indication terms
     - `actions` (string) - Top 10 target-based action terms
     - `technologies` (string) - Top 10 technologies terms
     - `company_size` (string) - The size of a company based on market capitalization in billions USD
       - Format: '<2' for less than $2B
       - Format: '2' or '>2' for greater than $2B (default behavior)
     - `status` (string) - Highest status of linked drugs
     - `offset` (number) - For pagination
     - `hits` (number) - Number of results per page (default: 100)
   - Returns: JSON response with company information

6. `ci_search_deals`
   - Search for deals in the Cortellis database
   - Optional Inputs:
     - `query` (string) - Raw search query (if you want to use the full Cortellis query syntax directly)
     - `dealDrugNamesAll` (string) - Main name of drug including synonyms associated with the deal
     - `indications` (string) - Indications associated with the deal
     - `dealDrugCompanyPartnerIndications` (string) - The indication and the partner company linked to a drug associated with the deal
     - `dealPhaseHighestStart` (string) - Highest dev. status of the drug at the deal start
     - `dealPhaseHighestNow` (string) - Current highest dev. status of the drug
     - `dealStatus` (string) - Status of the deal
     - `dealSummary` (string) - Summary of the deal
     - `dealTitleSummary` (string) - Title or summary of the deal
     - `technologies` (string) - Technology linked to the drug
     - `dealTitle` (string) - Title of the deal
     - `dealType` (string) - Type of deal
     - `actionsPrimary` (string) - Primary mechanism of action associated with the deal
     - `sortBy` (string) - Sort order for results. Use '+field' for ascending or '-field' for descending. Supported fields: dealDateStart, dealDateEnd, dealDateEventMostRecent, dealTotalPaidSortBy, dealTotalProjectedCurrentSortBy, dealValuePaidToPrincipalMaxSortBy, dealValueProjectedToPrincipalMaxSortBy. Example: '+dealDateStart' for oldest first, '-dealDateStart' for newest first. Useful for queries like 'last 10 deals for a company'.
     - `offset` (number) - For pagination
   - Returns: JSON response with deal information

7. `ci_search_trials`
   - Search for clinical trials in the Cortellis database
   - Optional Inputs:
     - `query` (string) - Raw search query for direct searching
     - `sortBy` (string) - Sort field (trialPhase, trialRecruitmentStatus, trialPatientCountEnrollment, trialDateStart, trialDateEnd, trialDateChangeLast)
     - `trialTitleOfficial` (string) - Official trial title
     - `trialIdentifiers` (string) - Trial identifiers (e.g., NCT00003140, CTI_umbrella)
     - `indications` (string) - Medical condition being treated
     - `trialPhase` (string) - Phase of clinical trial (e.g., 'C12' for Phase 1/2 or 'Phase 1/Phase 2 Clinical')
     - `trialRecruitmentStatus` (string) - Trial recruitment status
     - `trialCompaniesSponsor` (string) - Sponsoring organization (name or ID)
     - `trialPatientCountEnrollment` (string) - Number of patients (exact or RANGE format)
     - `trialDateStart` (string) - Trial start date (YYYY-MM-DD)
     - `trialDateEnd` (string) - Trial end date (YYYY-MM-DD)
   - Returns: JSON response with clinical trial information

8. `ci_get_trial`
   - Retrieve trial information. Can return the full trial record or trial sites based on the category parameter.
   - Required Input:
     - `id` (string) - Trial identifier (e.g., "9997", "77227")
   - Optional Inputs:
     - `category` (string) - Type of information to retrieve:
       - "report" (default) - Full trial record with all available fields
       - "sites" - Trial sites information
     - `hits` (number) - Number of results per page (for sites category only, default: 20)
     - `offset` (number) - Number of records to skip (for sites category only, default: 0)
   - Examples:
     {
       "tool-name": "ci_get_trial",
       "arguments": {
         "id": "9997",
         "category": "report"
       }
     }
     {
       "tool-name": "ci_get_trial",
       "arguments": {
         "id": "77227",
         "category": "sites",
         "hits": 20,
         "offset": 0
       }
     }
   - Returns: JSON response with trial information based on the requested category

## Features

- Direct access to Cortellis drug and deal database
- Comprehensive drug and deal development status search
- Ontology/taxonomy term exploration
- Detailed drug and deal information retrieval
- SWOT analysis for drugs
- Financial data and forecasts
- Structured JSON responses
- Pagination support for large result sets

## HTTP API Endpoints

When running in HTTP mode (USE_HTTP=true), the following REST endpoints are available:

1. `POST /ci_search_drugs`
   - Search for drugs with optional filters
   - Body: JSON object with search parameters (see `ci_search_drugs` tool inputs)

2. `POST /ci_explore_ontology`
   - Search taxonomy terms
   - Body: JSON object with search parameters (see `ci_explore_ontology` tool inputs)

3. `GET /ci_get_drug/:id`
   - Get complete drug record by ID
   - Parameters:
     - `id`: Drug identifier
   - Query Parameters:
     - `category`: Optional. Values: "report" (default), "swot", "financial"
   - Example: 
     - `GET /ci_get_drug/101964` (full report)
     - `GET /ci_get_drug/101964?category=swot` (SWOT analysis)
     - `