Skip to main content
Glama
README.md
# Biologist Model Context Protocol (MCP) Server

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.32.2-purple.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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

B3/5.0

Scored across 51 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count2/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues