<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# Integrating with IDEs and Clients

BioMCP can be integrated into your development workflow through multiple approaches. This guide covers integration with IDEs, Python applications, and MCP-compatible clients.

## Integration Methods Overview

| Method         | Best For                  | Installation | Usage Pattern            |
| -------------- | ------------------------- | ------------ | ------------------------ |
| **Cursor IDE** | Interactive development   | Smithery CLI | Natural language queries |
| **Python SDK** | Application development   | pip/uv       | Direct function calls    |
| **MCP Client** | AI assistants & protocols | Subprocess   | Tool-based communication |

## Cursor IDE Integration

Cursor IDE provides the most seamless integration for interactive biomedical research during development.

### Installation

1. **Prerequisites:**

   - [Cursor IDE](https://cursor.sh/) installed
   - [Smithery](https://smithery.ai/) account and token

2. **Install BioMCP:**

   ```bash
   npx -y @smithery/cli@latest install @genomoncology/biomcp --client cursor
   ```

3. **Configuration:**
   - The Smithery CLI automatically configures Cursor
   - No manual configuration needed

### Usage in Cursor

Once installed, you can query biomedical data using natural language:

#### Clinical Trials

```
"Find Phase 3 clinical trials for lung cancer with immunotherapy"
```

#### Research Articles

```
"Summarize recent research on EGFR mutations in lung cancer"
```

#### Genetic Variants

```
"What's the clinical significance of the BRAF V600E mutation?"
```

#### Complex Queries

```
"Compare treatment outcomes for ALK-positive vs EGFR-mutant NSCLC"
```

### Cursor Tips

1. **Be Specific**: Include gene names, disease types, and treatment modalities
2. **Iterate**: Refine queries based on initial results
3. **Cross-Reference**: Ask for both articles and trials on the same topic
4. **Export Results**: Copy formatted results for documentation

## Python SDK Integration

The Python SDK provides programmatic access to BioMCP for building applications.

### Installation

```bash
# Using pip
pip install biomcp-python

# Using uv
uv add biomcp-python

# For scripts
uv pip install biomcp-python
```

### Basic Usage

```python
import asyncio
from biomcp import BioMCP

async def main():
    # Initialize client
    client = BioMCP()

    # Search for articles
    articles = await client.articles.search(
        genes=["BRAF"],
        diseases=["melanoma"],
        limit=5
    )

    # Search for trials
    trials = await client.trials.search(
        conditions=["breast cancer"],
        interventions=["CDK4/6 inhibitor"],
        recruiting_status="RECRUITING"
    )

    # Get variant details
    variant = await client.variants.get("rs121913529")

    return articles, trials, variant

# Run the async function
results = asyncio.run(main())
```

### Advanced Features

#### Domain-Specific Modules

```python
from biomcp import BioMCP
from biomcp.variants import search_variants, get_variant
from biomcp.trials import search_trials, get_trial
from biomcp.articles import search_articles, fetch_articles

# Direct module usage
async def variant_analysis():
    # Search pathogenic TP53 variants
    results = await search_variants(
        gene="TP53",
        significance="pathogenic",
        frequency_max=0.01,
        limit=20
    )

    # Get detailed annotations
    for variant in results:
        details = await get_variant(variant.id)
        print(f"{variant.id}: {details.clinical_significance}")
```

#### Output Formats

```python
# JSON for programmatic use
articles_json = await client.articles.search(
    genes=["KRAS"],
    format="json"
)

# Markdown for display
articles_md = await client.articles.search(
    genes=["KRAS"],
    format="markdown"
)
```

#### Error Handling

```python
from biomcp.exceptions import BioMCPError, APIError, ValidationError

try:
    results = await client.articles.search(genes=["INVALID_GENE"])
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIError as e:
    print(f"API error: {e}")
except BioMCPError as e:
    print(f"General error: {e}")
```

### Example: Building a Variant Report

```python
import asyncio
from biomcp import BioMCP

async def generate_variant_report(gene: str, mutation: str):
    client = BioMCP()

    # 1. Get gene information
    gene_info = await client.genes.get(gene)

    # 2. Search for the specific variant
    variants = await client.variants.search(
        gene=gene,
        keywords=[mutation]
    )

    # 3. Find relevant articles
    articles = await client.articles.search(
        genes=[gene],
        keywords=[mutation],
        limit=10
    )

    # 4. Look for clinical trials
    trials = await client.trials.search(
        conditions=["cancer"],
        other_terms=[f"{gene} {mutation}"],
        recruiting_status="RECRUITING"
    )

    # 5. Generate report
    report = f"""
# Variant Report: {gene} {mutation}

## Gene Information
- **Official Name**: {gene_info.name}
- **Summary**: {gene_info.summary}

## Variant Details
Found {len(variants)} matching variants

## Literature ({len(articles)} articles)
Recent publications discussing this variant...

## Clinical Trials ({len(trials)} active trials)
Currently recruiting studies...
"""

    return report

# Generate report
report = asyncio.run(generate_variant_report("BRAF", "V600E"))
print(report)
```

## MCP Client Integration

The Model Context Protocol (MCP) provides a standardized way to integrate BioMCP with AI assistants and other tools.

### Understanding MCP

MCP is a protocol for communication between:

- **Clients**: AI assistants, IDEs, or custom applications
- **Servers**: Tool providers like BioMCP

### Critical Requirement: Think Tool

**IMPORTANT**: When using MCP, you MUST call the `think` tool first before any search or fetch operations. This ensures systematic analysis and optimal results.

### Basic MCP Integration

```python
import asyncio
import subprocess
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_biomcp_query():
    # Start BioMCP server
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "--with", "biomcp-python", "biomcp", "run"],
        env={"PYTHONUNBUFFERED": "1"}
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize and discover tools
            await session.initialize()
            tools = await session.list_tools()

            # CRITICAL: Always think first!
            await session.call_tool(
                "think",
                arguments={
                    "thought": "Analyzing BRAF V600E in melanoma...",
                    "thoughtNumber": 1,
                    "nextThoughtNeeded": True
                }
            )

            # Now search for articles
            result = await session.call_tool(
                "article_searcher",
                arguments={
                    "genes": ["BRAF"],
                    "diseases": ["melanoma"],
                    "keywords": ["V600E"]
                }
            )

            return result

# Run the query
result = asyncio.run(run_biomcp_query())
```

### Available MCP Tools

BioMCP provides 24 tools through MCP:

#### Core Tools (Always Use First)

- `think` - Sequential reasoning (MANDATORY first step)
- `search` - Unified search across domains
- `fetch` - Retrieve specific records

#### Domain-Specific Tools

- **Articles**: `article_searcher`, `article_getter`
- **Trials**: `trial_searcher`, `trial_getter`, plus detail getters
- **Variants**: `variant_searcher`, `variant_getter`, `alphagenome_predictor`
- **BioThings**: `gene_getter`, `disease_getter`, `drug_getter`
- **NCI**: Organization, intervention, biomarker, disease tools

### MCP Integration Patterns

#### Pattern 1: AI Assistant Integration

```python
# Example for integrating with an AI assistant
class BioMCPAssistant:
    def __init__(self):
        self.session = None

    async def connect(self):
        # Initialize MCP connection
        server_params = StdioServerParameters(
            command="biomcp",
            args=["run"]
        )
        # ... connection setup ...

    async def process_query(self, user_query: str):
        # 1. Always think first
        await self.think_about_query(user_query)

        # 2. Determine appropriate tools
        tools_needed = self.analyze_query(user_query)

        # 3. Execute tool calls
        results = []
        for tool in tools_needed:
            result = await self.session.call_tool(tool.name, tool.args)
            results.append(result)

        # 4. Synthesize results
        return self.format_response(results)
```

#### Pattern 2: Custom Client Implementation

```python
import json
from typing import Any, Dict

class BioMCPClient:
    """Custom client for specific biomedical workflows"""

    async def variant_to_trials_pipeline(self, variant_id: str):
        """Find trials for patients with specific variants"""

        # Step 1: Think and plan
        await self.think(
            "Planning variant-to-trials search pipeline...",
            thoughtNumber=1
        )

        # Step 2: Get variant details
        variant = await self.call_tool("variant_getter", {
            "variant_id": variant_id
        })

        # Step 3: Extract gene and disease associations
        gene = variant.get("gene", {}).get("symbol")
        diseases = self.extract_diseases(variant)

        # Step 4: Search for relevant trials
        trials = await self.call_tool("trial_searcher", {
            "conditions": diseases,
            "other_terms": [f"{gene} mutation"],
            "recruiting_status": "RECRUITING"
        })

        return {
            "variant": variant,
            "associated_trials": trials
        }
```

### MCP Best Practices

1. **Always Think First**

   ```python
   # ✅ Correct
   await think(thought="Planning research...", thoughtNumber=1)
   await search(...)

   # ❌ Wrong - skips thinking
   await search(...)  # Will produce poor results
   ```

2. **Use Appropriate Tools**

   ```python
   # For broad searches across domains
   await call_tool("search", {"query": "gene:BRAF AND melanoma"})

   # For specific domain searches
   await call_tool("article_searcher", {"genes": ["BRAF"]})
   ```

3. **Handle Tool Responses**
   ```python
   try:
       result = await session.call_tool("variant_getter", {
           "variant_id": "rs121913529"
       })
       # Process structured result
       if result.get("error"):
           handle_error(result["error"])
       else:
           process_variant(result["data"])
   except Exception as e:
       logger.error(f"Tool call failed: {e}")
   ```

## Choosing the Right Integration

### Use Cursor IDE When:

- Doing interactive research during development
- Exploring biomedical data for new projects
- Need quick answers without writing code
- Want natural language queries

### Use Python SDK When:

- Building production applications
- Need type-safe interfaces
- Want direct function calls
- Require custom error handling

### Use MCP Client When:

- Integrating with AI assistants
- Building protocol-compliant tools
- Need standardized tool interfaces
- Want language-agnostic integration

## Integration Examples

### Example 1: Research Dashboard (Python SDK)

```python
from biomcp import BioMCP
import streamlit as st

async def create_dashboard():
    client = BioMCP()

    st.title("Biomedical Research Dashboard")

    # Gene input
    gene = st.text_input("Enter gene symbol:", "BRAF")

    if st.button("Search"):
        # Fetch comprehensive data
        col1, col2 = st.columns(2)

        with col1:
            st.subheader("Recent Articles")
            articles = await client.articles.search(genes=[gene], limit=5)
            for article in articles:
                st.write(f"- [{article.title}]({article.url})")

        with col2:
            st.subheader("Active Trials")
            trials = await client.trials.search(
                other_terms=[gene],
                recruiting_status="RECRUITING",
                limit=5
            )
            for trial in trials:
                st.write(f"- [{trial.nct_id}]({trial.url})")
```

### Example 2: Variant Analysis Pipeline (MCP)

```python
async def comprehensive_variant_analysis(session, hgvs: str):
    """Complete variant analysis workflow using MCP"""

    # Think about the analysis
    await session.call_tool("think", {
        "thought": f"Planning comprehensive analysis for {hgvs}",
        "thoughtNumber": 1
    })

    # Get variant details
    variant = await session.call_tool("variant_getter", {
        "variant_id": hgvs
    })

    # Search related articles
    articles = await session.call_tool("article_searcher", {
        "variants": [hgvs],
        "limit": 10
    })

    # Find applicable trials
    gene = variant.get("gene", {}).get("symbol")
    trials = await session.call_tool("trial_searcher", {
        "other_terms": [f"{gene} mutation"],
        "recruiting_status": "RECRUITING"
    })

    # Predict functional effects if genomic coordinates available
    if variant.get("chrom") and variant.get("pos"):
        prediction = await session.call_tool("alphagenome_predictor", {
            "chromosome": f"chr{variant['chrom']}",
            "position": variant["pos"],
            "reference": variant["ref"],
            "alternate": variant["alt"]
        })

    return {
        "variant": variant,
        "articles": articles,
        "trials": trials,
        "prediction": prediction
    }
```

## Troubleshooting

### Common Issues

1. **"Think tool not called" errors**

   - Always call think before other operations
   - Include thoughtNumber parameter

2. **API rate limits**

   - Add delays between requests
   - Use API keys for higher limits

3. **Connection failures**

   - Check network connectivity
   - Verify server is running
   - Ensure correct installation

4. **Invalid gene symbols**
   - Use official HGNC symbols
   - Check [genenames.org](https://www.genenames.org)

### Debug Mode

Enable debug logging:

```python
# Python SDK
import logging
logging.basicConfig(level=logging.DEBUG)

# MCP Client
server_params = StdioServerParameters(
    command="biomcp",
    args=["run", "--log-level", "DEBUG"]
)
```

## Next Steps

- Explore [tool-specific documentation](02-mcp-tools-reference.md)
- Review [API authentication](../getting-started/03-authentication-and-api-keys.md)
- Check [example workflows](../how-to-guides/01-find-articles-and-cbioportal-data.md) for your use case


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->