open-index/open-npm huggingface dataset:
npm package: @meishijian/hsq-mcp-server
Description: Hsq MCP server with payment service
Latest version: 1.0.1

# @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 方式）

```bash
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/hsq-mcp-server@1.0.0
```

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

```json
{
  "mcpServers": {
    "hsq-mcp-server": {
      "command": "npx",
      "args": ["-y", "@meishijian/hsq-mcp-server@1.0.0"],
      "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`

## 本地开发

```bash
npm ci
npm run build
npm start
```

建议在 package.json 中添加：

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

## 发布到 npm（可选）

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

## 许可

MIT