noctua-mcp

MCP server for GO-CAM model editing via the Barista API.

This package provides a thin MCP (Model Context Protocol) wrapper around the noctua-py library, exposing GO-CAM editing capabilities through a standardized interface.

Quick Start

Once published:

uvx noctua-mcp

For development:

uv run noctua-mcp serve

Using with Claude Code

1. Configure the MCP server: The project includes a .mcp.json configuration file that tells Claude Code how to run the server.

2. Set your Barista token: You'll need to set the BARISTA_TOKEN environment variable before starting Claude Code:

   export BARISTA_TOKEN="your-barista-token-here"
   claude-code /path/to/noctua-mcp
   

3. Verify the connection: Once Claude Code starts, the MCP server will be available. You can ask Claude to use the Noctua tools to interact with GO-CAM models.

The .mcp.json configuration is already set up to:

• Run the server using uv run noctua-mcp
• Pass through the BARISTA_TOKEN environment variable
• Configure the default Barista endpoints

Environment Variables

• BARISTA_TOKEN (required) – Barista API token for privileged operations
• BARISTA_BASE (default: http://barista-dev.berkeleybop.org) – Barista server URL
• BARISTA_NAMESPACE (default: minerva_public_dev) – Minerva namespace
• BARISTA_PROVIDED_BY (default: http://geneontology.org) – Provider identifier

Available Tools

Model Editing

• add_individual(model_id, class_curie, assign_var) – Add an instance of a GO/ECO term
• add_fact(model_id, subject_id, object_id, predicate_id) – Add a relation between individuals
• add_evidence_to_fact(model_id, subject_id, object_id, predicate_id, eco_id, sources, with_from) – Add evidence to a fact
• remove_individual(model_id, individual_id) – Remove an individual
• remove_fact(model_id, subject_id, object_id, predicate_id) – Remove a fact

Model Patterns

• add_basic_pathway(model_id, pathway_curie, mf_curie, gene_product_curie, cc_curie) – Add a basic GO-CAM unit
• add_causal_chain(model_id, mf1_curie, mf2_curie, gp1_curie, gp2_curie, causal_relation) – Add causally linked activities

Model Query

• get_model(model_id) – Retrieve full model JSON
• model_summary(model_id) – Get model statistics and summary

Configuration

• configure_token(token) – Set Barista token at runtime (not echoed)

Architecture

This server is designed as a thin shim layer:

MCP Client (e.g., Claude)
    ↓
noctua-mcp (this package)
    ↓
noctua-py library
    ↓
Barista API / Noctua

All core logic resides in the noctua-py library. This MCP server only:

1. Exposes noctua-py functionality through MCP tools
2. Manages client singleton
3. Provides prompts for common patterns

Testing

The package includes comprehensive tests:

# Run all tests
uv run pytest

# Run unit tests only
uv run pytest tests/test_unit.py

# Run MCP integration tests
uv run pytest tests/test_mcp.py

# Run with coverage
uv run pytest --cov=noctua_mcp --cov-report=term-missing

Tests are divided into:

• Unit tests (test_unit.py): Direct function testing with mocks
• MCP tests (test_mcp.py): Server startup and tool invocation via FastMCP client
• Live tests: Optional tests that require BARISTA_TOKEN and network access

Development

# Install dependencies including noctua-py from local path
uv sync

# Run the server
uv run noctua-mcp serve

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

Protocol Overview

This project implements an MCP server using FastMCP. MCP (Model Context Protocol) standardizes how tools/resources are exposed to LLMs and agent clients.

Useful links:

• MCP Specification
• FastMCP Documentation
• noctua-py Library

Best Practices

• stdio transport by default with single entry point
• Rich docstrings for all tools (parameters, returns, examples)
• No secrets echoed in outputs (Barista token handled securely)
• Comprehensive async testing using fastmcp.Client
• Thin wrapper pattern - core logic in upstream library

Credits

This project uses the monarch-project-copier template.