SuperOffice CRM Onsite – Model Context Protocol (MCP) Server

Ein produktionsreifer Model Context Protocol (MCP)-Server, der in TypeScript für SuperOffice CRM Onsite-Installationen entwickelt wurde. Er ermöglicht LLM-Assistenten (wie Claude Desktop, Antigravity IDE, Cursor und andere MCP-Clients), nahtlos Kontakte, Personen, Termine, Support-Tickets, benutzerdefinierte Zusatztabellen (y_*) und Audit-Logs über standardmäßige SuperOffice REST WebAPI-Endpunkte abzufragen.

🌟 Funktionen

• ⚡ Nativer MCP-stdio-Transport: Integriert sich direkt in Desktop- und Terminal-KI-Clients.

• 🏢 Unternehmens- & Kontaktsuche: Detaillierte Unternehmensinformationen abrufen (get_contact_by_id).

• 👥 Personensuche: Unscharfe und filterbasierte Suche über Namen und E-Mails (search_persons).

• 📅 Kalender- & Termin-Intelligenz: Datumsbereichsfilterung mit Benutzerzuordnung (get_recent_appointments).

• 🎫 Support-Ticket-Verwaltung: Aktuelle Tickets abrufen und vollständige Ticket-Metadaten einsehen (get_latest_tickets, get_ticket_by_id).

• 📊 Benutzerdefinierte Zusatztabellen-Engine: Alle benutzerdefinierten y_*-Tabellen dynamisch entdecken und abfragen (list_extra_tables, query_extra_table).

• 🛡️ Audit- & Log-Tabellen-Explorer: Audit-Trails wie y_logticket, y_logactivity und Systemereignisse einsehen (list_log_tables).

• 🔒 Onsite-bereit: Robuste Basisauthentifizierung, Timeout-Schutz und konfigurierbare Handhabung selbstsignierter Zertifikate.

• 🛡️ Sanfte Fehlertoleranz: Mehrstufige Fallback-Abfragestrategien (Archive Provider ➔ REST Entity API) für garantiertes absturzsicheres Verhalten.

🏗️ Architektur

flowchart LR
    subgraph Client["Local Workstation / MCP Client"]
        Claude["Claude Desktop / Antigravity / Cursor"]
        MCP["SuperOffice MCP Server\n(Node.js / TypeScript)"]
        Claude <-->|stdio JSON-RPC| MCP
    end

    subgraph Server["SuperOffice Onsite Environment (VM)"]
        IIS["IIS Web Server / REST WebAPI\n/api/v1/"]
        SOApp["SuperOffice CRM Core"]
        SODb[("SuperOffice Database\n(Core + y_* Extra Tables)")]

        IIS --> SOApp --> SODb
    end

    MCP <-->|HTTP(S) Basic Auth\nREST / Archive / Entities| IIS

🛠️ Verfügbare MCP-Tools

🚀 Schnellstart

1. Voraussetzungen

• Node.js: v18.0.0 oder höher

• SuperOffice CRM Onsite: Installiert mit aktivierter REST WebAPI (/api/v1/)

• Ein aktives SuperOffice-Benutzerkonto mit API-Berechtigungen

2. Klonen & Erstellen

# Clone the repository
git clone https://github.com/your-username/superoffice-mcp-server.git
cd superoffice-mcp-server

# Install dependencies
npm install

# Compile TypeScript to dist/
npm run build

⚙️ Konfiguration

Umgebungsvariablen

🔌 Client-Einrichtungsanleitungen

1. Claude Desktop

Fügen Sie diesen Eintrag zu Ihrer claude_desktop_config.json hinzu:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "superoffice": {
      "command": "node",
      "args": [
        "C:\\path\\to\\superoffice-mcp-server\\dist\\index.js"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "SUPEROFFICE_API_URL": "https://your-crm-server/SuperOffice",
        "SUPEROFFICE_USERNAME": "admin",
        "SUPEROFFICE_PASSWORD": "your-password"
      }
    }
  }
}

2. Antigravity IDE / Benutzerdefinierte MCP-Konfiguration (mcp_config.json)

{
  "mcpServers": {
    "superoffice": {
      "command": "node",
      "args": [
        "C:\\Users\\aliha\\.gemini\\antigravity-ide\\scratch\\superoffice-mcp-server\\dist\\index.js"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "SUPEROFFICE_API_URL": "https://osl-so-iis2.ls.local/SuperOffice",
        "SUPEROFFICE_USERNAME": "admin",
        "SUPEROFFICE_PASSWORD": "your-password"
      }
    }
  }
}

🧪 Testen & Verifizieren

Sie können die Konnektivität direkt im Terminal mit PowerShell oder bash testen:

# Set test environment
$env:SUPEROFFICE_API_URL="https://osl-so-iis2.ls.local/SuperOffice"
$env:SUPEROFFICE_USERNAME="admin"
$env:SUPEROFFICE_PASSWORD="your-password"
$env:NODE_TLS_REJECT_UNAUTHORIZED="0"

# Run server (logs to stderr, listens on stdin)
node dist/index.js

Sie sollten Folgendes sehen:

[superoffice-mcp] Server v1.1.0 started — connected to https://osl-so-iis2.ls.local/SuperOffice

📂 Projektstruktur

superoffice-mcp-server/
├── .github/
│   └── workflows/
│       └── ci.yml               # Automated multi-version build testing
├── src/
│   └── index.ts                 # Main MCP Server implementation (8 tools)
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore specifications
├── LICENSE                      # MIT License
├── package.json                 # Project manifest and scripts
├── tsconfig.json                # TypeScript compiler configuration
└── README.md                    # Comprehensive documentation

🛡️ Fehlerbehebung

Wenn Ihr Onsite-Server eine interne Zertifizierungsstelle (CA) oder ein selbstsigniertes Zertifikat verwendet, bricht Node.js fetch standardmäßig ab. Stellen Sie sicher, dass:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

in den env-Abschnitt Ihrer MCP-Konfiguration aufgenommen wird.

Überprüfen Sie:

• Das Benutzerkonto hat REST-WebAPI-Berechtigungen in SuperOffice Admin.

• Die Basisauthentifizierung ist in IIS für den SuperOffice-WebAPI-Anwendungspool aktiviert.

Der Server nutzt SuperOffices umfangreiche Archive/Dynamic- und Archive/FindPerson-Provider für ausdrucksstarke Abfragen. Wenn ein bestimmter Provider in der Benutzerrolle Ihrer Installation eingeschränkt ist, greift der Server automatisch elegant auf einfache REST-Entity-Endpunkte zurück.

📜 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.