MCP Rag Go

🚀 MCP RAG概念驗證 — 石油與天然氣原型

本項目是針對石油和天然氣行業的 多上下文協議（Multi Context Protocol，MCP）和檢索增強生成（Retrieval-Augmented Generation，RAG） 概念驗證。該應用將各種內部領域源（鑽井、生產、健康安全環保（HSSE）、採購訂單、時間序列和RAG搜索）連接到一個路由器中，從而使客戶端的查詢能夠自動路由到合適的服務或存儲庫。

✨ 主要特性

什麼是MCP？

多上下文協議（Multi Context Protocol，MCP） 是一種用於將大語言模型（LLM）與幕後的各種工具或服務相連接的協議。藉助MCP，用戶的問題可以自動映射到特定領域（例如鑽井事件、採購訂單或RAG搜索），然後以最恰當的方式執行。

什麼是RAG？

檢索增強生成（Retrieval-Augmented Generation，RAG） 是一種將大語言模型（LLM）的能力與基於文檔的搜索相結合的技術。RAG並非僅僅依賴模型，而是從數據庫（例如 doc_chunks）中提取相關的文本片段，然後利用這些片段生成更準確且有引用的答案。

🛑 問題

在石油和天然氣行業，運營數據分散在多個不同的領域和系統中：

• 鑽井 → 鑽井報告和非生產時間（Non Productive Time，NPT）。
• 生產 → 每日生產數據和時間序列。
• HSSE → 事故記錄和安全報告。
• 採購訂單 → 採購狀態和供應商信息。
• 技術文檔 → 分散在各個部門的PDF/Word文件。

因此，要回答一個簡單的問題（例如 “本月B07鑽機發生了多少起HSSE事故？”），用戶必須：

• 聯繫多個團隊/部門。
• 手動查找報告文件。
• 等待數據驗證和彙總。

這個過程可能需要 數天時間，並且容易出現不同數據源之間的不一致情況。

✅ 解決方案

這個 MCP + RAG 項目提供了一種現代化的方法：

• MCP路由器 → 充當 “智能網關”，將用戶的問題路由到合適的領域/數據存儲庫（鑽井、生產、HSSE、採購訂單、時間序列）。
• RAG搜索 → 結合 “關鍵詞搜索（BM25）” 和 “語義搜索（餘弦相似度）” 來提取最相關的文檔片段。
• 大語言模型集成 → 理解並回答用戶的自然語言查詢，並結合上下文，同時提供來自源文檔的引用。
• 聊天服務器發送事件（Chat SSE） → 以流式方式發送答案，實現交互式體驗，類似於與人工智能助手聊天。

對石油和天然氣公司的影響：

• ⏱ 更快 → 跨領域的答案在數秒內即可獲得。
• 📊 更準確 → 基於文檔和引用的答案，易於驗證。
• 🔄 更高效 → 減少部門間的協調負擔。
• 🧩 更靈活 → 可根據業務需求輕鬆擴展新的工具或領域。

項目名稱：MCP_RAG（石油與天然氣） — Go 版本：0.1.0 作者：Kukuh Tripamungkas Wicaksono（Kukuh TW） 郵箱：kukuhtw@gmail.com WhatsApp：https://wa.me/628129893706 領英：https://www.linkedin.com/in/kukuhtw/ 許可證：MIT（詳見 LICENSE 文件）

總結

這是一個用於石油和天然氣公司案例研究的MCP + RAG概念驗證單倉庫項目。主要功能包括：

• MCP路由器和工具（採購訂單、生產、鑽井、時間序列、非生產時間）。
• 通過 /rag/search_v2 實現的混合RAG（BM25 + 餘弦相似度）（MySQL doc_chunks）。
• 基於文檔的答案（answer_with_docs），並帶有引用。
• 聊天服務器發送事件（/chat/stream）：規劃 → 規範化 → 執行 → 流式傳輸答案。
• 規劃規範化器（自動切換 rag_search_v2，按金額排名的前N個採購訂單）。
• 可用的REST端點。
• 通過環境變量進行配置；支持使用OpenAI的大語言模型和嵌入（可選）。

📚 詳細文檔

主要功能

• MCP路由器和工具：get_production、get_timeseries、get_drilling_events、get_po_status、get_po_vendor_compare、get_po_vendor_summary、summarize_npt_events、answer_with_docs、get_po_top_amount（按金額排名的前N個）。
• 混合RAG：/rag/search_v2 端點直接在 doc_chunks.embedding (JSON) 上使用MySQL（BM25 + 餘弦相似度）。
• 帶文檔的答案：答案引用文檔並帶有引用（DOC-XXXX#pY）。
• 聊天服務器發送事件（Chat SSE）：/chat/stream 端點 → 規劃（大語言模型） → 規範化規劃 → 執行路由（MCP/RAG） → 流式傳輸答案。
• 規劃規範化器：
  • 將路由 rag 重寫為工具 rag_search_v2（有效負載 {query, top_k, alpha}）。
  • 如果 detect_anomalies 的有效負載錯誤，但問題具有文檔性質，則回退到RAG。
  • 自動修正 “按金額排名的前N個採購訂單” 的情況，使用 get_po_top_amount。
• 可觀測性：/metrics、/healthz，結構化日誌。

快速開始

1) 前提條件

• Go 1.22 及以上版本
• MySQL 8 及以上版本
• Node.js 18 及以上版本（用於前端）

2) 數據庫設置

make build
make gen-data
make demo-data
make ingest-docs

3) 啟動服務

# Aminer mysql
[http://localhost:8080/chat](http://localhost:18080/?)

4) 啟動前端

# 訪問 http://localhost:5173

環境配置

示例 .env 變量：

# 數據庫
DB_DSN="user:pass@tcp(localhost:3306)/mcp_oilgas?parseTime=true"

# JWT / 管理員
ADMIN_JWT_SECRET="supersecret"

# 大語言模型（可選）
OPENAI_API_KEY="sk-..."

# 規劃器
MCP_SCHEMAS_DIR="schemas/mcp"
PLAN_MAX_ROUTES=8

沒有 OPENAI_API_KEY，系統仍然可以運行（混合RAG和 answer_with_docs 的提取式回退）。

重要端點

• 健康檢查和指標
  • GET /healthz、GET /readyz、GET /metrics
• 聊天服務器發送事件（Chat SSE）
  • GET|POST /chat/stream?q=...（服務器發送事件：plan、sources、delta、done 等）
• MCP路由器（內部HTTP）
  • POST /mcp/route（接收規劃或問題以自動選擇工具）
• 混合RAG
  • GET|POST /rag/search_v2 → 請求體 {"query":"...","top_k":10,"alpha":0.6} 響應包含 retrieved_chunks
• 領域HTTP（鏡像MCP）
  • /api/timeseries、/api/drilling-events、/api/po/status、/api/production、/api/work-orders/search、/api/npt/summarize、/api/po/vendor-compare、/api/answer-with-docs 等。

架構和聊天服務器發送事件（Chat SSE）流程

1. 規劃器（大語言模型JSON模式）從 schemas/mcp/*.schema.json 讀取工具。
2. 規範化規劃：

• 將路由 kind:"rag" 重寫為 rag_search_v2。
• 修正錯誤路由（例如按金額排名的前N個採購訂單）。
• 如果相關，添加輔助RAG。

3. 執行路由：

• 在進程內運行MCP工具。
• 通過閉包 ragFn 運行RAG（混合 /rag/search_v2 → 回退到嵌入存儲庫）。

4. 合成器：

• 大語言模型根據 sources 流式傳輸答案（或提取式回退）。

規劃規範化（規劃器）

自動處理的事項：

• RAG重寫：所有 kind:"rag" 的路由（包括舊工具 "rag"）都將被重寫為工具 rag_search_v2，請求體為 {query, top_k, alpha}。
• 檢測異常 → RAG：如果 detect_anomalies 的有效負載無效，並且問題看起來 “基於文檔”，則將其重定向到RAG。
• 按金額排名的前N個採購訂單：檢測 “按金額排名的前/最高採購訂單” 等短語，添加/修正路由 get_po_top_amount {limit, ...}。

示例問題

1. WELL_A12 在 2025-09-05 的產量是多少？
2. 比較 2025-09-20 至 2025-10-06 期間，供應商 SLB 和 Weatherford 的 “已交付” 採購訂單總價值。
3. 提供最新的按狀態分類的採購訂單數量總結。
4. 比較 2025-09-01 至 2025-10-11 期間，供應商 Halliburton、NOV 和 Weatherford 的採購訂單總價值。
5. 應急響應計劃。
6. 2025年第四季度生產預測。
7. 獲取 WELL_E05 在 2025-09-01 的天然氣產量。
8. WELL_B07 在2025年9月的產量是多少？
9. 顯示 WELL_C03 在 2025-09-04 的天然氣產量。
10. 獲取 WELL_A12 的最新產量值。
11. 顯示 WELL_B07 在2025年9月的所有非生產時間（NPT）事件。
12. WELL_D02 在2025年9月7日至13日有哪些鑽井事件？
13. WELL_E05 在2025年9月3日有哪些非生產時間（NPT）事件？
14. 獲取 WELL_C03 在2025年9月24日至30日的所有鑽井事件。
15. WELL_F10 在2025年9月10日發生了哪些事件？
16. 顯示 FLOW_A12 在2025年9月1日00:00 - 00:23的 “流量趨勢”。
17. FLOW_A12 在2025年9月11日至12日期間，quality=0 的流量值是多少？
18. FLOW_A12 在2025年9月1日開始的 “5分鐘平均比較趨勢” 如何？
19. FLOW_A12 在2025年9月14日00:05 - 00:10與00:15 - 00:20之間的流量是否有顯著下降？
20. 獲取 OIL_D01 在2025年9月18日全天（00:00 - 23:59）的 “油率”。
21. 顯示 OIL_B07 在2025年9月15日至16日的 “趨勢”。
22. 獲取 FLOW_A12 在 2025-09-01 06:00 - 12:00之間的 “油率”。
23. 比較 OIL_D01 和 OIL_D02 在2025年9月18日的流量。
24. 獲取 FLOW_C03、FLOW_E05、FLOW_F10 在2025年9月3日的時間序列數據，然後顯示 “每日平均值”。

故障排除

1) /chat/stream 未找到文檔（retrieved_chunks 為空）

• 檢查混合端點：

  curl "http://localhost:8080/rag/search_v2?q=Production%20Forecast%20Q4%202025"
  

  確保響應格式如下：

  {
    "query":"...",
    "alpha":0.6,
    "count":10,
    "retrieved_chunks":[
      {"doc_id":"DOC-1005","title":"...","url":"...","page_no":3,"snippet":"...","score":0.123}
    ]
  }
  

• 如果結構正確但服務器發送事件（SSE）仍然為空，請確保 規範化規劃 已啟用，並且 chat_sse_handler.go 中的 ragFn 讀取 retrieved_chunks[*].page_no（而不是 page）。

2) MCP規劃RAG時解碼錯誤

• 確保消費者解碼包含 retrieved_chunks 字段的 對象（而不是直接解碼切片）。
• 正確解碼示例（Go）：

  var resp struct {
    RetrievedChunks []struct {
      DocID string `json:"doc_id"`
      ...
    } `json:"retrieved_chunks"`
  }
  

3) 大語言模型/嵌入不可用

• 系統仍然可以運行：混合RAG + answer_with_docs 的提取式回退。 添加 OPENAI_API_KEY 以獲得更自然的答案。

4) 可觀測性

• 檢查 /healthz、/metrics 和 logs/ 中的日誌。

許可證

本項目採用MIT許可證 — 詳見 LICENSE 文件。

💡 使用建議

本項目採用Go語言開發，主要基於一些與石油和天然氣行業高度相關的技術和業務原因：

• 🚀 高性能和效率：編譯型語言，生成的二進制文件運行速度快、穩定且開銷小，非常適合低延遲的跨領域查詢。
• ⚡ 通過Goroutines實現併發：可以並行獲取來自多個源（如SCADA、物聯網、ERP）的數據。
• 🛡️ 穩定且經過驗證：在Kubernetes、Docker、Hashicorp Consul等項目中廣泛使用。
• 📦 易於部署（單二進制文件）：不存在依賴問題，便於遷移到本地部署或私有云環境。
• 🔄 支持即時流式傳輸（SSE）：藉助 net/http 和Goroutines，即使處理數千個連接也能保持輕量級。

致謝

本項目由 Kukuh Tripamungkas Wicaksono（Kukuh TW） 開發，作為石油和天然氣領域MCP + RAG架構的概念驗證。