코맥스 결제 링크 MCP

Comax와 통합하여 결제 링크 생성, 주문 관리, 고객 정보 조회를 위한 FastMCP 서버입니다. MCP 서버용 TypeScript 프레임워크인 FastMCP를 기반으로 구축되었습니다.

[!메모]
이 서버는 Comax ERP/결제 시스템과의 인터페이스를 위해 설계되었습니다.

특징

Comax 통합: Comax의 주요 운영을 위한 도구를 제공합니다.
FastMCP Core: 다음을 포함한 강력한 MCP 서버 기능을 위해 FastMCP를 활용합니다.
- Zod 스키마 검증을 통한 간단한 도구 정의
- 세션 관리
- 로깅 및 오류 처리
- 원격 통신을 위한 SSE(구성 가능)
- CORS(기본적으로 활성화됨)
- 장기 실행 도구의 경우 진행 알림(구현된 경우)
- 입력된 서버 이벤트
- 테스트 및 디버깅을 위한 CLI

설치

Node.js와 pnpm(또는 npm/yarn)이 설치되어 있는지 확인하세요.

지엑스피1

구성

이 서버는 Comax API와 상호 작용하기 위해 여러 자격 증명과 ID가 필요합니다. 이러한 자격 증명과 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.

로컬 개발을 위해 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는 도구 매개변수를 정의하기 위해 표준 스키마 사양을 사용합니다. 이 서버는 이 목적으로 주로 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` 으로 검사하세요

또 다른 방법은 공식 MCP Inspector 사용하여 웹 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
  },
});

그런 다음 TS를 JS로 컴파일한 후(예: tsc 사용) node src/index.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 프로토콜에서 채택되었습니다.