Comax Zahlungslink MCP

Ein FastMCP-Server zur Integration mit Comax zum Erstellen von Zahlungslinks, Verwalten von Bestellungen und Abrufen von Kundeninformationen. Erstellt mit FastMCP , einem TypeScript-Framework für MCP-Server.

[!NOTIZ]
Dieser Server ist für die Schnittstelle mit dem ERP-/Zahlungssystem von Comax konzipiert.

Merkmale

Comax-Integration: Bietet Tools für wichtige Comax-Operationen.
FastMCP Core: Nutzt FastMCP für robuste MCP-Serverfunktionen, einschließlich:
- Einfache Tooldefinition mit Zod-Schemavalidierung
- Sitzungsverwaltung
- Protokollierung und Fehlerbehandlung
- SSE für Remote-Kommunikation (konfigurierbar)
- CORS (standardmäßig aktiviert)
- Fortschrittsbenachrichtigungen (für Tools mit langer Laufzeit, falls implementiert)
- Typisierte Serverereignisse
- CLI zum Testen und Debuggen

Installation

Stellen Sie sicher, dass Sie Node.js und pnpm (oder npm/yarn) installiert haben.

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

# Install dependencies
pnpm install

Konfiguration

Dieser Server benötigt mehrere Anmeldeinformationen und IDs für die Interaktion mit der Comax-API. Diese sind derzeit als Konstanten in src/index.ts fest codiert, sollten aber für den produktiven Einsatz idealerweise über Umgebungsvariablen konfiguriert werden.

Erforderliche Konfiguration (siehe src/index.ts ):

ORDER_LOGIN_ID , ORDER_LOGIN_PASSWORD : Für Comax-Bestellvorgänge.
TOKEN_LOGIN_NAME , TOKEN_LOGIN_PASSWORD : Für die Generierung von Comax-Guthabentoken.
PAYMENT_LOGIN_ID , PAYMENT_LOGIN_PASSWORD : Für die Comax-Zahlungsseite.
BRANCH_ID , STORE_ID , PRICE_LIST_ID : Standardmäßige Betriebs-IDs von Comax.
RETURN_PAGE : URL zur Weiterleitung nach der Zahlung.
COMAX_ORDER_ENDPOINT , COMAX_TOKEN_ENDPOINT , COMAX_PAYMENT_PAGE , COMAX_CUSTOMER_ENDPOINT : Comax API-Endpunkt-URLs.

Erwägen Sie die Verwendung einer Bibliothek wie dotenv , um diese in einer .env Datei für die lokale Entwicklung zu verwalten.

Schnellstart

Das Folgende ist ein vereinfachtes Beispiel dafür, wie ein Tool auf diesem Server definiert ist ( 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");

Sie können den Server im Terminal mit der FastMCP-CLI testen.

Verfügbare Tools

Dieser Server stellt die folgenden Tools zur Interaktion mit Comax bereit:

create_comax_payment_link : Erstellt eine Comax-Bestellung und gibt einen Zahlungslink zurück.
update_comax_order_payment : Aktualisiert eine Comax-Bestellung mit Zahlungsbestätigung.
get_comax_customer_details : Ruft die Geschäftskundendetails von Comax nach Kunden-ID ab.
get_comax_order_status : Ruft den Status einer Comax-Bestellung nach Dokumentnummer oder Referenz ab.
get_comax_order_details : Ruft detaillierte Informationen zu einer Comax-Bestellung ab.
get_comax_order_pdf_link : Ruft einen PDF-Link für eine Comax-Bestellung ab.
set_comax_order_status : Legt den Status einer Comax-Bestellung fest.
get_comax_orders_by_credit_card : Ruft Bestellungen ab, die mit einer Kreditkartennummer verknüpft sind.
get_comax_orders_simple : Ruft Bestellungen basierend auf einem Datumsbereich und optionalen Filtern ab. Wenn das Ergebnis eine XML-URL ist, wird eine Stichprobe der Datensätze abgerufen und bereitgestellt.
chk_item_exists_in_orders : Überprüft, ob ein bestimmter Artikel in einer Bestellung vorhanden ist.
set_comax_order_self_pickup : Markiert eine Comax-Bestellung zur Selbstabholung.

Die genauen Parameter und Implementierungsdetails der einzelnen Tools finden Sie unter src/index.ts .

Kernkonzepte (FastMCP)

Werkzeuge

Tools in MCP ermöglichen Servern die Bereitstellung ausführbarer Funktionen, die von Clients (z. B. KI-Modellen oder anderen Anwendungen) aufgerufen werden können, um Aktionen auszuführen. Dieser Server verwendet Tools zur Interaktion mit der Comax-API.

FastMCP verwendet die Standardschemaspezifikation zur Definition von Werkzeugparametern. Dieser Server verwendet hierfür hauptsächlich Zod.

Beispiel einer Werkzeugdefinition (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." }],
    };
  },
});

Protokollierung und Fehlerbehandlung

Protokollierung: Tools können log.info() , log.warn() usw. aus dem execute verwenden, um Protokollnachrichten zu senden.
Benutzerfehler: Geben Sie UserError von fastmcp aus, wenn die Fehler dem Endbenutzer angezeigt werden sollen.
Fortschritt: Verwenden Sie reportProgress für Vorgänge mit langer Ausführungsdauer.

Sitzungen

FastMCP weist jeder Clientverbindung eine neue Serverinstanz zu und ermöglicht so eine 1:1-Kommunikation. Auf sitzungsspezifische Daten kann zugegriffen werden, wenn die Authentifizierung auf dem FastMCP-Server konfiguriert ist (nicht zu verwechseln mit der Comax-API-Authentifizierung, die innerhalb der Tools anfrageweise abgewickelt wird).

Ausführen Ihres Servers

Testen mit `mcp-cli`

Der schnellste Weg zum Testen und Debuggen Ihres Servers ist mit fastmcp dev :

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

Dadurch wird Ihr Server mit mcp-cli ausgeführt, um Ihren MCP-Server im Terminal zu testen und zu debuggen.

Prüfen mit `MCP Inspector`

Eine andere Möglichkeit besteht darin, den offiziellen MCP Inspector zu verwenden, um Ihren Server mit einer Web-Benutzeroberfläche zu überprüfen:

npx fastmcp inspect src/index.ts

Ausführen mit SSE für den Netzwerkzugriff

So machen Sie den Server über das Netzwerk zugänglich (z. B. für einen Remote-Client oder 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
  },
});

Führen Sie dann node src/index.js aus (nachdem Sie TS in JS kompiliert haben, z. B. mit tsc ) oder verwenden Sie tsx zur direkten Ausführung: npx tsx src/index.ts .

Häufig gestellte Fragen

Wie verwende ich es mit Claude Desktop (oder ähnlichen MCP-Clients)?

Befolgen Sie die allgemeine Anleitung unter https://modelcontextprotocol.io/quickstart/user und konfigurieren Sie den MCP-Client zum Starten Ihres Servers.

Beispieleintrag 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
      }
    }
  }
}

Stellen Sie sicher, dass der Pfad zu src/index.ts korrekt ist und dass alle erforderlichen Umgebungsvariablen (wenn Sie diese anstelle von Konstanten verwenden möchten) festgelegt sind.

Smithery Integration

Dieses Projekt soll in Smithery integriert werden, um automatisierte Codeverbesserungen, Tests und Bereitstellungs-Workflows über GitHub-Pull-Requests zu ermöglichen. Smithery benötigt entsprechende GitHub-Berechtigungen, um Branches zu erstellen und Änderungen vorzuschlagen.

Danksagung

Dieser Server wurde mit FastMCP erstellt.
FastMCP ist von der Python-Implementierung von Jonathan Lowin inspiriert.
Teile der Codebasis von FastMCP wurden von LiteMCP und dem Model Context-Protokoll übernommen.