README.md•4.52 kB
# 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](https://github.com/geneontology/noctua-py) library, exposing GO-CAM editing capabilities through a standardized interface.
## Quick Start
Once published:
```bash
uvx noctua-mcp
```
For development:
```bash
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:
```bash
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:
```bash
# 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
```bash
# 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](https://gofastmcp.com).
MCP (Model Context Protocol) standardizes how tools/resources are exposed to
LLMs and agent clients.
Useful links:
- [MCP Specification](https://github.com/modelcontextprotocol/spec)
- [FastMCP Documentation](https://gofastmcp.com/getting-started/welcome)
- [noctua-py Library](https://github.com/geneontology/noctua-py)
## 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](https://github.com/monarch-initiative/monarch-project-copier) template.