Skip to main content
Glama
README.md
<div align="center">

# ๐Ÿ’Š PharmaMCP
### The Unified Model Context Protocol (MCP) Server for Pharmaceutical Sciences

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-8A2BE2.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests Status](https://img.shields.io/badge/tests-18%2F18%20passing-brightgreen.svg)](tests/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-orange.svg)](CONTRIBUTING.md)

**An enterprise-grade, all-in-one AI agent toolkit tailored for Pharmacy Students, Clinical Researchers, Formulation Scientists, and Pharmacologists.**

[Features](#-key-capabilities) โ€ข [Architecture](#-architecture) โ€ข [Quickstart](#-quickstart--installation) โ€ข [Client Configuration](#-how-to-connect) โ€ข [Tool Catalog](#-comprehensive-tool-catalog) โ€ข [Workflows](#-real-world-pharmacy-workflows)

</div>

---

## ๐Ÿ“Œ Overview

Pharmaceutical education and research demand constant context switching across fragmented platforms: literature databases (PubMed, ClinicalTrials), cheminformatics suites (PubChem, RDKit), PK/PD calculation worksheets, statistical packages (Prism, SPSS), and reference managers.

**PharmaMCP** unifies these six disjointed ecosystems into a single, high-performance **FastMCP server**. Connecting PharmaMCP to your LLM (Claude, Antigravity, Cursor, Windsurf, or ChatGPT) equips the AI with direct execution capabilities over:

1. ๐Ÿ“š **Paper Scraping & Literature Search** (PubMed, ClinicalTrials.gov, CrossRef DOIs, PDF parsing)
2. ๐Ÿงช **Medicinal & Analytical Chemistry** (PubChem, Lipinski Rule of 5, Veber filters, buffer recipes)
3. ๐Ÿฉบ **Pharmacology & Toxicology** (Drug-drug interactions, $ke/t_{1/2}/AUC/C_{ss}$ PK math, ADMET evaluation)
4. ๐Ÿ’Š **Pharmaceutics & Formulation Science** ($f_1/f_2$ dissolution similarity, release kinetics modeling, Henderson-Hasselbalch pH-solubility, pediatric dosing)
5. ๐Ÿ“Š **Pharmaceutical Biostatistics** (Hypothesis testing, One-Way ANOVA with Tukey HSD, 4PL IC50/EC50 regression, %RSD assay precision)
6. โœ๏ธ **Scientific Manuscript Writing** (Vancouver/APA citations, IMRaD section auditing, LaTeX/Markdown tables)

---

## ๐Ÿ—๏ธ Architecture

```mermaid
flowchart TD
    subgraph Client["MCP Host Clients"]
        C1["Claude Desktop"]
        C2["Antigravity CLI"]
        C3["Cursor / Windsurf"]
        C4["Custom Python / Agent"]
    end

    subgraph Protocol["Transport Layer (Stdio / Streamable HTTP)"]
        FastMCP["FastMCP Core Server (server.py)"]
    end

    subgraph Modules["PharmaMCP Specialized Modules"]
        M1["๐Ÿ“š Literature Engine (literature.py)"]
        M2["๐Ÿงช Cheminformatics Engine (chemistry.py)"]
        M3["๐Ÿฉบ Pharmacology & PK (pharmacology.py)"]
        M4["๐Ÿ’Š Pharmaceutics Science (pharmaceutics.py)"]
        M5["๐Ÿ“Š Biostatistics Engine (statistics.py)"]
        M6["โœ๏ธ Scientific Writing Engine (writing.py)"]
    end

    subgraph Services["External APIs & Scientific Compute"]
        API1[("NCBI E-Utilities / PubMed")]
        API2[("ClinicalTrials.gov v2")]
        API3[("CrossRef DOI API")]
        API4[("PubChem PUG REST API")]
        COMP1["SciPy & NumPy (4PL / ANOVA / Stats)"]
        COMP2["PyPDF Document Engine"]
    end

    C1 & C2 & C3 & C4 <--> FastMCP
    FastMCP --> M1 & M2 & M3 & M4 & M5 & M6
    M1 --> API1 & API2 & API3 & COMP2
    M2 --> API4
    M3 --> COMP1
    M4 --> COMP1
    M5 --> COMP1
    M6 --> API1 & API3
```

---

## โšก Quickstart & Installation

### 1. Clone the Repository
```bash
git clone https://github.com/contacttamilselvan25-lang/pharma-mcp.git
cd pharma-mcp
```

### 2. Create and Activate a Virtual Environment
```bash
# Windows
python -m venv venv
venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Verify Local Installation
Run the automated test suite to ensure all 18 test cases pass:
```bash
pytest tests/test_modules.py -v
```

---

## ๐Ÿ”Œ How to Connect

### ๐Ÿ–ฅ๏ธ Claude Desktop
Open your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the `pharma_mcp` server entry:
```json
{
  "mcpServers": {
    "pharma_mcp": {
      "command": "python",
      "args": [
        "C:\\path\\to\\pharma-mcp\\server.py"
      ]
    }
  }
}
```
*(Replace `C:\\path\\to\\pharma-mcp` with your actual directory path).*

---

### ๐Ÿš€ Antigravity CLI / Gemini Agents
Add the server entry to your `.gemini/antigravity-cli/mcp_servers.json`:
```json
{
  "pharma_mcp": {
    "command": "python",
    "args": [
      "C:/path/to/pharma-mcp/server.py"
    ]
  }
}
```

---

### ๐Ÿ’ป Cursor / Windsurf
In your workspace `.cursor/mcp.json` or MCP Settings:
```json
{
  "mcpServers": {
    "pharma_mcp": {
      "command": "python",
      "args": [
        "server.py"
      ]
    }
  }
}
```

---

## ๐Ÿ“‹ Comprehensive Tool Catalog (28 Tools)

### 1. ๐Ÿ“š Literature & Paper Scraping
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_search_pubmed` | `query`, `max_results`, `sort` | Searches NCBI PubMed for peer-reviewed studies with MeSH indexing. |
| `pharma_get_pubmed_article` | `pmid` | Retrieves complete abstract, authors, affiliations, and MeSH headings. |
| `pharma_search_clinical_trials` | `query`, `status`, `phase`, `max_results` | Searches ClinicalTrials.gov API v2 for Phase 1โ€“4 study records. |
| `pharma_lookup_doi` | `doi` | Queries CrossRef for publisher metadata, authors, volume, and BibTeX. |
| `pharma_extract_paper_pdf` | `pdf_path`, `max_pages` | Extracts and parses IMRaD sections from local research PDFs. |

### 2. ๐Ÿงช Medicinal & Analytical Chemistry
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_compound_lookup` | `name_or_cid` | Authoritative PubChem lookups (MW, LogP, TPSA, SMILES, InChIKey). |
| `pharma_lipinski_rule_of_five` | `query` | Calculates Lipinski (MW, LogP, HBD, HBA) and Veber oral drug-likeness. |
| `pharma_convert_chemical_id` | `identifier` | Converts across Name, CID, SMILES, InChI, and InChIKey. |
| `pharma_get_chemical_structure_image` | `query` | Generates 2D molecular structure diagram URLs & markdown embeds. |
| `pharma_calculate_buffer_recipe` | `buffer_system`, `target_ph`, `volume_ml`, `target_molarity` | Computes gram masses & protocols for USP Phosphate, Acetate & Gastric buffers. |

### 3. ๐Ÿฉบ Pharmacology & Pharmacokinetics
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_drug_interactions_check` | `drugs` | Identifies clinical CYP450 and pharmacodynamic drug-drug interactions. |
| `pharma_calculate_pk_params` | `dose_mg`, `clearance_L_hr`, `volume_distribution_L`, `bioavailability_F`, `dosing_interval_hr` | Computes $ke, t_{1/2}, AUC, C_{ss}, C_{max}$, loading and maintenance doses. |
| `pharma_drug_target_lookup` | `drug_name` | Identifies receptor target, mechanism of action, and metabolic pathways. |
| `pharma_admet_risk_evaluator` | `molecular_weight`, `logp`, `tpsa`, `h_bond_donors`, `h_bond_acceptors`, `rotatable_bonds` | Evaluates BBB penetration, P-gp efflux liability, and estimated BCS class. |

### 4. ๐Ÿ’Š Pharmaceutics & Formulation Science
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_dissolution_similarity_f1_f2` | `reference_profile`, `test_profile` | FDA/EMA difference factor ($f_1$) and similarity factor ($f_2$) calculation. |
| `pharma_fit_release_kinetics` | `time_points`, `percent_released` | Fits Zero-Order, First-Order, Higuchi, Korsmeyer-Peppas ($n$), and Hixson-Crowell. |
| `pharma_ph_solubility_profile` | `pka`, `drug_type`, `intrinsic_solubility_mg_mL` | Henderson-Hasselbalch ionization and solubility across stomach & intestinal pH. |
| `pharma_pediatric_dosage_calc` | `adult_dose_mg`, `age_years`, `weight_kg`, `height_cm` | Calculates pediatric doses using Young's, Dilling's, Clark's, and Mosteller BSA. |
| `pharma_excipient_compatibility_guide` | `category`, `functional_group` | Guides binder/disintegrant choices and warns against Maillard/hydrolysis degradation. |

### 5. ๐Ÿ“Š Pharmaceutical Biostatistics
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_comparative_stats` | `group_a`, `group_b`, `group_a_name`, `group_b_name`, `paired` | Shapiro-Wilk normality check + Student's/Welch's/Mann-Whitney test + Cohen's d. |
| `pharma_one_way_anova` | `groups` | One-Way ANOVA across formulation batches with Tukey HSD post-hoc testing. |
| `pharma_fit_ic50_ec50` | `concentrations`, `responses` | 4-Parameter Logistic (4PL) regression for $IC_{50} / EC_{50}$ with 95% CI and $R^2$. |
| `pharma_sample_size_calculator` | `alpha`, `power`, `effect_size_cohens_d`, `test_type` | Calculates animal sample size per group with 10% attrition buffer for IACUC/ethics. |
| `pharma_descriptive_stats` | `data` | Computes assay precision (%RSD / CV%), Mean, SD, SEM, and USP compliance. |

### 6. โœ๏ธ Scientific & Manuscript Writing
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `pharma_format_citation` | `identifier`, `style` | Formats citations in Vancouver, APA 7, Elsevier, Nature, Harvard, or BibTeX. |
| `pharma_audit_imrad_section` | `text`, `section_type` | Audits manuscript sections against ICMJE, ARRIVE, and CONSORT standards. |
| `pharma_format_scientific_table` | `headers`, `rows`, `caption`, `table_style` | Formats lab data into publication-ready Markdown or LaTeX `booktabs` tables. |
| `pharma_paraphrase_academic_phrases` | `sentence`, `context` | Upgrades informal lab notes into professional academic journal prose. |

---

## ๐Ÿ’ก Real-World Pharmacy Workflows

### ๐Ÿงช Scenario 1: Tablet Formulation & Dissolution Comparison
> **User**: *"We formulated a generic sustained-release tablet (F3) and compared its 8-hour dissolution against the innovator brand. Can you check if they are bioequivalent and find the drug release mechanism?"*
> 
> **Agent Action**:
> 1. Calls `pharma_dissolution_similarity_f1_f2` with innovator `[20, 42, 65, 82, 95]` and test `[19, 40, 67, 83, 94]`.
>    - **Result**: $f_1 = 3.12$ (Pass $\le 15$), $f_2 = 82.45$ (Pass $\ge 50$) $\rightarrow$ **Bioequivalent per FDA/EMA criteria**.
> 2. Calls `pharma_fit_release_kinetics` with times `[0.5, 1, 2, 4, 8]` and release percentages.
>    - **Result**: Fits Higuchi ($R^2 = 0.991$) and Korsmeyer-Peppas ($n = 0.48$) $\rightarrow$ **Non-Fickian anomalous diffusion**.

---

### ๐Ÿฉบ Scenario 2: Preclinical In-Vivo Animal Study Design
> **User**: *"We are writing an animal protocol for testing our novel formulation in diabetic rats against Metformin. What sample size do we need, and what are the ethical considerations?"*
> 
> **Agent Action**:
> 1. Calls `pharma_sample_size_calculator` with $\alpha = 0.05, \text{Power} = 0.80, d = 0.80$.
>    - **Result**: Minimum $n = 26$ per group; recommended $n = 29$ with 10% attrition buffer.
> 2. Provides ready-to-paste justification snippet for CPCSEA / IACUC ethics approval.

---

### ๐Ÿ“Š Scenario 3: Cytotoxicity IC50 & Dose-Response Determination
> **User**: *"Here is our MTT assay data for compound X against MCF-7 breast cancer cells at 0.01, 0.1, 1, 10, 100 uM: [98.5, 84.1, 52.3, 16.4, 2.1]. Compute the IC50."*
> 
> **Agent Action**:
> 1. Calls `pharma_fit_ic50_ec50`.
>    - **Result**: $IC_{50} = 1.05\ \mu\text{M}$ ($pIC_{50} = 5.98$, 95% CI: $0.92\text{--}1.21\ \mu\text{M}$, $R^2 = 0.999$).

---

## ๐Ÿ“‚ Project Structure

```
pharma-mcp/
โ”œโ”€โ”€ server.py                         # FastMCP entrypoint & tool registrations
โ”œโ”€โ”€ requirements.txt                  # Python dependencies
โ”œโ”€โ”€ LICENSE                           # MIT License
โ”œโ”€โ”€ README.md                         # Project documentation
โ”œโ”€โ”€ claude_desktop_config_snippet.json # Ready-to-copy MCP client configuration
โ”œโ”€โ”€ modules/                          # Domain engines
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ literature.py                 # PubMed, ClinicalTrials, DOI, PDF parsing
โ”‚   โ”œโ”€โ”€ chemistry.py                  # PubChem, Lipinski, buffer formulations
โ”‚   โ”œโ”€โ”€ pharmacology.py               # DDI check, PK equations, ADMET rules
โ”‚   โ”œโ”€โ”€ pharmaceutics.py              # f1/f2, dissolution models, Henderson-Hasselbalch
โ”‚   โ”œโ”€โ”€ statistics.py                 # t-test, ANOVA, 4PL IC50, power sample size
โ”‚   โ””โ”€โ”€ writing.py                    # Vancouver/APA citations, IMRaD review
โ””โ”€โ”€ tests/                            # Automated test suite
    โ”œโ”€โ”€ __init__.py
    โ””โ”€โ”€ test_modules.py               # 18 unit and integration tests
```

---

## ๐Ÿค Contributing

Contributions are welcomed from pharmacists, chemists, pharmacologists, and developers!
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/NewPharmaTool`)
3. Commit your changes (`git commit -m 'Add new bioanalytical tool'`)
4. Push to the branch (`git push origin feature/NewPharmaTool`)
5. Open a Pull Request

---

## ๐Ÿ“„ License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.