Metadata-Version: 2.4
Name: observe-instrument-mcp
Version: 0.1.0
Summary: MCP server that instruments Python AI agents with the ioa-observe-sdk
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/agntcy/observe
Project-URL: Repository, https://github.com/agntcy/observe
Keywords: mcp,observability,opentelemetry,agents,langgraph,llama-index,crewai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: python-dotenv>=1.0.0

# observe-instrument-mcp

An MCP server that automatically instruments Python AI agents with the [ioa-observe-sdk](https://github.com/agntcy/observe) — adding OpenTelemetry-based tracing, metrics, and logs with zero manual effort.

Works with any MCP-compatible AI coding assistant: Claude Desktop, Cursor, Windsurf, and others.

## What it does

Two tools:

**`instrument_agent`** — reads a Python agent file, applies full observe SDK instrumentation, writes it back, and returns a summary of changes. Creates a `.bak` backup before modifying.

**`check_instrumentation`** — audits a file for missing instrumentation without modifying it.

Supported frameworks: LlamaIndex, LangGraph, CrewAI, raw OpenAI SDK.

## Installation

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

Requires an `ANTHROPIC_API_KEY` — the server calls Claude to apply instrumentation.

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

### Cursor

Add to `.cursor/mcp.json` in your project:

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

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

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

## Usage

Once configured, ask your AI assistant:

```
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
```

## Environment variables

| Variable | Description |
|---|---|
| `LLM_MODEL` | Model to use (default: `claude-sonnet-4-6`). See provider table below. |
| `ANTHROPIC_API_KEY` | Required for Anthropic models |
| `OPENAI_API_KEY` | Required for OpenAI models |
| `GEMINI_API_KEY` | Required for Google Gemini models |
| `GROQ_API_KEY` | Required for Groq models |

### Supported providers

| Provider | Key variable | `LLM_MODEL` example |
|---|---|---|
| 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 (local, free) | none | `ollama/llama3.2` |

## After instrumentation

Install the SDK in your project:

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

Start the observability stack (OTel Collector + ClickHouse):

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

Run your agent:

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

Query traces:

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

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

## Development

```bash
git clone https://github.com/agntcy/observe
cd observe-instrument-mcp
pip install -e ".[dev]"

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

## License

Apache-2.0
