spanlens

Name: spanlens
Author: spanlens

本地服务

github.com/spanlens数据与分析132 天前更新

代码仓库

关于 spanlens

spanlens 是一个 MCP 服务，供 IDE Agent 和客户端查询 Spanlens 的 LLM 可观测性数据。工具涵盖用量与成本、请求详情、Trace、异常、节省成本建议及用户分析；仅接受只读的 public-scope 密钥。

主要功能

01汇总用量与成本统计
02可筛选的请求记录
03Agent Trace 与 Span 详情
04成本和延迟异常查询
05模型替换节省成本建议
06按用户分析用量

适用场景

01按服务商查看每周 LLM 支出
02调查错误请求和高成本 Trace
03查找成本或延迟异常

MCP 相关

它向 Cursor、Continue 和 Claude Desktop 等 MCP 客户端提供七种只读 Spanlens 分析工具。服务会验证 API 密钥是否为 public scope，并拒绝完整权限密钥。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "spanlens": {
      "command": "npx",
      "args": [
        "-y",
        "@spanlens/mcp-server"
      ],
      "env": {
        "SPANLENS_API_KEY": "<SPANLENS_API_KEY>",
        "SPANLENS_BASE_URL": "<SPANLENS_BASE_URL>"
      }
    }
  }
}

启动命令npx -y @spanlens/mcp-server

需要配置的环境变量

SPANLENS_API_KEY密钥Spanlens API key. Must be a scope=public key (sl_live_pub_*) issued from the Public Keys card at https://spanlens.io/projects — the server refuses to start with a full-access sl_live_* key.

SPANLENS_BASE_URLOverride the API endpoint for self-hosted Spanlens. Default: https://api.spanlens.io

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@spanlens/mcp-server0.3.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@spanlens/mcp-server

在 Cursor、Continue 或 Claude Desktop 中查询 LLM 可观测性数据。由 Spanlens 提供支持。

向 IDE 的 Agent 提问，例如 “我本周的 OpenAI 支出是多少？”、“有没有成本异常？” 或 “显示今天成本最高的跟踪记录”，即可通过 Model Context Protocol 从你的 Spanlens 工作区获取真实数据。

30 秒快速设置

1. 创建 Spanlens 公共范围密钥

公共范围密钥（sl_live_pub_*）为只读密钥，可查询你的仪表板数据，但无法触发 LLM 代理支出。由于凭据将保存在 IDE 的纯文本配置文件中，此服务拒绝使用完全访问权限密钥启动。

前往 spanlens.io/projects → 页面顶部的 Public Keys 卡片 → + New public key，创建密钥。显示密钥后，复制 sl_live_pub_… 值。

2. 将服务添加到 IDE

Cursor — ~/.cursor/mcp.json（或工作区中的 .cursor/mcp.json）

{
  "mcpServers": {
    "spanlens": {
      "command": "npx",
      "args": ["-y", "@spanlens/mcp-server"],
      "env": { "SPANLENS_API_KEY": "sl_live_pub_..." }
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "spanlens": {
      "command": "npx",
      "args": ["-y", "@spanlens/mcp-server"],
      "env": { "SPANLENS_API_KEY": "sl_live_pub_..." }
    }
  }
}

Continue — ~/.continue/config.yaml

mcpServers:
  - name: spanlens
    command: npx
    args: ['-y', '@spanlens/mcp-server']
    env:
      SPANLENS_API_KEY: sl_live_pub_...

3. 重新加载 IDE 并开始提问

Agent 会发现七个工具，并在相关时自动使用。

可以询问的问题

问题	调用的工具
“我们本周在大模型上花了多少钱？”	`get_stats`
“按模型细分过去 30 天的成本”	`get_stats(groupBy=model)`
“本周哪个提供商的成本最高？”	`get_stats(groupBy=provider)`
“有没有成本或延迟异常？”	`get_anomalies`
“显示 gpt-4o 上最近的 10 次错误调用”	`query_requests`
“列出我最近的 Agent 运行记录”	`list_traces`
“带我查看跟踪记录 `abc123…`”	`get_trace`
“有哪些模型可以替换，以节省开支？”	`get_savings`
“哪个最终用户带来的支出最多？”	`get_user_analytics`

可用工具

工具	返回内容
`get_stats`	汇总成本、请求数、令牌用量、延迟和错误率。可选参数 `groupBy` 可按成本、请求数、延迟和错误率细分：`model` 会为每个提供商与模型组合返回一行，`provider` 会将这些行汇总为每个提供商一行，延迟和错误率按请求数加权。
`query_requests`	单个 LLM 请求的成本、延迟、模型和错误消息。可按 `model`、`provider`、`status`、`userId`、`since`、`limit` 筛选。
`list_traces`	Agent 跟踪摘要（名称、状态、时长、跨度数、令牌总数、总成本），用于查找跟踪 ID。可按 `limit`、`status`、`since`、`query` 筛选。搭配 `get_trace` 可查看完整跨度树。
`get_trace`	指定跟踪 ID 的完整 Agent 跨度树，包含每个 LLM、工具和检索跨度的计时、令牌数及成本。
`get_anomalies`	平台检测到的成本、延迟或错误率异常。可选参数 `since`（观测时间窗口）和 `sigma`（灵敏度）。
`get_savings`	模型替换建议，包含预计月度节省金额和采用状态。
`get_user_analytics`	按最终用户细分的用量，包括总成本、请求数、使用过的模型和近期调用。

安全性

此服务面向 IDE 配置场景设计，凭据以明文形式存放在容易泄露的文件中（点文件同步、屏幕共享、意外提交）。我们提供了两项防护措施：

仅限公开范围的密钥。 服务启动后，会向你的工作区调用 /api/v1/me/key-info，并验证密钥的 scope=public。如果你不小心粘贴了具有完整访问权限的 sl_live_* 密钥，服务会拒绝启动，并清楚指出正确的密钥类型。
API 层只读。 即使公开密钥泄露，也无法调用 /proxy/* 或 /ingest/* —— Spanlens 服务会通过 403 状态码和 PUBLIC_KEY_WRITE_FORBIDDEN 代码强制执行此限制。密钥泄露造成的影响是“竞争对手看到我的使用统计”，而不是“竞争对手让我的 OpenAI 账单暴涨”。

配置

环境变量	默认值	说明
`SPANLENS_API_KEY`	必填	来自 `/projects` 上 Public Keys 卡片的 `sl_live_pub_` 密钥。没有该密钥时，服务会拒绝启动；如果使用 `sl_live_`（完整权限）密钥，服务也会拒绝启动。
`SPANLENS_BASE_URL`	`https://api.spanlens.io`	用于可自托管的 Spanlens 的覆盖值。末尾斜杠会被规范化。
`SPANLENS_TIMEOUT_MS`	`30000`	每次 API 调用在超时失败之前允许耗费的时长，单位为毫秒。适用于启动时的密钥检查和每次工具调用。接受 1 到 600000 之间的整数。其他任何值都会导致服务在启动时停止，并提示出错的变量名。

自托管 Spanlens

{
  "mcpServers": {
    "spanlens": {
      "command": "npx",
      "args": ["-y", "@spanlens/mcp-server"],
      "env": {
        "SPANLENS_API_KEY": "sl_live_pub_...",
        "SPANLENS_BASE_URL": "https://spanlens.your-company.com"
      }
    }
  }
}

链接

许可证

MIT — 请参阅仓库根目录中的 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。