auto-ontology-mcp

Auto Ontology MCP (auto-ontology-mcp) brings NVIDIA Auto Ontology's semantic layer to any MCP client, for two jobs:

• Ask your databases. Point it at a database, and the model you already use (Claude Code, Codex, OpenClaw, Hermes Agent, Cursor, VS Code, or the Claude and ChatGPT apps) builds business Terms, reviews joins and answers questions with SQL that the server checks against the ontology and the data.
• Keep a personal knowledge base. Share receipts, statements, papers, book notes or screenshots with your assistant; it reads them and stores the facts as records, the ideas as linked concepts, the passages worth finding again in a full-text index, and where each came from. The full originals stay in your Obsidian vault. Later questions get exact numbers, searchable quotes and links back to the original.

[!TIP] Use it in place of an LLM Wiki. In Karpathy's LLM Wiki pattern the model compiles your sources into markdown pages that you read in Obsidian. Auto Ontology MCP runs the same loop (ingest, query, lint, with an index and a log) on an ontology instead of loose pages: facts go into typed tables you can sum, filter and compare with SQL, ideas become concept pages with typed links, every record, page and link keeps its source and the quote behind it, and export_wiki writes it all out as an Obsidian vault with aliases, [[links]] and the graph view. How the two map

Auto Ontology runs its own LLMs (NVIDIA NIM) behind a Next.js, FastAPI and Postgres stack. This project hands every language step (reading, extracting, naming, judging, writing SQL) to the model in your MCP client, so there is no model endpoint to host and no API key to configure. The server keeps the deterministic work: schema extraction, profiling, key inference, validation, storage and read-only execution, in local SQLite files.

Why

Text-to-SQL fails quietly. The query runs, a number comes back, and nothing says it is wrong.

See it in action

auto-ontology-mcp demo sets up three demos about one fictional store: a synthetic retail database (11 tables, 3,200 orders), three of the store's documents in the knowledge store (a meeting note, a tag guide and a quality digest, with their originals in the Obsidian vault), and questions that need both. Tool output below is abridged from real runs of the test fixtures (tests/test_demo.py); the model's replies are illustrative.

1. Structured data: the retail database

A question asked after the model modeled the tables and reviewed the joins. In that review it made customers.delivery_city_id the default city role, so states below are delivery states. A fresh scan makes billing_city_id the default instead: neither column name is the unqualified city_id, and Auto Ontology's fallback then picks the alphabetically first role. set_relationship(..., is_default=true) changes it, and get_query_context names the other role in its role notes either way.

You     What was revenue for the sushi roll flash drive in Pennsylvania in June 2024?

Model   → check_answerable(entities=["revenue", "sushi roll flash drive", "Pennsylvania"])
          verdict: answerable
          revenue                  covered           Order Line › Revenue (order_lines.line_total)
          sushi roll flash drive   covered_by_value  products.product_name = 'USB Food Flash Drive - Sushi Roll'
          Pennsylvania             covered_by_value  states.state_name = 'Pennsylvania'

        → get_query_context(terms=["Order Line", "Product", "State", "Order"])
          join path: order_lines → products
                     order_lines → orders → customers → cities → states
          role note: customers.delivery_city_id = cities.city_id is the default;
                     other roles: customers.billing_city_id (billing)

        → validate_sql(first draft)
          ✗ Join customers.customer_id = orders.order_id is not how the ontology joins these
            tables (orders.customer_id = customers.customer_id).
          ! No row has states.state_name = 'pennsylvania'. Close real values: 'Pennsylvania'.

        → run_sql(fixed query)
          revenue 316.8, order_lines 4
          draft Terms used: City, Customer, Order, Order Line, Product, State

Model   Revenue was 316.80 from 4 order lines (delivery state Pennsylvania, June 2024).
        The Terms behind this answer are still drafts, so treat the definition as unreviewed.
        [SQL shown]

And a question the data cannot answer:

You     What was return on ad spend for the sushi roll flash drive?

Model   → check_answerable(...)
          verdict: partially_answerable   coverage: 0.33
          not covered: "return on ad spend", "ad spend"

Model   This database has sales but no advertising spend, so I can't compute ROAS.
        I can give you revenue for that product instead.

2. Unstructured data: the store's documents

The demo stores the three documents the way a model would after reading them: each full text as an original note in the vault, the passages worth finding again, the concepts and causal links they describe, and the action items they decide.

You     [Merchandising tag guide] Remember this.

Model   → save_passages(source={title: "Merchandising tag guide", kind: "wiki", original_text: "# Merchandising tag guide …"},
              passages=[{heading: "bestseller", text: "A product the buyers want to feature …", terms: ["Bestseller Tag"]}, …])
          original kept in the vault: originals/Merchandising tag guide.md
        → save_concept("Bestseller Tag", relations=[is_a Merchandising Tag], source=2, locator="bestseller")

You     What does the bestseller tag mean?

Model   → search_text("bestseller")
          term     Bestseller Tag                          [Bestseller] Tag
          passage  Merchandising tag guide › bestseller    "A product the buyers want to feature on the home page.
                                                            It is a placement decision and does not mean the
                                                            product sells the most units."
                   link: [[originals/Merchandising tag guide#bestseller]]

Model   Buyers pick it for home-page placement; it is not a sales ranking
        ([[originals/Merchandising tag guide#bestseller]]).

You     What led to the Midwest sales decline?

Model   → run_sql(datasource="knowledge", sql="WITH RECURSIVE chain AS (… FROM term_relations r JOIN chain
              ON r.to_term_id = chain.id WHERE r.relation IN ('causes', 'part_of')) …")
          Fewer Repeat Orders   part_of   1
          Delivery Delay        causes    2
          September Stockout    causes    2
          Fulfilment Cutover    causes    3

You     Which product problems sent products back?

Model   → run_sql(datasource="knowledge", sql="SELECT t.name, p.heading, snippet(passages_fts, …)
              FROM passages_fts JOIN passages p … JOIN passage_terms … JOIN terms t … JOIN term_relations r …
              WHERE passages_fts MATCH '"returns"* OR "back"' AND r.relation = 'instance_of'
              AND r.to_term = 'Product Quality Issue' ORDER BY bm25(passages_fts)")
          Wobbling Chair Base    Office Chair                  …Several chairs came [back] before support …
          Ear Cushion Cracking   Noise Cancelling Headphones   …the product customers sent [back] most often.

The last query is a full-text search, a