Kivor Ontology MCP

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. 商店生物学 -上传并存储新的本体
2. retrieve_ontology_by_id -按ID获取本体
3. 选择门票 ⭐ - 基于LLM的票证分类（主要工具）
4. 列表_生物学家 -具有过滤和分页功能的列表
5. validate_ontology -验证GraphRAG SDK兼容性

P1工具（重要）

1. retrieve_ontology_by_name -按名称获取（最新或特定版本）
2. 更新生物学 -更新现有本体
3. 缺失生物学 -软删除（保留历史记录）
4. override_ticket_生物学 -手动分配超控
5. 获取门票登录历史 -查看作业历史记录

数据库模式

本体论_商店

使用元数据存储所有本体定义：

• 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. 克隆和导航:

   cd kivor-ontology-mcp

1. 安装依赖项:

   pip install -r requirements.txt

1. 配置环境:

   cp .env.example .env
   # Edit .env with your credentials

1. 运行数据库迁移:

   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. 启动服务器:

   python ontology_mcp.py

服务器在上运行 http://localhost:8102

Docker设置

1. 构建并运行:

   docker-compose up -d

1. 查看日志:

   docker-compose logs -f ontology-mcp

1. 停止服务器:

   docker-compose down

配置

环境变量

使用示例

示例1：存储本体

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）

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
}

答复：

{
  "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：列出本体论

POST /tools/list_ontologies
{
  "category": "infrastructure",
  "is_active": true,
  "limit": 10
}

示例4：手动超控

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中的静态本体选择：

# 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
2. 处理器：将门票详细信息传递给Planner（已经这样做了）
3. 代理注册表：注册本体mcp服务器
4. 移除: 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

发展

运行测试

# 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

添加新工具

1. 实现功能 src/agents/ontology_agent.py
2. 在中注册工具 ontology_mcp.py 随着 @mcp.tool 装饰器
3. 将文档添加到此README中

从旧系统迁移

第一阶段：平行运行（推荐）

1. 部署本体mcp服务器
2. 使用迁移现有本体 store_ontology 工具
3. 更新Planner以调用新旧系统
4. 记录差异以供验证

第二阶段：切换

1. 移除 project_description_detector.py 逻辑
2. 更新所有引用以供使用 select_ontology_for_ticket
3. 监控分类质量

第三阶段：清理

1. 归档旧本体存储文件
2. 删除未使用的代码
3. 更新文档

API 参考

API完整文档可在以下网址获取： http://localhost:8102/docs （服务器运行时）

支持

对于问题或疑问：

• 检查日志： logs/ontology_mcp.log
• 审查迁移： migrations/*.sql
• 联系人：Kivor平台团队

许可证

专有-Kivor人工智能平台