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 服务器中可用的工具。

📄 许可证

文档中未提及相关内容，故跳过该章节。