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
Configure the MCP server: The project includes a
.mcp.json
configuration file that tells Claude Code how to run the server.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-mcpVerify 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 variableConfigure the default Barista endpoints
Environment Variables
BARISTA_TOKEN
(required) – Barista API token for privileged operationsBARISTA_BASE
(default: http://barista-dev.berkeleybop.org) – Barista server URLBARISTA_NAMESPACE
(default: minerva_public_dev) – Minerva namespaceBARISTA_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 termadd_fact(model_id, subject_id, object_id, predicate_id)
– Add a relation between individualsadd_evidence_to_fact(model_id, subject_id, object_id, predicate_id, eco_id, sources, with_from)
– Add evidence to a factremove_individual(model_id, individual_id)
– Remove an individualremove_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 unitadd_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 JSONmodel_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:
Exposes noctua-py functionality through MCP tools
Manages client singleton
Provides prompts for common patterns
Testing
The package includes comprehensive tests:
Tests are divided into:
Unit tests (
test_unit.py
): Direct function testing with mocksMCP tests (
test_mcp.py
): Server startup and tool invocation via FastMCP clientLive 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:
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.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables editing and querying of Gene Ontology Causal Activity Models (GO-CAMs) through the Barista API. Supports model creation, individual and fact management, evidence addition, and causal pathway construction for biological knowledge representation.