# Langfuse Observability MCP

`langfuse-observability-mcp` 是一个只读 MCP Server，让 Codex、Claude Code、
Claude Agent SDK 等 Agent 能够渐进式查询和分析 Langfuse 中的可观测数据。
本项目的首要兼容目标是 **Langfuse Self-hosted v3.175.0**。

```text
Agent -> MCP Tools -> Services -> LangfuseQueryClient -> V3 Adapter
      -> Langfuse 官方 Python SDK -> Langfuse v3.175.0
```

项目将能力分为两层：

- SDK 等价查询：Trace、Session、Observation、Score 和 Metrics 查询。
- Agent 分析：Trace Tree、Trace/Session Summary、错误节点、慢节点、Token/Cost 聚合。

MCP Tools 和 Services 不直接导入 SDK 生成代码，只有 `compat/v3.py` 了解具体 SDK
Namespace。未来升级 Langfuse v4 时可以新增 `compat/v4.py`，而不修改 Tool 和分析逻辑。

## 版本选择与兼容性研究

实现已对照以下源码：

- Langfuse Server `v3.175.0` Tag
- Langfuse 官方 Python SDK `v3.15.0` Tag

两个版本均发布于 2026-05-21。SDK `3.15.0` 提供本项目需要的 v3 查询接口，
因此项目固定使用该版本，避免意外切换到 v4-first API。

Langfuse Server `v3.175.0` 已确认提供：

- `/api/public/traces` 和 `/api/public/traces/{id}`
- `/api/public/sessions` 和 `/api/public/sessions/{id}`
- `/api/public/observations` 和 `/api/public/observations/{id}`（v1）
- `/api/public/v2/scores`
- `/api/public/metrics`（v1/Legacy）

虽然该服务端版本中已经出现 Observations v2 和 Metrics v2，但当前项目不使用它们。
稳定的 v1 接口已经覆盖当前需求，也能避免 MCP 契约过早绑定 v4 的
observations-first 和 Cursor Pagination 语义。

依赖版本：

- Python `>=3.11`
- Langfuse 官方 Python SDK `langfuse==3.15.0`
- MCP 官方 Python SDK `mcp>=1.27,<2`，当前锁定为 `1.28.1`
- MCP Transport：Streamable HTTP

## 安装与运行

需要安装 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。

```bash
cp .env.example .env
make install
make run
```

默认监听地址：

```text
http://0.0.0.0:8000/mcp
```

本机客户端应连接：

```text
http://127.0.0.1:8000/mcp
```

`make run` 会在启动前清除继承的 `ALL_PROXY`、`HTTP_PROXY` 和 `HTTPS_PROXY`
环境变量，使 Langfuse 官方 SDK 直接连接远端实例，不依赖 `socksio`。

## 配置

使用 Langfuse Project API Key：

```env
LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASE_URL=https://langfuse.example.com

LOG_LEVEL=INFO

MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_PATH=/mcp
```

Secret 和 Authorization Header 不会被记录或通过 MCP 返回。日志只包含 Tool 名称、
安全的 ID/Filter、查询耗时、返回数量、分页信息和错误，不记录完整 Input/Output。

跨域默认全部开放，无需配置环境变量。服务返回 `Access-Control-Allow-Origin: *`，
允许所有 Method 和 Header，并向浏览器暴露 `Mcp-Session-Id` 响应头。

Host Header 默认不做白名单限制，也无需配置 `MCP_ALLOWED_HOSTS`。公网部署时应由
反向代理负责 Host 校验、TLS 和身份认证。

本项目当前没有额外实现 MCP 身份认证。部署到非私有网络时，应放在带 TLS 和认证的
反向代理后面，不要直接把 8000 端口暴露到公网。

## MCP 客户端配置

Codex 的 `~/.codex/config.toml`：

```toml
[mcp_servers.langfuse-observability]
url = "http://127.0.0.1:8000/mcp"
```

Claude Code：

```bash
claude mcp add --transport http \
  langfuse-observability http://127.0.0.1:8000/mcp
```

Claude Agent SDK 使用相同的 Streamable HTTP URL。

## Docker 与 Kubernetes

构建并运行：

```bash
make docker-build
make docker-run
```

等价命令：

```bash
docker build -t langfuse-observability-mcp:local .
docker run --rm \
  --name langfuse-observability-mcp \
  --env-file .env \
  -p 8000:8000 \
  langfuse-observability-mcp:local
```

容器以 UID `10001` 的非 root 用户运行，监听 `0.0.0.0:8000`，健康检查通过 TCP
连接探测 MCP 端口。Docker 构建不依赖 uv 基础镜像，而是在 Python 基础镜像中通过
清华 PyPI 镜像安装固定版本 `uv==0.11.8`。镜像内置以下 Pod 排障工具：

```text
curl, dig, nslookup, ip, ping, ss, nc, ps, top, jq, less, vi
```

进入运行中的 Pod：

```bash
kubectl exec -it <pod-name> -- bash
```

常用检查：

```bash
curl -i http://127.0.0.1:8000/mcp
ss -lntp
dig <langfuse-domain>
nc -vz <langfuse-host> 443
ps aux
```

`.dockerignore` 会排除 `.env`、Git 数据、虚拟环境和缓存，真实 Key 只能通过运行时
环境变量或 Kubernetes Secret 注入，不会写入镜像。

## 可用 Tools

| Tool | 用途 |
|---|---|
| `get_trace` | 按 ID 查询 Trace，支持 compact/standard/full 字段裁剪 |
| `list_traces` | 使用 Langfuse v3 原生 Filter 和 Pagination 查询 Trace |
| `get_trace_summary` | Trace 时长、错误、告警、Token、Cost 和慢节点摘要 |
| `get_trace_tree` | 构建有界 Trace Forest，处理多 Root、Orphan 和 Cycle |
| `get_session` | 查询 Session 及其 Trace 引用 |
| `list_sessions` | 使用 v3 原生参数分页查询 Session |
| `get_session_summary` | Session 级 Trace、Observation、错误、Token 和 Cost 摘要 |
| `get_session_trace_list` | 分页获取 Session 下的紧凑 Trace 列表 |
| `get_observation` | 查询单个 Observation，Input/Output 默认不返回 |
| `list_observations` | Observation v1 查询，以及派生的 Session 查询 |
| `get_error_observations` | 查询 ERROR、WARNING 或带 Status Message 的节点 |
| `get_slow_observations` | 按 Duration 倒序查询慢节点 |
| `list_scores` | 使用 v3.175.0 支持的 Score API v2 查询评分 |
| `query_metrics` | 使用 Metrics API v1/Legacy 查询指标 |

## Query Tool 参数

所有 List Tool 保留原生 `page + limit` 分页，并补充：

```text
pagination.has_more
pagination.next_page
```

### list_traces

```text
page, limit, user_id, name, session_id,
from_timestamp, to_timestamp, order_by, tags,
version, release, environment, fields,
raw_filter, detail_level
```

### list_sessions

```text
page, limit, from_timestamp, to_timestamp, environment
```

### list_observations

```text
page, limit, trace_id, session_id, user_id, name,
type, level, parent_observation_id,
from_start_time, to_start_time,
version, environment, raw_filter, detail_level
```

Observation v1 没有原生 `session_id` Filter。项目会严格通过官方 SDK 执行：

```text
按 Session 查询 Trace
-> 获取 Trace IDs
-> 分页查询各 Trace 的 v1 Observations
-> 合并并应用 MCP 分页
```

不会绕过 SDK 手写 REST Client。

### list_scores

```text
page, limit, trace_id, observation_id, session_id,
user_id, name, source, value, operator,
from_timestamp, to_timestamp, environment,
score_ids, config_id, queue_id, data_type,
trace_tags, fields
```

### query_metrics

接收官方 Metrics v1 Query Object：

```text
view, dimensions, metrics, filters,
timeDimension, fromTimestamp, toTimestamp,
orderBy, config
```

`raw_filter` 是 Langfuse 官方 Filter 数组，元素包含 `type`、`column`、`operator`、
`value` 和可选的 `key`。提供 `raw_filter` 时，它优先于对应的简单参数。

字段裁剪规则：

- `compact`：移除 Input、Output、Metadata。
- `standard`：移除 Input、Output。
- `full`：保留 SDK 返回字段。
- `get_observation(include_io=true)`：显式返回 Input/Output。

## Agent 渐进式分析示例

分析慢 Session：

```text
get_session_summary(session_id)
-> get_session_trace_list(session_id)
-> get_trace_summary(trace_id)
-> get_trace_tree(trace_id)
-> get_slow_observations(trace_id=...)
-> 仅在必要时 get_observation(observation_id, include_io=true)
```

查询用户最近的失败请求：

```text
list_traces(
    user_id="user-123",
    from_timestamp="...",
    order_by="timestamp.desc"
)
-> get_trace_summary(trace_id)
-> get_error_observations(trace_id=...)
-> get_observation(observation_id)
```

## Langfuse v3.175.0 Compatibility Matrix

以下能力已核对源码和官方 SDK，并于 2026-07-22 在配置的真实
Langfuse v3.175.0 实例上完成运行验证。

| Capability | v3.175.0 状态 | 官方 SDK 3.15.0 Namespace/Method |
|---|---|---|
| Authentication | 运行验证通过 | `Langfuse(public_key, secret_key, base_url)` |
| `get_trace` | 运行验证通过 | `async_api.trace.get` |
| `list_traces` | 运行验证通过 | `async_api.trace.list` |
| `get_session` | 运行验证通过 | `async_api.sessions.get` |
| `list_sessions` | 运行验证通过 | `async_api.sessions.list` |
| `get_observation` | 运行验证通过，v1 | `async_api.observations.get` |
| `list_observations` | 运行验证通过，v1 | `async_api.observations.get_many` |
| `list_scores` | 运行验证通过，Score v2 | `async_api.score_v_2.get` |
| `query_metrics` | 运行验证通过，Legacy/Limited | `async_api.metrics.metrics`（v1） |

Metrics 明确限制为 v1 Query Model 及其 View/Measure，不调用 Metrics v2。

## 测试与质量检查

```bash
make test
make test-unit
make test-integration
make lint
make typecheck
make check
```

真实兼容测试默认跳过。执行方式：

```bash
LANGFUSE_COMPAT_TEST=1 \
LANGFUSE_EXPECTED_SERVER_VERSION=3.175.0 \
LANGFUSE_PUBLIC_KEY=pk-lf-... \
LANGFUSE_SECRET_KEY=sk-lf-... \
LANGFUSE_BASE_URL=https://langfuse.example.com \
make test-compat
```

`LANGFUSE_EXPECTED_SERVER_VERSION` 是显式保护，避免误将其他版本的部署认证为
v3.175.0。

Unit Test 覆盖：

- Trace Tree
- 2000+ Observation
- Cycle Parent
- Orphan Node
- Pagination
- Query Filter Mapping
- Detail Level 和 Input/Output 裁剪
- Session Summary
- Error/Slow Observation

Integration Test 验证官方 SDK 的 Generated Client Namespace 和 Method 签名。
Compatibility Test 验证真实 Langfuse v3.175.0 实例。

## 已知限制

- 分析聚合最多采集 10,000 条 Trace/Observation，达到上限时返回 `truncated=true`。
- Session Observation 查询可能产生较多官方 SDK 请求，大型 Session 应先使用 Summary，
  再缩小到具体 Trace。
- Trace Tree 会限制 Depth 和 Children，并返回省略数量。
- Metrics 仅使用 v1，不暴露 Metrics v2-only View 或 Measure。
- Observation v1 使用 Page Pagination，没有 Fields Selection 和原生 Session Filter。
- `get_session` 的 Trace 由后端不分页返回；大型 Session 推荐使用
  `get_session_summary` 和 `get_session_trace_list`。

## Langfuse v4 升级路径

升级时新增 `compat/v4.py`，实现相同的 `LangfuseQueryAdapter`，并在 Client 构造阶段
切换 Adapter，然后更新 Compatibility Test 和 Matrix。

届时 v4 Adapter 可以使用：

- Observations API v2
- Metrics API v2
- Cursor Pagination
- 原生 Fields Selection

MCP Tools、Services、Agent 调用语义和分析算法无需修改。

## Makefile 命令

```text
make install
make run
make docker-build
make docker-run
make test
make test-unit
make test-integration
make test-compat
make lint
make format
make typecheck
make check
make clean
```

项目仅使用 uv 管理依赖，不维护 `requirements.txt`。
项目级 uv 默认索引已配置为清华 PyPI 镜像：

```text
https://pypi.tuna.tsinghua.edu.cn/simple
```