Surfa MCP

Surfa MCP服务器

  

查询您的 Surfa分析 通过Claude Desktop、ChatGPT或任何兼容MCP的客户端使用自然语言存储数据。

通过人工智能将您的分析转化为洞察力：

• 问“我的成功率是多少？”→ 获得即时答案
• “查找昨天的所有错误”→ 筛选事件列表
• “分析我的产品健康状况”→ 基于人工智能的推荐

非常适合产品经理、DevOps团队和任何使用MCP构建的人。

特性

• 🔍 查询事件 -过滤和搜索您的实时流量事件
• 📊 分析指标 -获取高级指标（会话、成功率、延迟）
• ⚡ 性能分析 -查找延迟最高的查询
• 🔎 深度潜水课程 -详细调查具体会议
• 🤖 PM代理就绪 -针对AI代理消费优化的JSON响应
• 🔗 多查询工作流 -将查询链接在一起进行复杂分析

安装

cd packages/mcp-server
uv pip install -e .

配置

创建一个 .env 文件：

SURFA_API_KEY=sk_live_your_key_here
SURFA_API_URL=https://surfa-web.vercel.app
SURFA_TIMEOUT=30

用法

选项1：本地（克劳德桌面）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "surfa": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/surfa/packages/mcp-server",
        "run",
        "surfa-mcp"
      ],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}

选项2：远程（托管在Fly.io上）-多租户

公共Surfa MCP部署在 https://surfa-mcp.fly.dev 并支持多个用户。

每个用户都提供自己的API密钥：

{
  "mcpServers": {
    "surfa": {
      "url": "https://surfa-mcp.fly.dev",
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

优点：

• ✅ 无需部署-使用公共实例
• ✅ 自动缩放-仅在使用时运行
• ✅ 安全-您的API密钥保留在您的计算机上
• ✅ Dogfooded-跟踪所有使用情况以进行分析

看 部署.md 用于部署您自己的实例。

重新启动Claude Desktop并开始查询您的分析！

可用工具

1. get_analytics

获取高级分析指标。

例子：

"Show me my analytics overview"

退货：

{
  "ok": true,
  "data": {
    "totalSessions": 150,
    "successRate": 85,
    "avgExecutionTime": 245,
    "activeSessions": 12
  }
}

2. query_events

使用筛选器查询事件。

例子：

"Show me all errors from the last 24 hours"
"Find tool calls with latency over 1000ms"

参数：

• tool_name -按工具名称筛选
• min_latency / max_latency -延迟范围（毫秒）
• start_date / end_date -ISO 8601时间戳
• kind -事件类型（工具、会话、运行时）
• status -事件状态（成功、错误）
• limit -最大结果（默认值：100）

3. find_highest_latency

查找时间范围内最慢的查询。

例子：

"What were the slowest queries this week?"

参数：

• time_range -小时、日、周或月
• tool_name -可选：按工具筛选
• limit -结果数（默认值：10）

4. get_session

获取详细的会话信息。

例子：

"Show me details for session abc123"

参数：

• session_id -要检索的会话ID

多查询工作流

PM Agent可以将查询链接在一起：

工作流程示例：

1. 获取分析→ 成功率低
2. 通过以下方式查询事件 status=error → 查找错误
3. 获取会话详细信息→ 调查具体故障

所有响应都是JSON格式，便于AI代理解析。

狗食（跟踪您自己的MCP使用情况）

想在Surfa中查看您自己的MCP服务器使用情况吗？通过添加摄取密钥启用分析：

# Add to .env
SURFA_INGEST_KEY=sk_live_your_ingest_key_here

这将跟踪：

• ✅ 工具调用（get_analytics、query_events等）
• ✅ 每个工具的延迟
• ✅ 成功/失败率
• ✅ 会话分析

所有工具调用都将显示在您的Surfa仪表板上，让您分析自己的MCP服务器性能！

发展

运行测试：

pytest tests/

格式代码：

black src/
ruff check src/

许可证

麻省理工学院