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架构的概念验证。