AI导哈

支付协议服务器

Woovi MCP Server是一个支付协议服务器，提供Pix支付、客户管理、交易查询、余额查询、退款处理等功能，并支持AI助手通过MCP接口与Woovi API交互。

  • by guilhermemarch
  • TypeScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 guilhermemarch/mcp-woovi-api

使用说明

Woovi MCP服务器

Woovi/OpenPix的模型上下文协议服务器。它公开了Pix的收费、客户、交易、余额、退款、资源和可重复使用的提示，因此像Claude这样的人工智能助手可以在干净的MCP表面上对抗Woovi API进行操作。

实施了什么

  • 10个必需的MCP工具：
    • create_charge, get_charge, list_charges
    • create_customer, get_customer, list_customers
    • get_transactions, get_balance
    • create_refund, get_refund
  • 3所需的MCP资源：
    • balance
    • endpoints
    • webhook_schemas
  • 3个必需的MCP提示：
    • daily_summary
    • customer_report
    • reconciliation_check
  • 奖励能力：
    • list_accounts
    • get_charge_analytics
    • get_customer_payment_summary
    • SSE事件流 GET /events
    • webhook入口端点位于 POST /webhooks/events
    • 通过以下方式查找多账户余额 accountId
    • 缓存TTL，用于客户查找和工具驱动的余额读取

堆栈

  • TypeScript
  • @modelcontextprotocol/sdk
  • Zod验证
  • 可重复使用的 @woovi/client 包裹
  • stdio和HTTP传输

快速开始

pnpm install
cp .env.example .env
pnpm build
pnpm start:stdio

要运行HTTP传输，请执行以下操作：

pnpm start:http

要使用Woovi凭据验证实时沙盒流，请执行以下操作：

pnpm smoke:sandbox

环境

在开发时使用沙盒值：

WOOVI_APP_ID=your_sandbox_app_id_here
WOOVI_API_URL=https://api.woovi-sandbox.com
WOOVI_AUTH_MODE=raw
WOOVI_LOG_LEVEL=info
PORT=3000
MCP_HTTP_AUTH_TOKEN=replace-with-strong-random-token
WOOVI_WEBHOOK_INGRESS_TOKEN=

笔记：

  • WOOVI_AUTH_MODE=raw 发送 Authorization: <appId>
  • WOOVI_AUTH_MODE=bearer 发送 Authorization: Bearer <appId>
  • MCP_HTTP_AUTH_TOKEN 是HTTP传输和保护所必需的 POST /mcp 和 GET /events
  • WOOVI_WEBHOOK_INGRESS_TOKEN 启用并保护 POST /webhooks/events

克劳德桌面版

示例配置位于 config/claude-desktop.example.json.

相关条目为：

{
  "mcpServers": {
    "woovi": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-woovi-server-ts/packages/server/dist/stdio.js"
      ],
      "env": {
        "WOOVI_APP_ID": "your-sandbox-app-id",
        "WOOVI_API_URL": "https://api.woovi-sandbox.com"
      }
    }
  }
}

HTTP传输

终点：

  • POST /mcp：可流式传输的HTTP MCP端点
  • GET /healthz：健康检查
  • GET /events：用于webhook通知的SSE流
  • POST /webhooks/events：在以下情况下将webhook有效负载发布到SSE总线 WOOVI_WEBHOOK_INGRESS_TOKEN 已配置

例子：

curl -H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
  http://localhost:3000/healthz

码头工人

在容器中构建并运行HTTP传输：

docker build -t woovi-mcp-server .
docker run --rm -p 3000:3000 \
  -e WOOVI_APP_ID=your-sandbox-app-id \
  -e WOOVI_API_URL=https://api.woovi-sandbox.com \
  -e MCP_HTTP_AUTH_TOKEN=replace-with-strong-random-token \
  woovi-mcp-server

开发人员命令

pnpm build
pnpm test
pnpm test:unit
pnpm test:integration
pnpm test:coverage
pnpm typecheck
pnpm quality
pnpm smoke:sandbox
pnpm verify:build

pnpm verify:build 编译仓库并验证内存中暴露的MCP表面。 pnpm quality 是用于挑战准备的单命令本地门：构建、类型检查、覆盖阈值和MCP表面验证。 pnpm smoke:sandbox 构建仓库，启动 stdio 并通过MCP客户端验证实时沙盒流。

项目布局

packages/client/src
  cache.ts
  client.ts
  logger.ts
  types.ts

packages/client/tests/unit
  *.test.ts

packages/server/src
  core/config.ts
  core/event-bus.ts
  domains/
  mcp/register.ts
  tools/
  resources/
  prompts/
  transports/
  server.ts
  stdio.ts
  http.ts
  index.ts

packages/server/tests
  unit/
  integration/

文档

验证状态

当前本地状态：

  • pnpm build 通过
  • pnpm test 通过
  • pnpm test:coverage 通过
  • node scripts/verify-challenge.mjs 通过
  • pnpm smoke:sandbox 2026年3月12日，当 WOOVI_APP_ID 已提供
  • pnpm audit --prod --json 报告 0 通过固定修补的传递依赖关系后的生产漏洞 pnpm.overrides

覆盖门：

  • 声明： >= 80%
  • 线： >= 80%
  • 功能： >= 80%
  • 分支机构： >= 65%

重要行为

  • 值总是以分为单位
  • 在适当的情况下，日志和MCP输出中会屏蔽敏感字段
  • 429个响应、瞬时获取失败和超时在中以回退方式重试 @woovi/client
  • get_customer 使用记录的客户标识符路径(correlationID 或 taxID)
  • Woovi沙盒可能会解决 create_customer.correlationID 发送到提供商生成的标识符；使用返回的客户有效负载进行后续读取
  • list_customers 支持MCP级别 search 过滤器应用于分页的上游客户结果，而不发送未记录的查询参数
  • get_balance 返回嵌套的所选帐户摘要 balance 字段，默认为新读取； fresh: false 选择进入60秒缓存
  • 平衡资源(woovi://balance/current 和 woovi://balance/{accountId})始终绕过缓存进行实时读取
  • create_refund 支持两种退款流程：
    • 通过以下方式退款 chargeID
    • Pix交易退款通过 transactionEndToEndId
    • MCP模式只强制执行其中一个标识符
  • /webhooks/events 在广播之前，对入站有效载荷进行标准化并屏蔽敏感数据 GET /events

相关 MCP