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 — 一个由 AI 助手构建并查询的语义层
一句话总结: Auto Ontology MCP 是一个为 AI 编码助手(Claude Code, Codex, Cursor, VS Code 等)提供可靠“语义层”的工具,覆盖您的数据库和文档。这样当您用简单的英语提问时,助手不会猜测表名或连接逻辑,而是基于经过审查和验证的数据模型进行工作。
它解决的问题
Text-to-SQL(让 AI 根据简单英语编写数据库查询)往往会静默失败。查询运行了,返回了一个数字,但没有任何提示告诉你它是错的。README 中给出了具体示例:
- 模型猜测
billing_city_id和delivery_city_id中哪一个是“客户所在州” - 它在恰好共享整数值但实际上并无关联的列上连接了两个表
- 当存储的值为
'Pennsylvania'时,它在state_name = 'pennsylvania'上进行过滤 - 它在连接到订单行后对产品价格求和,导致总数膨胀(“扇出”错误)
Auto Ontology MCP 通过构建和维护一个语义层(一套经过审查的业务术语、表关系和验证规则)来解决这个问题,助手在编写 SQL 之前和期间会参考该层。
工作原理
两个组件协同工作:
- MCP 客户端中的模型(Claude, Codex 等)负责语言工作:读取模式、从文档中提取事实、命名概念、判断答案、编写 SQL。
- 服务器负责确定性工作:模式提取、数据分析、键推断、验证、存储和只读查询执行——所有这些都在本地 SQLite 文件中完成。
这与 NVIDIA 原版的 Auto Ontology 形成了鲜明对比,后者在 Next.js/FastAPI/Postgres 堆栈后运行自己的 LLM。本项目将每个语言步骤交给您现有的模型,因此无需托管模型端点,也无需配置 API 密钥。
两大主要功能
1. 查询您的数据库
指向一个数据库,助手会:
- 构建业务术语(例如,“收入” =
order_lines.line_total) - 审查表之间的连接并记录正确的路径
- 使用 SQL 回答问题,服务器会在运行前根据本体和实际数据对 SQL 进行验证
验证可以捕获:未知列、本体不知道的连接、近似匹配的字面量(如 'pennsylvania' 与 'Pennsylvania')、百分比与分数阈值,以及一对多扇出错误。
2. 维护个人知识库
与您的助手共享收据、报表、论文、读书笔记或截图。它会读取并存储:
- 事实作为类型化记录
- 想法作为带有类型关系(例如,“导致”、“部分属于”)的链接概念
- 段落在全文索引中以便再次查找
- 来源 — 每条记录都保留其来源和背后的引用
原始文件保留在您的 Obsidian 库中。后续提问可以获得确切的数字、可搜索的引用以及指向原始文档的链接。
这被定位为“LLM Wiki”模式(Karpathy 提出的让模型将来源编译成 markdown 页面的想法)的直接替代方案。您得到的不是松散的页面,而是可以用 SQL 求和/过滤/比较的类型化表、带有类型链接的概念页面,以及一个 export_wiki 命令,它将所有内容写出为带有 [[links]] 和图形视图的 Obsidian 库。
主要功能(来自 README)
| 功能 | 作用 |
|---|---|
| 目录与分析 | 读取表/列/键,采样行以记录最高值、唯一性、空值率、范围、日期格式、小枚举的完整值集以及存储列表的文本列 |
| 键推断 | 通过名称查找未声明的主键/外键并按值包含确认;检测角色(billing_ 与 delivery_)、自引用、桥接表 |
| 使用您的模型建模 | 每次向模型提供一个带有样本和键的表;验证并存储它提出的术语和列映射 |
| SQL 属性 | 从执行的查询中挖掘可重用的过滤器、度量和连接模式;在保存前针对数据库测试每个候选者 |
| 可回答性 | 检查问题的实体是否被术语、属性或存储的值覆盖;验证匹配的表如何链接(行对行、在共享父级处,或根本不链接) |
| 验证 | 捕获未知列、未知连接、近似匹配字面量、列表列相等性、百分比与分数错误、扇出错误,并运行试运行 |
| 治理 | 术语的草稿/认证/弃用状态;编辑认证定义会将其返回为草稿 |
| 知识存储 | 实体、概念、段落和来源的可写存储,每条记录都有定位器/引用 |
| 全文搜索 | 带有 bm25 排名的 FTS5 索引;前缀匹配处理韩语助词(기억 → 기억을);返回片段和 [[links]] |
| SQL 中的概念图 | 术语、关系和段落是可查询的表,因此一个经过验证的查询可以结合文本搜索、递归关系遍历和记录 |
| Obsidian 中的原始文件 | 每个来源的全文保留在您的库中;存储保留摘要并链接回标题 |
| 就地更新 | 重新扫描保留术语、认证和审查过的连接;更改的文档替换其自身的段落而无需重建所有内容 |
| 便携 | 将整个语义层导出/导入为单个 YAML 或 JSON 文档 |
演示
README 包含一个演示(auto-ontology-mcp demo),其中包含一家虚构的零售店:11 个表、3,200 个订单、知识库中的三个文档以及需要两者的提问。它展示了:
- 助手在编写 SQL 前检查可回答性
- 验证捕获错误的连接和错误的字面量
- 助手解释何时无法回答问题(例如,“广告支出回报率” — 数据库有销售额但没有广告支出数据)
- 在一条 SQL 语句中结合结构化数据(收入数字)与非结构化文档(收入下降的原因)
- 全文搜索 + 类型关系遍历 + 段落连接
入门
需要 uv。
- 设置演示:
uvx --from git+https://github.com/gogoymh/auto-ontology-mcp auto-ontology-mcp demo - 连接您的客户端: Cursor 或 VS Code 一键安装;其他客户端使用配置片段(
config命令会打印带有绝对路径的配置)。
安全说明
所有 SQL 执行都是只读的 — 服务器针对本地 SQLite 文件运行查询,并在执行前根据本体进行验证。
许可证
Apache-2.0。Python 3.12+。
相关
- 项目
- 项目
- 项目
- 项目