Jami

jami-mcp

面向 JamiDev 的官方 Model Context Protocol 服务。JamiDev 是用于 Jami 创作者收益支付的 SDK。将它连接到 Claude、Cursor、VS Code、Codex 或任何 MCP 客户端后，你的 Agent 就能创建 ETB 结账、监控结算、对账、预览并发送付款、调试 Webhook，还能在编写集成时阅读 Jami 文档。支付由 ArifPay 处理。

基于官方 jami-sdk 构建，因此每个工具的行为都与 SDK 和 REST API 完全一致。

npx -y jami-mcp

快速开始

1. 获取令牌：Jami dashboard → JamiDev → Developer → API Tokens。先从沙盒组织开始——它的 jamidev_test_… 令牌不会转移真实资金。
2. 将服务添加到你的客户端（见下文），并将令牌设为 JAMI_TOKEN。
3. 提问：“通过 Telebirr 向 [email protected] 收取 1,237 比尔，用于订单 #1042，电话号码为 251900000001，并等待支付完成。”

还没有令牌？服务仍可运行。文档、提现报价和 Webhook 工具无需令牌即可使用，因此你可以立即开始构建。

Claude Code

claude mcp add jami -e JAMI_TOKEN=jamidev_test_xxx -- npx -y jami-mcp

Claude Desktop · Cursor · Windsurf

添加到 claude_desktop_config.json、~/.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "jami": {
      "command": "npx",
      "args": ["-y", "jami-mcp"],
      "env": { "JAMI_TOKEN": "jamidev_test_xxx" }
    }
  }
}

VS Code

.vscode/mcp.json — VS Code 会提示输入令牌并安全存储：

{
  "inputs": [
    { "type": "promptString", "id": "jami-token", "description": "JamiDev API token", "password": true }
  ],
  "servers": {
    "jami": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jami-mcp"],
      "env": { "JAMI_TOKEN": "${input:jami-token}" }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.jami]
command = "npx"
args = ["-y", "jami-mcp"]
env = { JAMI_TOKEN = "jamidev_test_xxx" }

工具

工具	功能	需要令牌
jami_create_checkout	为商品（p_… 令牌或 ID）或任意金额（amount_minor + description）收款。指定 gateway：会将提示词推送到买家的手机。不指定：会返回 Jami 支付链接，供你发送给买家。	✓
jami_create_product · jami_update_product	创建或编辑商品；每个商品都会返回其公开页面和 p_… 令牌。	✓
jami_get_product · jami_list_products	查看商品目录。	✓
jami_get_checkout_status	检查一次会话状态；会话过期时会返回失败原因。	✓
jami_wait_for_checkout	等待买家完成支付，并提供进度更新。不会无限等待：超时时会返回 open。	✓
jami_list_orders	查看订单，按最新顺序排列，支持分页并可按状态筛选。	✓
jami_get_balance	查看可提现收益，以及组织是否可以提现。	✓
jami_quote_withdrawal	计算指定金额的费用、税款和净额，并检查自动付款和限额。离线可用。	—
jami_create_withdrawal	付款至 Telebirr、M-Pesa 或 CBE Birr。需主动启用（见安全说明）。	✓
jami_get_withdrawal · jami_list_withdrawals	跟踪付款。	✓
jami_verify_webhook	检查已捕获投递的签名及其失败原因。	—
jami_create_test_webhook	构建签名正确的测试事件，也可选择将其 POST 到你的本地处理程序。	—
jami_search_docs · jami_read_doc	搜索并阅读 dev.jami.bio 上的实时文档。	—

每个工具都会返回易读的 Markdown 摘要和类型化的 structuredContent。传入 response_format: "json" 可获取原始载荷。货币始终以整数 分（santim） 表示，且所有金额参数都以 _minor 结尾：amount_minor: 15000 = 150.00 ETB。

提示词：integrate_jami（在你的技术栈中构建完整集成）、go_live_checklist、 debug_payment。资源：jami://reference — 在一个页面中查看费用、限额、沙盒号码、失败代码和 Webhook 规则。

安全性

默认设置可防止 Agent 意外转移资金。

• 提款功能默认关闭，除非使用 --enable-withdrawals（或 JAMI_ENABLE_WITHDRAWALS=true）启动服务。启用后，支持请求确认的客户端会要求你确认每笔付款；每笔付款都需要 idempotency_key，因此重试绝不会重复付款。沙盒令牌会在发出任何请求前被拒绝。
• --read-only 仅注册读取数据的工具。可用于报告 Agent。
• 实时模式会明确提示。 使用 jamidev_live_ 令牌时，服务会告知 Agent 结账将向真实买家收费，并要求先行确认。
• 令牌保存在环境中，绝不会出现在工具输出中。

选项

--http                 Streamable HTTP on POST /mcp instead of stdio
--port <n>             HTTP port (default 3333)
--host <addr>          HTTP bind address (default 127.0.0.1)
--read-only            Only read tools
--enable-withdrawals   Register jami_create_withdrawal
--base-url <url>       Override the API base (default https://jami.bio/api/jamidev)
--docs-url <url>       Override the docs origin (default https://dev.jami.bio)

环境变量	用途
JAMI_TOKEN	jamidev_test_… 或 jamidev_live_…
JAMI_WEBHOOK_SECRET	Webhook 工具的默认密钥
JAMI_READ_ONLY, JAMI_ENABLE_WITHDRAWALS	与对应标志相同

远程（HTTP）模式

npx -y jami-mcp --http --port 3333
# → http://127.0.0.1:3333/mcp   (health check: /healthz)

HTTP 服务是无状态的，因此任意数量的客户端都可以共用一个进程。未设置 JAMI_TOKEN 时，每个请求都使用各自的 Authorization: Bearer jamidev_… 标头进行身份验证，因此一个部署可安全地供多个团队共享。通过环回地址访问时，服务会拒绝外部 Host 标头（DNS 重绑定防护）。在 HTTP 模式下，jami_create_test_webhook 不会发送请求；它只会返回签名后的负载和一条 curl 命令。

嵌入

import { createJamiServer } from 'jami-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createJamiServer({ token: process.env.JAMI_TOKEN, docsUrl: 'https://dev.jami.bio', readOnly: true, withdrawals: false });
await server.connect(new StdioServerTransport());

开发

npm install
npm test          # in-memory MCP client against a mocked API
npm run build
npm run inspect   # opens the MCP Inspector on dist/index.js

完整指南：dev.jami.bio/docs/mcp · 支持：[email protected]

MIT © Jami