observe-instrument-mcp

observe-instrument-mcp

ioa-observe-sdk を使用して Python AI エージェントを自動で計装する MCP サーバーです。手作業なしで、OpenTelemetry に基づくトレース、メトリクス、ログを追加します。

Claude Desktop、Cursor、Windsurf など、MCP 互換の AI コーディングアシスタントであればどれでも利用できます。

機能

ツールは 2 つあります。

instrument_agent — Python エージェントのファイルを読み込み、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/ フォルダーに含まれています。

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

エージェントを実行します。

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