Skip to main content
Glama
SynkVault Ontology MCP

SynkVault Ontology MCP

Official
README.md
# @synkvault/ontology-mcp

An MCP server and a bundled skill for designing a SynkVault ontology with an AI assistant. You
describe a domain; the assistant writes an ontology document to a local file, checks it, shows
you exactly what an import would change, and applies it only after you confirm. It talks to the
SynkVault partners API. It also lets the assistant answer questions from the organisation's
knowledge base, read-only, using the knowledge routes of the same API.

This package has not been verified against a live SynkVault deployment. Treat it as pre-release
and try it on a disposable organisation first.

## Requirements

- Node.js 20 or newer.
- An MCP host that can launch a stdio server (for example Claude Code).
- The partners API origin for your SynkVault environment, an API key, and the id of the
  organisation. The key's owner must be an organisation admin or owner; otherwise the API refuses
  the calls with a 403.
- The classifier route must be deployed on your environment for `ontology_classifier` to work. A
  404 from it is reported as an error, never as "no classifier".

## Setup

1. Copy `examples/mcp.json` to a local `.mcp.json` in your project, and make sure `.mcp.json` is
   git-ignored.
2. Set the three environment values in it:
   - `SYNKVAULT_PARTNERS_BASE_URL`: the API origin only, no path. `https` is required except for a
     loopback host.
   - `SYNKVAULT_API_KEY`: your API key.
   - `SYNKVAULT_ORG_ID`: the organisation id (a uuid).
3. Start your MCP host. The server runs with `npx -y @synkvault/ontology-mcp`. Alternatively run
   `npm install -g @synkvault/ontology-mcp`, then `ontology-mcp`. If any of the three
   values is missing or invalid it exits with status 1 and names the key.

Never commit a key. Never put one in a shared or checked-in config.

Source: https://github.com/cyberneticlabs/synkvault-ontology-mcp

### Tool timeout

A large import can take a while. Raise your MCP host's tool timeout above 300 seconds so a slow
import is not cut off on the host side while the server is still working.

## Installing the skill

The skill teaches the assistant how to model and how to drive the tools. Copy it into a skills
directory your host reads:

```bash
npx @synkvault/ontology-mcp install-skill <dir>
```

This creates `<dir>/ontology-architect`. Pass `--force` to overwrite an existing copy.

## Tools

| Tool | What it does |
|---|---|
| `ontology_export` | Writes the live ontology to a local file. Refuses to overwrite unless asked. |
| `ontology_validate` | Checks a document file and returns itemised errors and warnings. |
| `ontology_preview_import` | A dry run. Returns a `preview_id` and what would be added, changed and kept. |
| `ontology_apply_import` | The real import. Needs the `preview_id`, `confirmed: true` and `acknowledged_moves`. |
| `ontology_classifier` | Reads the configured classifier entry path, depth and category limit. |
| `knowledge_list_records` | Read-only. Lists knowledge-base records of one node type, optionally within a time window or by a text `search` on name, description and label. |
| `knowledge_schema` | Read-only. Lists node types with their properties and record counts. |
| `knowledge_search` | Read-only. Searches records of one node type by property conditions, with optional aggregations and sort. |
| `knowledge_get_record` | Read-only. Gets one record by id, with related records when asked. |

Every file path must be absolute. A relative path is refused.

## The flow

1. Export the live ontology to a scratch file.
2. Author or edit the document file.
3. Validate it.
4. Preview the import. The preview lists what would be added, changed, moved and kept, and any
   warnings.
5. Read the preview and say yes or no. Applying needs the preview's id, an explicit
   confirmation, and an acknowledgement of every node the preview says would move.

A preview id is single-use and bound to the exact file contents. If the file changes, or the live
ontology changes after the preview, apply refuses and you preview again.

## Behaviours to know

- Import never removes anything. It is an additive merge: stated values win, and anything the
  document omits stays.
- A rename adds the new name and keeps the old one. Documents stay on the old name. Renaming a
  node that has children moves the children to the new node and leaves the old one childless.
- A delete keeps the item. Clearing a property's key leaves the property in place. The preview
  says so, and the assistant must never report something as deleted.
- There is no reset. Starting "from scratch" on an organisation that already has content is still
  a merge.
- A node that appears in both the document and the live ontology under a different parent is a
  move. Moves need an explicit acknowledgement before apply.
- Fields omitted on an entity you do state are reset to their defaults, not kept. Always send a
  full document.
- Draft mode: when the organisation has draft mode on and already has documents, an import opens
  a draft instead of changing the live ontology. A draft that changes a static reference cannot
  be submitted for approval and blocks further imports until an organisation admin or owner
  abandons it in the web app; the preview warns about this.
- The classifier route must be deployed. Structural changes can alter which nodes are
  classification targets; the preview notes this conditionally because it does not call the classifier.
- If an apply returns an unknown outcome (a timeout, a server error), the write may have
  happened. Export the ontology and compare before doing anything else.

## API compatibility

This package follows semantic versioning. The skill is pinned inside the package: a given version
always installs the same skill text. Each release states the partners ontology API it targets in
`CHANGELOG.md`; 0.1.0 targets the export, validate, import and classifier routes, the ontology listing route (`GET /api/v1/ontology`) and the knowledge list, search and record routes as of this release.

The server's validation is the authority. The package does no local schema validation: it only
checks that a file parses as JSON. What an import adds, changes and moves comes from the server's
dry run (the `changes` list of the import response), and the move acknowledgement at apply is
checked against it. Only what the document omits (`kept_absent`) and the classifier flags are
worked out locally, from the live export, for display. A server whose import response has no
`changes` list is too old for this client: preview refuses with an error. There is no version negotiation, so a client that is out of date with the API
surfaces the server's errors as they are.

## License

MIT. See `LICENSE`.