Comax 決済リンク MCP

Comaxと統合して支払いリンクの作成、注文管理、顧客情報の取得を行うFastMCPサーバー。MCPサーバー用のTypeScriptフレームワークであるFastMCPを使用して構築されています。

[！注記]
このサーバーは、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

構成

このサーバーは、Comax APIとやり取りするために、いくつかの認証情報とIDを必要とします。これらは現在、 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。

ローカル開発用の.envファイルでこれらを管理するには、 dotenvなどのライブラリの使用を検討してください。

クイックスタート

以下は、このサーバー ( 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は、ツールパラメータの定義に標準スキーマ仕様を使用します。このサーバーでは、主に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は、クライアント接続ごとに新しいサーバーインスタンスを割り当て、1対1の通信を実現します。FastMCPサーバーで認証が設定されている場合、セッション固有のデータにアクセスできます（ツール内でリクエストごとに処理されるComax API認証とは異なります）。

サーバーの実行

`mcp-cli`でテストする

サーバーをテストおよびデバッグする最も速い方法はfastmcp devを使用することです。

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

これにより、ターミナルで MCP サーバーをテストおよびデバッグするために、 mcp-cliを使用してサーバーが実行されます。

`MCP Inspector`で検査する

もう 1 つの方法は、公式の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 をtscなどで JS にコンパイルした後)。または、 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へのパスが正しいこと、および必要な環境変数 (定数よりも環境変数を使用する場合) が設定されていることを確認します。

鍛冶屋の統合

このプロジェクトは、GitHub プルリクエストを介してコードの改善、テスト、デプロイのワークフローを自動化するために Smithery と統合される予定です。Smithery では、ブランチの作成や変更の提案を行うために適切な GitHub 権限が必要です。

謝辞

このサーバーはFastMCPを使用して構築されています。
FastMCP は、 Jonathan LowinによるPython 実装にインスピレーションを受けています。
FastMCP のコードベースの一部はLiteMCPおよびModel Context プロトコルで SSE をやってみるから採用されました。