Neocarta is a Python library and CLI that builds a semantic layer for your data in Neo4j and serves it to agents over a Model Context Protocol (MCP) server. It reads metadata from a data source into a graph and leaves the data itself in place: only schema metadata, glossary terms, metric definitions, and query history cross into Neo4j. It is a Neo4j Labs project rather than a Neo4j product, and is marked experimental.
The graph gives an agent a map of the data landscape — what tables and columns exist, what business terms describe them, how they join through foreign keys, and which database holds them — which the project targets at text-to-query generation, query routing, and data discovery. A worked example ships in the repository: a LangGraph agent wired to the Neocarta MCP server plus a BigQuery query tool searches the graph, follows foreign keys to build a join, and runs the query.
Ingestion is organised as connectors, each pairing an extractor, a transformer that validates against the graph schema with Pydantic, and a Neo4j loader. Connectors cover BigQuery information-schema metadata, BigQuery query logs parsed for table and column usage, GCP Dataplex catalog and business glossary, local query-log JSON files, structured CSV directories, and the Open Semantic Interchange (OSI) YAML format, which is the one bidirectional connector — it both ingests a spec and exports a semantic-model subgraph back to YAML.
Embeddings are optional. Without them the catalog and full-text tools work from schema alone; adding them turns on semantic table and column search. Two embedding connectors are available: one going through LiteLLM for multi-provider routing with auto-detected vector dimensions, and one using the OpenAI SDK directly with an explicit dimension and your own client.
The MCP server probes the target database at startup and registers, per label, the highest-priority retrieval tool whose indexes are present — business-term-bridged hybrid, then hybrid, then vector or full-text alone. Every MCP tool is mirrored in the CLI as neocarta tool with the same arguments, for shell use or agents that do not speak MCP, and neocarta agent-context emits the whole CLI shape as JSON for an agent to read.
Features
- Metadata graph: Database, Schema, Table, Column, and Value nodes joined by HASSCHEMA, HASTABLE, HASCOLUMN, HASVALUE, and REFERENCES foreign-key edges
- Beyond schema: business glossary terms and categories, governed metric definitions with dialect-specific expressions, and query history linked to the tables and columns each query touches
- Connectors: BigQuery schema, BigQuery logs, Dataplex catalog and glossary, query-log JSON, CSV directories, and bidirectional OSI YAML
- Retrieval tools: schema and table listing, plus full-text, vector, and hybrid search over tables, columns, and business terms, each returning columns, types, example values, and foreign-key references
- Optional embeddings: LiteLLM multi-provider or direct OpenAI embedding connectors over node descriptions
- CLI parity: a noun-verb command set that wraps every connector and mirrors every MCP tool, with --json output and an exit-code contract
- Data stays put: only metadata is loaded into Neo4j; queries run against the source database
- Performance extra: an optional neo4j-rust-ext install replaces the driver's Python serialisation layer for faster bulk loads, requiring Python 3.11 or newer
