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桌面版集成
• ✅ 提供切換腳本，便於啟用/禁用