# PomBase MCP Server

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives AI agents
structured access to [PomBase](https://www.pombase.org), the comprehensive database for the fission
yeast *Schizosaccharomyces pombe*. It wraps PomBase's public, unauthenticated JSON API
(`https://www.pombase.org/api/v1/dataset/latest/data`, see the
[API documentation](https://www.pombase.org/documentation/api)) so agents can look up genes, GO
annotations, phenotypes, orthologs, protein domains, and interactions without scraping the website.

No API key or account is required — PomBase's API is free and open for academic/research use.

## Features

- 🔎 Keyword search across all ~12,700 curated *S. pombe* genes
- 🧬 Gene summaries, protein domains, GO annotations, phenotypes, orthologs, and interactions
- 📊 A multi-gene comparison tool for quickly triaging gene lists (e.g. screen hits)
- 📝 Markdown (human-readable) or JSON (machine-readable) output for every tool
- ⚡ Async I/O throughout, with an in-memory cache for the large gene-summary dataset

## Available Tools

| Tool | Description |
|---|---|
| `pombase_search_genes` | Search/browse genes by name, systematic ID, or product keyword. Use this to resolve a gene name (e.g. `cdc2`) to its systematic ID (e.g. `SPBC11B10.09`). Supports pagination. |
| `pombase_get_gene_summary` | Core identifying info for a gene: name, product, synonyms, genomic location, taxon, UniProt/BioGRID IDs, characterisation status, deletion viability. |
| `pombase_get_gene_domains` | Protein domain/motif annotations: InterPro matches (source DB, coordinates, descriptions) and transmembrane domain coordinates. |
| `pombase_get_gene_go_annotations` | Gene Ontology annotations (Molecular Function, Biological Process, Cellular Component), optionally filtered to one aspect. |
| `pombase_get_gene_phenotypes` | FYPO (Fission Yeast Phenotype Ontology) annotations plus the gene's deletion viability (essential vs. non-essential). |
| `pombase_get_gene_orthologs` | Curated human and *S. cerevisiae* orthologs of the gene. |
| `pombase_get_gene_interactions` | Curated physical and/or genetic interactions, with interactor names, evidence, and source references. |
| `pombase_compare_genes` | Workflow tool: fetches 2-10 genes in parallel and returns a side-by-side comparison (product, viability, characterisation status, ortholog counts). |

Every tool accepts a `response_format` of `"markdown"` (default, human-readable) or `"json"`
(structured, for programmatic use).

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or `pip`

## Installation

Clone or download this repository, then choose one of the install paths below.

```bash
git clone [pombase-mcp](https://github.com/ubcd-ibfg/pombase-mcp)
cd pombase-mcp
```

### Option A: uv (recommended — no separate install step needed)

`uv` can run the server directly from the project directory with `uv run`, resolving
dependencies automatically. This is the command used in the client configs below.

### Option B: pip

```bash
pip install -e .
```

This installs the `pombase-mcp` console command (defined in `pyproject.toml`) on your `PATH`.

---

## Connecting to Claude Code

[Claude Code](https://docs.claude.com/en/docs/claude-code) can register MCP servers with the
`claude mcp add` CLI command.

**Using uv (from the cloned project directory):**

```bash
claude mcp add pombase -- uv run --directory /absolute/path/to/pombase-mcp pombase-mcp
```

**Using a pip install:**

```bash
claude mcp add pombase -- pombase-mcp
```

Verify it's connected:

```bash
claude mcp list
```

Then just ask Claude Code things like *"Use PomBase to find the human ortholog of cdc2 in fission
yeast"* — it will discover and call the tools automatically.

To remove it later: `claude mcp remove pombase`.

### Project-scoped config (checked into a repo)

Alternatively, add a `.mcp.json` file to your project root:

```json
{
  "mcpServers": {
    "pombase": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
    }
  }
}
```

---

## Connecting to Claude Desktop

Edit your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "pombase": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
    }
  }
}
```

(If you installed via `pip install -e .` instead, replace `"command"`/`"args"` with
`"command": "pombase-mcp", "args": []`, using the full path to the executable if it's not on
Claude Desktop's `PATH`.)

Restart Claude Desktop after saving. The PomBase tools will appear under the 🔌 connector icon.

---

## Connecting to Cursor

Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pombase": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
    }
  }
}
```

---

## Connecting to Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "pombase": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
    }
  }
}
```

---

## Connecting to OpenCode

[OpenCode](https://opencode.ai/) is a web-based IDE with built-in MCP support. To connect PomBase MCP:

1. Open your OpenCode workspace
2. Go to **Settings** → **MCP Servers**
3. Add a new server with the following configuration:

```json
{
  "pombase": {
    "command": "uv",
    "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
  }
}
```

Replace `/absolute/path/to/pombase-mcp` with the full path to your cloned repository.

Alternatively, if you've installed via `pip install -e .`:

```json
{
  "pombase": {
    "command": "pombase-mcp",
    "args": []
  }
}
```

Save the configuration and the PomBase tools will be available in your OpenCode AI assistant.

---

## Connecting to any other MCP-compatible client (generic stdio config)

Most agent platforms (Cline, Continue, LibreChat, Zed, custom MCP clients, etc.) accept the same
shape of config — a command to launch the server over stdio:

```json
{
  "mcpServers": {
    "pombase": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pombase-mcp", "pombase-mcp"]
    }
  }
}
```

or, if installed with pip:

```json
{
  "mcpServers": {
    "pombase": {
      "command": "pombase-mcp",
      "args": []
    }
  }
}
```

Consult your client's docs for where this config file lives.

---

## Running and testing manually

Run the server directly over stdio:

```bash
uv run --directory /absolute/path/to/pombase-mcp pombase-mcp
# or, if pip-installed:
pombase-mcp
```

Inspect and test tool calls interactively with the official
[MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector uv run --directory /absolute/path/to/pombase-mcp pombase-mcp
```

## Example prompts once connected

- "Search PomBase for kinase genes and show me the first 10."
- "What is the product of SPBC11B10.09, and is it essential?"
- "What GO biological process terms is pom1 (SPAC2F7.03c) annotated with?"
- "What are the human orthologs of cdc2?"
- "List the physical interactions for ase1."
- "Compare cdc2, cdc13, and wee1 — which are essential and what are their human orthologs?"

## Data source and licensing

All data is served live from PomBase (https://www.pombase.org/api/v1/dataset/latest/data) and is
not bundled with this server. PomBase is funded by the Wellcome Trust and run by a consortium
comprising the University of Cambridge, University College London, and the Babraham Institute. If
you use PomBase data in your research, please cite PomBase — see
https://www.pombase.org/help/citing-pombase.

This project is an independent, unofficial MCP wrapper and is not developed or endorsed by the
PomBase team.

## License

MIT — see [LICENSE](LICENSE).