@meishijian/hsq-mcp-server

基于 Model Context Protocol (MCP) 的慧收钱支付服务，支持主扫下单、查询支付、申请退款、退款查询。可通过 npx 一键拉起，适配 Cursor 等 MCP 客户端。

特性

• STDIO 传输，开箱即用
• 四个工具：
  • create-hsq-dynamic-pay（主扫下单，返回链接需转二维码）
  • query-hsq-pay（查询支付结果，orderStatus = INIT/PROCESSING/SUCCESS/FAIL）
  • refund-hsq-pay（申请退款，refundType 固定 2）
  • query-hsq-refund（退款查询，orderStatus = INIT/PROCESSING/SUCCESS/FAIL）
• 环境变量前缀统一为 HSQ_
• 可通过 HSQ_SELECT_TOOLS 按需暴露工具，默认 ALL（全部）
• 日志默认开启（HSQ_LOG_ENABLED=true），输出到 ~/mcp-server-hsqpay.log

快速开始（npx 方式）

export HSQ_MERCHANT_NO="your-merchant-no"
export HSQ_PRIVATE_KEY="your-private-key"
export HSQ_PUBLIC_KEY="your-public-key"
export HSQ_MERCHANT_KEY="your-merchant-key"
export HSQ_RETURN_URL="https://your.domain/hsq/notify"   # 可选
export HSQ_PAGE_URL="https://your.domain/hsq/page"       # 可选
export HSQ_LOG_ENABLED=true                                # 默认已开启
export HSQ_SELECT_TOOLS=ALL                                # 或 create-hsq-dynamic-pay,query-hsq-pay

npx -y @meishijian/[email protected]

在 Cursor 的 ~/.cursor/mcp.json 中也可配置：

{
  "mcpServers": {
    "hsq-mcp-server": {
      "command": "npx",
      "args": ["-y", "@meishijian/[email protected]"],
      "env": {
        "HSQ_MERCHANT_NO": "your-merchant-no",
        "HSQ_PRIVATE_KEY": "your-private-key",
        "HSQ_PUBLIC_KEY": "your-public-key",
        "HSQ_MERCHANT_KEY": "your-merchant-key",
        "HSQ_RETURN_URL": "https://your.domain/hsq/notify",
        "HSQ_PAGE_URL": "https://your.domain/hsq/page",
        "HSQ_LOG_ENABLED": "true",
        "HSQ_SELECT_TOOLS": "ALL"
      }
    }
  }
}

工具与参数

通用规则：所有“单号”字段请勿包含 -、_ 等符号。

• create-hsq-dynamic-pay

  • 入参：transNo、orderAmt（单位：元；1=1分，100=1元）、goodsInfo
  • 说明：返回的链接需转换为二维码，用户可使用支付宝/微信/云闪付扫码支付

• query-hsq-pay

  • 入参：transNo
  • 返回：result.orderStatus ∈ { INIT, PROCESSING, SUCCESS, FAIL }

• refund-hsq-pay

  • 入参：transNo、origTransNo、origOrderAmt（分）、orderAmt（分）、refundReason

• query-hsq-refund

  • 入参：transNo（退款申请时的商户订单号）
  • 返回：result.orderStatus ∈ { INIT, PROCESSING, SUCCESS, FAIL }

环境变量

• 必填：HSQ_MERCHANT_NO、HSQ_PRIVATE_KEY、HSQ_PUBLIC_KEY、HSQ_MERCHANT_KEY
• 可选：HSQ_RETURN_URL、HSQ_PAGE_URL
• 日志：HSQ_LOG_ENABLED（默认 true）
• 工具选择：HSQ_SELECT_TOOLS，默认 ALL；示例：create-hsq-dynamic-pay,query-hsq-pay

本地开发

npm ci
npm run build
npm start

建议在 package.json 中添加：

{
  "files": ["build/**", "package.json", "README.md", "LICENSE"],
  "scripts": {
    "prepublishOnly": "npm run build"
  }
}

发布到 npm（可选）

npm version patch   # or minor / major
npm publish --access public

许可

MIT