sapiom

@sapiom/mcp

Sapiom 的本地开发者 MCP 服务。它通过 stdio 在你的机器上运行，服务名称为 sapiom-dev。目前，它为编码 Agent 提供构建脚手架、测试、部署和检查 Sapiom Agent 的工具，并可将 Web 应用置于实时沙盒 URL 或持久 App Link 之后；该命名空间也为今后添加其他开发者工具留出了空间。

并非能力工具集。 这不是远程的“Sapiom” MCP（托管连接器，提供 sapiom_sandbox_*、抓取、搜索等能力工具）。 sapiom-dev 不提供直接的能力工具。它的本地检查和 Local Run 流程会使用桩能力，不会产生 Sapiom 能力调用费用；部署、云构建、生产运行、信号和计划则会操作 Sapiom 云端状态，且可能计费。请参阅 两个 Sapiom MCP 服务，了解应在何时使用哪个服务。

安装

无需全局安装——使用 npx 按需运行：

{
  "mcpServers": {
    "sapiom-dev": {
      "command": "npx",
      "args": ["-y", "@sapiom/mcp"],
    },
  },
}

在 Claude Code 中：

claude mcp add sapiom -- npx -y @sapiom/mcp

配置

该服务默认面向 production 环境。使用 SAPIOM_ENVIRONMENT 环境变量覆盖：

{
  "mcpServers": {
    "sapiom-dev": {
      "command": "npx",
      "args": ["-y", "@sapiom/mcp"],
      "env": { "SAPIOM_ENVIRONMENT": "staging" },
    },
  },
}

• production（别名 prod）→ app.sapiom.ai / api.sapiom.ai——默认环境。
• staging（别名 dev）→ app.sapiom.dev / api.sapiom.dev。

两者均从内置预设解析，因此无需配置文件。可在 ~/.sapiom/credentials.json 中定义自定义目标（如果遇到未知环境名称，服务会打印预期的配置格式）。

API 密钥只会通过 https:// 传输，或通过指向环回主机（localhost、*.localhost、127.0.0.1、[::1]）的纯 http:// 传输。请求发送前，如果自定义目标使用其他 http:// 主机，服务会拒绝该请求。在可信的专用网络上，可在服务的 env 中设置 SAPIOM_ALLOW_INSECURE_HTTP=1。

身份验证

首次联网调用（link、deploy、run、inspect、signal）需要 Sapiom API 密钥。运行 sapiom_authenticate，服务会打开浏览器登录流程，然后按环境将获取的密钥缓存到 ~/.sapiom/credentials.json。之后，工具无需重新进行身份验证即可使用。 sapiom_status 会报告当前身份验证对应的账号；sapiom_logout 会清除缓存的凭据。

本地编写工具（scaffold、check、run_local）无需 Sapiom 身份验证。scaffold 可能会向 npm 查询当前依赖版本； check 会导入定义；run_local 会执行作者编写的常规本地代码。只有 ctx.sapiom.* 调用会被桩替代，因此作者代码中的直接网络、文件系统、环境和进程操作仍会真实执行。

工具

工具	网络	功能
sapiom_authenticate	浏览器	登录并为当前环境缓存 API 密钥
sapiom_status	—	报告身份验证状态
sapiom_logout	—	清除缓存的凭据
sapiom_send_feedback	✓	将用户的产品反馈转达给 Sapiom 团队
sapiom_dev_agents_scaffold	npm 可选	创建新的 Agent 项目；可能会查询 npm 以获取当前依赖项版本
sapiom_dev_agents_check	仅作者代码	对定义和步骤图进行类型检查、导入、打包和验证
sapiom_dev_agents_run_local	仅作者代码	在本地运行，并将 ctx.sapiom.* 调用替换为存根（不消耗 Sapiom 能力额度）
sapiom_dev_agents_link	✓	解析或创建托管编排，并缓存其 ID
sapiom_dev_agents_clone	✓	将图库模板（或其分支）克隆到本地项目
sapiom_dev_agents_deploy	✓	打包当前本地源码，在云端构建并等待
sapiom_dev_agents_run	✓	启动一次真实的云端执行
sapiom_dev_agents_inspect	✓	检查执行或构建（可选择等待其完成）
sapiom_dev_agents_signal	✓	通过发送信号恢复已暂停的执行
sapiom_dev_agents_emit_event	✓	发出自定义事件；针对该类型的每个有效 event 触发器启动一次运行（0..N）
sapiom_dev_agents_schedule	✓	创建触发器：cron、一次性、事件（eventType）或 webhook（URL + 密钥）
sapiom_dev_agents_schedule_inspect	✓	检查单个触发器（含触发历史），或列出某个 Agent 的触发器
sapiom_dev_agents_schedule_cancel	✓	取消任意类型的触发器（停止所有后续触发）
sapiom_dev_agents_schedule_secret	✓	轮换、完成轮换或撤销 webhook 触发器的签名密钥
sapiom_dev_agents_cron_preview	✓	验证 cron 表达式并预览接下来的触发时间
sapiom_dev_sandbox_configure	—	将通过验证的 type: "sandbox" 预览资源写入 sapiom.json
sapiom_dev_sandbox_check	—	验证项目的沙盒资源，无需部署
sapiom_dev_sandbox_preview	✓	将应用部署到沙盒，生成会在其 ttl 到期时失效的实时 URL
sapiom_dev_app_publish	✓	将同一应用发布到持久的 App Link（apps.sapiom.ai/{org}/{slug}）
sapiom_dev_app_list	✓	列出组织的 App Link：URL、可见性、webhook、支出上限、唤醒状态
sapiom_dev_app_settings	✓	更改链接的 webhooksEnabled、可见性、支出上限和唤醒速率限制
sapiom_dev_app_delete	✓	删除链接（URL 将无法解析，slug 将被释放）；必须提供 confirm: true
sapiom_dev_map	可选	Agent 地图：系统、Agent、步骤以及代码证明的关联关系
一个典型的循环：scaffold → 编写步骤代码 → 反复运行 run_local，直到成功 → link
→ deploy → run → inspect。

对于 Web 应用而非 Agent：迭代时使用 sandbox_configure → sandbox_preview （这是一个临时 URL，会随沙盒销毁）→ 等到链接需要永久保留或分享时，再使用 app_publish。app_publish 会读取同一个 sapiom.json 沙盒资源，将源代码上传为已存储的纯文本包 （≤ 10 MiB），并返回一个持久的 https://apps.sapiom.ai/{org}/{slug} URL，按需唤醒应用；重新发布相同的 slug 会原地更新应用。路由规则请参阅 sapiom-sandbox-preview 技能。

创建链接后，可以使用 app_list、app_settings 和 app_delete 管理它，无需离开终端。Webhook 默认关闭：app_settings { slug, webhooksEnabled: true } 可将其开启，之后第三方可向 https://apps.sapiom.ai/{org}/{slug}/hook/<path> 发送 POST 请求（/hook 前缀会被剥离，正文会逐字节转发，因此 Slack/Stripe/GitHub 的签名 检查可在应用内运行）。这些设置需要 org.write 权限——仅有发布权限并不足够——拒绝操作时会返回一条注明所需权限和字段的消息，供 Agent 转达，而不是重试。

Agent 映射

sapiom_dev_map 返回 Agent Studio 绘制的映射，每次调用都会根据代码计算；不会存储任何 Agent 或边。传入项目文件夹（root，默认为工作目录），并可选传入 git ref（HEAD、分支或提交），即可绘制该版本：

{ "root": "~/agents/support-desk", "ref": "HEAD" }

扫描会查找所有包含 sapiom.json 或 defineAgent 的文件夹，并读取：

• 边，即 Agent 到 Agent 的连接，每条边都附有证明它存在的文件和行号： agents.run / agents.launch（launch）、针对其他 Agent 的 schedules.create（timer），以及与事件类型所触发的 Agent 匹配的 events.emit（event）。只要代码能确定目标，就会计入：字面量、常量（本地或导入）、运行时按索引访问的常量映射中的所有值、调用读取的输入字段上 zod 的 .default()，或在 sapiom.json 中设置的 process.env 键。其他情况会列在 unresolved 下。
• 系统：由这些边构成的连通分量。仅共享 vault 键、数据库或连接器的 Agent 不会合并；共享资源会显示在每个 Agent 的 shared 列表中。在已提交的 .sapiom/map.json 中为系统命名： { "systems": [{ "agent": "intake", "name": "Support desk" }] }。
• 来自 agents check 的步骤（需要安装该 Agent 的依赖项）。
• 来自已登录账户的触发器和部署状态，以及 fleet.json 中声明的触发器。未登录时，platform 会说明这一点，但映射仍会绘制。
• changedSinceRef：Agent 文件夹与 ref 不同（绘制工作副本时以 HEAD 为准）。

若要映射你自行描述的 Agent，而不进行扫描，请传入 agents：

{
  "agents": [
    { "slug": "intake", "emits": [{ "eventType": "ticket.opened" }] },
    {
      "slug": "triage",
      "triggers": [{ "kind": "event", "eventType": "ticket.opened" }],
      "calls": [{ "to": "notify", "kind": "launch" }]
    },
    { "slug": "notify", "resources": ["connector:slack"] }
  ]
}

每个 Agent 都需要 slug，还可选传入 path、description、deployed、steps（{ entry, steps: [{ id }], transitions: [{ from, to, kind }] }）、calls（{ to, kind: "launch" | "signal" | "timer", evidence? }）、emits、triggers 和 resources。系统规则相同。

标签。 登录后，该工具会为每个所描述 Agent 的 role（intake、worker、orchestrator、reporter、monitor 或 utility）以及每条 launch 或 event 边的 label（交接工作、传递数据或进行监控），向 Jev（jev-1.13.0，一次批量 decisions.evaluate 调用）发起询问。只有概率 p 至少为 0.8 时才会显示标签。答案会缓存在 <root>/.sapiom/cache/map-labels.json 中（在该文件夹内会被 git 忽略；对于描述式映射则缓存在内存中），并以问题事实的哈希值作为键，因此未更改的 Agent 不会被重复询问，其标签也不会变化。在扫描项目中，Agent 发生变化时，原先显示的标签会保留，除非新答案不同且概率达到 0.8。 未登录、设置了 platform: false，或 Jev 失败或耗时超过 5 秒时，映射会返回 labels: "unavailable"，其他内容保持不变。

能力如何融入其中

在此编写的 Agent 会通过 @sapiom/tools（ctx.sapiom.*）调用 Sapiom 能力——沙箱、代码仓库、编码 Agent、搜索、存储和内容生成。run_local 会通过存根解析这些调用；部署和生产运行则会进入经过身份验证的云端操作，并可能按用量计费。此 MCP 不会为任何单项能力新增专属工具—— 能力由 @sapiom/tools 和远程 sapiom MCP 提供。完整政策请参阅 定位文档。

发送反馈

sapiom_send_feedback 会将用户的产品反馈（错误、体验不佳之处、功能请求）转发给 Sapiom 团队。Agent 只会发送用户说的内容；服务端会自行附加软件包版本、平台、架构、Node 版本、环境和时间戳，因此模型无需从机器上读取这些信息。

嵌入此服务的宿主可以通过 SAPIOM_HARNESS_VERSION 声明自己的版本——它会随 clientMeta.harnessVersion 一起发送，从而在问题排查时能够回答“该用户使用的是哪个构建版本”。未设置此变量时，会完全省略该字段，不会填入占位符。@sapiom/harness 会自动设置此变量。

使用分析

默认情况下，服务会通过 @sapiom/analytics-core 向托管的 Sapiom 收集器发送匿名使用分析数据（每次工具调用发送一个 tool.call 事件：工具名称、参数、耗时、成功／错误类别）。你可以随时通过 SAPIOM_TELEMETRY_DISABLED=1 或 DO_NOT_TRACK=1 选择退出——任一设置都会让发送器完全不执行任何操作（不会发送任何内容，也不会写入磁盘）。SAPIOM_ANALYTICS_ENDPOINT 可用于覆盖目标地址。遥测数据会同步加入内存队列，不会抛出异常、阻塞工具调用，也绝不会更改工具结果。

许可证

MIT