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_id and delivery_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:

  1. 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.
  2. 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.

  1. Set up the demo: uvx --from git+https://github.com/gogoymh/auto-ontology-mcp auto-ontology-mcp demo
  2. Connect your client: One-click install for Cursor or VS Code; other clients use a config snippet (the config command 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