Observe Experimental MCP

🚀 Observe MCP Server

Observe MCP Server 是一個模型上下文協議（MCP）服務器，通過向量搜索提供對 Observe API 功能、OPAL 查詢協助和故障排除手冊的訪問。

🚀 快速開始

前提條件

• 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 並填寫相應的值。

填充向量數據庫

文檔索引

在服務器提供語義搜索功能之前，需要用 OPAL 參考數據填充向量數據庫。

重要提示：如果你不是 Observe 員工，將無法訪問文檔 markdown 文件。請聯繫你的 Observe 代表獲取此步驟的幫助。

運行以下命令填充文檔數據庫：

python populate_docs_index.py

注意：如果你之前已經創建了索引，並且想重新開始，可以使用 --force 標誌重新創建索引。

此腳本將處理 observe-docs 目錄中的所有 markdown 文件，併為語義搜索創建向量嵌入。腳本將：

• 從 observe-docs 目錄讀取 markdown 文件（包括文檔和提示）
• 從這些文件中提取元數據和內容
• 使用 Pinecone 的集成嵌入模型（llama-text-embed-v2）為每個文檔生成嵌入
• 將嵌入和元數據存儲在 Pinecone 索引中

選項：

• --force：即使索引已經存在，也強制重新創建
• --verbose：啟用詳細日誌記錄
• --limit <n>：限制要處理的文件數量（0 表示無限制）

腳本在處理文件並上傳到 Pinecone 時會顯示進度條。

故障排除手冊索引

要填充故障排除手冊向量數據庫，請運行：

python populate_runbooks_index.py

注意：如果你之前已經創建了索引，並且想重新開始，可以使用 --force 標誌重新創建索引。

此腳本將：

• 在 runbooks 目錄中查找所有 markdown（.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 文件中修改端口和傳輸方法。

✨ 主要特性

用途

本服務器旨在與技術能力較強的大語言模型（LLM）配合使用，特別是與 Claude Sonnet 3.7 和 Claude Sonnet 4 進行了測試。與傳統聊天機器人不同，此 MCP 服務器具有以下特點：

• 以對大語言模型友好的方式直接與 Observe 平臺進行交互
• 避免使用大語言模型進行內部功能，以防止私有數據洩露
• 作為第三方大語言模型與你的 Observe 數據之間的安全橋樑

⚠️ 重要免責聲明：這是一個實驗性且不受支持的 MCP 服務器，專為與 Observe AI 設計合作伙伴進行測試和協作而創建。Observe 對該服務器的任何使用不承擔任何責任，也不以任何方式提供支持。Observe 正在開發一個單獨的生產就緒的 MCP 服務器。

概述

該 MCP 服務器通過以下方式實現與 Observe 平臺的無縫交互：

• 執行 OPAL 查詢
• 以靈活的時間參數導出工作表數據
• 列出和檢索數據集信息
• 提供 OPAL 查詢編寫協助
• 管理監視器（列出和創建）

服務器利用 Pinecone 作為向量數據庫進行語義搜索，搜索範圍包括：

• OPAL 參考文檔
• 故障排除手冊

儘管該服務器處於實驗階段，但它通過以下方式提供了顯著的價值：

• 使用多種數據類型（日誌、指標、跟蹤）進行全面的故障排除
• 與上下文數據（GitHub 提交、業務指標、客戶旅程）集成
• 訪問矢量化文檔和專業手冊，以獲取有關 OPAL 查詢、Observe 概念和最佳實踐的深入信息

優勢

• 語義理解：向量搜索理解查詢的含義，而不僅僅是關鍵詞
• 模糊匹配：即使存在拼寫錯誤或不同的措辭，也能找到相關結果
• 相關性排序：結果按語義相似度排序
• 可擴展性：無需更改架構即可輕鬆添加新文檔
• 直接使用 Markdown：使用 markdown 文件作為事實來源
• 集成嵌入：使用 Pinecone 的內置嵌入模型，無需 OpenAI API 密鑰
• 可擴展性：Pinecone 提供託管的、可擴展的向量數據庫服務
• 分割與完整文檔檢索：通過分割優化搜索準確性，同時通過完整文檔檢索提供完整上下文

📦 安裝指南

前提條件

• 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 並填寫相應的值。

填充向量數據庫

文檔索引

在服務器提供語義搜索功能之前，需要用 OPAL 參考數據填充向量數據庫。

重要提示：如果你不是 Observe 員工，將無法訪問文檔 markdown 文件。請聯繫你的 Observe 代表獲取此步驟的幫助。

運行以下命令填充文檔數據庫：

python populate_docs_index.py

注意：如果你之前已經創建了索引，並且想重新開始，可以使用 --force 標誌重新創建索引。

此腳本將處理 observe-docs 目錄中的所有 markdown 文件，併為語義搜索創建向量嵌入。腳本將：

• 從 observe-docs 目錄讀取 markdown 文件（包括文檔和提示）
• 從這些文件中提取元數據和內容
• 使用 Pinecone 的集成嵌入模型（llama-text-embed-v2）為每個文檔生成嵌入
• 將嵌入和元數據存儲在 Pinecone 索引中

選項：

• --force：即使索引已經存在，也強制重新創建
• --verbose：啟用詳細日誌記錄
• --limit <n>：限制要處理的文件數量（0 表示無限制）

腳本在處理文件並上傳到 Pinecone 時會顯示進度條。

故障排除手冊索引

要填充故障排除手冊向量數據庫，請運行：

python populate_runbooks_index.py

注意：如果你之前已經創建了索引，並且想重新開始，可以使用 --force 標誌重新創建索引。

此腳本將：

• 在 runbooks 目錄中查找所有 markdown（.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 文件中修改端口和傳輸方法。

💻 使用示例

基礎用法

# 運行服務器
python observe_server.py

高級用法

# 修改端口和傳輸方法
# 在 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 服務器的系統提示

工作表導出工具

參數

• 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 獲取特定文檔

架構和工作原理

該系統使用多索引向量數據庫架構，以提供文檔協助和故障排除手冊推薦。主要有兩個工作流程：索引過程和運行時查詢過程。

索引過程

此圖展示了文檔和故障排除手冊如何被處理並加載到 Pinecone 向量數據庫中：

運行時查詢過程

此圖展示了用戶查詢在運行時如何被處理：

文檔協助流程

1. 大語言模型助手向 MCP 服務器發送用戶的文檔查詢
2. 調用 get_relevant_docs 函數處理查詢
3. 系統使用 Pinecone 的推理 API 為查詢生成嵌入
4. 使用此嵌入在 "observe-docs" 索引中搜索相關的文檔片段
5. 系統按源文檔對片段進行分組並計算相關性得分
6. 從文件系統中檢索完整文檔並按相關性排序返回

故障排除手冊推薦流程

1. 大語言模型助手向 MCP 服務器發送用戶的故障排除查詢
2. 調用 recommend_runbook 函數處理查詢
3. 系統使用 Pinecone 的推理 API 為查詢生成嵌入
4. 使用此嵌入在 "observe-runbooks" 索引中搜索相關的故障排除手冊片段
5. 系統按源故障排除手冊對片段進行分組並計算平均相關性得分
6. 從文件系統中檢索最相關的完整故障排除手冊並返回給用戶

充分利用 MCP 服務器

使用智能客戶端大語言模型

與 Observe 的官方 MCP 服務器不同，當前項目在底層不使用大語言模型。這是當前的設計選擇，未來可能會改變。相反，它假設客戶端大語言模型將提供必要的智能，以最有效地使用可用工具。Observe MCP 服務器旨在與技術能力較強的大語言模型配合使用，特別是與 Claude Sonnet 3.7 和 Claude Sonnet 4 進行了測試。

理解理想的事件流程

一般來說，大語言模型使用當前 MCP 服務器有一個預定義的方式。理解這個期望的流程可以幫助你更好地指導大語言模型，以充分利用 Observe。

1. MCP 客戶端（例如 Claude Desktop 或任何其他大語言模型）連接到 MCP 服務器
2. MCP 客戶端發現可用的工具及其描述
3. MCP 服務器嘗試說服模型使用 prompts/Observe MCP System Prompt.md 中的系統提示，將自己配置為 Observe 專家
4. 大語言模型解析查詢並決定遵循的路徑：
   • 對於與 Observe 功能相關的簡單問題（例如 Create tutorial on OPAL window functions），大語言模型將反覆使用 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 服務器，將系統提示硬編碼到你的大語言模型配置中，不要依賴 MCP 服務器來配置模型。以下是在 Claude Desktop 中如何進行此操作的示例：

編寫有效的提示

提示工程仍然適用！你可以通過編寫有效的提示來加快調查速度，包括明確調查的目標、指定感興趣的時間範圍以集中分析、識別應檢查的相關數據集或系統，並定義預期的輸出格式，例如請求包含前 3 個問題的摘要。

你還可以使用漸進式披露來幫助大語言模型構建你的環境的心理模型。從高層次問題開始，根據發現逐步深入。在調查過程中提供反饋。當大語言模型做出錯誤假設或無效使用工具時，引導它回到正確的方向。

使用故障排除手冊指導大語言模型

你可以根據需要自由創建、更新或刪除故障排除手冊。根據你的特定環境或用例進行調整。例如，如果你創建了一些特定於你的環境的自定義數據集，可以創建一個自定義故障排除手冊，幫助大語言模型在調查中使用它們。使用大語言模型通過 Improve this prompt 類型的提示來改進你的故障排除手冊。

提醒大語言模型使用工具

由於在調查過程中大量的令牌被推到大語言模型的上下文窗口中，大語言模型可能會變得“健忘”，並停止有效使用可用的工具。例如，它可能會反覆難以編寫有效的 OPAL 查詢。你可以通過提醒它使用 get_dataset_info 工具（該工具返回字段列表及其類型）和 get_relevant_docs 工具（該工具在文檔中進行語義搜索並返回相關片段）來引導它回到正確的方向。結合使用這些工具可以顯著提高大語言模型編寫有效 OPAL 查詢的能力。

維護

更新文檔

要使用新文檔更新向量數據庫：

1. 在 observe-docs 目錄中添加或更新 markdown 文件
2. 運行 python populate_pinecone_db.py --force 重建索引

更新故障排除手冊

要更新故障排除手冊向量數據庫：

1. 在 runbooks 目錄中添加或更新 markdown 文件
2. 運行 python populate_runbooks_index.py --force 重建索引

🔧 技術細節

關鍵組件

組件	描述
observe_server.py	帶有 Observe API 工具的主 MCP 服務器實現
pinecone_reference_helpers.py	用於訪問 Pinecone 向量數據庫的輔助函數
populate_docs_index.py	將 observe-docs 中的 markdown 文件導入 Pinecone 的腳本
populate_runbooks_index.py	將 runbooks 中的故障排除手冊導入 Pinecone 的腳本
runbooks/	包含故障排除手冊的目錄
observe-docs/	包含 Observe 文檔 markdown 文件的目錄（公共倉庫中不包含）
generate_mcp_token.sh	生成 MCP 令牌的腳本

認證設置

有兩種類型的認證機制用於此服務器：Observe API 認證和 MCP 認證。

Observe API 認證（Observe API 承載令牌）

這繼承了用於對創建令牌的用戶進行 Observe 平臺認證的令牌的上下文。此令牌應被視為機密信息，永遠不會暴露給 MCP 用戶。

⚠️ 危險區域：上述情況的後果是，一旦用戶通過 MCP 服務器進行認證，他們將不會在 Observe 中使用自己的身份，而是使用生成 Observe 令牌的用戶的身份。請確保使用基於角色的訪問控制（RBAC），並將 Observe API 令牌的訪問權限限制為你希望提供給 Observe MCP 服務器用戶的特定角色和權限。

MCP 認證（MCP 承載令牌）

這是用於授權用戶訪問和使用 MCP 服務器功能的認證。此令牌由服務器管理員生成，並暴露給 MCP 用戶，例如在 Claude Desktop 或其他 MCP 客戶端中使用。

第二層認證是必要的，因為服務器向 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

這將創建兩個文件：

• private_key.pem：私鑰文件。請妥善保管，你將需要它來簽署 MCP 承載令牌。
• public_key.pem：公鑰文件。你需要將其添加到 observe_server.py 文件中。

cat public_key.pem

複製公鑰並將其添加到 .env 文件中：

# 用於 MCP 令牌驗證的公共 PEM 密鑰
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 服務器中可用的工具。

📄 許可證

文檔中未提及相關內容，故跳過該章節。