observe-instrument-mcp

observe-instrument-mcp

一个 MCP 服务，可使用 ioa-observe-sdk 自动为 Python AI Agent 添加检测能力，无需手动操作，即可添加基于 OpenTelemetry 的追踪、指标和日志。

适用于任何兼容 MCP 的 AI 编码助手：Claude Desktop、Cursor、Windsurf 等。

功能

提供两个工具：

instrument_agent — 读取 Python Agent 文件，为其添加完整的 observe SDK 检测，然后写回文件并返回更改摘要。修改前会创建 .bak 备份。

check_instrumentation — 检查文件中缺失的检测配置，但不会修改文件。

支持的框架：LlamaIndex、LangGraph、CrewAI、原始 OpenAI SDK。

安装

pip install observe-instrument-mcp
# or
uv add observe-instrument-mcp

需要提供所选 LLM 提供商的 API 密钥。默认使用 Claude（ANTHROPIC_API_KEY）。请参阅下方的支持的提供商。

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Cursor

添加到项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

示例

examples/ 文件夹中包含可直接使用的、未经检测配置的 Agent 文件：

examples/
  single-agent/
    openai-sdk-example.py      # OpenAI SDK customer support agent
    langgraph-example.py       # LangGraph currency converter
    llama-index-example.py     # LlamaIndex math agent
    crewai-example.py          # CrewAI research crew
  multi-agent/
    openai-sdk-multi-agent-example.py   # OpenAI SDK orchestrator pipeline
    langgraph-multi-agent-example.py    # LangGraph supervisor pattern
    llama-index-multi-agent-example.py  # LlamaIndex research + writing pipeline
    crewai-multi-agent-example.py       # CrewAI research + publishing crews

使用方法

配置完成后，向 AI 助手提出请求：

Instrument my agent with the observe SDK: path/to/my_agent.py

Check what observe SDK instrumentation is missing from path/to/my_agent.py

环境变量

变量	描述
LLM_MODEL	要使用的模型（默认值：claude-sonnet-4-6）。请参阅下方的提供商表。
ANTHROPIC_API_KEY	Anthropic 模型必需
OPENAI_API_KEY	OpenAI 模型必需
GEMINI_API_KEY	Google Gemini 模型必需
GROQ_API_KEY	Groq 模型必需

支持的提供商

提供商	密钥变量	LLM_MODEL 示例
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-6
OpenAI	OPENAI_API_KEY	gpt-4o
Google Gemini	GEMINI_API_KEY	gemini/gemini-2.0-flash
Groq	GROQ_API_KEY	groq/llama-3.3-70b
Ollama（本地，免费）	无	ollama/llama3.2

添加检测配置后

在项目中安装 SDK：

pip install ioa-observe-sdk
# or
uv add ioa-observe-sdk

启动可观测性技术栈（OTel Collector + ClickHouse）：

cd path/to/observe/deploy
docker compose up -d

运行 Agent：

OPENAI_API_KEY=sk-... OTLP_HTTP_ENDPOINT=http://localhost:4318 python my_agent.py

查询追踪记录：

docker exec -it clickhouse-server clickhouse-client --user admin --password admin

SELECT SpanName, ServiceName, Duration / 1000000. AS ms, Timestamp
FROM otel_traces
ORDER BY Timestamp DESC
LIMIT 20;

开发

git clone https://github.com/alanzha2/observe-instrument-mcp
cd observe-instrument-mcp
pip install -e .

# Test the server locally
mcp dev observe_instrument_mcp/server.py

许可证

Apache-2.0