# Virtuoso MCP Server

MCP server for Virtuoso Community Edition with guardrailed SPARQL tools and optional domain plugins.

## Current transport

- **FastMCP (SSE)** mounted at `GET /mcp/sse`
- message endpoint provided by FastMCP under `/mcp/messages/`
- **legacy compatibility router** at `POST /rpc` (`{"tool":"...","input":{...}}`)
- health/discovery at `GET /` and `GET /health`

## Why this shape

- mcporter compatibility via FastMCP transport
- stable migration path for existing internal scripts via `/rpc`

## Run

```bash
pip install -r requirements.txt
./run.sh
```

Default host/port: `0.0.0.0:8501`

## Core tools

- Query/navigation: `sparql_query`, `list_graphs`, `search_label`, `get_entities_by_type`, `get_predicates_for_subject`, `get_labels_for_subject`, `traverse_property`
- Ontology discovery: `list_classes`, `list_properties`, `describe_class`, `describe_property`
- Relationship helpers: `describe_subject`, `path_traverse`, `property_usage_statistics`
- Update helpers: `insert_triple`, `batch_insert`, `load_examples`

## Domain plugin tools (garden layer)

Current garden-prefixed set is intentionally trimmed to non-redundant domain helpers:

- `garden_add_seedling`
- `garden_cycle_plants`
- `garden_latest_cycle_by_dates`
- `garden_clone_to`
- `garden_cycle_list_detailed`
- `garden_reassign_cycle`

## Guardrails

- `sparql_query` is SELECT-only
- LIMIT is enforced (`SPARQL_DEFAULT_LIMIT`, clamped by `SPARQL_MAX_LIMIT`)
- fixture loading requires `MCP_ALLOW_EXAMPLE_LOAD=true`

## Environment

Use `.env` (optional). Key variables:

- `VIRTUOSO_ENDPOINT`, `VIRTUOSO_USER`, `VIRTUOSO_PASS`
- `SPARQL_TIMEOUT`, `SPARQL_UPDATE_TIMEOUT`
- `SPARQL_DEFAULT_LIMIT`, `SPARQL_MAX_LIMIT`
- `GRAPH_URI`, `EXAMPLE_GRAPH`
- `MCP_ALLOW_EXAMPLE_LOAD`
- `DOMAIN_LAYERS` (default: `garden_layer.plugin`)

## Tests

```bash
./test.sh
```

(Exercises `/rpc` compatibility flow and validates guardrailed behavior.)