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: BearerMCP_HTTP_AUTH_TOKEN是HTTP传输和保护所必需的POST /mcp和GET /eventsWOOVI_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:buildpnpm 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:sandbox2026年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