Test AI Payment MCP Local

test-ai-payment-mcp-local is a local-only MCP server for demonstrating AI-agent payment flows on any machine.

It does not perform real payments. When an AI-agent starts the MCP server, the package launches an embedded local Runtime API, browser approval page, and mock payment provider inside the same process. The agent talks to MCP over stdio; the human demo user can approve in a local browser or complete the test flow through MCP tools.

What It Provides

• A globally installable MCP command: test-ai-payment-mcp-local
• Local payment request creation, polling, cancellation, success, and failure simulation
• A browser approval page returned as a localhost payment URL
• A no-browser completion tool for scripted demos
• JSON-file persistence in the user's local app data directory
• No external database, hosted server, or real payment provider dependency

Requirements

• Node.js 20 or newer
• npm

Install

From npm:

npm install -g test-ai-payment-mcp-local

For local package testing before publishing:

npm pack
npm install -g .\test-ai-payment-mcp-local-1.0.0.tgz

Confirm the command is available:

test-ai-payment-mcp-local

The command is intended to be launched by an MCP client. If you run it directly in a terminal, it will wait for MCP JSON-RPC messages on stdin.

Add To An AI Agent

Use this MCP server configuration:

{
  "mcpServers": {
    "test-ai-payment": {
      "command": "test-ai-payment-mcp-local"
    }
  }
}

The MCP process writes protocol messages only to stdout. Service logs are written to stderr so MCP clients can parse stdout safely.

Demo Flow With Browser Approval

Ask the AI-agent to request a payment using the request_payment tool:

{
  "title": "购买九天 API Credits",
  "description": "本地 MCP 测试支付",
  "amount": 19,
  "currency": "CNY",
  "merchant_id": "jiutian_001",
  "agent_name": "Demo Agent",
  "task_context": "正在测试 AI Agent 本地支付确认流程"
}

The tool returns a response like:

{
  "payment_id": "pay_abc123def456",
  "payment_url": "http://127.0.0.1:54321/approve/pay_abc123def456",
  "status": "PENDING",
  "expires_at": "2026-06-01T10:05:00.000Z"
}

Open payment_url in a browser and click confirm or cancel. The agent can then call get_payment_status until the payment reaches SUCCESS, FAILED, CANCELLED, or EXPIRED.

Demo Flow Without Browser

After request_payment, call complete_test_payment:

{
  "payment_id": "pay_abc123def456",
  "status": "SUCCESS"
}

Use "FAILED" to simulate a failed payment.

MCP Tools

request_payment

Creates a local test payment and returns a browser approval URL.

Required input:

• title: payment title
• description: payment description
• amount: numeric amount
• currency: currently CNY for bundled demo merchants
• merchant_id: for example jiutian_001
• agent_name: name of the calling agent

Optional input:

• task_context: task text shown on the approval page
• metadata: JSON object preserved in terminal status responses

get_payment_status

Returns the latest status for a payment.

Required input:

• payment_id

cancel_payment

Cancels a pending or approving payment.

Required input:

• payment_id
• reason: one of user_declined, task_aborted, or timeout

complete_test_payment

Completes a local test payment without opening the approval page.

Required input:

• payment_id
• status: SUCCESS or FAILED

list_test_payments

Lists locally stored payment sessions.

Optional input:

• status: a single status or an array of statuses

Local Data

By default, state is written outside the package directory:

• Windows: %LOCALAPPDATA%\test-ai-payment-mcp-local\state.json
• macOS: ~/Library/Application Support/test-ai-payment-mcp-local/state.json
• Linux: $XDG_DATA_HOME/test-ai-payment-mcp-local/state.json or ~/.local/share/test-ai-payment-mcp-local/state.json

Override the state file with:

$env:PAYMENT_STATE_FILE="D:\tmp\payment-state.json"

or:

$env:DATABASE_URL="file:./dev.db.json"

Optional Environment Variables

• RUNTIME_PORT: local Runtime API port. Defaults to an available random port.
• UI_PORT: local approval UI port. Defaults to an available random port.
• MOCK_PORT: local mock provider port. Defaults to an available random port.
• SESSION_TTL_MINUTES: payment expiry window. Defaults to 5.
• MOCK_FAILURE_RATE: browser confirmation failure rate. Defaults to 0.
• PAYMENT_STATE_FILE: explicit JSON state file path.
• DATABASE_URL: legacy file: state path override.

Troubleshooting

• If the agent cannot start the MCP command, confirm node --version is 20 or newer and test-ai-payment-mcp-local is on PATH.
• If browser approval links do not open, check whether local firewall software blocks loopback ports on 127.0.0.1.
• If a fixed port is already in use, unset RUNTIME_PORT, UI_PORT, and MOCK_PORT so the server can choose random available ports.
• If stale demo data appears, delete the local state file or set PAYMENT_STATE_FILE to a fresh path.

Development

npm test
npm run build

Legacy standalone services are still available for development:

npm run dev:runtime
npm run dev:mock
npm run dev:ui
npm run dev:mcp

The local MCP architecture is specified in docs/local_mcp_spec.md.

License

This package uses a restrictive local evaluation license. Commercial use, redistribution, sublicensing, and derivative works are not permitted. See LICENSE.