项目简介

Langfuse MCP 服务是一个基于 Model Context Protocol (MCP) 构建的后端应用，旨在将 Langfuse 平台提供的遥测数据（如 LLM 调用追踪、观测、会话等）以标准化工具的形式暴露给大型语言模型（LLM）客户端。通过此服务，LLM 可以通过调用工具获取和分析 Langfuse 中的应用行为数据，从而增强其对外部世界的感知和执行能力。

主要功能点

数据查询: 提供丰富的工具，可以查询 Langfuse 中的追踪（Traces）、观测（Observations）、会话（Sessions）等关键遥测数据。例如，你可以查询最近的错误，获取特定会话的详细信息，或检索用户的所有会话。
异常发现: 允许 LLM 发现应用中发生的异常，并可以按文件或其他维度进行分组，帮助 LLM 理解和诊断问题。
灵活输出: 支持多种数据输出模式，包括紧凑模式（compact）和完整 JSON 字符串模式（full_json_string），甚至可以将结果写入文件，以适应不同场景的需求。
集成 Langfuse: 封装了 Langfuse v3 API 客户端，使 LLM 能够无缝访问和利用 Langfuse 中的丰富数据。

安装步骤

安装 Python: 确保你的系统已安装 Python 3.10 或更高版本。
安装 'uv': 推荐使用 'uv' 作为包管理器和运行器，它提供了比 'pip' 和 'python' 更快的性能。如果尚未安装，请通过以下命令安装：
```
pip install uv
```

安装 Langfuse MCP 服务:

uv pip install langfuse-mcp

或者，如果你想从源代码安装或进行开发：

git clone https://github.com/avivsinai/langfuse-mcp.git
cd langfuse-mcp
uv pip install .

服务器配置

Langfuse MCP 服务器通过命令行参数接收 Langfuse 凭据。MCP 客户端（例如 'mcp' 命令行工具或集成到 LLM 应用中的 MCP 客户端库）需要知道如何启动这个服务器。你需要在 MCP 客户端的配置文件中声明如何启动 Langfuse MCP 服务。以下是一个典型的 MCP 客户端配置示例（JSON 格式）：

{
  "servers": {
    "langfuse": {
      "command": "uv",
      "args": [
        "run",
        "-m", "langfuse_mcp",
        "--public-key", "YOUR_LANGFUSE_PUBLIC_KEY",  // 请替换为你的 Langfuse 公钥
        "--secret-key", "YOUR_LANGFUSE_SECRET_KEY",  // 请替换为你的 Langfuse 私钥
        "--host", "https://cloud.langfuse.com",      // (可选) Langfuse API 主机地址，默认为官方云服务
        "--log-level", "INFO",                       // (可选) 日志级别，可选 DEBUG, INFO, WARNING, ERROR, CRITICAL
        "--log-to-console", "true"                   // (可选) 是否将日志输出到控制台
      ],
      "env": {
        // (可选) 如果希望通过环境变量安全地提供凭据，可以在这里配置，例如：
        // "LANGFUSE_PUBLIC_KEY": "your_public_key_from_env",
        // "LANGFUSE_SECRET_KEY": "your_secret_key_from_env"
      }
    }
  }
}

请将 'YOUR_LANGFUSE_PUBLIC_KEY' 和 'YOUR_LANGFUSE_SECRET_KEY' 替换为你的实际 Langfuse 凭据。这些通常从 Langfuse 控制台获取，并建议通过环境变量或客户端的安全机制来管理。

基本使用方法

一旦 MCP 客户端配置好并启动了 Langfuse MCP 服务器，LLM 就可以通过 JSON-RPC 调用服务器提供的工具。以下是一个调用 'fetch_traces' 工具来获取最近 Langfuse 追踪数据的示例：

启动 MCP 客户端: 根据你使用的 MCP 客户端库或工具启动会话。
初始化会话: 客户端会向服务器发送初始化请求。

调用工具: LLM 通过客户端调用工具，例如获取过去 60 分钟内最新的 5 个追踪：

# 假设 session 是一个已初始化的 mcp.ClientSession 实例
result = await session.call_tool(
    "fetch_traces",
    {
        "age": 60,  # 过去 60 分钟
        "limit": 5, # 限制 5 条
        "include_observations": True, # 包含观测数据
        "output_mode": "compact" # 紧凑输出模式
    }
)
# result 将包含 Langfuse 追踪数据的 JSON 响应
# 你可以通过 result.content[0].text 获取原始文本内容，然后解析 JSON
print(result.content[0].text)

解析结果: LLM 接收 JSON 响应并进行解析，以获取所需的遥测数据。

更多工具（如 'find_exceptions', 'fetch_observations' 等）可根据实际需求调用，具体参数和功能请参考 MCP 客户端的工具声明或项目源代码。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息