ops-graph
Stores the reconciled Ops knowledge graph and powers tools for asset lookup, impact analysis, root-cause candidates, decommissioning, compliance findings, reconciliation reporting, schema inspection, and guarded read-only Cypher queries.
Provides local embeddings for runbook content via nomic-embed-text, enabling GraphRAG search that returns relevant runbook passages alongside live alerts and dependency context.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ops-graph what breaks if we stop db01 tonight?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 didNeo4j 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 stdioBehind 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 |
| "db01.par", "SRV-PAR-DB01", "claims-api" to an entity id |
| everything that stops if an asset stops, with the path that proves it |
| alerting dependencies, most likely cause first |
| servers with no live workload, with reasons; unknown workload is |
| personal data on an unsupported OS or on an unregistered server |
| what reconciliation could not settle, and how every link was made |
| GraphRAG: runbook passages plus the live alerts and dependencies of what they mention |
| counts and direction conventions |
| 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] --> AgentStage 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 |
| same IP address | 1.0 | no |
| same stem, number and site | 0.9 | no |
| site unknown, exactly one server fits | 0.8 | no |
| same site and number, letters 80% similar ("bacth01") | 0.6 | yes |
| several servers fit: one | 0 | yes |
| 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 --> ADependency 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 distanceRoot 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 DESCWhere 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.confidenceDemo script
uv run ops-graph run # day 1Ask why is customer-portal slow?
root_cause_candidatesranksSRV-PAR-DB01first (replication lag, disk at 92%) throughcustomer-portal → claims-api → claims-db, ahead ofclaims-apiwhose errors are an echo.Ask what does the runbook say?
search_docsreturns the db01 replication-lag passage with db01's two live alerts attached.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 reconcileAsk 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:
read transaction: Neo4j itself refuses writes;
denylist:
LOAD CSV,CALL dbms.*,apoc.*,IN TRANSACTIONS, checked after removing comments while keeping string literals (a probe showedLOAD CSVruns inside a read transaction, so layer 1 alone would let the database fetch URLs);5-second transaction timeout;
200-row cap, extra rows never pulled from the server;
server setting: no
LOAD CSVfrom 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 neededIntegration 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 toolscompliance_findingsBRead-onlyIdempotent
Personal data on servers with an unsupported OS or not registered in the CMDB.
Inputs: no named parameters. Returns: object
decommission_candidatesBRead-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_schemaBRead-onlyIdempotent
Node and relationship counts and the direction conventions of the graph.
Inputs: no named parameters. Returns: object
find_assetARead-onlyIdempotent
Find servers, applications or databases by id, name or any hostname spelling (e.g. 'db01.par').
Inputs: name (required). Returns: result
impact_analysisBRead-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_cypherARead-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_reportBRead-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_candidatesARead-onlyIdempotent
Why is this asset failing? Alerting dependencies, most likely root cause first ('deepest' = nothing below it alerts).
Inputs: asset (required). Returns: object
search_docsBRead-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Autonomous and governed SRE & MLOps control plane for AI agent platforms.
Reliability intelligence: production incidents, risk register, controls catalog, knowledge graph.
Deterministic IT asset registry operated by AI agents over MCP. Agents propose, humans approve.
Ontology platform for field service: AI agents observe, connect and act on business objects.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceTransforms 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-
- AlicenseAqualityCmaintenanceEnables AI agents to safely inspect and execute version-controlled operational runbooks with policy checks, dry-run planning, and out-of-band approvals.3MIT
- FlicenseNot gradedqualityDmaintenanceLets 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.-
- AlicenseNot gradedqualityCmaintenanceEnables 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