Kivor本体MCP服务器
FastMCP服务器,用于基于LLM的票证分类的动态本体管理。
概述
此MCP服务器使用OpenAI LLM将静态项目级本体选择替换为动态票级分类。它提供了用于存储、检索、验证和为票证分配本体的全面工具。
特性
- 动态本体选择:基于LLM的智能票到本体匹配分类
- 版本管理:支持多个本体版本
- 作业历史:完成本体分配的审计跟踪
- 手动覆盖:能够用推理覆盖LLM选择
- GraphRAG SDK验证:内置本体结构验证
- RESTful API:FastMCP HTTP接口,易于集成
建筑```
kivor-ontology-mcp/
├── ontology_mcp.py # Main FastMCP server
├── src/
│ ├── agents/
│ │ └── ontology_agent.py # All 10 tool implementations
│ ├── config/ # Configuration management
│ ├── logging/ # Centralized logging
│ └── utility/
│ ├── db_manager.py # PostgreSQL connection
│ └── llm_classifier.py # LLM-based classification
├── migrations/ # Database schema migrations
├── logs/ # Application logs
└── docker-compose.yml # Container orchestration
## 提供的工具
### P0工具(必备)
1. **商店生物学** -上传并存储新的本体
1. **retrieve_ontology_by_id** -按ID获取本体
1. **选择门票** ⭐ - 基于LLM的票证分类(主要工具)
1. **列表_生物学家** -具有过滤和分页功能的列表
1. **validate_ontology** -验证GraphRAG SDK兼容性
### P1工具(重要)
6. **retrieve_ontology_by_name** -按名称获取(最新或特定版本)
1. **更新生物学** -更新现有本体
1. **缺失生物学** -软删除(保留历史记录)
1. **override_ticket_生物学** -手动分配超控
1. **获取门票登录历史** -查看作业历史记录
## 数据库模式
### 本体论_商店
使用元数据存储所有本体定义:
- `ontology_id` (PK)
- `name`, `version` (独一无二)
- `ontology_json` (JSONB)
- `category`, `description`, `tags`
- `priority` (选择偏好为1-100)
- `is_active`, `deleted_at` (软删除)
### 票务_票务_作业
记录所有本体分配的票:
- `assignment_id` (PK)
- `ticket_id`, `ontology_id` (FK)
- `match_confidence`, `match_method`
- `llm_reasoning`, `llm_category`, `llm_keywords_found`
- `is_override`, `override_reason`, `override_by`
- 完整的票证上下文以供审核
## 安装
### 先决条件
- Python 3.11+
- PostgreSQL 12+
- OpenAI API密钥
- Docker(可选)
### 本地设置
1. **克隆和导航**:```bash
cd kivor-ontology-mcp
- 安装依赖项:```bash
pip install -r requirements.txt
1. **配置环境**:```bash
cp .env.example .env
# Edit .env with your credentials
- 运行数据库迁移:```bash
psql -h 74.225.248.241 -p 5433 -U your_user -d kivorticketing -f migrations/001_create_ontology_store.sql
psql -h 74.225.248.241 -p 5433 -U your_user -d kivorticketing -f migrations/002_create_ticket_assignments.sql
psql -h 74.225.248.241 -p 5433 -U your_user -d kivorticketing -f migrations/003_create_functions.sql
1. **启动服务器**:```bash
python ontology_mcp.py
服务器在上运行 http://localhost:8102
Docker设置
- 构建并运行:```bash
docker-compose up -d
1. **查看日志**:```bash
docker-compose logs -f ontology-mcp
- 停止服务器:```bash
docker-compose down
## 配置
### 环境变量
|变量|描述|默认值|
|----------|-------------|---------|
| `DB_HOST` |PostgreSQL主机|74.225.248.241|
| `DB_PORT` |PostgreSQL端口|5433|
| `DB_NAME` |数据库名称|kivacticketing|
| `DB_SCHEMA` |架构名称|kivacticketing|
| `DB_USER` |数据库用户|(必填)|
| `DB_PASSWORD` |数据库密码|(必填)|
| `OPENAI_API_KEY` |OpenAI API密钥|(必需)|
| `OPENAI_MODEL` |LLM型号|gpt-4o-mini|
| `MCP_HOST` |服务器主机|0.0.0.0|
| `MCP_PORT` |服务器端口|8102|
## 使用示例
### 示例1:存储本体```json
POST /tools/store_ontology
{
"name": "infrastructure_ontology",
"ontology_json": {
"entities": [
{"name": "Server", "type": "Infrastructure"},
{"name": "Network", "type": "Infrastructure"}
],
"relationships": [
{"source": "Server", "target": "Network", "type": "CONNECTS_TO"}
]
},
"category": "infrastructure",
"description": "Ontology for infrastructure tickets",
"tags": ["infrastructure", "server", "network"],
"priority": 80,
"version": "1.0.0"
}
示例2:为票证选择本体(基于LLM)```json
POST /tools/select_ontology_for_ticket
{
"ticket_id": "TKT-ABC123",
"ticket_title": "Server connectivity issue in production",
"ticket_description": "Production server unable to connect to database. Network tests show intermittent packet loss.",
"project_id": 42
}
答复:```json
{
"success": true,
"assignment_id": 123,
"selected_ontology": {
"ontology_id": 5,
"name": "infrastructure_ontology",
"version": "1.0.0",
"category": "infrastructure"
},
"classification": {
"confidence": 0.92,
"reasoning": "Ticket involves infrastructure components (server, network, connectivity) requiring infrastructure ontology",
"category": "infrastructure",
"keywords_found": ["server", "network", "connectivity", "production"],
"processing_time_ms": 1234
}
}
示例3:列出本体论```json
POST /tools/list_ontologies
{
"category": "infrastructure",
"is_active": true,
"limit": 10
}
### 示例4:手动超控```json
POST /tools/override_ticket_ontology
{
"ticket_id": "TKT-ABC123",
"ontology_id": 7,
"override_reason": "Ticket requires specialized database ontology",
"override_by": "admin_user"
}
与现有系统集成
Planner代理集成
替换Planner Agent中的静态本体选择:```python
OLD CODE (project_description_detector.py)
ontology = get_ontology_by_project_description(project_description)
NEW CODE (using Ontology MCP)
response = await call_mcp_tool(
"select_ontology_for_ticket",
{
"ticket_id": ticket_id,
"ticket_title": ticket_title,
"ticket_description": ticket_description,
"project_id": project_id
}
)
ontology_id = response["selected_ontology"]["ontology_id"]
### 在哪里更新
1. **KivorPlanner代理**:更新 `generate_workflow_plan()` 叫 `select_ontology_for_ticket`
1. **处理器**:将门票详细信息传递给Planner(已经这样做了)
1. **代理注册表**:注册本体mcp服务器
1. **移除**: `project_description_detector.py` 逻辑(保留文件以保持向后兼容性)
## 监控
### 日志
- **位置**: `logs/ontology_mcp.log`
- **格式**:用函数和行号标记时间戳
- **旋转**:每个文件10MB,5个备份
### 要监控的指标
- LLM分类置信度得分
- 每个分类的处理时间
- 超控率(手动与LLM)
- 最常选择的本体
## 故障排除
### 常见问题
1. **“没有可用的活动本体”**
- 解决方案:至少存储一个本体 `is_active=true`
1. **“LLM返回了无效的JSON”**
- 解决方案:检查OpenAI API密钥和模型的可用性
- 验证 `OPENAI_MODEL` 支持JSON响应格式
1. **数据库连接错误**
- 解决方案:验证 `DB_*` 环境变量
- 从容器/主机检查PostgreSQL的可访问性
1. **端口8102已在使用中**
- 解决方案:更改 `MCP_PORT` 在 `.env` 和 `docker-compose.yml`
## 发展
### 运行测试```bash
# Unit tests (TODO)
pytest tests/
# Manual testing
python -m src.utility.llm_classifier # Test LLM classifier
python -m src.utility.db_manager # Test DB connection
添加新工具
- 实现功能
src/agents/ontology_agent.py - 在中注册工具
ontology_mcp.py随着@mcp.tool装饰器 - 将文档添加到此README中
从旧系统迁移
第一阶段:平行运行(推荐)
- 部署本体mcp服务器
- 使用迁移现有本体
store_ontology工具 - 更新Planner以调用新旧系统
- 记录差异以供验证
第二阶段:切换
- 移除
project_description_detector.py逻辑 - 更新所有引用以供使用
select_ontology_for_ticket - 监控分类质量
第三阶段:清理
- 归档旧本体存储文件
- 删除未使用的代码
- 更新文档
API 参考
API完整文档可在以下网址获取: http://localhost:8102/docs (服务器运行时)
支持
对于问题或疑问:
- 检查日志:
logs/ontology_mcp.log - 审查迁移:
migrations/*.sql - 联系人:Kivor平台团队
许可证
专有-Kivor人工智能平台
