@oml/mcp

MCP (Model Context Protocol) bridge that exposes the OML server REST interface to AI applications.

Usage

npx @oml/mcp [--workspace <path>] [--url <url>]

Options

| Flag | Short | Description | |------|-------|-------------| | --workspace | -w | Path to the OML workspace directory. Used to locate the server lock file under ~/.oml. Defaults to the current working directory. | | --url | -u | Explicit base URL of the OML server, including protocol and port (e.g. http://127.0.0.1:8080). Takes priority over --workspace when both are provided. |

When neither flag is given, the current working directory is treated as the workspace.

URL Resolution

• If --url is provided, it is used directly.
• Otherwise, the workspace path (from --workspace or cwd) is hashed (SHA-256 of its canonical path) to locate the server lock file at ~/.oml/workspaces/<hash>/server.lock, and the port is read from that file.

Exposed Tools

| Tool | Backend API | Description | |------|-------------|-------------| | oml_workspace | GET /v0/workspace | Return workspace root path | | oml_models | GET /v0/models | List model URIs (paginated) | | oml_ontologies | GET /v0/models + SPARQL | Map ontology IRI to oml:type (paginated) | | oml_members | SPARQL | List ontology members in context (paginated) | | oml_shapes | SPARQL | Find SHACL node shapes for a type (sh:targetClass or sh:class) | | oml_assertions | POST /v0/assertions | Return RDF assertions serialization | | oml_paths | SPARQL SELECT | Return path triples from source to target | | oml_sparql | SPARQL SELECT / ASK / CONSTRUCT / DESCRIBE | Return rows, booleans, or graph triples based on query kind | | oml_imports | SPARQL SELECT | Return owl:imports triples (paginated) | | oml_search | POST /v0/fuzzysearch | Fuzzy member search (paginated) | | oml_update | POST /v0/update | Apply operations and return diagnostics | | oml_preview | POST /v0/update with preview=true | Return workspace edit without persistence | | oml_lint | POST /v0/lint | Lint diagnostics (optional context filter client-side) | | oml_validate | POST /v0/validate | SHACL diagnostics (optional context filter client-side) |

oml_update / oml_preview operation types

Update operations use the same wrapper schema as the REST API: each item has exactly one top-level property named after the operation.

• { createInstance: { descriptionIri, instanceName } }
• { createRelationInstance: { descriptionIri, instanceName } }
• { createInstanceRef: { descriptionIri, instanceIri, typeIri? } }
• { createRelationInstanceRef: { descriptionIri, instanceIri, typeIri? } }
• { addAssertion: { descriptionIri, subjectIri, predicateIri, object } }
• { updateAssertion: { descriptionIri, subjectIri, predicateIri, object } }
• { removeAssertion: { descriptionIri, subjectIri, predicateIri, object? } }
• { addAnnotation: { ontologyIri, subjectIri, predicateIri, object } }
• { updateAnnotation: { ontologyIri, subjectIri, predicateIri, object } }
• { removeAnnotation: { ontologyIri, subjectIri, predicateIri, object? } }
• { deleteMemberCascade: { ontologyIri, memberIri } }
• { deleteMemberRef: { ontologyIri, memberIri, typeIri? } }
• { deleteOntology: { ontologyIri } } (deletes ontology file only; caller must ensure safety)
• { addImport: { importingIri, importedIri } }
• { removeImport: { importingIri, importedIri } }
• { createOntology: { ontologyKind, ontologyNamespace, ontologyPrefix } }

For backward compatibility, MCP still accepts the flat form like { kind: 'createInstance', ... } and normalizes it before calling REST.

Notes:

• referencingUri is a request-level anchor for update placement. For createOntology, pass an existing nearby .oml file URI under the workspace oml/ tree. Do not pass the destination URI you want created.
• createOntology derives the new file path from referencingUri plus ontologyNamespace; it does not accept an explicit output path.
• Prefer addImport after createOntology instead of hand-writing import text. addImport infers the correct extends / includes / uses kind and reuses the imported ontology prefix when possible.
• When creating a new ontology and importing it in the same request, send both operations in one oml_update transaction and keep referencingUri at the top level of the request.