Comax 支付链接 MCP

一个 FastMCP 服务器，用于与 Comax 集成，创建支付链接、管理订单并检索客户信息。它基于FastMCP构建，这是一个用于 MCP 服务器的 TypeScript 框架。

[！笔记]
该服务器旨在与 Comax ERP/支付系统接口。

特征

**Comax 集成：**为关键 Comax 操作提供工具。
**FastMCP 核心：**利用 FastMCP 实现强大的 MCP 服务器功能，包括：
- 使用 Zod 模式验证的简单工具定义
- 会话管理
- 日志记录和错误处理
- 用于远程通信的 SSE（可配置）
- CORS（默认启用）
- 进度通知（对于长期运行的工具，如果实施）
- 类型化服务器事件
- 用于测试和调试的 CLI

安装

确保您已安装 Node.js 和 pnpm（或 npm/yarn）。

# Clone the repository (if you haven't already)
# git clone <your-repo-url>
# cd <your-repo-name>

# Install dependencies
pnpm install

配置

此服务器需要多个凭据和 ID 才能与 Comax API 交互。这些内容目前已硬编码为src/index.ts中的常量，但理想情况下，应通过环境变量进行配置，以便在生产环境中使用。

所需配置（参见src/index.ts ）：

ORDER_LOGIN_ID , ORDER_LOGIN_PASSWORD ：用于 Comax 订单操作。
TOKEN_LOGIN_NAME 、 TOKEN_LOGIN_PASSWORD ：用于 Comax 信用令牌生成。
PAYMENT_LOGIN_ID , PAYMENT_LOGIN_PASSWORD ：用于 Comax 支付页面。
BRANCH_ID 、 STORE_ID 、 PRICE_LIST_ID ：默认 Comax 操作 ID。
RETURN_PAGE ：付款后重定向的 URL。
COMAX_ORDER_ENDPOINT 、 COMAX_TOKEN_ENDPOINT 、 COMAX_PAYMENT_PAGE 、 COMAX_CUSTOMER_ENDPOINT ：Comax API 端点 URL。

考虑使用像dotenv这样的库在.env文件中管理这些内容以进行本地开发。

快速入门

以下是在此服务器（ src/index.ts ）中定义工具的简化示例：

import { FastMCP } from "fastmcp";
import { z } from "zod"; // Using Zod for schema validation

const server = new FastMCP({
  name: "Comax Payment Link MCP",
  version: "1.0.0",
});

// Example: Create Comax Payment Link Tool
server.addTool({
  name: "create_comax_payment_link",
  description: "Creates a Comax order and returns a payment link.",
  parameters: z.object({
    customerId: z.string().default("22222"),
    customerName: z.string(),
    customerPhone: z.string(),
    customerCity: z.string(),
    items: z.array(z.object({ // Simplified item schema
      sku: z.string(),
      quantity: z.number().int().positive(),
      price: z.number().positive(),
      totalSum: z.number().positive(),
    })).min(1),
    // ... other parameters
  }),
  execute: async (args, { log }) => {
    log.info("Attempting to create Comax payment link for", args.customerName);
    // ... logic to call Comax API ...
    const paymentUrl = "https://example-payment-url.com/pay?token=XYZ"; // Placeholder
    log.info("Payment link created successfully.");
    return {
      content: [
        {
          type: "text",
          text: `Comax payment link created.\nOrder DocNumber: 12345\nPayment Link: ${paymentUrl}`,
        },
      ],
    };
  },
});

server.start({
  transportType: "stdio", // Or "sse" for network access
});

console.log("Comax Payment Link MCP server started");

您可以使用 FastMCP CLI 在终端中测试服务器。

可用工具

该服务器公开了以下与 Comax 交互的工具：

create_comax_payment_link ：创建 Comax 订单并返回付款链接。
update_comax_order_payment ：通过付款确认更新 Comax 订单。
get_comax_customer_details ：通过 CustomerID 获取 Comax 商业客户详细信息。
get_comax_order_status ：通过 DocNumber 或 Reference 检索 Comax 订单的状态。
get_comax_order_details ：获取 Comax 订单的详细信息。
get_comax_order_pdf_link ：获取 Comax 订单的 PDF 链接。
set_comax_order_status ：设置 Comax 订单的状态。
get_comax_orders_by_credit_card ：获取与信用卡号相关的订单。
get_comax_orders_simple ：根据日期范围和可选过滤器检索订单。如果结果为 XML URL，则获取并提供记录样本。
chk_item_exists_in_orders ：检查订单中是否存在特定商品。
set_comax_order_self_pickup ：将 Comax 订单标记为自提。

有关每个工具的具体参数和实现细节，请参阅src/index.ts 。

核心概念（FastMCP）

工具

MCP 中的工具允许服务器公开可执行函数，这些函数可被客户端（例如 AI 模型或其他应用程序）调用来执行操作。该服务器使用工具与 Comax API 进行交互。

FastMCP 使用标准 Schema规范来定义工具参数。本服务器主要使用 Zod 来实现此目的。

工具定义示例（Zod）：

import { z } from "zod";

server.addTool({
  name: "example_comax_tool",
  description: "An example tool description.",
  parameters: z.object({
    someParameter: z.string().describe("Description for the parameter"),
    // ... other parameters
  }),
  execute: async (args, { log, reportProgress }) => {
    log.info("Executing example_comax_tool with", args);
    // Your tool logic here - e.g., call Comax API
    // reportProgress({ progress: 50, total: 100 }); // Optional progress reporting
    return {
      content: [{ type: "text", text: "Tool execution finished." }],
    };
  },
});

日志记录和错误处理

**日志记录：**工具可以使用execute上下文中的log.info() 、 log.warn()等来发送日志消息。
**用户错误：**从fastmcp抛出UserError ，以便向最终用户显示错误。
**进度：**使用reportProgress进行长时间运行的操作。

会议

FastMCP 为每个客户端连接分配一个新的服务器实例，从而实现一对一通信。如果在 FastMCP 服务器上配置了身份验证，则可以访问会话特定的数据（不要与 Comax API 身份验证混淆，后者在工具中按请求进行处理）。

运行您的服务器

使用`mcp-cli`进行测试

测试和调试服务器的最快方法是使用fastmcp dev ：

# Ensure you are in the project root directory
npx fastmcp dev src/index.ts

这将使用mcp-cli运行您的服务器，以便在终端中测试和调试您的 MCP 服务器。

使用`MCP Inspector`进行检查

另一种方法是使用官方MCP Inspector通过 Web UI 检查您的服务器：

npx fastmcp inspect src/index.ts

使用 SSE 进行网络访问

为了使服务器可通过网络访问（例如，对于远程客户端或 Smithery）：

// In src/index.ts, modify server.start:
server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse", // Or your desired endpoint
    port: 8080,       // Or your desired port
  },
});

然后运行node src/index.js （将 TS 编译为 JS 之后，例如使用tsc ）或使用tsx直接执行： npx tsx src/index.ts 。

常问问题

如何与 Claude Desktop（或类似的 MCP 客户端）一起使用？

按照https://modelcontextprotocol.io/quickstart/user上的通用指南并配置 MCP 客户端以启动您的服务器。

mcp_config.json条目示例：

{
  "mcpServers": {
    "comax-gimo-mcp": {
      "command": "npx",
      "args": [
        "tsx",
        "/FULL/PATH/TO/YOUR/gimo-mcp/src/index.ts" // Replace with the absolute path
      ],
      "env": {
        // If you move Comax credentials to environment variables, define them here:
        // "ORDER_LOGIN_ID": "your_order_login_id",
        // "ORDER_LOGIN_PASSWORD": "your_order_login_password",
        // ... and so on for all required credentials/configs
      }
    }
  }
}

确保src/index.ts的路径正确，并且设置了所有必要的环境变量（如果您选择使用它们而不是常量）。

Smithery 集成

该项目旨在与 Smithery 集成，以便通过 GitHub 拉取请求实现代码改进、测试和部署的自动化工作流程。Smithery 需要适当的 GitHub 权限才能创建分支并提出变更建议。

致谢

该服务器是使用FastMCP构建的。
FastMCP 的灵感来自Jonathan Lowin的Python 实现。
FastMCP 的部分代码库采用了LiteMCP和Model Context 协议でSSEをやってみる。