内容
<div align="center">
# 🦉 OWL MCP Server
**让 AI 直接读写你的 OWL / TTL / RDF 本体文件**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://pypi.org/project/owlready2/)
[English](#english) · [快速开始](#快速开始) · [工具列表](#工具列表) · [示例](#示例用法)
</div>
---
## 简介
**OWL MCP Server** 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的本体操作服务器。
它让 Claude、Cursor、WorkBuddy 等 AI 助手能够像操作普通文件一样，**直接查询、修改、推理**你的 OWL/TTL/RDF 本体文件 —— 无需手写 SPARQL，无需了解 OWL 语法细节，用自然语言对话即可完成复杂的知识图谱操作。
```
你："找出所有 XX 类的个体，按金额降序排列"
AI：[调用 sparql_query] → 返回结构化结果
```
### 适用场景
- 🏦 **金融领域**：对账单、票据本体的增删改查
- 🏥 **医疗健康**：临床知识图谱探索与推理
- 🏗️ **工程建模**：设备、流程本体的管理与验证
- 🎓 **学术研究**：OWL 本体的快速原型开发与测试
---
## 快速开始
### 第一步：安装依赖
```bash
pip install mcp owlready2 rdflib
```
或使用 requirements.txt：
```bash
pip install -r requirements.txt
```
> ⚠️ **推理器依赖 Java**：使用 `run_reasoner`（Pellet/HermiT）需要本地安装 **JDK 8+**
### 第二步：配置 MCP 客户端
#### WorkBuddy
在 `~/.workbuddy/mcp.json` 中添加：
```json
{
"mcpServers": {
"owl": {
"command": "python",
"args": ["/绝对路径/server.py"]
}
}
}
```
> 💡 **推荐**：使用虚拟环境的 Python 绝对路径，避免依赖冲突：
> ```json
> "command": "C:/Users/yourname/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
> ```
#### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"owl-mcp": {
"command": "python",
"args": ["/绝对路径/server.py"]
}
}
}
```
#### Cursor
在 `.cursor/mcp.json` 中添加同样的配置，重启 Cursor 后即可在 Agent 模式中使用。
### 第三步：启用并开始对话
在 WorkBuddy 连接器管理页面找到 `owl`，点击 **Trust** 启用，然后直接开始自然语言对话：
```
"加载本体文件 C:/work/xxxx.ttl"
"列出所有类，只显示以 xxx: 开头的"
"描述 BankStatement 类的完整结构"
"运行 HermiT 推理器，检查本体一致性"
"把新增的类保存回原文件"
```
---
## 工具列表
### 📖 查询类
| 工具 | 说明 |
|------|------|
| `load_ontology` | 加载本体文件（支持本地路径或 IRI，格式：TTL / OWL / RDF） |
| `get_ontology_info` | 获取本体概览（类数、个体数、属性数、命名空间） |
| `list_classes` | 列出所有类，支持前缀过滤与数量限制 |
| `list_individuals` | 列出所有个体，支持按类过滤 |
| `list_properties` | 列出对象属性 / 数据属性 |
| `describe_class` | 详细描述类（父类、子类、限制、已知个体） |
| `describe_individual` | 描述个体（所属类型、全部属性值） |
| `search_entity` | 按关键词模糊搜索类 / 个体 / 属性 |
| `sparql_query` | 执行 SPARQL 1.1 SELECT 查询 |
### ✏️ 修改类
| 工具 | 说明 |
|------|------|
| `add_class` | 添加新类（可指定父类、rdfs:label、rdfs:comment） |
| `add_individual` | 添加新个体（可指定初始属性值） |
| `add_object_property_assertion` | 添加对象属性三元组断言 |
| `save_ontology` | 保存本体（支持 rdfxml / turtle / ntriples） |
### 🧠 推理类
| 工具 | 说明 |
|------|------|
| `run_reasoner` | 运行推理器（Pellet 或 HermiT），检查一致性并推断隐含知识 |
> **注意**：`add_*` 系列修改操作不会自动保存，需显式调用 `save_ontology`。
---
## 示例用法
### 探索本体结构
```
你：加载 xxx.ttl，给我一个整体介绍
AI：该本体共有 47 个类、213 个个体、18 个对象属性……
你：描述一下 BankStatement 类
AI：BankStatement 是 FinancialDocument 的子类，拥有以下数据属性：amount、currency、date……
```
### SPARQL 查询
```sparql
-- 查找所有 BankStatement 及其金额（降序）
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX : <http://test.com/t#>
SELECT ?ind ?amount WHERE {
?ind rdf:type :BankStatement .
?ind :amount ?amount .
}
ORDER BY DESC(?amount)
```
### 增量修改
```
你：新增一个 AA 类，父类是 BB，标签为"CC"
AI：[调用 add_class] → 已添加 AA 类
你：把这个改动保存为 turtle 格式
AI：[调用 save_ontology] → 已保存到 xxx.ttl
```
### 一致性检查
```
你：运行 HermiT 推理器，检查本体有没有逻辑矛盾
AI：[调用 run_reasoner] → 本体一致，推断出 3 个新的隐含类成员关系……
```
---
## 技术栈
| 组件 | 用途 |
|------|------|
| [owlready2](https://pypi.org/project/owlready2/) | OWL 本体加载、修改、推理器调用 |
| [rdflib](https://rdflib.readthedocs.io/) | SPARQL 1.1 查询引擎 |
| [mcp](https://github.com/modelcontextprotocol/python-sdk) | Model Context Protocol SDK |
---
## 注意事项
- **推理器需要 Java**：Pellet / HermiT 依赖 JDK 8+，请确保 `java` 在系统 PATH 中
- **大型本体**：超过 10 万三元组时，`list_*` 系列操作请配合 `limit` 参数使用
- **修改不自动保存**：所有 `add_*` 操作仅更新内存模型，需手动调用 `save_ontology`
- **SPARQL 语法**：使用标准 SPARQL 1.1 语法，由 rdflib 引擎执行
---
## 兼容的 MCP 客户端
- ✅ WorkBuddy
- ✅ Trae/Traw-work
- ✅ Claude
- ✅ Cursor (Agent 模式)
- ✅ 任何支持 MCP 标准的 AI 客户端
---
## License
[MIT](LICENSE)
---
## ☕ 请作者喝杯咖啡
OWL MCP Server 是我在业余时间独立开发和维护的开源项目，永久免费。
如果它帮你省下了哪怕半小时手写 SPARQL 的时间，可以考虑请我喝杯咖啡（¥9.9 就够 ☕）——
你的每一份支持都会直接转化为新功能开发和 bug 修复的动力。
<p align="center">
<img src="icon.jpg" alt="赞赏码 - 请作者喝咖啡" width="280">
</p>
<p align="center"><i>扫码赞赏时可以留言你最想要的功能，我会优先安排 😉</i></p>
**不方便赞赏？** 给项目点个 ⭐ Star、提一个 Issue、或把它分享给需要的人，同样是巨大的支持！
---
