langfuse-trace-mcp

# langfuse-trace-mcp 用于分析 Langfuse Trace、Session 和 badcase 的只读 Python MCP 服务，通过 stdio 提供六个工具。服务负责查询、分页和正文切片，分析由 Codex、Claude 等调用方完成；工具内部不调用大模型。 支持按 Trace ID、Session ID 或时间范围查询，先返回摘要，再按需分页读取节点和正文，减少一次查询带来的 token 消耗。 Python 分发包名为 `langfuse-trace-mcp`，命令行入口为 `langfuse-mcp`，Python 模块名为 `langfuse_mcp`。 ## 1. 从 PyPI 安装 准备好以下内容： - [uv](https://docs.astral.sh/uv/getting-started/installation/)（包含 `uvx`）。已有 uv 时无需重新安装。 - 运行客户端的机器能够下载 PyPI 依赖，并访问 Langfuse。 - 同一个 Langfuse 项目的 Public Key 和 Secret Key，可从该项目的 API Keys 设置中获取。 在任意目录执行以下命令，从 [PyPI](https://pypi.org/project/langfuse-trace-mcp/) 安装并检查启动入口： ```bash uvx --python 3.12 \ --from langfuse-trace-mcp==0.1.0.post1 \ langfuse-mcp --help ``` `uvx` 首次运行时会自动创建隔离环境、安装包及其依赖，后续复用缓存。`--python 3.12` 指定运行时；本机缺少该版本时，uv 默认会自动下载。运行依赖包含官方 MCP Python SDK 和 httpx，服务直接调用 Langfuse Public API。 正常输出应包含 `--base-url`、`--public-key`、`--secret-key` 三个参数。这个检查只启动命令行帮助，不连接 Langfuse。 包名与命令名不同：`--from langfuse-trace-mcp==0.1.0.post1` 指定安装来源，后面的 `langfuse-mcp` 是执行入口。客户端配置中也需要保留这一组合。 以下示例固定使用 `0.1.0.post1`。升级时，将配置中的版本号改为已发布的新版本，先运行对应版本的 `--help` 完成安装，再重启客户端。 ## 2. 在客户端中配置 服务通过 **stdio** 通信，由客户端自动启动和管理进程，无需先手动启动或使用 `nohup` 常驻后台。它不提供可填写到远程 MCP 连接框的 HTTP 地址。 所有客户端使用相同的三个启动参数： | 参数 | 填写内容 | | --- | --- | | `--base-url` | Langfuse 服务地址，如 `https://langfuse.example.com`；不要追加 `/api/public` | | `--public-key` | Langfuse 项目的 Public Key | | `--secret-key` | 同一项目的 Secret Key | 下面的地址和密钥都是占位符，使用前请替换。连接凭据在启动时传入，工具调用中无需传入凭据或 `environment`。 配置中的 `command` 使用 `uvx`。如果桌面客户端找不到它，请查出实际路径，并将 `command` 改为该绝对路径： | 系统 | 查找 uvx 的命令 | | --- | --- | | macOS / Linux | `command -v uvx` | | Windows PowerShell | `(Get-Command uvx).Source` | Windows 的 JSON / TOML 配置中可用 `/` 表示路径分隔符，例如 `C:/Users/你的用户名/.local/bin/uvx.exe`。 ### Codex 桌面客户端 / CLI 打开 `~/.codex/config.toml`，添加以下配置；若已有 `[mcp_servers.langfuse]`，修改原条目即可： ```toml [mcp_servers.langfuse] command = "uvx" args = [ "--python", "3.12", "--from", "langfuse-trace-mcp==0.1.0.post1", "langfuse-mcp", "--base-u…