Skip to main content
Glama

ops-graph

An Ops knowledge graph for AI agents. Three inventory sources that disagree with each other (a CMDB export, a monitoring export, a hand-edited service catalog) are ingested into Neo4j, reconciled into one graph with full provenance, and exposed to an agent through an MCP server: impact analysis, root cause, decommissioning, compliance, and GraphRAG over runbooks with a local embedding model.

All data is fictional ("Acme Mutual", a made-up insurer). It is small on purpose and seeded with the problems real inventories have: the same server spelled four ways, a typo, an ambiguous host name, a server nobody registered, a retired server that is still running.

Quick start

docker compose up -d                  # Neo4j + one-shot loader: ingest, reconcile, embed
docker compose logs loader            # what the loader did

Neo4j Browser: http://localhost:7474 (user neo4j, password ops-graph-demo, change it in .env). Runbook embedding needs Ollama on the host with ollama pull nomic-embed-text; without it the loader skips that step and every graph tool still works.

Without Docker for the Python side (Python 3.11 and uv):

docker compose up -d neo4j
uv run ops-graph run                  # ingest + reconcile + embed
uv run ops-graph serve                # MCP server on stdio

Behind a TLS-intercepting proxy or antivirus, the container cannot download packages (invalid peer certificate: UnknownIssuer); use the uv run path, or add your proxy's root certificate to the image.

Related MCP server: safe-runbook-mcp

Use it from an agent

.mcp.json declares the server for Claude Code and other MCP clients. Open the project, accept the ops-graph server, and ask:

  • Why is customer-portal slow?

  • What breaks if we stop db01 tonight?

  • Which servers can we decommission?

  • Where do we keep personal data on unsupported systems?

  • What does the runbook say about replication lag, and is it happening now?

Tool

Answers

find_asset

"db01.par", "SRV-PAR-DB01", "claims-api" to an entity id

impact_analysis

everything that stops if an asset stops, with the path that proves it

root_cause_candidates

alerting dependencies, most likely cause first

decommission_candidates

servers with no live workload, with reasons; unknown workload is blocked, never a candidate

compliance_findings

personal data on an unsupported OS or on an unregistered server

reconciliation_report

what reconciliation could not settle, and how every link was made

search_docs

GraphRAG: runbook passages plus the live alerts and dependencies of what they mention

describe_schema

counts and direction conventions

read_only_cypher

anything else, read-only and guarded (see below)

Every tool is declared read-only. Names are resolved for the agent; an ambiguous name ("app01" exists in Paris and Lyon) is refused with the candidates, so the agent asks instead of guessing. Answers carry confidence, needs_review and uncertain flags from reconciliation, so a deduction is never presented as a fact.

How it works

flowchart LR
  subgraph sources
    A[cmdb.csv]
    B[monitoring.json]
    C[services.yaml]
    D[runbooks/*.md]
  end
  A & B & C -->|ops-graph ingest<br/>one transaction per source| R[(SourceRecord<br/>raw layer)]
  R -->|ops-graph reconcile<br/>rules in Python, one transaction| G[(canonical graph<br/>Server, Application,<br/>Database, Team, Alert)]
  D -->|ops-graph embed<br/>Ollama nomic-embed-text| K[(Chunk + vector index)]
  K -->|MENTIONS| G
  G & K --> M[MCP server] --> Agent

Stage 1, ingest. Each source row becomes a SourceRecord node holding the raw row, a content hash and its batch id. One source is one transaction: records missing from the new batch are marked stale, and if anything fails the whole batch rolls back, so a half-read file can never make servers disappear.

Stage 2, reconcile. Live records are read back from Neo4j, matched in plain Python (reconcile.build_plan, unit-tested without a database), and the derived graph is replaced in one transaction. Because it reads the graph, not the files, reconciliation can be replayed alone after a rule change. Order matters: CMDB servers first (the CI id is the master identity), then monitoring hosts (an unknown host becomes a shadow server UNREG-<site>/<host>), then catalog services, placed on CMDB and shadow servers alike.

Matching rules

Every host spelling goes through one grammar (normalize.py): SRV-PAR-APP02, app-02.par.acme.local and srv-par-app02 all become (app, 2, par). Rules are tried from strongest to weakest evidence; the first rule with exactly one candidate wins, and a rule with several candidates stops and reports an ambiguity.

Rule

Evidence

Confidence

Review

ip_exact

same IP address

1.0

no

name_site

same stem, number and site

0.9

no

name_unique

site unknown, exactly one server fits

0.8

no

fuzzy_stem

same site and number, letters 80% similar ("bacth01")

0.6

yes

ambiguous

several servers fit: one MAYBE_RUNS_ON edge per candidate

0

yes

unresolved

nothing fits: reported

0

yes

The fuzzy rule never compares numbers: "web01" and "web11" are 89% similar as strings and are different machines. Confidences are ordinal levels, not calibrated probabilities.

Graph model

graph LR
  T[Team] -- OWNS --> A[Application]
  A -- DEPENDS_ON --> A2[Application]
  A -- DEPENDS_ON --> D[Database]
  A -- "RUNS_ON {rule, confidence}" --> S[Server]
  A -. MAYBE_RUNS_ON .-> S
  D -- "HOSTED_ON {rule, confidence}" --> S
  AL[Alert] -- RAISED_ON --> S
  AL -- RAISED_ON --> A
  SR[SourceRecord] -- "DESCRIBES {rule, confidence}" --> S
  SR -- HAS_ISSUE --> I[Issue]
  DOC[Document] -- HAS_CHUNK --> C[Chunk]
  C -- MENTIONS --> S
  C -- MENTIONS --> A

Dependency edges always point from the thing that needs to the thing it needs. Impact and root cause are then the same traversal read in opposite directions. Details in docs/model.md.

Example Cypher

What stops if db01 stops, and through which path:

MATCH (target:Server {host_key: 'par/db01'})
MATCH p = (impacted:Asset)-[:DEPENDS_ON|RUNS_ON|HOSTED_ON|MAYBE_RUNS_ON*1..6]->(target)
RETURN impacted.name, min(length(p)) AS distance
ORDER BY distance

Root cause: alerting things below customer-portal, deepest first (nothing below them alerts):

MATCH p = (:Application {name: 'customer-portal'})-[:DEPENDS_ON|RUNS_ON|HOSTED_ON*0..6]->(suspect)
WHERE EXISTS { (:Alert)-[:RAISED_ON]->(suspect) }
WITH suspect, min(length(p)) AS distance
RETURN suspect.name, distance,
       NOT EXISTS {
         MATCH (suspect)-[:DEPENDS_ON|RUNS_ON|HOSTED_ON*1..6]->(deeper)
         WHERE EXISTS { (:Alert)-[:RAISED_ON]->(deeper) }
       } AS deepest
ORDER BY deepest DESC, distance DESC

Where does this server come from, and which rule linked each source:

MATCH (r:SourceRecord)-[d:DESCRIBES]->(s:Server {id: 'CI00202'})
RETURN r.source, r.source_key, d.rule, d.confidence

Demo script

uv run ops-graph run                          # day 1
  1. Ask why is customer-portal slow? root_cause_candidates ranks SRV-PAR-DB01 first (replication lag, disk at 92%) through customer-portal → claims-api → claims-db, ahead of claims-api whose errors are an echo.

  2. Ask what does the runbook say? search_docs returns the db01 replication-lag passage with db01's two live alerts attached.

  3. Ask what is wrong in our inventory? reconciliation_report: mq01 is not in the CMDB, fraud-scoring's host "app01" is ambiguous, billing-batch was matched on a typo.

uv run ops-graph ingest --data data/day2      # day 2: the CMDB registers mq01
uv run ops-graph reconcile
  1. Ask what depends on mq01? The answer now lands on the CMDB id CI00801, the shadow node is gone, its alert and the runbook that mentions it followed.

This scenario is also the end-to-end test (tests/test_e2e_mcp.py), run through an MCP client.

Free Cypher, guarded

An agent that writes its own Cypher reads untrusted text (alert messages, documents), so read_only_cypher stacks five layers, each with a test:

  1. read transaction: Neo4j itself refuses writes;

  2. denylist: LOAD CSV, CALL dbms.*, apoc.*, IN TRANSACTIONS, checked after removing comments while keeping string literals (a probe showed LOAD CSV runs inside a read transaction, so layer 1 alone would let the database fetch URLs);

  3. 5-second transaction timeout;

  4. 200-row cap, extra rows never pulled from the server;

  5. server setting: no LOAD CSV from local files.

A denylist is not a security boundary on its own; Neo4j Community has no role-based access control. With Enterprise, the agent would get a read-only database user.

Tests

docker compose --profile test up -d neo4j-test   # throwaway database on port 7688
uv run pytest                                    # unit + integration
uv run pytest -m "not integration"               # no database needed

Integration tests never touch the demo database. GraphRAG tests use a deterministic bag-of-words embedder (HashingEmbedder), so they run without Ollama; one test checks the real model when it is installed.

Scope and limits

  • Built as a demonstration in a few days, at a scale of tens of entities. Full rebuild of the derived graph per reconciliation is simple and always correct here; at a large scale it would become a per-source incremental rebuild.

  • Matching is deterministic on purpose: reproducible, testable, auditable. An LLM would fit as an arbiter of the review queue, not as the first matcher.

  • Root-cause ranking is an explainable heuristic, not causal inference.

  • Stack: Neo4j 5.26 Community, Python 3.11, official MCP Python SDK 2.x (MCPServer, formerly FastMCP), neo4j-graphrag, Ollama, rapidfuzz.

License

MIT, see LICENSE.

Available Tools

9 tools
compliance_findingsB
Read-onlyIdempotent

Personal data on servers with an unsupported OS or not registered in the CMDB.

Inputs: no named parameters. Returns: object

decommission_candidatesB
Read-onlyIdempotent

Servers with no live workload, with reasons. Servers whose workload is unknown are listed as 'blocked', never as candidates.

Inputs: stale_days. Returns: object

describe_schemaB
Read-onlyIdempotent

Node and relationship counts and the direction conventions of the graph.

Inputs: no named parameters. Returns: object

find_assetA
Read-onlyIdempotent

Find servers, applications or databases by id, name or any hostname spelling (e.g. 'db01.par').

Inputs: name (required). Returns: result

impact_analysisB
Read-onlyIdempotent

What stops working if this asset stops? Returns every impacted asset with the dependency path that proves it.

Inputs: asset (required), max_depth. Returns: object

read_only_cypherA
Read-onlyIdempotent

Run your own read-only Cypher. Refuses writes, LOAD CSV and dbms/apoc procedures; 5 s timeout; at most 200 rows.

Inputs: query (required), params. Returns: object

reconciliation_reportB
Read-onlyIdempotent

Data quality: records reconciliation could not settle, links to review, and how many links each rule made.

Inputs: no named parameters. Returns: object

root_cause_candidatesA
Read-onlyIdempotent

Why is this asset failing? Alerting dependencies, most likely root cause first ('deepest' = nothing below it alerts).

Inputs: asset (required). Returns: object

search_docsB
Read-onlyIdempotent

Search the runbooks and postmortems (GraphRAG): best passages plus the live state of the assets they mention.

Inputs: question (required), k. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools map to distinct analytical questions: impact_analysis, root_cause_candidates, decommission_candidates, compliance_findings, and reconciliation_report each target a different report type. The main overlap is directionality between impact_analysis (downstream) and root_cause_candidates (upstream), but their descriptions explicitly clarify the direction. read_only_cypher is a deliberate catch-all escape hatch rather than a duplicate.

    Naming Consistency3/5

    There is a mix of conventions: verb_noun tools (find_asset, describe_schema, search_docs), noun_phrase report tools (impact_analysis, compliance_findings, reconciliation_report), and a bare descriptor (read_only_cypher). Each name is readable and self-explanatory, but no single predictable pattern governs the set.

    Tool Count5/5

    Nine tools is well within the sweet spot and each tool earns its place, covering a distinct analysis or lookup capability. No redundant or filler tools are present.

    Completeness4/5

    The read-only ops-graph surface covers dependency impact, root cause, decommission, compliance, data-quality reconciliation, schema introspection, doc search, asset lookup, and a query escape hatch — a solid lifecycle for read-only analysis. Minor gaps like a dedicated full-asset-detail/property listing exist, but find_asset plus read_only_cypher let agents work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Transforms code repositories and development documentation into a queryable Neo4j knowledge graph, enabling AI assistants to perform intelligent code analysis, dependency mapping, impact assessment, and automated documentation generation across 15+ programming languages.
      7
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Lets AI agents query a computerized system inventory as a knowledge graph using Cypher, enabling blast radius, data lineage, regulation checks, and change impact assessments while preventing hallucinated regulatory claims.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to trace upstream dependencies and downstream blast radius across a Neo4j-modeled service topology, rank root-cause hypotheses, and score composite risk from graph, temporal, git-diff, and trace signals. It also stages rollback-ready remediation plans that execute only after human approval and the required scope.
      Apache 2.0