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:
• WOOVI_AUTH_MODE=bearer 发送 Authorization: Bearer
• 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/

文档

• docs/tools/README.md
• docs/architecture/README.md
• docs/qa/api-parity-matrix.md
• docs/postman/woovi-api.postman_collection.json
• docs/postman/mcp-http.postman_collection.json
• docs/demo/README.md

验证状态

当前本地状态：

• 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