Yeepay Mcp

Yeepay MCP 服务集成

Yeepay MCP 服务通过模型上下文协议（MCP）与 Yeepay 服务集成。

阅读中文文档

功能

• create_webpage_yeepay_payment：创建 Yeepay 网页支付订单
  • 必需参数：orderId（string）、amount（number）、goodsName（string）、userIp（string）
• query_yeepay_payment_status：查询 Yeepay 支付订单状态
  • 必需参数：orderId（string）

先决条件

• Node.js（建议使用 LTS 版本）
• pnpm（或 npm）

安装和配置

1. 安装

# Clone the repository
git clone https://github.com/yop-platform/yeepay-mcp.git
cd yeepay-mcp

# Install dependencies
npm install
# or
pnpm install

2. 配置

将 .env.example 复制为 .env，并配置以下环境变量：

YOP_PARENT_MERCHANT_NO=Your parent merchant number
YOP_MERCHANT_NO=Your merchant number
YOP_APP_PRIVATE_KEY=Your private key
YOP_APP_KEY=Your application AppKey
YOP_NOTIFY_URL=https://your-domain.com/yeepay/notify

使用方法

有多种方式可以运行和使用此 MCP 服务：

1. 本地运行

开发模式（支持热重载）

npm run dev
# or
pnpm run dev

生产模式

# Build the project
npm run build
# or
pnpm run build

# Start the service
npm start
# or
pnpm start

2. 使用 Docker 运行

# Build the image
docker build -t yeepay-mcp .

# Run the container (ensure the .env file exists)
docker run -p 3000:3000 --env-file .env yeepay-mcp

3. 通过 npx 调用

本项目支持通过 npx 直接调用。

调用本地项目（发布前）

在项目目录中运行：

# First, build the project
npm run build

# Use npx to call the local package
npx . [arguments]

或使用完整路径：

npx /absolute/path/to/yeepay-mcp [arguments]

传递参数

可以向 npx 命令传递参数：

npx . --port 3001 --host 0.0.0.0

发布后调用

项目发布到 npm registry 后，可以直接使用：

npx yeepay-mcp [arguments]

也可以指定版本：

npx [email protected] [arguments]

4. 集成为 MCP 服务

此服务可集成到支持 MCP 的工具中（例如 Cline）。

启动方式

方式 1：包运行器（推荐）

pnpm dlx yeepay-mcp
# or
npx yeepay-mcp

（注意：此方式需在软件包发布到 npm 后才能使用）

方式 2：Node（本地开发/直接路径）

node /path/to/yeepay-mcp/dist/index.js

重要提示： 无论使用哪种启动方式，服务都需要在运行时访问工作目录中的 .env 文件以获取配置。

在 Cline 中配置

在 Cline 的 MCP 设置文件（cline_mcp_settings.json）中配置此服务。

使用 Node 配置（本地开发或指定路径）：

"yeepay-mcp": {
  "command": "node",
  "args": [
    "/path/to/yeepay-mcp/dist/index.js" // Replace with the actual absolute path
  ],
  "env": { // Alternatively, place the configuration in the .env file and ensure the service can read it
    "YOP_PARENT_MERCHANT_NO": "Your parent merchant number",
    "YOP_MERCHANT_NO": "Your merchant number",
    "YOP_APP_PRIVATE_KEY": "Your private key",
    "YOP_APP_KEY": "Your application AppKey",
    "YOP_NOTIFY_URL": "https://your-domain.com/yeepay/notify"
  },
  "disabled": false,
  "alwaysAllow": []
}

使用 npx 配置（发布后）：

"yeepay-mcp": {
  "command": "npx",
  "args": [
    "yeepay-mcp" // Package name
    // You can add a version number, e.g., "[email protected]"
    // You can also add arguments, e.g., "--port", "3001"
  ],
  "env": { // Same as above, env or .env file
    "YOP_PARENT_MERCHANT_NO": "Your parent merchant number",
    "YOP_MERCHANT_NO": "Your merchant number",
    "YOP_APP_PRIVATE_KEY": "Your private key",
    "YOP_APP_KEY": "Your application AppKey",
    "YOP_NOTIFY_URL": "https://your-domain.com/yeepay/notify"
  },
  "disabled": false,
  "alwaysAllow": []
}

开发指南

开发模式

使用热重载进行开发：

pnpm run dev
# or
npm run dev

提交消息规范

本项目使用 Conventional Commits 规范来格式化提交消息。每条提交消息都应遵循以下格式：

<type>(<scope>): <subject>

<body>

<footer>

其中：

• type：表示提交类型，例如 feat、fix、docs、style、refactor、test、chore 等。
• scope：（可选）表示提交影响的范围，例如 core、server、payment、config 等。
• subject：简要描述提交内容，使用祈使语气和一般现在时。
• body：（可选）详细描述提交内容，说明修改原因和方式。
• footer：（可选）包含有关破坏性变更（BREAKING CHANGE:）或关闭问题（Closes #123）的信息。

示例：

feat(server): add health check endpoint

Add a new endpoint `/health` to check the health status of the server and its dependencies. This helps with monitoring and deployment verification.

Closes #123
BREAKING CHANGE: The configuration format for database connection has changed.

项目已配置 commitlint 和 husky，会在提交前自动检查提交消息是否符合规范。你可以使用 .github/commit-template.txt 作为提交消息模板。

Git Hooks

本项目使用 Husky 管理 Git hooks：

• pre-commit：运行 lint-staged，自动格式化并检查暂存文件
• commit-msg：使用 commitlint 验证提交消息，确保其遵循 Conventional Commits 规范

运行 npm install 时会自动安装这些 hooks，无需全局安装 Husky。

代码风格

本项目使用 ESLint 和 Prettier 来强制执行并保持代码风格一致。提交代码前，lint-staged 会自动运行，以检查并格式化暂存文件。请确保编辑器已配置相应插件，以便实时获取反馈。

发布流程

准备工作

• 确保 package.json 中的 version 已更新。
• 确保 package.json 中的 bin 字段正确指向 dist/index.js，以便 npx 可以执行它。
• 确保所有更改均已提交，且构建成功（npm run build）。

手动发布到 npm

1. 登录 npm：

   npm login
   

2. 发布：

   npm publish
   # or if using pnpm
   pnpm publish
   

使用 GitHub Actions 自动发布

本项目已配置 GitHub Actions，在创建 GitHub Release 时自动发布到 npm。

1. 创建 GitHub Release：
   • 在 GitHub 仓库页面，点击“Releases”。
   • 点击“Draft a new release”或“Create a new release”。
   • 输入与 package.json 中版本号一致的 Tag version（例如，v0.1.0）。
   • 选择目标分支（通常是 main 或 master）。
   • 输入 Release title（例如，Version 0.1.0）。
   • 添加发布说明（描述此版本中的更改）。
   • 点击“Publish release”。

GitHub Actions 会自动触发 .github/workflows/release.yml 工作流，构建并将包发布到 npm。

版本更新

手动更新版本

使用 npm version 命令更新 package.json 中的版本号并创建 git 标签：

# Patch version update (1.0.0 -> 1.0.1)
npm version patch

# Minor version update (1.0.0 -> 1.1.0)
npm version minor

# Major version update (1.0.0 -> 2.0.0)
npm version major

然后推送到 GitHub 并手动发布：

git push --follow-tags
npm publish

使用 semantic-release 自动更新版本（如果已配置）

如果项目配置了 semantic-release，通常会根据 Conventional Commits 自动更新版本并发布：

• fix: 提交会触发补丁版本更新。
• feat: 提交会触发次要版本更新。
• 包含 BREAKING CHANGE: 的提交会触发主要版本更新。

合并到主分支后，CI/CD 流程会自动计算版本、创建标签、生成发布说明并发布到 npm。

发布后验证

成功发布后，可以通过以下方式进行验证：

1. 在 npm 网站上搜索包名（yeepay-mcp）。
2. 在一个新的空目录中，尝试使用 npx 安装并运行此包：

   npx yeepay-mcp --help # or other arguments
   

贡献指南

欢迎贡献代码、报告错误和提出改进建议。请按以下步骤操作：

1. Fork 此仓库到你的 GitHub 账户。
2. Clone 你 Fork 的仓库到本地：git clone https://github.com/YOUR_USERNAME/yeepay-mcp.git
3. 创建一个新的功能分支：git checkout -b feature/your-amazing-feature
4. 修改代码。
5. 提交更改时，请遵循提交消息约定：git commit -m 'feat: add some amazing feature'
6. 将分支推送到你的 Fork：git push origin feature/your-amazing-feature
7. 在原始仓库中创建一个 Pull Request，描述你的更改。

许可证

本项目采用 Apache 许可证。详情请参阅 LICENSE 文件。

联系方式

如有问题或建议，请通过以下方式联系我们：

• 在 GitHub 仓库中提交 Issue。
• 发送电子邮件至：[email protected]

提示

在软件包发布到 npm 注册表之前，配置或调用时请确保使用正确的 本地路径 或 绝对路径，而不是软件包名称，以避免出现“package was not found”等错误。