Case Management MCP

🚀 PatOrg案件管理MCP - 甲骨文自然语言转SQL

这是一个模型上下文协议（MCP）服务器，可将自然语言查询转换为适用于PatOrg案件管理系统的甲骨文SQL。本仓库仅支持甲骨文数据库，并使用真实的模式文档。

🚀 快速开始

安装依赖

pip install -e .

配置甲骨文凭证

cp .env.example .env
# 使用你的甲骨文凭证编辑.env文件

运行测试

pytest tests/test_queries.py -v

与Claude桌面版集成

完整的设置说明请参阅 CLAUDE_DESKTOP_INTEGRATION.md。

详细设置请参阅 QUICKSTART.md。

✨ 主要特性

• 此MCP服务器使Claude（或其他AI助手）能够：
  • 读取详细的甲骨文模式文档。
  • 查看查询模式和业务术语表。
  • 从自然语言生成安全的甲骨文SQL。
  • 在执行前验证查询。
  • 安全地执行只读的SELECT查询。

📦 安装指南

安装依赖

pip install -e .

配置甲骨文凭证

cp .env.example .env
# 使用你的甲骨文凭证编辑.env文件

💻 使用示例

基础用法

与Claude桌面版集成后，你可以用自然语言提问，例如：

简单查询

• "显示AKTE表中的所有案件文件"
• "用户RUH创建了哪些案件文件？"
• "显示AKTE表的结构"
• "CPIDE表中有多少行？"

近期活动

• "显示最近30天内修改的文件"
• "本周创建了哪些文件？"
• "显示LOHI表中的近期登录活动"

状态和优先级

• "显示STATUSAKT不为空的文件"
• "查找HAKTE = 1的主文件"
• "显示高优先级文件（PRIOANZ > 0）"

历史和更改

• "显示文件MK 118的历史记录"
• "HISTST01中最近的更改有哪些？"
• "显示DOVE表中的文档历史记录"

关系和连接

• "显示带有CPIDE中当事人信息的文件"
• "查找案件及其ADRS中的地址"
• "获取带有文档引用的文件"

分析

• "按创建文件的用户统计文件数量"
• "显示AKTE中的状态分布"
• "哪些用户最活跃？"

Claude将：

1. 读取模式文档（docs/schema.md）。
2. 查看查询模式（docs/patterns.md）。
3. 生成合适的甲骨文SQL。
4. 使用验证工具进行验证。
5. 安全地执行并返回结果。

📚 详细文档

项目结构

patorg-case-mcp-oracle/
├── src/
│   ├── server.py          # MCP服务器定义（资源和工具）
│   ├── db.py              # 甲骨文连接和查询执行
│   └── validators.py      # 查询验证和安全检查
├── docs/
│   ├── schema.md          # 甲骨文模式文档
│   ├── patterns.md        # 自然语言 → SQL示例
│   ├── glossary.md        # 业务术语定义
│   ├── end-to-end-testing.md        # 测试指南
│   └── fastmcp-tools-explained.md   # MCP工具说明
├── tests/
│   └── test_queries.py    # 验证和执行测试（pytest）
├── start_mcp_server.py    # MCP服务器包装器（加载.env凭证）
├── toggle_mcp.ps1         # 用于启用/禁用MCP的PowerShell脚本
├── toggle_mcp.bat         # 切换脚本的Windows批处理包装器
├── .env.example           # 甲骨文凭证模板
├── QUICKSTART.md          # 快速入门指南
├── CLAUDE_DESKTOP_INTEGRATION.md   # Claude桌面版设置指南
├── COMPLETION_SUMMARY.md  # 项目完成总结
├── claude_desktop_config.template.json
├── pyproject.toml
└── README.md

MCP资源与工具

资源（读取）

• case_schema → docs/schema.md
• query_patterns → docs/patterns.md
• business_glossary → docs/glossary.md
• db_summary → 实时甲骨文摘要

工具（执行）

• validate_query
• execute_query

安全特性

• 仅允许SELECT查询。
• 甲骨文模式的表白名单（AKTE、CPIDE/CPIDD/CPIDF、P7LIST*、HIST*、LOHI、ADRS*、DOVE*、DOKU）。
• 大表需要WHERE子句。
• 阻止关键字（DELETE/INSERT/UPDATE等）。
• 阻止SQL注释。
• 使用 FETCH FIRST n ROWS ONLY 自动限制行数。

🔧 技术细节

运行测试

# 运行所有测试
pytest tests/test_queries.py -v

# 运行特定测试
pytest tests/test_queries.py::TestQueryValidator::test_valid_select_queries -v

# 预期：12个测试通过

故障排除

• 需要甲骨文连接参数 → 检查 .env 文件中的凭证是否正确。
• 查询验证失败 → 查看 docs/patterns.md 中的安全查询模式。
• Claude看不到MCP → 重启Claude桌面版并验证配置路径。
• 导入错误 → 确保已安装包：pip install -e .
• MCP服务器无法启动 → 使用 python start_mcp_server.py 进行测试。

更多帮助请参阅：

• docs/end-to-end-testing.md - 完整测试指南
• CLAUDE_DESKTOP_INTEGRATION.md - 集成故障排除

实用脚本

• start_mcp_server.py - 使用 .env 凭证启动MCP服务器（与Claude桌面版一起使用）
• toggle_mcp.ps1 - 在Claude桌面版配置中启用/禁用MCP服务器
• toggle_mcp.bat - 切换脚本的Windows包装器（双击切换）

📄 许可证

文档中未提及相关信息，故跳过该章节。

参考资料

• MCP文档
• FastMCP
• python-oracledb文档
• SQL基础

版本： 1.0.0
最后更新： 2026年2月
状态： 仅支持甲骨文的生产就绪MCP服务器

主要特性：

• ✅ 仅支持甲骨文（已移除所有SQLite/模拟引用）
• ✅ 正确的Python打包（pip install -e .）
• ✅ 完整的pytest测试覆盖（12个测试）
• ✅ 安全的凭证管理（.env文件）
• ✅ 支持Claude桌面版集成
• ✅ 提供切换脚本，便于启用/禁用