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 参考数据填充向量数据库。

python populate_docs_index.py

注意：

• 如果你不是 Observe 员工，将无法访问文档 markdown 文件，请联系你的 Observe 代表获取帮助。
• 如果你之前已经创建了索引，并且想要重新开始，可以使用 --force 标志重新创建索引。

此脚本将处理 observe-docs 目录中的所有 markdown 文件，并为语义搜索创建向量嵌入。脚本将：

• 从 observe-docs 目录（包括文档和提示）读取 markdown 文件。
• 从这些文件中提取元数据和内容。
• 使用 Pinecone 的集成嵌入模型（llama-text-embed-v2）为每个文档生成嵌入。
• 将嵌入和元数据存储在 Pinecone 索引中。

选项：

• --force：即使索引已经存在，也强制重新创建。
• --verbose：启用详细日志记录。
• --limit <n>：限制要处理的文件数量（0 表示无限制）。

故障排除手册索引

python populate_runbooks_index.py

注意：如果你之前已经创建了索引，并且想要重新开始，可以使用 --force 标志重新创建索引。

此脚本将：

• 查找 runbooks 目录中的所有 markdown (.md) 文件。
• 将内容分割成有语义意义的片段（每个片段约 1000 个字符）。
• 使用 Pinecone 的集成嵌入模型为每个片段生成嵌入。
• 将嵌入和元数据存储在一个单独的 Pinecone 索引中。

选项：

• --force：即使索引已经存在，也强制重新创建。
• --runbooks_dir <path>：指定故障排除手册目录的自定义路径。

运行服务器

python observe_server.py

服务器默认使用 Server-Sent Events (SSE) 传输协议，运行在 8000 端口。如果需要，可以在 observe_server.py 文件中修改端口和传输方法。

✨ 主要特性

• 直接交互：以对大语言模型（LLM）友好的方式直接与 Observe 平台交互。
• 数据安全：避免使用 LLM 进行内部功能，防止私有数据泄露。
• 功能丰富：支持执行 OPAL 查询、导出工作表数据、列出和检索数据集信息、提供 OPAL 查询编写协助以及管理监视器等功能。
• 语义搜索：利用 Pinecone 作为向量数据库，对 OPAL 参考文档和故障排除手册进行语义搜索。

📦 安装指南

请参考上述快速开始部分的安装步骤。

💻 使用示例

基础用法

执行 OPAL 查询

# 假设存在一个可以调用 execute_opal_query 函数的客户端
execute_opal_query("your_opal_query")

导出工作表数据

# 仅指定时间范围
export_worksheet("42566610", time_range="1h")
# 指定开始和结束时间
export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", end_time="2025-07-22T00:00:00Z")

高级用法

故障排除

# 假设存在一个可以调用 recommend_runbook 函数的客户端
recommend_runbook("Find root cause of high CPU usage on production servers")

📚 详细文档

可用的 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"）。

时间参数组合

• 仅间隔（相对于当前时间）：export_worksheet("42566610", time_range="1h")
• 开始和结束时间：export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", end_time="2025-07-22T00:00:00Z")
• 开始时间 + 间隔：export_worksheet("42566610", start_time="2025-07-21T00:00:00Z", time_range="24h")
• 结束时间 + 间隔：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. 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. 从文件系统中检索最相关的完整故障排除手册并返回给用户。

向量数据库方法的优势

• 语义理解：向量搜索理解查询的含义，而不仅仅是关键词。
• 模糊匹配：即使查询存在拼写错误或不同的表述方式，也能找到相关结果。
• 相关性排序：结果按语义相似度排序。
• 可扩展性：无需更改架构即可轻松添加新文档。
• 直接使用 Markdown：使用 Markdown 文件作为事实来源。
• 集成嵌入：使用 Pinecone 的内置嵌入模型，无需 OpenAI API 密钥。
• 可伸缩性：Pinecone 提供托管的、可扩展的向量数据库服务。
• 分段与完整文档检索：通过分段优化搜索准确性，同时通过完整文档检索提供完整上下文。

📄 许可证

文档中未提及相关信息。

⚠️ 重要提示

这是一个实验性且不受支持的 MCP 服务器，专为与 Observe AI 设计合作伙伴进行测试和协作而创建。Observe 对该服务器的任何使用不承担任何责任，也不会以任何方式提供支持。Observe 正在开发一个单独的生产就绪 MCP 服务器。

此服务器使用两种身份验证机制：Observe API 身份验证和 MCP 身份验证。Observe API 身份验证使用的令牌继承了创建该令牌的用户在 Observe 平台上的上下文，该令牌应被视为机密信息，不会向 MCP 用户暴露。MCP 身份验证使用的令牌由服务器管理员生成，并向 MCP 用户暴露，例如用于在 Claude Desktop 或其他 MCP 客户端中使用。

请务必阅读并理解身份验证部分的内容，不要跳过。

💡 使用建议

• 使用智能客户端 LLM：该项目假设客户端 LLM 将提供必要的智能，以最有效地使用可用工具。建议使用技术能力较强的 LLM 模型，如 Claude Sonnet 3.7 和 Claude Sonnet 4。
• 理解理想的事件流程：了解 LLM 使用 MCP 服务器的理想流程，有助于更好地指导 LLM 发挥 Observe 的最大作用。
• 硬编码系统提示：为确保最一致地使用 MCP 服务器，建议将系统提示硬编码到 LLM 配置中，而不是依赖 MCP 服务器来配置模型。
• 编写有效提示：通过编写有效的提示，可以加快调查过程。提示应包括明确的调查目标、指定感兴趣的时间范围、识别相关的数据集或系统以及定义预期的输出格式。
• 使用故障排除手册指导 LLM：可以根据需要创建、更新或删除故障排除手册，以适应特定的环境或用例。还可以使用 LLM 改进故障排除手册。
• 提醒 LLM 使用工具：由于在调查过程中大量令牌被推送到 LLM 的上下文窗口中，LLM 可能会“忘记”有效使用可用工具。可以通过提醒 LLM 使用相关工具来引导其正确执行任务。