Surfa Ingest

MCP数据服务

提供方 gamladz

数据服务 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude DesktopClaudeCursor
查看接入方式

Surfa Ingest SDK 是一款用于MCP服务器和AI代理的分析工具,能够追踪使用情况、性能和任务完成情况,适用于本地和远程服务器。

一句话选型结论

按资料字段整理

Surfa Ingest 属于数据服务类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude Desktop、Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 4 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

数据分析Python本地部署性能监控AI代理MCP服务器隐私保护

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
pip install surfa-ingest

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Surfa Ingest当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方gamladz上游标注的维护方 gamladz
分类数据服务本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

9.0 KB
来自项目仓库与上游目录的原文,未做删改

Surfa摄取SDK

MCP服务器和AI代理的分析 -跟踪使用情况、性能和任务完成情况,无论您的服务器是本地运行还是远程运行。

为什么吃Surfa?

适用于MCP服务器构建者

了解您的MCP服务器的使用情况——无论是本地安装在用户的计算机上还是远程托管:

📊 获得否则不会有的可见性

  • 本地MCP服务器: 即使安装在用户的计算机上(Claude Desktop、Cursor等),也可以跟踪使用情况
  • 远程MCP服务器: 获取基本服务器日志之外的结构化分析

🎯 了解你的用户

  • 哪些工具最受欢迎
  • 哪些AI客户端正在使用您的服务器(Claude、ChatGPT、Cursor)
  • 实时使用模式和趋势
  • 地理分布和平台细分

🚀 基于真实数据进行优化

  • 性能指标(延迟、错误率)
  • 任务完成跟踪(用户是否实际完成了目标?)
  • 识别瓶颈和故障点
  • A/B测试改进

💰 启用基于使用量的定价

  • 跟踪API调用和工具使用情况
  • 监控配额消耗
  • 构建货币化模型

🔍 更快地调试问题

  • 看看到底是什么失败了,在哪里失败了
  • 端到端跟踪用户会话
  • 识别重试模式和错误序列

隐私优先设计

  • ✅ 默认情况下未收集PII
  • ✅ 用户可以通过环境变量选择退出
  • ✅ 您可以控制发送哪些数据
  • ✅ GDPR和隐私合规

MCP建设者的快速入门

1.安装SDK```bash

pip install surfa-ingest


**对于不同的MCP分配模式:**

Local MCP (stdio) - npm/PyPI package

添加到您的 `pyproject.toml`:```toml
[project]
dependencies = [
"surfa-ingest>=0.2.0",
"fastmcp>=2.0.0"
]

或 requirements.txt:```
surfa-ingest>=0.2.0
fastmcp>=2.0.0


用户在本地安装MCP:```bash
pip install your-mcp-server

Remote MCP (SSE) - Hosted service

添加到您的服务器 requirements.txt:```
surfa-ingest>=0.2.0
fastmcp>=2.0.0


部署到云端(Vercel、Railway、Fly.io等):```bash
# Set environment variables
SURFA_INGEST_KEY=sk_live_your_key
SURFA_API_URL=https://surfa.dev

用户通过URL连接(无需安装):```json
{
"mcp_servers": [{
"type": "url",
"url": "https://your-mcp.com/sse"
}]
}


### 2.添加到您的MCP服务器

选择与您的分发模式匹配的示例:

Local MCP (stdio) - Claude Desktop, Cursor```python
from surfa_ingest import SurfaClient
from fastmcp import FastMCP
import os

# Initialize analytics
analytics = SurfaClient(
ingest_key=os.getenv("SURFA_INGEST_KEY", "sk_live_your_key"),
api_url=os.getenv("SURFA_API_URL", "https://surfa.dev")
)

# Set runtime for local stdio mode
analytics.set_runtime(
provider="mcp",
model="your-mcp-server-name",
mode="stdio"  # Local mode
)

# Initialize MCP server
mcp = FastMCP("Your MCP Server")

@mcp.tool
def search_database(query: str) -> dict:
analytics.track({
"kind": "tool",
"subtype": "call_started",
"tool_name": "search_database"
})

result = perform_search(query)

analytics.track({
"kind": "tool",
"subtype": "call_completed",
"tool_name": "search_database",
"status": "success"
})
analytics.flush()

return result

# Run in stdio mode (for Claude Desktop)
if __name__ == "__main__":
mcp.run()  # Defaults to stdio

用户在Claude Desktop中配置:```json
{
"mcpServers": {
"your-mcp": {
"command": "npx",
"args": ["-y", "your-mcp-server"]
}
}
}


Remote MCP (SSE) - Claude API, OpenAI API```python
from surfa_ingest import SurfaClient
from fastmcp import FastMCP
import os

# Initialize analytics
analytics = SurfaClient(
ingest_key=os.getenv("SURFA_INGEST_KEY", "sk_live_your_key"),
api_url=os.getenv("SURFA_API_URL", "https://surfa.dev")
)

# Set runtime for remote SSE mode
analytics.set_runtime(
provider="mcp",
model="your-mcp-server-name",
mode="sse"  # Remote mode
)

# Initialize MCP server
mcp = FastMCP("Your MCP Server", stateless_http=True)

@mcp.tool
def search_database(query: str) -> dict:
analytics.track({
"kind": "tool",
"subtype": "call_started",
"tool_name": "search_database"
})

result = perform_search(query)

analytics.track({
"kind": "tool",
"subtype": "call_completed",
"tool_name": "search_database",
"status": "success"
})
analytics.flush()

return result

# Run in HTTP/SSE mode
if __name__ == "__main__":
mcp.run(
transport="http",
host="0.0.0.0",
port=8000,
path="/mcp"
)

用户通过URL连接:```python

Claude API

response = client.messages.create(
model="claude-opus-4",
mcp_servers=[{
"type": "url",
"url": "https://your-mcp.com/mcp"
}]
)

OpenAI API

response = client.responses.create(
model="gpt-5",
tools=[{
"type": "mcp",
"server_url": "https://your-mcp.com/mcp"
}]
)


#### 使用MCP上下文自动检测(v0.2.0+)

**新** 自动提取 `client_id`, `session_id`,以及 `request_id` 从MCP的角度来看!```python
from surfa_ingest import SurfaClient
from fastmcp import FastMCP, Context

analytics = SurfaClient(ingest_key="sk_live_...")
mcp = FastMCP("My MCP Server")

@mcp.tool
def search_database(query: str, ctx: Context) -> dict:
# Just pass ctx - auto-extracts client_id, session_id, request_id!
analytics.track({
"kind": "tool",
"subtype": "call_started",
"tool_name": "search_database"
}, ctx=ctx)  # ✨ Auto-extraction happens here

result = perform_search(query)

analytics.track({
"kind": "tool",
"subtype": "call_completed",
"tool_name": "search_database",
"status": "success"
}, ctx=ctx)

return result

优点:

  • ✅ 无需手动提取字段
  • ✅ 适用于FastMCP和未来的MCP框架
  • ✅ 向后兼容(ctx可选)
  • ✅ 永不中断跟踪(优雅地失败)

自动提取的内容:

  • client_id -客户端标识符(如果MCP上下文中有)
  • request_id -请求标识符(用于关联MCP请求)

3.获取您的分析

访问您的Surfa仪表板查看:

  • 实时工具使用
  • 性能指标
  • 任务完成率
  • 客户分布
  • 错误追踪

所得

实时仪表板

  • 📈 工具使用趋势
  • ⚡ 性能指标(P50、P95、P99延迟)
  • ✅ 任务完成率
  • 🔴 错误率和类型
  • 👥 活跃用户和会话

确定性代理度量

  • 任务完成: 用户真的实现了他们的目标吗?
  • 工具调用: 调用了多少工具?
  • 检索: 具有相同参数的重复调用
  • 恢复: 代理是否从错误中恢复?
  • 延迟时间: P95和总延迟跟踪

客户端智能

  • 哪些AI客户端正在使用您的MCP(Claude、ChatGPT、Cursor)
  • 平台分发(macOS、Linux、Windows)
  • 客户端版本和配置

主要特点

  • 🚀 事件缓冲 -具有可配置缓冲区大小的自动批处理
  • 🔄 自动重试 -具有指数回退的内置重试逻辑
  • 📦 上下文管理器 -自动会话生命周期管理
  • 🏷️ 运行时元数据 -跟踪AI提供商、模型和配置
  • ✨ MCP上下文自动检测 (v0.2.0+)-自动从MCP上下文中提取client_id、session_id
  • 📊 确定性代理度量 -跟踪传统分析平台无法提供的任务完成、重试、恢复和性能指标
  • ✅ 事件验证 -发送前的客户端验证
  • 🔍 相关ID -将相关事件链接在一起
  • 🛡️ 类型安全 -完整类型提示和IDE自动补全
  • 🔒 隐私第一 -默认情况下没有PII,用户选择退出支持

> 是什么让Surfa与众不同: 我们从您的事件流中自动计算任务完成、重试检测和恢复率等确定性指标,这些指标是通用分析平台无法提供的,因为它们不了解AI代理的行为。

了解更多

📚 文档

  • API完整参考 -完整的方法文档
  • 确定性度量 -我们如何计算任务完成、重试和恢复
  • 高级用法 -上下文管理器、错误处理、日志记录
  • 例子 -不同用例的更多代码示例

🔗 链接

  • 📦 PyPI: https://pypi.org/project/surfa-ingest/
  • 📝 更新日志: 更改日志.md
  • 🐛 问题: https://github.com/gamladz/surfa/issues
  • 💬 讨论: https://github.com/gamladz/surfa/discussions

快速参考

确定性度量(自动计算)

当您使用此SDK发送事件时,Surfa平台会自动计算每次执行的这些指标:

自动计算指标

度量 · 定义 · 如何计算
任务完成 · 任务是否实际完成 · 用途 task_completed 字段(如果存在),否则根据事件序列推断
工具调用 · 工具调用总数 · 计数 tool_call_started 事件
重试 · 从以下位置检测到使用相同工具+参数的重复调用 tool_name + payload.input 匹配
恢复 · 代理从错误中恢复 · 任何失败后的首次成功
延迟 · P50、P95、P99延迟 · 根据以下公式计算 latency_ms 分布

查看完整的指标文档→


开发状态

当前版本:0.2.0(Alpha)

此SDK正在积极开发中。API可能会在未来版本中更改。

贡献

欢迎投稿!请随时提交拉取请求。

许可证

麻省理工学院


由以下材料制成❤️ 面向MCP建设者

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Surfa Ingest 怎么安装?

在客户端按下面的安装命令接入:pip install surfa-ingest。装完在客户端配置里引用同一个包或端点。

Surfa Ingest 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Surfa Ingest 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Surfa Ingest 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Surfa Ingest 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Surfa Ingest 能提供哪些能力?

资料显示能力标签包括 数据分析、性能监控、Python、Claude、隐私保护。具体工具清单以官方文档为准。

Surfa Ingest 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Surfa Ingest 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。