Comax Платежная ссылка MCP

Сервер FastMCP для интеграции с Comax для создания платежных ссылок, управления заказами и получения информации о клиентах. Создан с помощью FastMCP , фреймворка TypeScript для серверов MCP.

[!ПРИМЕЧАНИЕ]
Этот сервер предназначен для взаимодействия с платежной системой Comax ERP.

Функции

Интеграция Comax: предоставляет инструменты для ключевых операций Comax.
FastMCP Core: использует 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

Конфигурация

Этот сервер требует несколько учетных данных и идентификаторов для взаимодействия с API Comax. В настоящее время они жестко закодированы как константы в 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 по умолчанию.
RETURN_PAGE : URL для перенаправления после оплаты.
COMAX_ORDER_ENDPOINT , COMAX_TOKEN_ENDPOINT , COMAX_PAYMENT_PAGE , COMAX_CUSTOMER_ENDPOINT : URL-адреса конечных точек API Comax.

Рассмотрите возможность использования библиотеки вроде 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 : извлекает данные о бизнес-клиенте Comax по CustomerID.
get_comax_order_status : Извлекает статус заказа Comax по DocNumber или Reference.
get_comax_order_details : Получает подробную информацию о заказе Comax.
get_comax_order_pdf_link : Получает ссылку PDF для заказа Comax.
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 позволяют серверам предоставлять исполняемые функции, которые могут быть вызваны клиентами (например, моделями ИИ или другими приложениями) для выполнения действий. Этот сервер использует инструменты для взаимодействия с API Comax.

FastMCP использует спецификацию Standard 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." }],
    };
  },
});

Ведение журнала и обработка ошибок

Ведение журнала: инструменты могут использовать log.info() , log.warn() и т. д. из контекста execute для отправки сообщений журнала.
Ошибки пользователя: выбрасывайте UserError из fastmcp для ошибок, которые должны отображаться конечному пользователю.
Прогресс: используйте reportProgress для длительных операций.

Сессии

FastMCP выделяет новый экземпляр сервера для каждого клиентского соединения, обеспечивая связь 1:1. Доступ к данным, специфичным для сеанса, возможен, если на сервере FastMCP настроена аутентификация (не путать с аутентификацией API Comax, которая обрабатывается по запросу в инструментах).

Запуск вашего сервера

Тест с `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 для проверки вашего сервера с помощью веб-интерфейса:

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 для упрощения автоматизированных рабочих процессов улучшения кода, тестирования и развертывания с помощью запросов на извлечение GitHub. Smithery потребуются соответствующие разрешения GitHub для создания ветвей и предложения изменений.

Благодарности

Этот сервер создан с использованием FastMCP .
FastMCP вдохновлен реализацией Python Джонатана Лоуина .
Части кодовой базы FastMCP были заимствованы из протокола LiteMCP и Model Context (SSE) .