E Sewa MCP

eSewa MCP服务器

用于将eSewa支付网关与AI应用程序集成的模型上下文协议（MCP）服务器。该服务器提供了一个标准化的接口，用于通过MCP协议处理电子支付。

特性

• 动态凭据配置：为每个会话配置商家凭据
• 沙盒和生产支持：在测试和现场环境之间切换
• 基于会话的管理：使用单独的凭据存储处理多个用户
• 符合JSON-RPC 2.0标准：标准MCP协议实施
• 健康监测：内置健康检查和状态端点
• 错误处理：全面的错误处理和验证
• HMAC签名验证：使用HMAC-SHA256进行安全支付验证

快速开始

先决条件

• Node.js 18+
• npm或纱线
• eSewa商家账户（用于生产）

安装

# Clone the repository
git clone 
cd esewa-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Start the server
npm start

环境配置

创建一个 .env 文件基于 .env.example:

# Server Configuration
PORT=3000
NODE_ENV=production

# eSewa API Configuration
ESEWA_ENVIRONMENT=sandbox  # or 'production'

# Optional: Default merchant credentials
ESEWA_MERCHANT_CODE=your_merchant_code
ESEWA_SECRET_KEY=your_secret_key

# Security Configuration
CORS_ORIGIN=https://yourdomain.com
SESSION_SECRET=your_session_secret_here

# Logging
LOG_LEVEL=info

API终点

健康检查

GET /

返回服务器状态和可用功能。

MCP端点

POST /mcp

用于工具发现和执行的主MCP协议端点。

SSE端点

GET /sse

用于实时通信的服务器发送事件端点。

消息端点

POST /messages

处理来自MCP客户端的传入消息。

可用工具

配置证书

为会话配置eSewa商家凭据。

参数：

• merchantCode （string）：您的eSewa商户代码
• secretKey （string）：您的eSewa密钥
• environment （string）：“沙盒”或“生产”
• sessionId （字符串，可选）：凭证存储的会话ID

get_test_credentials

获取用于开发的沙盒测试凭据。

起始日期_付款

发起电子钱包付款。

参数：

• amount （数字）：付款金额
• productCode （string）：产品/服务代码
• successUrl （string）：成功支付重定向的URL
• failureUrl （string）：支付重定向失败的URL

验证_付款

验证已完成的付款。

参数：

• amount （数字）：预计付款金额
• referenceId （string）：eSewa交易参考ID
• productCode （string）：产品/服务代码

付款状态

获取付款状态。

参数：

• referenceId （string）：eSewa交易参考ID

get_test_users

获取沙盒测试的测试用户凭据。

测试

连接测试

npm run test:connection

完整测试套件

npm run test:all

手动测试

# Start server with validation
npm run start:safe

# Test health endpoint
curl http://localhost:3000/

# Test MCP endpoint
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "id": 1}'

部署

本地开发

npm run dev

生产部署

# Set production environment
export NODE_ENV=production
export PORT=3000

# Start server
npm start

Docker部署

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install --production

COPY . .
EXPOSE 3000

CMD ["npm", "start"]

生产环境变量

• NODE_ENV=production
• PORT=3000 （或您偏好的端口）
• ESEWA_ENVIRONMENT=production
• ESEWA_MERCHANT_CODE=your_production_merchant_code
• ESEWA_SECRET_KEY=your_production_secret_key
• SESSION_SECRET=strong_random_string
• CORS_ORIGIN=your_domain

安全考虑

1. 永不承诺 .env 文件 包含真实凭证
2. 使用HTTPS 所有端点的生产中
3. 验证所有输入 在客户端和服务器端
4. 安全地存储凭据 使用环境变量
5. 使用强会话秘密 用于生产部署
6. 实施速率限制 用于生产用途
7. 监控日志 可疑活动

eSewa集成

沙盘环境

• 使用来自的测试凭据 get_test_credentials 工具
• 为支付模拟提供测试用户
• 无真实货币交易

生产环境

• 需要有效的eSewa商家帐户
• 真实货币交易
• 需要安全的凭据管理

付款流程

1. 使用配置凭据 configure_credentials
2. 使用发起付款 initiate_payment
3. 用户在eSewa门户完成付款
4. 使用验证付款 verify_payment
5. 使用检查状态 get_payment_status

错误处理

服务器为以下对象提供详细的错误消息：

• 无效凭证
• 网络超时
• 付款验证失败
• 会话管理问题
• 参数验证错误

监控

监控这些端点的运行状况：

• / -基本健康检查
• 服务器日志中的错误和警告
• 付款成功/失败率
• API调用的响应时间

故障排除

常见问题

端口已在使用中

# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

连接被拒绝

• 检查服务器是否正在运行
• 验证端口配置
• 检查防火墙设置

MCP连接问题

• 验证MCP客户端配置
• 检查服务器日志是否有错误
• 测试用 npm run test:connection

付款验证失败

• 验证商户凭据
• 检查eSewa环境（沙盒与生产环境）
• 验证付款参数

贡献

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交拉取请求

许可证

该项目根据MIT许可证获得许可。

支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看服务器日志以了解错误详细信息
3. 使用提供的测试脚本进行测试
4. 在GitHub上打开一个问题

更新日志

v1.0.0

• 初始版本
• MCP协议实现
• eSewa支付集成
• 基于会话的凭证管理
• 健康监测和错误处理