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:

For development:

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:

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:

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

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.