# Virtuoso MCP & Garden Layer design notes

## Observations from `test.sh`
- The test drive beats through the /mcp tools (list_graphs, search_label, get_entities_by_type, ...). Every section assumes the graph contains catalog items, categories, cycles, and a `derivedFrom` relationship for lineage-style traversal.
- The `derivedFrom` traversal, property usage stats, and path helpers expect a small fixture dataset so their queries return bindings rather than empty results.
- Without the fixture, only the synthetic `batch_insert`/`insert_triple` checks succeed; the rest rely on the loaded example graph.

## Immediate plan
1. Fabricate a deterministic fixture in the MCP repo (`virtuoso_mcp/examples/catalog_fixture.ttl`) that models an innocuous domain (catalog items). The model should include:
   - A cycle-like class and a handful of items tied together with generic relationships.
   - Labels, descriptions, and simple lineage properties so `get_entities_by_type`, `search_label`, `traverse_property`, and `path_traverse` have meaningful hits.
2. Keep `garden_layer` tests pointed at the ganja domain data while ensuring MCP tests only load the harmless catalog fixture.
3. Adjust `virtuoso_mcp/test.sh` to load the fixture (via the MCP `load_examples` tool) before running the queries—this ensures the tests no longer depend on an out-of-band dataset and remain legal/harmless.
4. Extend `garden_layer/test_garden_layer.py` to optionally load a domain fixture when `MCP_ALLOW_EXAMPLE_LOAD` is true and to assert the ganja data gives the expected clones, labels, and cycle members.

## Design ambitions & notes for future work
- **Strict separation:** Keep the MCP server as a generic toolset (traverse_property, describe_subject, property_usage_statistics, etc.) and let `garden_layer` orchestrate those atomics into higher-level workflows. No MCP tools should hard-code domain-specific strings; those belong in the domain layer config/tests.
- **Pedigree builder:** Create a sequential helper (e.g., `GardenLayer.pedigree(subject_uri, depth=3, include_siblings=True)`) that uses `traverse_property` + `describe_subject` + `property_usage_statistics` to collect ancestors and the sibling labels/metadata most helpful for downstream agents.
- **Descriptive label resolver:** Add a helper that cycles through `cloneOf` siblings/parents to pick the most descriptive `rdfs:label`/`dc:description` so agents can surface the best wording when summarizing a clone.
- **Tool chaining narrative:** Document the envisioned flow where an agent asks for a clone pedigree, the domain layer calls the atomic MCP tools in sequence, and the agent sees a structured response (list of ancestors, best labels, cycle membership). Keep this description in `virtuoso_mcp/DESIGN_NOTES.md` so we can revisit it when building the next iteration.
- **Test data hygiene:** Any new fixtures should be clearly named/dated and loadable via `MCP_ALLOW_EXAMPLE_LOAD`. That makes the data easy to reset between runs and avoids accidentally shipping sensitive domain data.

## Domain vs test data reminder
- `garden_layer` represents the ganja breeding project; we keep its configuration and helpers pointed at that domain so the real use case remains visible.
- The MCP core and its test fixtures stay generic—roses/fish/wine or other harmless examples—so the reusable tools can be consumed without dragging domain-specific terminology into every test run.

## Next concrete steps
- Design the catalog fixture TTL (classes, relationships, labels).
- Create loader automation: a short script or `test.sh` snippet that invokes `/mcp` → `load_examples` when `MCP_ALLOW_EXAMPLE_LOAD=true` before other tests run.
- Expand `GardenLayer` with the pedigree/descriptive helpers and add matching domain-layer tools so OpenClaw agents can call them.
- Keep this file updated with outcomes so we have a historical log of why we structured things this way.