Observe Experimental MCP

🚀 Observe MCP Server

このModel Context Protocol (MCP)サーバーは、ベクトル検索を通じて、Observe APIの機能、OPALクエリの支援、およびトラブルシューティングのランブックにアクセスできるようにします。

✨ 主な機能

目的

このサーバーは、技術的に高度なLLMモデルと連携するように設計されており、特にClaude Sonnet 3.7とClaude Sonnet 4でテストされています。従来のチャットボットとは異なり、このMCPサーバーは以下の特徴を持っています。

• LLMに友好的な方法でObserveプラットフォームと直接インターフェースを持ちます。
• 内部機能にLLMを使用せず、機密データの漏洩を防止します。
• サードパーティのLLMとあなたのObserveデータの間の安全なブリッジとして機能します。

⚠️ 重要な免責事項

これは、Observe AIの設計パートナーとのテストおよびコラボレーションのために作成された実験的でサポート対象外のMCPサーバーです。Observeは、このサーバーの使用について一切の責任を負わず、またいかなる形でもサポートしません。Observeによる別の本番環境向けのMCPサーバーが開発中です。

概要

このMCPサーバーは、以下の機能を通じてObserveプラットフォームとシームレスにやり取りできるようにします。

• OPALクエリの実行
• 柔軟な時間パラメータでのワークシートデータのエクスポート
• データセット情報の一覧表示と取得
• OPALクエリの作成支援
• モニターの管理（一覧表示と作成）

サーバーは、Pineconeをベクトルデータベースとして利用し、以下のものを対象に意味検索を行います。

• OPALリファレンスドキュメント
• トラブルシューティングのランブック

実験的な性質であるものの、サーバーは以下のことを可能にすることで大きな価値を提供します。

• 複数のデータタイプ（ログ、メトリクス、トレース）を使用した包括的なトラブルシューティング
• コンテキストデータ（GitHubのコミット、ビジネスメトリクス、顧客の旅程）との統合
• OPALクエリ、Observeの概念、およびベストプラクティスに関する詳細情報のためのベクトル化されたドキュメントと専用のランブックへのアクセス

主要コンポーネント

📦 インストール

前提条件

• Python 3.8以上
• APIキーを持つPineconeアカウント
• Observe APIの認証情報

インストール手順

まず、リポジトリをクローンします。

git clone https://github.com/rustomax/observe-experimental-mcp.git
cd observe-experimental-mcp

仮想環境を作成し、アクティブ化します。

python3 -m venv .venv
source .venv/bin/activate

必要な依存関係をインストールします。

pip install -r requirements.txt

環境設定

.env.templateを.envにコピーし、値を入力します。

ベクトルデータベースのデータ投入

⚠️ 重要な注意

Pineconeのベクトルインデックスは最終的に一貫性が保たれる性質を持っています。インデックスにデータを投入した後、検索が最新のデータを返すまで数分かかる場合があります。

ドキュメントインデックス

サーバーが意味検索機能を提供する前に、ベクトルデータベースにOPALリファレンスデータを投入する必要があります。

⚠️ 重要

Observeの社員でない場合は、ドキュメントのマークダウンファイルにアクセスできません。この手順については、Observeの担当者に相談してください。

以下のコマンドを実行して、ドキュメントデータベースにデータを投入します。

python populate_docs_index.py

💡 使用提案

以前にインデックスを作成しており、クリーンな状態に戻したい場合は、--forceフラグを使用してインデックスを再作成できます。

このコマンドは、observe-docsディレクトリ内のすべてのマークダウンファイルを処理し、意味検索用のベクトル埋め込みを作成します。スクリプトは以下のことを行います。

• observe-docsディレクトリからマークダウンファイル（ドキュメントとプロンプトの両方）を読み取ります。
• これらのファイルからメタデータとコンテンツを抽出します。
• Pineconeの統合埋め込みモデル（llama-text-embed-v2）を使用して、各ドキュメントの埋め込みを生成します。
• 埋め込みとメタデータをPineconeインデックスに保存します。

オプション:

• --force: インデックスが既に存在する場合でも、強制的に再作成します。
• --verbose: 詳細なログを有効にします。
• --limit <n>: 処理するファイルの数を制限します（0は制限なし）。

スクリプトは、ファイルを処理してPineconeにアップロードする際に進捗バーを表示します。

ランブックインデックス

ランブックのベクトルデータベースにデータを投入するには、以下のコマンドを実行します。

python populate_runbooks_index.py

💡 使用提案

以前にインデックスを作成しており、クリーンな状態に戻したい場合は、--forceフラグを使用してインデックスを再作成できます。

このスクリプトは以下のことを行います。

• runbooksディレクトリ内のすべてのマークダウン（.md）ファイルを見つけます。
• コンテンツを意味的に有意義なセグメント（約1000文字ごと）に分割します。
• Pineconeの統合埋め込みモデルを使用して、各セグメントの埋め込みを生成します。
• 埋め込みとメタデータをランブック用の別のPineconeインデックスに保存します。

オプション:

• --force: インデックスが既に存在する場合でも、強制的に再作成します。
• --runbooks_dir <path>: ランブックディレクトリへのカスタムパスを指定します。

チャンク化のプロセスは、コンテンツの意味を維持しながらベクトル検索を最適化しますが、recommend_runbook関数は完全なランブックを返し、チャンクだけではありません。

実行例:

python ./populate_runbooks_index.py --force

Forcing recreation of index
Deleting existing index: observe-runbooks
Initializing Pinecone client
Creating new Pinecone index with integrated embedding model: observe-runbooks
Waiting for index to be ready...
Connected to Pinecone index: observe-runbooks
Found 11 runbook files
Processing files: 100%|███████████████████████████| 11/11 [00:00<00:00, 5327.02it/s]
Collected 116 chunks from 11 files
Upserting batch 1/2 with 95 records
Successfully upserted batch 1/2
Upserting batch 2/2 with 21 records
Successfully upserted batch 2/2
Total chunks added to Pinecone: 116

💻 使用例

サーバーの起動

python observe_server.py

サーバーはデフォルトでServer-Sent Events (SSE)トランスポートを使用し、ポート8000で起動します。必要に応じて、observe_server.pyファイルでポートとトランスポート方法を変更できます。

利用可能なMCPツール

Observe APIツール

• execute_opal_query: データセット上でOPALクエリを実行します。
• export_worksheet: 柔軟な時間パラメータでObserveのワークシートからデータをエクスポートします（デフォルトは15分間隔）。
• list_datasets: Observeで利用可能なデータセットを一覧表示します。
• get_dataset_info: データセットに関する詳細情報を取得します。
• create_monitor: Observeで新しいモニターを作成します。
• list_monitors: Observeのすべてのモニターを一覧表示します。
• get_monitor: 特定のモニターに関する詳細情報を取得します。

ドキュメントと支援ツール

• get_relevant_docs: Pineconeベクトル検索を使用して、クエリに関連するドキュメントを取得します。

トラブルシューティングツール

• recommend_runbook: ユーザーのクエリを分析し、最も関連するトラブルシューティングランブックを推薦します。

システムツール

• get_system_prompt: Observe MCPサーバーのシステムプロンプトを取得します。

ワークシートエクスポートツール

export_worksheetツールは、複数の時間パラメータオプションを持つ柔軟なワークシートデータエクスポート機能を提供します。

パラメータ

• worksheet_id (必須): エクスポートするワークシートのID
• time_range (オプション): エクスポートの時間範囲（例: "15m", "1h", "24h"）。時間パラメータが指定されない場合は、デフォルトで"15m"になります。
• start_time (オプション): ISO形式の開始時間（例: "2025-07-21T00:00:00Z"）
• end_time (オプション): ISO形式の終了時間（例: "2025-07-22T00:00:00Z"）

時間パラメータの組み合わせ

このツールは、すべての標準的なObserve APIの時間パラメータパターンをサポートしています。

1. 区間のみ (現在時刻を基準): export_worksheet("42566610", time_range="1h")
2. 開始時間と終了時間: export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", end_time="2025-07-22T00:00:00Z")
3. 開始時間 + 区間: export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", time_range="24h")
4. 終了時間 + 区間: export_worksheet("42566610", end_time="2025-07-22T00:00:00Z", time_range="24h")

レスポンス形式

このツールは、NDJSON（改行区切りのJSON）形式でデータを返します。大規模なデータセットの場合は、レスポンスは自動的に切り捨てられ、最初の50行と総行数を示す要約が表示されます。

ベクトルデータベースヘルパー

pinecone_reference_helpers.pyモジュールは、Pineconeベクトルデータベースをクエリするための関数を提供します。

• initialize_pinecone() - Pineconeクライアントを初期化し、インデックスが存在することを確認します。
• get_embedding(pc, text, is_query) - Pineconeの統合埋め込みモデルを使用して、テキストの埋め込みを取得します。
• semantic_search(query, n_results) - Pineconeを使用して意味検索を実行します。
• list_all_entities() - Pineconeインデックス内のすべてのドキュメントを一覧表示します。
• get_document_by_id(doc_id) - IDで特定のドキュメントを取得します。

アーキテクチャと動作原理

このシステムは、マルチインデックスのベクトルデータベースアーキテクチャを使用して、ドキュメント支援とランブック推薦の両方を提供します。主なワークフローは2つあります。インデックス作成プロセスとランタイムクエリプロセスです。

インデックス作成プロセス

この図は、ドキュメントとランブックが処理され、Pineconeベクトルデータベースにロードされる方法を示しています。

ランタイムクエリプロセス

この図は、ユーザーのクエリがランタイムで処理される方法を示しています。

ドキュメント支援フロー

1. LLMアシスタントが、ユーザーのドキュメントクエリをMCPサーバーに送信します。
2. get_relevant_docs関数が呼び出され、クエリが処理されます。
3. システムは、Pineconeの推論APIを使用してクエリの埋め込みを生成します。
4. この埋め込みを使用して、"observe-docs"インデックスから関連するドキュメントチャンクを検索します。
5. システムは、チャンクをソースドキュメントごとにグループ化し、関連性スコアを計算します。
6. 完全なドキュメントがファイルシステムから取得され、関連性の高い順に返されます。

ランブック推薦フロー

1. LLMアシスタントが、ユーザーのトラブルシューティングクエリをMCPサーバーに送信します。
2. recommend_runbook関数が呼び出され、クエリが処理されます。
3. システムは、Pineconeの推論APIを使用してクエリの埋め込みを生成します。
4. この埋め込みを使用して、"observe-runbooks"インデックスから関連するランブックチャンクを検索します。
5. システムは、チャンクをソースランブックごとにグループ化し、平均関連性スコアを計算します。
6. 最も関連性の高い完全なランブックがファイルシステムから取得され、ユーザーに返されます。

ベクトルデータベースアプローチの利点

• 意味理解: ベクトル検索は、キーワードだけでなく、クエリの意味を理解します。
• 曖昧なマッチング: タイプミスや異なる表現でも関連する結果を見つけることができます。
• 関連性ランキング: 結果は意味的な類似性でランク付けされます。
• 拡張性: スキーマを変更することなく、新しいドキュメントを簡単に追加できます。
• マークダウンの直接利用: マークダウンファイルを信頼できる情報源として使用します。
• 統合埋め込み: Pineconeの組み込み埋め込みモデルを使用するため、OpenAI APIキーは必要ありません。
• スケーラビリティ: Pineconeは、管理されたスケーラブルなベクトルデータベースサービスを提供します。
• チャンク化と完全ドキュメント検索: チャンク化によって検索精度を最適化しながら、完全なドキュメント検索によって完全な文脈を提供します。

認証の設定

⚠️ 重要な注意

このセクションをスキップしないでください。全体を読んでください。

このサーバーでは、2種類の認証メカニズムが使用されています。Observe API認証とMCP認証です。

Observe API認証 (Observe APIベアラートークン) - これは、Observeプラットフォームにユーザーを認証するために使用されるトークンのコンテキストを引き継ぎます。このトークンは機密情報と見なされ、MCPユーザーには決して公開されません。

⚠️ 危険区域

上記の結果として、ユーザーがMCPサーバーに認証されると、彼らはObserveで自分自身のアイデンティティを引き継ぐのではなく、Observeトークンを生成したユーザーのアイデンティティを引き継ぐことになります。Observe APIトークンのアクセスを、Observe MCPサーバーのユーザーに利用可能にしたい特定のロールとパーミッションに制限するために、RBACを使用するようにしてください。

MCP認証 (MCPベアラートークン) - これは、ユーザーがMCPサーバーの機能にアクセスして使用するための認証です。このトークンはサーバー管理者によって生成され、Claude Desktopや他のMCPクライアントで使用するためにMCPユーザーに公開されます。

この2層目の認証は、サーバーがMCPユーザーにリソースを大量に消費するAPI（Pineconeなど）を公開しているために必要です。サーバー管理者がアクセスを制御し、リソースの乱用を防止できるようにします。

⚠️ 重要

MCPサーバーの現在の実装には、事前定義されたロール（admin, read, write）による基本的なRBACも含まれています。これらはObserve内のいかなるロールにもマッピングされません。MCPサーバーへのアクセスを制御するために使用されます。

ローカルのみのデプロイ: サーバーを公開アクセスなしでローカルで実行する場合は、observe_server.pyを変更し、MCPクライアント構成からAuthorizationヘッダーを削除することで、MCP認証を無効にできます。

MCP認証の設定

安全な場所（例えば_secureディレクトリ）に秘密鍵と公開鍵のファイルを作成します。

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

これにより、2つのファイルが作成されます。

• private_key.pem - 秘密鍵ファイル。これは秘密にしておく必要があり、MCPベアラートークンを署名するために必要です。
• public_key.pem - 公開鍵ファイル。これをobserve_server.pyファイルに追加する必要があります。

cat public_key.pem

公開鍵をコピーし、.envファイルに追加します。

# Public PEM key for MCP token verification
PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----
<your_public_key_here>
-----END PUBLIC KEY-----"

秘密鍵でベアラートークンに署名します。

./generate_mcp_token.sh 'user@example.com' 'admin,read,write' '4H'

💡 使用提案

トークンの有効期限を短く設定することをおすすめします（日単位ではなく時間単位）。長期間有効なトークンの発行を避け、セキュリティリスクを最小限に抑えてください。

Claude Desktopでの使用

MPCサーバーをローカルで実行している場合は、claude_desktop_config.jsonに以下を追加します。また、サーバーを公開している場合は、URLを指定します。

⚠️ ネットワーク構成に関する注意

MCPクライアントは通常、HTTPアクセスをローカルホストのみに制限しています。インターネットにアクセス可能なデプロイメントの場合は、適切なDNS構成とSSL証明書を持つHTTPSリバースプロキシ（Nginx、Caddyなど）を実装してください。

{
  "mcpServers": {
    "observe-epic": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "http://localhost:8000/sse",
        "--header",
        "Authorization: Bearer bearer_token"
      ]
    }
  }
}

サーバーはデフォルトでポート8000で起動します。必要に応じて、observe_server.pyファイルでポートを変更できます。

💡 パフォーマンスに関する注意

サーバーはデフォルトでServer-Sent Events (SSE)トランスポートを使用し、大きなペイロードでも効率的にレスポンスをストリーミングします。必要に応じて、observe_server.pyファイルでトランスポート方法を変更できます。

起動例:

mcp run ./observe_server.py

Starting observe_server.py
Python version: 3.13.5 (main, Jun 11 2025, 15:36:57) [Clang 15.0.0 (clang-1500.1.0.2.5)]
Python path: ...
Basic imports successful
Attempting to import pinecone module...
Pinecone import successful. Version: 7.0.2
Attempting to import pinecone_reference_helpers...
Successfully imported semantic_search from pinecone_reference_helpers

Python MCP server starting...
[07/22/25 08:50:22] INFO     Starting MCP server 'observe-epic'   server.py:1297
                             with transport 'sse' on                            
                             http://0.0.0.0:8000/sse/                                   

INFO:     Started server process [67344]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Claude Desktopや他のMCPクライアントで、Observe MCPサーバーで利用可能なツールを確認してテストしてみてください。

MCPサーバーの最大限の活用方法

スマートなクライアントLLMを使用する

Observeの公式MCPサーバーとは異なり、現在のプロジェクトは内部でLLMを使用していません。これは現在の設計上の選択であり、将来的に変更される可能性もあればない可能性もあります。代わりに、クライアントLLMが利用可能なツールを最も効果的に使用するために必要な知性を提供することを前提としています。Observe MCPサーバーは、技術的に高度なLLMモデルと連携するように設計されています。特にClaude Sonnet 3.7とClaude Sonnet 4でテストされています。

理想的なイベントフローを理解する

一般的に、LLMが現在のMCPサーバーを使用するための事前定義された方法があります。この望ましいフローを理解することで、Observeから最大限の利益を得るためにLLMにより良い指示を与えることができます。

1. MCPクライアント（Claude Desktopや他のLLM）がMCPサーバーに接続します。
2. MCPクライアントが利用可能なツールとその説明を発見します。
3. MCPサーバーは、モデルにprompts/Observe MCP System Prompt.mdのシステムプロンプトを使用してObserveの専門家として設定するように説得しようとします。
4. LLMはクエリを解析し、どのパスをたどるかを決定します。
   • Observeの機能に関する単純な質問（例: Create tutorial on OPAL window functions）の場合、LLMはget_relevant_docsツールを繰り返し使用して、Pineconeベクトルデータベースで意味検索を行い、応答を理解して生成します。
   • より複雑なトラブルシューティングや調査（例: Find root cause of high CPU usage on production serversやInvestigate slow queries in the database）の場合、まずMCPサーバーに関連するランブックの推薦を依頼し（ランブックのベクトルデータベースインデックスでも意味検索されます）、その後ランブックを使用して調査プロセスをガイドします。
5. 他のツールを使用してObserveクエリを作成して実行し、データセットのリストと情報を取得し、モニターを一覧表示して作成します。困難に直面した場合は、関連するドキュメントを検索して自分自身をガイドしようとします。

システムプロンプトをハードコードする

前述のように、MCPクライアントが最初にMCPサーバーに接続すると、利用可能なツールとその説明を発見し、MCPサーバーはモデルにprompts/Observe MCP System Prompt.mdのシステムプロンプトを使用してObserveの専門家として設定するように説得しようとします。モデルがそれを行えない場合、要求されたタスクを達成するためにより多くの呼び出しが必要になる場合があります。MCPサーバーを最も一貫して使用するために、システムプロンプトをLLMの構成にハードコードし、MCPサーバーにモデルを設定することに依存しないでください。Claude Desktopでの実行例を以下に示します。

効果的なプロンプトを作成する

プロンプトエンジニアリングは依然として有効です！効果的なプロンプトを作成することで、調査を高速化することができます。調査の明確な目的を含め、分析を集中させるために関心のある時間範囲を指定し、調査すべき関連するデータセットやシステムを特定し、上位3つの問題の要約を要求するなど、期待する出力形式を定義します。

また、段階的な開示を使用して、LLMがあなたの環境の心理モデルを構築するのを助けることができます。高レベルな質問から始め、調査の進行に伴って徐々に深く掘り下げます。調査の過程でフィードバックを提供します。LLMが誤った仮定をしたり、ツールを効果的に使用できない場合は、正しい方向に導くようにしてください。

ランブックを使用してLLMをガイドする

必要に応じて、ランブックを自由に作成、更新、または削除してください。あなたの特定の環境やユースケースに合わせて調整します。たとえば、あなたの環境に固有の多数のカスタムデータセットを作成した場合は、LLMが調査でそれらを使用するのを助けるカスタムランブックを作成します。Improve this promptのようなプロンプトを使用して、LLMを使ってランブックを改善します。

LLMにツールの使用を思い出させる

調査プロセスで大量のトークンがLLMのコンテキストウィンドウに投入されるため、LLMは「忘れっぽく」なり、利用可能なツールを効果的に使用しなくなることがあります。たとえば、機能するOPALクエリを作成するのに繰り返し苦労することがあります。get_dataset_infoツール（フィールドのリストとそのタイプを返します）やget_relevant_docsツール（ドキュメント全体で意味検索を行い、関連するチャンクを返します）を使用するように思い出させることで、正しい方向に導くことができます。これらのツールを組み合わせて使用することで、LLMが機能するOPALクエリを作成する能力が大幅に向上します。

メンテナンス

ドキュメントの更新

新しいドキュメントでベクトルデータベースを更新するには、以下の手順を実行します。

1. observe-docsディレクトリにマークダウンファイルを追加または更新します。
2. python populate_pinecone_db.py --forceを実行してインデックスを再構築します。

ランブックの更新

ランブックのベクトルデータベースを更新するには、以下の手順を実行します。

1. runbooksディレクトリにマークダウンファイルを追加または更新します。
2. python populate_runbooks_index.py --forceを実行してインデックスを再構築します。