MCP Rag Go

🚀 MCP RAG 概念実証 — 石油・ガス産業向けプロトタイプ

このプロジェクトは、石油・ガス産業向けのマルチコンテキストプロトコル（MCP）と検索拡張生成（RAG） の概念実証です。
このアプリケーションは、さまざまな内部ドメインソース（掘削、生産、HSSE、注文書、時系列データ、およびRAG検索）を1つのルーターに接続し、クライアントからのクエリを適切なサービスまたはリポジトリに自動的にルーティングします。

🚀 クイックスタート

このプロジェクトは、石油・ガス産業におけるデータの分散化問題を解決するために開発されました。以下のセクションでは、MCPとRAGの基本概念、問題点、解決策、およびシステムのアーキテクチャについて詳しく説明します。

✨ 主な機能

MCPとは？

マルチコンテキストプロトコル（MCP） は、LLMをさまざまなツールやサービスに接続するためのプロトコルです。
MCPを使用すると、ユーザーの質問を特定のドメイン（たとえば、掘削イベント、注文書、またはRAG検索）に自動的にマッピングし、最適な方法で実行することができます。

RAGとは？

検索拡張生成（RAG） は、LLMの機能とドキュメントベースの検索を組み合わせた技術です。
RAGは、モデルだけに依存するのではなく、データベース（たとえば、doc_chunks）から関連するテキスト片を取得し、それを使用してより正確で引用付きの回答を生成します。

🛑 問題点

石油・ガス産業では、運用データが多くのドメインやシステムに分散しています。

• 掘削 → 掘削報告書と非生産時間（NPT）。
• 生産 → 日次生産データと時系列データ。
• HSSE → 事故記録と安全報告。
• 注文書 → 購入ステータスとベンダー情報。
• 技術文書 → さまざまな部門に分散したPDF/Wordファイル。

その結果、簡単な質問（たとえば、「今月、リグB07で発生したHSSE事故は何件ですか？」）に答えるために、ユーザーは次のことを行う必要があります。

• 複数のチームや部門に問い合わせる。
• 報告書ファイルを手動で検索する。
• データの検証と集計を待つ。

このプロセスは数日間かかる可能性があり、情報源間の不一致が生じやすいです。

✅ 解決策

このMCP + RAGプロジェクトは、次のような現代的なアプローチを提供します。

• MCPルーター → ユーザーの質問を適切なドメインまたはデータリポジトリ（掘削、生産、HSSE、注文書、時系列データ）に誘導する「スマートゲートウェイ」として機能します。
• RAG検索 → 「キーワード検索（BM25）」と「セマンティック検索（コサイン類似度）」を組み合わせて、最も関連性の高いドキュメント片を取得します。
• LLM統合 → ユーザーの自然言語クエリを理解し、ソースドメインのコンテキストを考慮して回答し、ソースドキュメントの引用を含めます。
• Chat SSE → 回答を「ストリーミング」で送信するため、対話的でAIアシスタントとのチャットのような感覚を提供します。

石油・ガス企業に与える影響

• ⏱ 高速化 → ドメインをまたいだ回答が数秒で得られます。
• 📊 高精度化 → ドキュメントと引用に基づく回答で、検証が容易です。
• 🔄 効率化 → 部門間の調整負荷を軽減します。
• 🧩 柔軟性向上 → ビジネスニーズに応じて、追加のツールやドメインを簡単に拡張できます。

プロジェクト: MCP_RAG (石油・ガス) — Go バージョン: 0.1.0 作者: Kukuh Tripamungkas Wicaksono (Kukuh TW)

メール: kukuhtw@gmail.com

WhatsApp: https://wa.me/628129893706

Linkedin: https://www.linkedin.com/in/kukuhtw/

ライセンス: MIT（LICENSE を参照）

概要

石油・ガス企業のケーススタディ向けのMCP + RAGのモノレポ概念実証です。 主な機能:

• MCPルーターとツール（注文書、生産、掘削、時系列データ、NPT）。
• RAGハイブリッド（BM25 + コサイン） via /rag/search_v2（MySQLの doc_chunks）。
• ドキュメントに基づく回答（answer_with_docs）と引用。
• Chat SSE (/chat/stream)：計画 → 正規化 → 実行 → 回答のストリーミング。
• 計画正規化機能（自動的に rag_search_v2 を切り替え、注文書の上位N件を金額で抽出）。
• すぐに使用できるRESTエンドポイント。
• 環境変数による設定；LLM/埋め込みベクトルにOpenAIをサポート（オプション）。

📦 インストール

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"

# LLM（オプション）
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=...（SSEイベント: 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. 計画生成器（LLM JSONモード）が schemas/mcp/*.schema.json からツールを読み込みます。
2. 計画正規化
   • kind:"rag" のルートを rag_search_v2 に変換します。
   • ルートの誤りを修正します（たとえば、注文書の上位金額）。
   • 関連する場合、サポート用のRAGを追加します。
3. ルート実行
   • MCPツールをプロセス内で実行します。
   • クロージャ ragFn を介してRAGを実行します（ハイブリッド /rag/search_v2 → フォールバックの埋め込みベクトルリポジトリ）。
4. 合成器
   • LLMが sources に基づいて回答をストリーミングします（または抽出型フォールバック）。

計画正規化（計画生成器）

自動的に処理される事項:

• RAGの書き換え: すべての kind:"rag" ルート（古いツール "rag" を含む）を、ボディが {query, top_k, alpha} の rag_search_v2 ツールに変換します。
• 異常検出 → 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. Emergency Response Plan（緊急対応計画）を取得してください。
6. Production Forecast Q4 2025（2025年第4四半期の生産予測）を取得してください。
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年9月1日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) LLM/埋め込みベクトルが利用できない

• システムは引き続き動作します：RAGハイブリッド + answer_with_docs の抽出型フォールバック。 より自然な回答を得るには、OPENAI_API_KEY を追加してください。

4) 監視

• /healthz、/metrics、および logs/ のログを確認してください。

📄 ライセンス

MIT — LICENSE ファイルを参照してください。

💡 なぜGo（Golang）を使うのか？

MCP + RAGプロジェクトは、石油・ガス産業に非常に関連するいくつかの技術的およびビジネス的理由からGoで構築されています。

🚀 高いパフォーマンスと効率性 コンパイル型 → 高速で安定したバイナリ、最小限のオーバーヘッド。 低遅延のドメイン横断クエリに最適。

⚡ ゴルーチンによる並行処理 多数のデータソース（SCADA、IoT、ERP）からのデータを並列に取得できます。

🛡️ 安定性と実績 Kubernetes、Docker、Hashicorp Consulで使用されています。

📦 簡単なデプロイ（シングルバイナリ） 依存関係の問題がなく、オンプレミス/プライベートクラウドへの移行が容易。

🔄 リアルタイムストリーミング（SSE）のサポート net/httpとゴルーチンを使用して、数千の接続を軽負荷で維持できます。

クレジット

このプロジェクトは、Kukuh Tripamungkas Wicaksono (Kukuh TW) によって開発され、石油・ガスドメイン向けのMCP + RAGアーキテクチャの概念実証として提供されています。