# vmikhailov/cypher-mcp architecture

> Architecture diagram of the GitHub repository vmikhailov/cypher-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vmikhailov/cypher-mcp
- Repository: https://github.com/vmikhailov/cypher-mcp

## Overview

Cypher MCP is an embedded SQLite knowledge-graph server and standalone CLI for AI agents and developers. The main workflow is an agent sending OpenCypher or graph-tool requests over MCP, followed by query execution against the local graph and structured results; users can also manage the graph with the CLI. The product additionally supports graph mutations, schema governance, full-text search, and vector-based entity resolution. The README documents the main product capabilities; some internal package relationships are omitted where the excerpts do not show their callers.

Main entry points: [`internal/storage/storage.go`](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/storage/storage.go) (SQLite Store), [`internal/transport/execute.go`](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/transport/execute.go) (Tool Executor), [`cmd/cypher-mcp/main.go`](https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/main.go) (MCP Server), [`internal/graph/mutate.go`](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/mutate.go) (Graph Mutations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_mcp["MCP Server<br/>[main.go]"]
  node_cli["Standalone CLI<br/>[cli.go]"]
  node_tool_specs["Tool Definitions<br/>[specs.go]"]
  node_tool_executor["Tool Executor<br/>[execute.go]"]
end

subgraph group_graph["Graph Operations"]
  node_cypher_query["Cypher Queries<br/>[query.go]"]
  node_graph_mutations["Graph Mutations<br/>[mutate.go]"]
  node_schema_governance["Schema Governance<br/>[schema.go]"]
  node_graph_validation["Graph Validation<br/>[validate.go]"]
  node_full_text_search["Full-Text Search<br/>[search.go]"]
  node_graph_models["Graph Models<br/>[models.go]"]
end

subgraph group_persistence["Persistence"]
  node_sqlite_store[("SQLite Store<br/>[storage.go]")]
end

subgraph group_extensions["Entity Resolution"]
  node_vector_resolution["Vector Resolution<br/>[vector.go]"]
  node_vector_cli["Vector Tool Handlers<br/>[vector.go]"]
  node_metaqa_indexer["MetaQA Indexer<br/>[index_metaqa.py]"]
end

node_agent(("AI Agent"))

node_agent -->|"sends MCP requests"| node_mcp
node_mcp -->|"dispatches CLI mode"| node_cli
node_mcp -->|"uses embedded SQLite"| node_sqlite_store
node_tool_specs -.->|"defines tools"| node_tool_executor
node_tool_executor -->|"executes queries"| node_cypher_query
node_tool_executor -->|"resolves entities"| node_vector_resolution
node_tool_executor -->|"upserts graph"| node_graph_mutations
node_cypher_query -->|"queries SQLite"| node_sqlite_store
node_graph_mutations -->|"validates changes"| node_graph_validation
node_graph_mutations -->|"checks schema"| node_schema_governance
node_full_text_search -->|"searches index"| node_sqlite_store
node_vector_resolution -->|"reads embeddings"| node_sqlite_store
node_vector_cli -.->|"handles vector tools"| node_vector_resolution
node_metaqa_indexer -.->|"builds graph database"| node_sqlite_store

click node_mcp "https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/main.go"
click node_cli "https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/cli.go"
click node_tool_specs "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/transport/specs.go"
click node_tool_executor "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/transport/execute.go"
click node_cypher_query "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/query.go"
click node_graph_mutations "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/mutate.go"
click node_schema_governance "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/schema.go"
click node_graph_validation "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/validate.go"
click node_full_text_search "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/search.go"
click node_graph_models "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/models.go"
click node_sqlite_store "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/storage/storage.go"
click node_vector_resolution "https://github.com/vmikhailov/cypher-mcp/blob/main/internal/vector/vector.go"
click node_vector_cli "https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/vector.go"
click node_metaqa_indexer "https://github.com/vmikhailov/cypher-mcp/blob/main/scripts/index_metaqa.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_cli,node_tool_specs,node_tool_executor toneBlue
class node_cypher_query,node_graph_mutations,node_schema_governance,node_graph_validation,node_full_text_search,node_graph_models toneAmber
class node_sqlite_store toneMint
class node_vector_resolution,node_vector_cli,node_metaqa_indexer toneRose
class node_agent toneIndigo
```

## Components

### User Interfaces

- [MCP Server](https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/main.go): `cmd/cypher-mcp/main.go`
- [Standalone CLI](https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/cli.go): `cmd/cypher-mcp/cli.go`
- [Tool Definitions](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/transport/specs.go): `internal/transport/specs.go`
- [Tool Executor](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/transport/execute.go): `internal/transport/execute.go`

### Graph Operations

- [Cypher Queries](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/query.go): `internal/graph/query.go`
- [Graph Mutations](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/mutate.go): `internal/graph/mutate.go`
- [Schema Governance](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/schema.go): `internal/graph/schema.go`
- [Graph Validation](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/validate.go): `internal/graph/validate.go`
- [Full-Text Search](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/search.go): `internal/graph/search.go`
- [Graph Models](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/graph/models.go): `internal/graph/models.go`

### Persistence

- [SQLite Store](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/storage/storage.go): `internal/storage/storage.go`

### Entity Resolution

- [Vector Resolution](https://github.com/vmikhailov/cypher-mcp/blob/main/internal/vector/vector.go): `internal/vector/vector.go`
- [Vector Tool Handlers](https://github.com/vmikhailov/cypher-mcp/blob/main/cmd/cypher-mcp/vector.go): `cmd/cypher-mcp/vector.go`
- [MetaQA Indexer](https://github.com/vmikhailov/cypher-mcp/blob/main/scripts/index_metaqa.py): `scripts/index_metaqa.py`

### Other components

- **AI Agent**

## Connections

- AI Agent → MCP Server: sends MCP requests (evidence: `README.md`)
- MCP Server → Standalone CLI: dispatches CLI mode (evidence: `cmd/cypher-mcp/main.go`)
- MCP Server → SQLite Store: uses embedded SQLite (evidence: `README.md`)
- Tool Definitions → Tool Executor: defines tools
- Tool Executor → Cypher Queries: executes queries (evidence: `internal/transport/execute.go`)
- Tool Executor → Vector Resolution: resolves entities (evidence: `internal/transport/execute.go`)
- Tool Executor → Graph Mutations: upserts graph (evidence: `internal/transport/execute.go`)
- Cypher Queries → SQLite Store: queries SQLite (evidence: `internal/graph/query.go`)
- Graph Mutations → Graph Validation: validates changes (evidence: `internal/graph/mutate.go`)
- Graph Mutations → Schema Governance: checks schema (evidence: `internal/graph/mutate.go`)
- Full-Text Search → SQLite Store: searches index (evidence: `internal/graph/search.go`)
- Vector Resolution → SQLite Store: reads embeddings (evidence: `internal/vector/vector.go`)
- Vector Tool Handlers → Vector Resolution: handles vector tools
- MetaQA Indexer → SQLite Store: builds graph database
