gogoymh/auto-ontology-mcp
NVIDIA Auto Ontology's semantic layer and a personal knowledge base as an MCP server for Claude, ChatGPT and other MCP clients. No LLM API key needed.
Auto Ontology MCP — A semantic layer your AI assistant builds and queries
One-line summary: Auto Ontology MCP is a tool that gives AI coding assistants (Claude Code, Codex, Cursor, VS Code, etc.) a reliable "semantic layer" over your databases and documents — so when you ask a question in plain English, the assistant doesn't guess at table names or join logic, but works from a reviewed, validated model of your data.
The problem it solves
Text-to-SQL (asking an AI to write database queries from plain English) fails quietly. The query runs, a number comes back, and nothing tells you it's wrong. The README gives concrete examples:
- The model guesses which of
billing_city_idanddelivery_city_id"the customer's state" means - It joins two tables on columns that happen to share integer values but aren't actually related
- It filters on
state_name = 'pennsylvania'when the stored value is'Pennsylvania' - It sums a product price after joining to order lines, inflating the total (a "fan-out" error)
Auto Ontology MCP fixes this by building and maintaining a semantic layer — a reviewed set of business terms, table relationships, and validation rules — that the assistant consults before and while writing SQL.
How it works
Two components work together:
- The model in your MCP client (Claude, Codex, etc.) does the language work: reading schemas, extracting facts from documents, naming concepts, judging answers, writing SQL.
- The server does the deterministic work: schema extraction, data profiling, key inference, validation, storage, and read-only query execution — all in local SQLite files.
This is a deliberate contrast with NVIDIA's original Auto Ontology, which runs its own LLMs behind a Next.js/FastAPI/Postgres stack. This project hands every language step to the model you already have, so there's no model endpoint to host and no API key to configure.
Two main jobs
1. Ask your databases
Point it at a database, and the assistant:
- Builds business Terms (e.g., "Revenue" =
order_lines.line_total) - Reviews joins between tables and records the correct paths
- Answers questions with SQL that the server validates against the ontology and the actual data before running
Validation catches: unknown columns, joins the ontology doesn't know, near-miss literals (like 'pennsylvania' vs 'Pennsylvania'), percent-vs-fraction thresholds, and one-to-many fan-out errors.
2. Keep a personal knowledge base
Share receipts, statements, papers, book notes, or screenshots with your assistant. It reads them and stores:
- Facts as typed records
- Ideas as linked concepts with typed relations (e.g., "causes", "part_of")
- Passages worth finding again in a full-text index
- Sources — every record keeps its origin and the quote behind it
The full originals stay in your Obsidian vault. Later questions get exact numbers, searchable quotes, and links back to the original document.
This is positioned as a drop-in replacement for the "LLM Wiki" pattern (Karpathy's idea of having a model compile sources into markdown pages). Instead of loose pages, you get typed tables you can sum/filter/compare with SQL, concept pages with typed links, and an export_wiki command that writes it all out as an Obsidian vault with [[links]] and graph view.
Key features (from the README)
| Feature | What it does |
|---|---|
| Catalog & profiling | Reads tables/columns/keys, samples rows to record top values, uniqueness, null rates, ranges, date formats, complete value sets of small enums, and text columns that store lists |
| Key inference | Finds undeclared primary/foreign keys by name and confirms by value containment; detects roles (billing_ vs delivery_), self-references, bridge tables |
| Modeling with your model | Hands the model one table at a time with samples and keys; validates and stores the Terms and column mappings it proposes |
| SQL attributes | Mines reusable filters, measures, and join patterns from executed queries; tests each candidate against the database before saving |
| Answerability | Checks whether a question's entities are covered by Terms, attributes, or stored values; verifies how matched tables link (row-to-row, at a shared parent, or not at all) |
| Validation | Catches unknown columns, unknown joins, near-miss literals, list-column equality, percent-vs-fraction mistakes, fan-out errors, and runs a dry run |
| Governance | Draft/certified/deprecated status on Terms; editing a certified definition returns it to draft |
| Knowledge store | Writable store for entities, concepts, passages, and sources with locator/quote on every record |
| Full-text search | FTS5 indexes with bm25 ranking; prefix matching handles Korean particles (기억 → 기억을); returns snippets and [[links]] |
| Concept graph in SQL | Terms, relations, and passages are queryable tables, so one validated query can combine text search, recursive relation walks, and records |
| Originals in Obsidian | Full text of each source stays in your vault; the store keeps summaries and links back to headings |
| Updates in place | Re-scanning keeps Terms, certification, and reviewed joins; changed documents replace their own passages without rebuilding everything |
| Portable | Export/import the whole semantic layer as one YAML or JSON document |
Demo
The README includes a demo (auto-ontology-mcp demo) with a fictional retail store: 11 tables, 3,200 orders, three documents in the knowledge store, and questions that need both. It shows:
- The assistant checking answerability before writing SQL
- Validation catching a wrong join and a wrong literal
- The assistant explaining when a question can't be answered (e.g., "return on ad spend" — the database has sales but no ad spend data)
- Combining structured data (revenue numbers) with unstructured documents (why revenue fell)
- A full-text search + typed-relation walk + passage join in one SQL statement
Getting started
Requires uv.
- Set up the demo:
uvx --from git+https://github.com/gogoymh/auto-ontology-mcp auto-ontology-mcp demo - Connect your client: One-click install for Cursor or VS Code; other clients use a config snippet (the
configcommand prints them with absolute paths).
Safety note
All SQL execution is read-only — the server runs queries against local SQLite files and validates them against the ontology before executing.
License
Apache-2.0. Python 3.12+.
Related
- Project
- Project
- Project
- Project