# 🔬 PocketScout MCP

**Scout the binding landscape before you design the binder.**

PocketScout is a fast triage tool for drug-target binding sites — it gives an AI assistant the tools to pull together everything known about a protein's pockets (structure, chemistry, conservation, literature) into a single briefing in minutes. It's especially handy as the reconnaissance step before computational binder design, filling the gap between *"I have a target"* and *"I'm running RFdiffusion."*

## Get Started

### Use instantly on claude.ai (no install)

1. Go to [claude.ai → Customize → Connectors → **+**](https://claude.ai/customize/connectors)
2. Name: `PocketScout`
3. URL: `https://pocketscout-mcp.up.railway.app/mcp`
4. Ask Claude:

> "Assess KRAS G12C (PDB 6OIM) as a target for de novo protein binder design. Where are the best pockets, and what should I watch out for?"

### Use with Claude Code

```bash
claude mcp add pocketscout --transport http https://pocketscout-mcp.up.railway.app/mcp
```

### Use with Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pocketscout": {
      "url": "https://pocketscout-mcp.up.railway.app/mcp"
    }
  }
}
```

Restart Claude Desktop, then ask Claude to assess a target.

---

## The Problem

Drug discovery scientists spend hours to days manually gathering information across 6-10 browser tabs before they can make an informed decision about a target. Scientists evaluating an unfamiliar target, new team members trying to get up to speed, and scouting or BD roles screening many candidates face the same bottleneck: they check UniProt for function, browse PDB for structures, search ChEMBL for prior art, read papers for allosteric insights — and then synthesize it all in their heads.

This manual triage step is where campaigns quietly go wrong. A scientist picks the obvious orthosteric site without checking that 200 compounds have already failed there. They miss an allosteric pocket described in a 2023 paper. They don't realize the binding site residues aren't conserved in mouse until their in vivo model fails. For binder-design campaigns specifically, it's the gap between "I have a target" and knowing which pocket to hand off to RFdiffusion.

## The Solution

PocketScout gives an AI assistant (Claude, or any MCP-compatible model) the tools to perform systematic binding site triage in minutes instead of hours — whether you're screening a target for the first time, briefing a new team member, or preparing a computational design campaign. Eight tools compose into a scientific workflow that reflects how expert medicinal chemists actually evaluate targets.

## Tools

| Tool | What it does | Key APIs |
|------|-------------|----------|
| `characterize_target` | Biological context + AlphaFold confidence | UniProt, AlphaFold DB |
| `get_related_structures` | All PDB structures, ligands, quality | RCSB PDB Search |
| `get_binding_sites` | Map known pockets with residue contacts | RCSB PDB Data + gemmi |
| `get_ligand_history` | Competitive landscape from bioactivity data | ChEMBL |
| `check_conservation` | Human vs. mouse at binding residues | UniProt Orthologs |
| `search_target_literature` | Structural/design-focused papers | PubMed E-utilities |
| `check_known_variants` | Flag known disease/resistance variants at binding-site residues | UniProt |
| `consolidate_binding_sites` | Union of pockets across all structures of a target, ranked by recurrence | RCSB PDB + gemmi |

### Orchestration Prompts

`target_briefing` — Quick triage briefing for a drug target: what the protein is, its main pockets, the competitive landscape, and the one or two things worth knowing before going deeper. Use this for fast first-pass assessment.

`binding_site_assessment` — In-depth, design-focused workup. Guides the AI through all tools in scientific workflow order, producing a ranked recommendation of binding regions with evidence, trade-offs, and design parameters.

### Install locally (optional)

If you prefer to run the server yourself:

```bash
pip install pocketscout-mcp
```

Or from source:

```bash
git clone https://github.com/Proprius-Labs/pocketscout-mcp.git
cd pocketscout-mcp
pip install -e .
```

> **Requires Python 3.11+.** If your system Python is older, use [uv](https://docs.astral.sh/uv/): `uv pip install pocketscout-mcp`

Then configure Claude Desktop to run locally:

```json
{
  "mcpServers": {
    "pocketscout": {
      "command": "pocketscout-mcp"
    }
  }
}
```

> **Tip**: If you installed in a virtual environment, use the full path:
> `"command": "/path/to/venv/bin/pocketscout-mcp"`

### Test with MCP Inspector

```bash
fastmcp dev src/pocketscout_mcp/server.py
```

## Design Decisions

### Why these tools?

The tool set reflects the actual decision workflow of an experienced drug discovery scientist evaluating a new target. Each tool answers a specific question that gates the next decision:

1. **characterize_target**: *"What am I looking at?"* — You can't interpret binding sites without knowing the protein family, location, and structure quality. AlphaFold confidence is included here because it determines whether downstream structural analysis is trustworthy.

2. **get_related_structures**: *"How much do we know?"* — A target with 200 co-crystal structures is a different problem than one with a single cryo-EM map. This step sets expectations for the binding site analysis.

3. **get_binding_sites**: *"Where can I bind?"* — The core deliverable. Downloads the mmCIF coordinate file, uses gemmi to compute residue contacts within 4.5 A of each co-crystallized ligand, and classifies pockets (orthosteric, allosteric, cofactor) with size-based druggability assessment. When a structure has both cofactor and non-cofactor ligands, non-overlapping sites are automatically reclassified as allosteric.

4. **get_ligand_history**: *"What's been tried?"* — Determines whether you're entering a crowded or greenfield space. A crowded orthosteric site argues for novel sites or modalities.

5. **check_conservation**: *"Will my mouse model work?"* — Non-conserved binding residues mean your preclinical model may give misleading results. This is the step most scientists skip — and the one that most often causes late-stage failures.

6. **search_target_literature**: *"What do the experts know that the databases don't?"* — Cryptic sites from MD simulations, allosteric mechanisms from mutagenesis studies, resistance mutations that reshape pockets — these insights live in papers, not databases.

7. **check_known_variants**: *"Will this pocket mutate out from under me?"* — Binding-site residues that are documented resistance/disease variants (e.g. EGFR T790M) flag pockets that change under drug pressure.

8. **consolidate_binding_sites**: *"Which pocket is real and recurrent?"* — Unions pockets across all structures of a target so the dominant, repeatedly-observed site stands out from one-offs.

### Why not include pocket prediction?

Tools like fpocket, P2Rank, and SiteMap predict novel binding sites computationally. These are valuable but require computational infrastructure (CPU/GPU) that doesn't fit the MCP model of lightweight API-based tools. PocketScout focuses on *known* binding intelligence from experimental data and literature. Pocket prediction belongs in a separate compute-oriented server.

### Why pre-compute interpretations?

Each tool returns both raw data and an `interpretation` field with scientific context. This is a deliberate design choice: the interpretation encodes domain expertise that helps the AI make better reasoning decisions. A raw list of ChEMBL activities is harder for Claude to reason about than a structured competitive landscape assessment.

### Why local-context conservation across mouse, rat, and cynomolgus?

Full multi-species conservation requires multiple sequence alignment, which is computationally expensive and error-prone without proper gap handling. The tool now checks three preclinical model organisms — mouse (NCBI taxonomy 10090), rat (10116), and cynomolgus macaque (9541) — covering both rodent and non-human primate translatability questions in a single call. Each species is assessed independently using local-context (sliding-window) matching to handle insertions/deletions between the human and ortholog sequences, providing accurate residue correspondence without requiring a full MSA or a BioPython dependency. The tool is deliberately kept lightweight: no MSA, no external alignment tools, no heavy dependencies.

## Architecture

```
User: "Assess PDB 7S4S for de novo binder design"
  │
  ▼
Claude (or any MCP client)
  │
  ├── characterize_target(pdb_id="7S4S")
  │     └── UniProt API + AlphaFold DB
  │
  ├── get_related_structures(pdb_id="7S4S")
  │     └── RCSB PDB Search API
  │
  ├── get_binding_sites(pdb_id="7S4S")
  │     └── RCSB PDB Data API
  │
  ├── get_ligand_history(uniprot_id="...")
  │     └── ChEMBL REST API
  │
  ├── check_conservation(uniprot_id="...", residues=[...])
  │     └── UniProt Orthologs
  │
  ├── check_known_variants(uniprot_id="...", residues=[...])
  │     └── UniProt variants
  │
  ├── consolidate_binding_sites(uniprot_id="...")
  │     └── RCSB PDB + gemmi (cross-structure)
  │
  └── search_target_literature(gene_name="...")
        └── PubMed E-utilities
  │
  ▼
Ranked binding site assessment with evidence + trade-offs
```

## Example Output

See [examples/egfr_assessment.md](examples/egfr_assessment.md) for a complete walkthrough using EGFR (PDB 1M17) — a well-studied kinase with rich structural and chemical data.

## Configuration

### PubMed API Key (optional but recommended)

NCBI rate limits to 3 requests/second without a key. Get a free key at [NCBI](https://www.ncbi.nlm.nih.gov/account/settings/) and set:

```bash
export NCBI_API_KEY=your_key_here
```

## Limitations

- **No pocket prediction**: PocketScout reports *known* binding sites from experimental structures. Novel/cryptic site prediction requires computational tools not included here.
- **Simplified conservation**: Human vs. mouse, rat, and cynomolgus comparison using local context matching. Handles indels but not a full MSA — accurate for most drug targets.
- **Public data only**: All data comes from public APIs (UniProt, PDB, ChEMBL, PubMed, AlphaFold DB). Proprietary databases are not accessed.

## Roadmap

- [x] Coordinate-level binding site analysis with gemmi
- [x] Per-residue AlphaFold pLDDT from CIF files
- [x] Multi-species conservation (mouse/rat/cynomolgus via local-context matching)
- [ ] Integration with computational pocket prediction (fpocket MCP)
- [ ] Allosteric site detection from ensemble structures
- [ ] Patent landscape integration (SureChEMBL)

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT

## Author

**Paul Mangiamele, PhD**
[Proprius Labs](https://propriuslabs.ai) · [LinkedIn](https://www.linkedin.com/in/paulmm/)