Yeepay MCP Service Integration

The Yeepay MCP service provides integration with Yeepay services via the Model Context Protocol (MCP).

阅读中文文档

Features

• create_webpage_yeepay_payment: Create Yeepay webpage payment order
  • Required parameters: orderId (string), amount (number), goodsName (string), userIp (string)
• query_yeepay_payment_status: Query Yeepay payment order status
  • Required parameters: orderId (string)

Prerequisites

• Node.js (LTS version recommended)
• pnpm (or npm)

Installation and Configuration

1. Installation

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

# Install dependencies
npm install
# or
pnpm install

2. Configuration

Copy .env.example to .env and configure the following environment variables:

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

Usage

There are several ways to run and use this MCP service:

1. Run Locally

Development Mode (with hot-reloading)

npm run dev
# or
pnpm run dev

Production Mode

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

# Start the service
npm start
# or
pnpm start

2. Run with 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. Call via npx

This project supports direct invocation via npx.

Local Project Invocation (Before Publishing)

Run in the project directory:

# First, build the project
npm run build

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

Or use the full path:

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

Passing Arguments

You can pass arguments to the npx command:

npx . --port 3001 --host 0.0.0.0

Invocation After Publishing

Once the project is published to the npm registry, you can use it directly:

npx yeepay-mcp [arguments]

And you can specify a version:

npx yeepay-mcp@0.1.0 [arguments]

4. Integrate as an MCP Service

This service can be integrated into tools that support MCP (like Cline).

Startup Methods

Method 1: Package Runner (Recommended)

pnpm dlx yeepay-mcp
# or
npx yeepay-mcp

(Note: This method is available after the package is published to npm)

Method 2: Node (Local Development/Direct Path)

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

Important Note: Regardless of the startup method, the service needs access to the .env file in the working directory at runtime to obtain configuration.

Configure in Cline

Configure this service in Cline's MCP settings file (cline_mcp_settings.json).

Configure using Node (Local Development or Specific Path):

"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": []
}

Configure using npx (After Publishing):

"yeepay-mcp": {
  "command": "npx",
  "args": [
    "yeepay-mcp" // Package name
    // You can add a version number, e.g., "yeepay-mcp@0.1.0"
    // 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": []
}

Development Guide

Development Mode

Develop with hot-reloading:

pnpm run dev
# or
npm run dev

Commit Message Convention

This project uses the Conventional Commits specification to format commit messages. Each commit message should follow this format:

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

<body>

<footer>

Where:

• type: Indicates the type of commit, e.g., feat, fix, docs, style, refactor, test, chore, etc.
• scope: (Optional) Indicates the scope affected by the commit, e.g., core, server, payment, config, etc.
• subject: Briefly describe the content of the commit, use imperative, present tense.
• body: (Optional) Describe the content of the commit in detail, explaining the reason and method of modification.
• footer: (Optional) Contains information about breaking changes (BREAKING CHANGE:) or closing issues (Closes #123).

Example:

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.

The project has configured commitlint and husky to automatically check if commit messages conform to the specification before committing. You can use .github/commit-template.txt as a template for commit messages.

Git Hooks

This project uses Husky to manage Git hooks:

• pre-commit: Runs lint-staged to automatically format and lint staged files
• commit-msg: Validates commit messages using commitlint to ensure they follow the Conventional Commits specification

The hooks are automatically installed when you run npm install and do not require any global installation of Husky.

Code Style

This project uses ESLint and Prettier to enforce and maintain code style consistency. Before committing code, lint-staged will automatically run to check and format staged files. Please ensure your editor is configured with the corresponding plugins for real-time feedback.

Release Process

Preparation

• Ensure the version in package.json is up-to-date.
• Ensure the bin field in package.json correctly points to dist/index.js so that npx can execute it.
• Ensure all changes are committed and the build is successful (npm run build).

Manual Publishing to npm

1. Log in to npm:

   npm login

2. Publish:

   npm publish
   # or if using pnpm
   pnpm publish

Automatic Publishing with GitHub Actions

This project is configured with GitHub Actions to automatically publish to npm when a GitHub Release is created.

1. Create GitHub Release:
   • On the GitHub repository page, click "Releases".
   • Click "Draft a new release" or "Create a new release".
   • Enter a Tag version matching the version number in package.json (e.g., v0.1.0).
   • Select the target branch (usually main or master).
   • Enter the Release title (e.g., Version 0.1.0).
   • Add release notes (describe the changes in this version).
   • Click "Publish release".

GitHub Actions will automatically trigger the .github/workflows/release.yml workflow to build and publish the package to npm.

Version Updates

Manual Version Update

Use the npm version command to update the version number in package.json and create a git tag:

# 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

Then push to GitHub and publish manually:

git push --follow-tags
npm publish

Automatic Version Update with semantic-release (If Configured)

If the project is configured with semantic-release, version updates and publishing are usually automated based on Conventional Commits:

• fix: commits trigger a patch version update.
• feat: commits trigger a minor version update.
• Commits containing BREAKING CHANGE: trigger a major version update.

After merging into the main branch, the CI/CD process automatically calculates the version, creates tags, generates release notes, and publishes to npm.

Post-Publish Verification

After successful publishing, you can verify in the following ways:

1. Search for your package name (yeepay-mcp) on the npm website.
2. In a new empty directory, try installing and running your package using npx:

   npx yeepay-mcp --help # or other arguments

Contributing Guide

Contributions, bug reports, and improvement suggestions are welcome. Please follow these steps:

1. Fork this repository to your GitHub account.
2. Clone your forked repository locally: git clone https://github.com/YOUR_USERNAME/yeepay-mcp.git
3. Create a new feature branch: git checkout -b feature/your-amazing-feature
4. Make your code changes.
5. Ensure you follow the commit message convention when committing changes: git commit -m 'feat: add some amazing feature'
6. Push your branch to your fork: git push origin feature/your-amazing-feature
7. Create a Pull Request in the original repository describing your changes.

License

This project is licensed under the Apache License. See the LICENSE file for details.

Contact

For questions or suggestions, please contact us via:

• Submit an Issue in the GitHub repository.
• Send an email to: dreambt@gmail.com

Tip

Before the package is published to the npm registry, ensure you use the correct local path or absolute path when configuring or calling it, instead of the package name, to avoid errors like "package was not found".