TypeDB Analysis Knowledge Graph

A demo of using TypeDB 3.x as a structured knowledge graph to track engineering analysis tasks, results, and dependencies. An AI agent (Claude Code) interacts with the database through the TypeDB MCP server, reading and writing state as analyses progress.

What this demonstrates

Instead of tracking analysis plans in spreadsheets or unstructured notes, this project stores them in a typed knowledge graph:

• Design variables with bounds and units (e.g. wing_span: 28–42 m)
• Objectives and constraints that define the optimisation problem
• Analysis tasks with status, priority, and dependency edges
• Results linked back to the tasks that produced them and the objectives/constraints they inform

The schema enforces structure — you can't insert a result without linking it to a task, and cardinality constraints prevent malformed relations. Claude Code queries and mutates this graph via MCP tools during a conversation, treating TypeDB as persistent state across sessions.

Repository structure

.
├── docker-compose.yml          # TypeDB + MCP server
├── .mcp.json                   # MCP server endpoint config
├── schema/
│   └── wing-design-study.tql   # TypeQL schema definition
├── typedb-mcp/                 # TypeDB MCP server (git submodule / clone)
├── CLAUDE.md                   # Agent instructions and TypeQL reference
└── README.md

Prerequisites

• Docker and Docker Compose
• Claude Code CLI (for the AI-agent workflow)

Setup

1. Clone the repo

git clone <repo-url>
cd typedb-project

2. Get the TypeDB MCP server

Clone the MCP server into the typedb-mcp/ directory:

git clone https://github.com/typedb/typedb-mcp.git typedb-mcp

3. Patch the MCP server

The upstream server.py passes timeout_graceful_shutdown=30 to mcp.run(), but this parameter isn't supported by the current FastMCP version and causes a startup crash. Remove it:

cd typedb-mcp
sed -i 's/mcp.run(transport="http", host="0.0.0.0", port=args.port, timeout_graceful_shutdown=30)/mcp.run(transport="http", host="0.0.0.0", port=args.port)/' server.py
cd ..

Or manually edit typedb-mcp/server.py and remove the timeout_graceful_shutdown=30 argument from the mcp.run(...) call at the bottom of the file.

4. Start the services

docker compose up -d

This starts:

• TypeDB on ports 1729 (native) and 8000 (HTTP)
• TypeDB MCP server on port 8001, connected to the TypeDB instance

Data is persisted in a Docker named volume (typedb-data), so it survives container restarts.

Default credentials:

• Username: admin
• Password: password

5. Create the database and load the schema

Open Claude Code in this directory and ask it to set up the database:

claude
> Create a database called 'wing-design-study' and load the schema from schema/wing-design-study.tql

Or use the MCP tools directly — the schema file at schema/wing-design-study.tql contains the full define block.

6. Populate initial data

Ask Claude Code to insert the design problem, variables, objectives, constraints, and analysis tasks. The CLAUDE.md file provides TypeQL syntax examples and domain context that guide the agent.

How it works

The MCP connection

The .mcp.json file configures Claude Code to connect to the TypeDB MCP server:

{
  "mcpServers": {
    "typedb": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

This gives Claude Code tools like mcp__typedb__query, mcp__typedb__database_create, and mcp__typedb__database_schema — it reads and writes TypeDB directly during conversation.

The schema

The schema (schema/wing-design-study.tql) models three layers:

1. Decision problem — design variables, objectives, constraints, and a problem-scope relation that ties them together
2. Analysis plan — tasks with status/priority, task-dependency edges for ordering, and task-evaluates relations linking tasks to the variables/objectives/constraints they assess
3. Results — analysis-result entities with values and confidence, linked via result-link to the producing task and the objectives/constraints they inform

Example workflow

A typical session looks like:

1. Query the plan — "What tasks are planned and what are their dependencies?"
2. Run an analysis — execute the analysis (via external tools or manually)
3. Record results — insert analysis-result entities, update task status to completed
4. Adapt the plan — based on results (e.g. constraint has margin), add new tasks
5. Query again — see the updated dependency graph with results

The knowledge graph acts as a shared, structured scratchpad between the human and the AI agent. The schema prevents drift — every result must reference a task, every task can declare dependencies, and types are validated on insert.

Example queries

Get all tasks and their status:

match
  $t isa analysis-task, has name $n, has status $s, has priority $p;
fetch { "name": $n, "status": $s, "priority": $p };

Get the dependency graph:

match
  $dep isa task-dependency (dependent: $d, dependency: $p);
  $d has name $dn;
  $p has name $pn;
fetch { "task": $dn, "depends_on": $pn };

Get results linked to their tasks:

match
  $rl isa result-link (result: $r, producing-task: $t);
  $r has name $rn, has result-value $v, has unit $u;
  $t has name $tn;
fetch { "result": $rn, "value": $v, "unit": $u, "task": $tn };

Browsing the database with TypeDB Studio

You can inspect the database visually using TypeDB Studio. Connect to your local instance at localhost:8000 with the default credentials (admin / password). Studio lets you browse the schema, run TypeQL queries interactively, and visualize the knowledge graph.

Using the TypeDB Console CLI

As an alternative to the MCP server, you can install the TypeDB Console CLI — a standalone client for managing and querying TypeDB from the command line.

Install (macOS / Linux):

curl -sSL https://typedb.com/install.sh | sh && export PATH="$HOME/.typedb:$PATH"

Or via Homebrew on macOS: brew install typedb/tap/typedb

Connect to the local Docker instance:

typedb console --server=localhost:8000

From the console you can open transactions and run TypeQL directly:

> transaction wing-design-study read
wing-design-study::read> match $t isa analysis-task, has name $n; fetch { "name": $n };
wing-design-study::read> close

The console is useful for ad-hoc debugging, schema inspection, and running queries outside of the Claude Code / MCP workflow. See the TypeDB Console docs for full usage.

Teardown

docker compose down        # stop containers (data persists in volume)
docker compose down -v     # stop containers and delete data