Woovi MCP Server

关键词

上下文服务工具与资源Woovi OpenPix 集成Pix 支付多传输 MCP

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个基于 MCP 的 Woovi API 后端服务器，面向 LLM 客户端提供统一的工具集合、资源数据和 Prompts，便于在对话中直接读取余额、列示交易、创建收费等操作，并可渲染成对话友好的内容。

  • 主要功能点

    • MCP 核心能力：注册并暴露工具（如创建 Charge、查询 Charge、管理 Customers、Transactions、Refunds 等）、资源（余额、文档端点、Webhook schemas）以及提示模板（daily_summary、customer_report、reconciliation_check）。
    • 多传输通道：支持标准输出/输入的 Stdio 传输以及基于 Express 的 HTTP 传输，方便本地桌面客户端和远程多租户场景接入。
    • 安全与健壮性：完整的 TypeScript 实现、Zod 的输入校验、缓存策略、429 重试与回退、错误处理与日志掩码（PII 保护）。
    • 服务器端能力：通过 WooviClient 调用 Woovi/OpenPix API，具备会话管理、能力声明与多租户支持能力。
    • 生产就绪特性：包含单元和集成测试、详细的文档结构及清晰的开发/部署说明。

  • 安装步骤

    1. 安装依赖并构建：使用 pnpm install 进行依赖安装，然后执行 pnpm build 构建服务器包。
    2. 启动方式
      • Stdio 传输：适用于 Claude Desktop 等桌面工具，启动后通过配置的命令路径加载 stdio.js 入口。
      • HTTP 传输：使用 Node 启动 HTTP 服务器，监听端口并提供 /mcp 的请求入口。
    3. 环境配置
      • 需要在环境中设置 WOOVI_APP_ID，用于 Woovi 客户端的初始化。
      • 若使用 HTTP 传输，需可选地配置 WOOVI_API_URL（默认为生产环境）以及端口等参数。

  • 服务器配置（给 MCP 客户端使用的配置信息，示例以 JSON 表示，实际在客户端按需填写）

    • STDIO 模式示例配置（服务器名为 woovi-mcp-server） { "name": "woovi-mcp-server", "command": "node", "args": ["packages/server/dist/stdio.js"], "env": { "WOOVI_APP_ID": "your-app-id" } // 注：该配置用于在 MCP 客户端通过 Stdio 方式连接 MCP 服务器 }

    • HTTP 模式示例配置（服务器名为 woovi-mcp-server-http） { "name": "woovi-mcp-server-http", "command": "node", "args": ["packages/server/dist/http.js"], "env": { "WOOVI_APP_ID": "your-app-id", "WOOVI_API_URL": "https://api.woovi.com", "PORT": "3000" } // 注：该配置用于在 MCP 客户端通过 HTTP/POST /mcp 方式连接 MCP 服务器 }

  • 基本使用方法

    1. 启动服务器（根据选择的传输通道启动相应入口，例如 stdio.js 或 http.js）。
    2. 在 MCP 客户端配置中注册相应的服务器信息（见上面的服务器配置示例）。
    3. 客户端通过 JSON-RPC 调用工具、读取资源、执行 prompts，服务器会与 Woovi API 进行交互并返回结构化结果。
    4. 通过服务器的日志与错误处理机制进行运维和调试。

  • 重要提示

    • 服务器端会对敏感信息进行遮罩处理，在返回给 AI 客户端的工具输出中隐藏税号、手机号等 PII。
    • 余额与部分数据具备缓存机制（默认 60 秒）以提升性能，必要时可通过参数关闭缓存。

服务器信息

访问项目