ontoforge

OntoForge

A Neo4j-native ontology studio for designing graph schemas and using them through generic, schema-driven APIs.

Motivation

When building applications that depend on structured domain knowledge — whether it's a research tool, a recommendation system, or an internal knowledge base — the schema behind the data matters as much as the data itself. Without a way to define and enforce that schema, knowledge graphs tend to drift into inconsistency.

OntoForge exists to solve this. It lets you model a global schema (entity types, relation types, property definitions) through a dedicated UI and API, and then interact with instance data through a generic, schema-driven runtime API that validates every write against your schema. You define the rules once; the system enforces them on every operation.

Ontologies are lenses. The schema is global and independent. Ontologies are named views over this schema — either unscoped (full access to all types and properties) or scoped to a filtered subset. This lets different teams or applications work with the same data through focused, domain-specific views without fragmenting the data model.

The intended workflow:

1. Design your schema using the modeling UI or API — define what entity types, relation types, and properties exist in your domain.
2. Create ontologies — define named lenses over the schema, optionally scoping each to specific types and properties.
3. Test your schema by creating instance data through the runtime API and iterating until it fits.
4. Integrate the runtime API into your application's backend — OntoForge becomes the schema-enforced persistence layer for your domain knowledge.
5. Connect AI tools via MCP servers — one for modeling the schema, one for structured read/write access to instance data, giving coding assistants controlled access to your knowledge graph.

The key idea: no unstructured writes. Every entity and relation that goes into the graph must conform to the schema. Read access can be more flexible (e.g., direct Neo4j queries for analytics), but writes are always schema-enforced through the runtime API.

Quick Start (Docker)

Start the full stack — Neo4j, backend, and frontend — with a single command:

cd docker
docker compose up -d --build

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
API docs	http://localhost:8000/docs
Neo4j Browser	http://localhost:17474

Stop everything (data is preserved):

cd docker
docker compose stop

MCP Servers

OntoForge exposes two MCP servers for AI-assisted workflows — one for schema design, one for data access. Both run inside the same backend process.

Modeling Server

Design and iterate on the global schema. Tools for managing entity types, relation types, properties, ontology scopes, validation, and export/import.

Endpoint: http://localhost:8000/mcp/model

The modeling server operates on the global schema — no ontology key required.

Runtime Server

Read and write instance data validated against the schema through an ontology lens. Tools for entity/relation CRUD, semantic search, filtering, and graph exploration.

Endpoint: http://localhost:8000/mcp/runtime/{ontologyKey}

The runtime server requires an ontology key to determine which lens to apply.

Client Configuration

To connect an MCP client (e.g., Claude Code, Cursor), add one or both servers to your MCP configuration. Replace my_ontology with your ontology's key.

URL-based (default)

The ontology key is part of the runtime URL path. Example config at mcp-example.json:

claude --mcp-config mcp-example.json

{
  "mcpServers": {
    "ontoforge-modeling": {
      "type": "http",
      "url": "http://localhost:8000/mcp/model"
    },
    "ontoforge-runtime": {
      "type": "http",
      "url": "http://localhost:8000/mcp/runtime/my_ontology"
    }
  }
}

Header-based

The ontology key is passed via the X-Ontology-Key HTTP header. Useful for orchestration frameworks that manage config via headers. Example config at mcp-example-header.json:

claude --mcp-config mcp-example-header.json

{
  "mcpServers": {
    "ontoforge-modeling": {
      "type": "http",
      "url": "http://localhost:8000/mcp/model"
    },
    "ontoforge-runtime": {
      "type": "http",
      "url": "http://localhost:8000/mcp/runtime",
      "headers": {
        "X-Ontology-Key": "my_ontology"
      }
    }
  }
}

Environment variable

For single-ontology deployments, set DEFAULT_MCP_ONTOLOGY_KEY on the server. Runtime MCP connections without a URL key or header will use this default.

Runtime resolution order: URL path (highest priority) → X-Ontology-Key header → DEFAULT_MCP_ONTOLOGY_KEY env var → 400 error.

Example: Runtime Server Quick Start