Biologist MCP Server
# Biologist Model Context Protocol (MCP) Server
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
A Model Context Protocol (MCP) server providing deep LLM-agent tool, resource, and prompt integrations with **[Biologist](https://github.com/leouofa/biologist)** — an open-source computational research platform and quantitative analytical laboratory for comparative biology, ecology, and organismal taxonomy.
---
## Overview
The `biologist-mcp` server enables AI agents (Claude Code, Cursor, Gemini CLI, Antigravity) to query, manipulate, cluster, and synthesize ecological and taxonomic domain models directly over standard input/output (`stdio`):
- **51 Registered MCP Tools** across 8 functional modules (Search, Biomes, Species, Organisms, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).
- **4 Registered MCP Resources** exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.
- **3 MCP Prompt Templates** for comparative biological studies, cluster synthesis monographs, and evolutionary convergence inquiries.
- **1024-dimensional semantic manifold** querying via PostgreSQL `pgvector` HNSW indexes.
---
## Architectural Mapping
| Tier / Domain | Model | Table Name | MCP Module / Tools |
|---|---|---|---|
| **Tier 1** | Biomes & Climatic Zones | `biomes` | `list_biomes`, `get_biome`, `create_biome`, `update_biome`, `delete_biome`, `upsert_biomes_batch`, `populate_biomes`, `populate_biome_species` |
| **Tier 2** | Species & Keystone Taxa | `species` | `list_species`, `get_species`, `create_species`, `update_species`, `delete_species`, `upsert_species_batch`, `generate_species_embedding`, `populate_species_organisms`, `populate_species_bulk` |
| **Tier 3** | Individual Organisms & Morphs | `organisms` | `list_organisms`, `get_organism`, `create_organism`, `update_organism`, `delete_organism`, `upsert_organisms_batch`, `generate_organism_embedding`, `populate_organisms_bulk` |
| **Clustering** | 15-Level Agglomerative | `cluster_snapshots`, `cluster_groups` | `compute_clusters`, `create_cluster_snapshot`, `list_cluster_snapshots`, `get_cluster_snapshot`, `delete_cluster_snapshot`, `list_cluster_groups`, `get_cluster_group` |
| **Synthesis** | Multi-Stage Map-Reduce | `cluster_reports`, `cluster_report_summaries` | `list_cluster_reports`, `get_cluster_report`, `create_cluster_report`, `delete_cluster_report`, `generate_deep_synthesis`, `list_report_summaries`, `get_report_summary`, `list_report_sub_reports`, `get_report_sub_report` |
| **Global Search** | Cross-Catalog pgvector | Multi-table | `search`, `find_counterparts` |
| **Platform** | Jobs & System Info | Multi-service | `list_jobs`, `get_job_status`, `wait_for_job`, `get_platform_status`, `get_settings`, `update_context_window`, `trigger_bulk_embeddings`, `get_openapi_spec` |
---
## Installation & Setup
### Prerequisites
- Node.js 20+
- Running instance of [Biologist](https://github.com/leouofa/biologist) (`http://localhost:3000`)
### Build
```bash
git clone https://github.com/leouofa/biologist-mcp.git
cd biologist-mcp
npm install
npm run build
```
---
## Configuration
### Environment Variables
Configure via `.env` file or export in your shell:
```bash
# Base URL for the Biologist Rails API (v1)
BIOLOGIST_API_BASE_URL=http://localhost:3000/api/v1
# Optional Bearer Token for protected endpoints
BIOLOGIST_API_TOKEN=
# Request timeout in milliseconds (default: 60000)
BIOLOGIST_TIMEOUT_MS=60000
# Enable debug logging
BIOLOGIST_DEBUG=false
```
### CLI Options
```bash
biologist-mcp [options]
Options:
-u, --url <url> Biologist API base URL (default: http://localhost:3000/api/v1)
-k, --api-key <key> Optional API key / Bearer token
-t, --timeout <ms> Request timeout in milliseconds (default: 60000)
-d, --debug Enable debug logging
-h, --help Display this help message
```
---
## MCP Client Configuration
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"biologist": {
"command": "node",
"args": ["/path/to/biologist-mcp/dist/index.js"],
"env": {
"BIOLOGIST_API_BASE_URL": "http://localhost:3000/api/v1"
}
}
}
}
```
### Antigravity
Add to your `antigravity_config.json` or MCP settings:
```json
{
"mcpServers": {
"biologist": {
"command": "node",
"args": ["/path/to/biologist-mcp/dist/index.js"],
"env": {
"BIOLOGIST_API_BASE_URL": "http://localhost:3000/api/v1"
}
}
}
}
```
---
## MCP Resources
| URI Template | MIME Type | Description |
|---|---|---|
| `biologist://status` | `application/json` | Real-time platform health, counts, and LLM configuration |
| `biologist://biomes` | `application/json` | Catalog of all registered biomes |
| `biologist://snapshots/{id}` | `application/json` | Frozen cluster snapshot data with members and reports |
| `biologist://reports/{id}` | `text/markdown` | Generated synthesis monograph in academic Markdown |
---
## MCP Prompts
1. **`comparative_biological_analysis`**: Rigorous comparative analysis between two species or organisms using semantic manifold distance, trophic strategies, and functional adaptations.
2. **`biological_cluster_monograph`**: Academic synthesis monograph prompt for drafting a formal treatise from frozen archetype clusters.
3. **`evolutionary_convergence_inquiry`**: Cross-biome convergence analysis prompt investigating analog adaptations across independent lineages.
---
## Testing
```bash
# Run test suite
npm test
# Run tests in watch mode
npm run test:watch
```
---
## License
This project is open-source software licensed under the [MIT License](LICENSE).
TDQS
Scored across 51 tools
The tool set is organized by resource, but several tools have overlapping boundaries: get_platform_status and get_settings both expose embedding/LLM configuration, while create_*, upsert_*_batch, and populate_* provide three different creation paths for biomes, species, and organisms. report_summary/sub_report/cluster_report tools are distinguishable, but the sheer number of similarly named lifecycle tools increases misselection risk.
Most names follow a clear snake_case verb_noun pattern (list_biomes, create_species, delete_organism, generate_organism_embedding). There are minor deviations such as the bare 'search' and some noun-heavy report names, but the convention is generally predictable.
At 51 tools, the surface is heavy for any MCP server and includes many near-parallel CRUD, batch, populate, embedding, snapshot, reporting, job, and system tools. The domain is broad, but the count still feels excessive relative to the core workflow.
The server covers full CRUD lifecycles for biomes, species, organisms, cluster snapshots, and reports, plus embedding, job, search, and system operations. Minor gaps exist (for example, no direct update/delete for cluster groups, and snapshot immutability is intentional), but the main workflows are well supported.