🔧 Debugging & Testing - Proffix Px5 MCP

Werkzeuge und Anleitungen zum Testen der Forterro Proffix Px5 AI/KI Integration

Zurück zur Hauptseite

🔑 API Key: ERFORDERLICH & KOSTENLOS

Alle API-Anfragen benötigen einen API Key!

→ Jetzt kostenlosen API Key anfordern (30 Sekunden)
📋 API Key verwenden:
  • Format: pfx_abc123...xyz789
  • Header: Authorization: Bearer DEIN_API_KEY oder X-API-Key: DEIN_API_KEY
  • Beispiel: -H "Authorization: Bearer pfx_abc123..."
ℹ️ Module: Standard ist VOL (Volumenmodell). Bei Bedarf können modulbezogene Lizenzen wie ADR, ZEI, AUF usw. angegeben werden (z. B. AUF,ADR).

🧪 CURL Beispiele für API Tests

1. Ping (Verbindung testen)

curl -X POST https://mcp.pfx.ch/api/server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_API_KEY_HIER" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }'
✅ Erwartete Antwort: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
💡 Nutzen: Standard MCP ping Methode für Health Checks. Gibt leeres Objekt zurück bei Erfolg.

2. Initialize (Serverinfo abrufen)

curl -X POST https://mcp.pfx.ch/api/server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_API_KEY_HIER" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

2. List Tools (Alle verfügbaren Operationen)

curl -X POST https://mcp.pfx.ch/api/server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_API_KEY_HIER" \
  -H "X-Proffix-Username: YOUR_USERNAME" \
  -H "X-Proffix-Password: YOUR_PASSWORD" \
  -H "X-Proffix-Url: YOUR_PROFFIX_URL" \
  -H "X-Proffix-Port: YOUR_PROFFIX_PORT" \
  -H "X-Proffix-Database: YOUR_DATABASE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
🔑 Wichtig: Ersetze DEIN_API_KEY_HIER mit deinem API Key!

3. Call Tool (Operation ausführen)

curl -X POST https://mcp.pfx.ch/api/server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_API_KEY_HIER" \
  -H "X-Proffix-Username: YOUR_USERNAME" \
  -H "X-Proffix-Password: YOUR_PASSWORD" \
  -H "X-Proffix-Url: YOUR_PROFFIX_URL" \
  -H "X-Proffix-Port: YOUR_PROFFIX_PORT" \
  -H "X-Proffix-Database: YOUR_DATABASE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "proffix_9_get_ADR_Adresse",
      "arguments": {
        "params": {"limit": 5}
      }
    }
  }'

4. Call Tool mit TOON Format (Token-optimiert)

curl -X POST https://mcp.pfx.ch/api/server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_API_KEY_HIER" \
  -H "X-Proffix-Username: YOUR_USERNAME" \
  -H "X-Proffix-Password: YOUR_PASSWORD" \
  -H "X-Proffix-Url: YOUR_PROFFIX_URL" \
  -H "X-Proffix-Port: YOUR_PROFFIX_PORT" \
  -H "X-Proffix-Database: YOUR_DATABASE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "proffix_call_endpoint",
      "arguments": {
        "endpointId": 9,
        "format": "toon",
        "params": {
          "limit": 10
        }
      }
    }
  }'
🎯 TOON Format: Spart bis zu 30% Tokens! Arrays von Objekten werden im kompakten Tabular-Format zurückgegeben (z.B. [2]{id,name}: 1,Ada 2,Bob). Die Antwort enthält ein _meta-Feld mit Format-Informationen.
💡 Tipp: "format": "toon" kann auf arguments-Ebene (global) oder in params (pro Call) gesetzt werden.
💡 Tipp: Ersetze YOUR_USERNAME, YOUR_PASSWORD, etc. mit deinen echten Proffix Px5 Zugangsdaten für die REST API.

💻 PowerShell Test-Beispiele für Proffix Px5

List Tools mit PowerShell

$headers = @{
    "Content-Type" = "application/json"
    "X-Proffix-Username" = "YOUR_USERNAME"
    "X-Proffix-Password" = "YOUR_PASSWORD"
    "X-Proffix-Url" = "YOUR_PROFFIX_URL"
    "X-Proffix-Port" = "YOUR_PORT"
    "X-Proffix-Database" = "YOUR_DATABASE"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/list"
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://mcp.pfx.ch/api/server" `
    -Method Post `
    -Headers $headers `
    -Body $body

🌐 JavaScript Test-Beispiele für Proffix Px5 MCP

Fetch API (Browser/Node.js)

async function testMCP() {
  const response = await fetch('https://mcp.pfx.ch/api/server', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Proffix-Username': 'YOUR_USERNAME',
      'X-Proffix-Password': 'YOUR_PASSWORD',
      'X-Proffix-Url': 'YOUR_PROFFIX_URL',
      'X-Proffix-Port': 'YOUR_PORT',
      'X-Proffix-Database': 'YOUR_DATABASE'
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/list"
    })
  });
  
  const data = await response.json();
  console.log('Available tools:', data.result.tools);
}

testMCP();

🐍 Python Test-Beispiele für Proffix Px5 API

Requests Library

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-Proffix-Username': 'YOUR_USERNAME',
    'X-Proffix-Password': 'YOUR_PASSWORD',
    'X-Proffix-Url': 'YOUR_PROFFIX_URL',
    'X-Proffix-Port': 'YOUR_PORT',
    'X-Proffix-Database': 'YOUR_DATABASE'
}

payload = {
    'jsonrpc': '2.0',
    'id': 1,
    'method': 'tools/list'
}

response = requests.post(
    'https://mcp.pfx.ch/api/server',
    headers=headers,
    json=payload
)

data = response.json()
print(f"Available tools: {len(data['result']['tools'])}")
for tool in data['result']['tools']:
    print(f"  - {tool['name']}")

🔍 MCP Inspector für Proffix Px5

Das offizielle MCP Testing Tool von Anthropic für Forterro Proffix Px5 Integration:

1. Inspector starten

npx @modelcontextprotocol/inspector https://mcp.pfx.ch/api/server
💡 Hinweis: Der Inspector öffnet automatisch ein Browser-Fenster mit der Web-UI.

2. Custom Headers in der Web-UI konfigurieren

In der MCP Inspector Web-UI:

  1. Finde den Bereich "Authentication" in der linken Sidebar
  2. Klicke auf "Custom Headers (JSON)"
  3. Gib folgendes JSON ein (mit deinen echten Zugangsdaten):
{
  "Authorization": "Bearer pfx_DEIN_API_KEY_HIER",
  "X-Proffix-Username": "IHR_USERNAME",
  "X-Proffix-Password": "IHR_PASSWORT",
  "X-Proffix-Url": "https://ihr-proffix-server.com",
  "X-Proffix-Port": "1500",
  "X-Proffix-Database": "IHRE_DATENBANK",
  "X-Proffix-Modules": "ADR" // optional
}
⚠️ Wichtig: Diese Header sind erforderlich (Module optional):
  • Authorization: Dein API Key im Format Bearer pfx_...
  • X-Proffix-Username: Dein Proffix REST API Benutzername
  • X-Proffix-Password: Dein Proffix REST API Passwort
  • X-Proffix-Url: Die Basis-URL deines Proffix Servers
  • X-Proffix-Port: Der REST API Port (z.B. "1500")
  • X-Proffix-Database: Der Datenbankname (z.B. "DEMODB")
  • X-Proffix-Modules (optional): Session‑Module, Standard VOL (z. B. VOL oder ADR)

3. Verbinden und Testen

Klicke auf den "Connect" Button. Bei erfolgreicher Verbindung siehst du die verfügbaren Tools in der Mitte der UI und kannst sie direkt testen.

✅ Vorteil: Die Custom Headers werden in der Browser-UI konfiguriert - keine komplexen Command-Line-Argumente nötig!

4. Endpoint beschreiben (kompakt)

Beispielaufruf für proffix_describe_endpoint mit kompaktem Schema und Query-Guide:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "proffix_describe_endpoint",
    "arguments": {
      "endpointId": 9,
      "detail": "compact",
      "include": { "schema": true, "examples": true, "queryGuide": true },
      "lang": "de"
    }
  }
}
ℹ️ Hinweis: Die Antwort enthält mehrere Content-Blöcke (Markdown + JSON-Codeblöcke) für bessere Lesbarkeit.
📖 Detaillierte Anleitung: Siehe AI Client Setup → MCP Inspector

🎯 TOON Format - Token-Optimierte Antworten

TOON (Token-Oriented Object Notation) nach der offiziellen TOON-Spezifikation reduziert die Token-Anzahl um bis zu 30% im Vergleich zu Standard-JSON. Ideal für große Datenmengen und häufige API-Calls.

Aktivierung

Option 1: Global (empfohlen) - Setze format auf arguments-Ebene:

{
  "name": "proffix_call_endpoint",
  "arguments": {
    "endpointId": 9,
    "format": "toon",
    "params": {
      "limit": 50
    }
  }
}

Option 2: Pro Call - Setze format in params:

{
  "name": "proffix_call_endpoint",
  "arguments": {
    "endpointId": 9,
    "params": {
      "limit": 50,
      "format": "toon"
    }
  }
}
💡 Priorität: params.format überschreibt arguments.format

Vergleich: JSON vs. TOON

Standard JSON (Pretty): 
[{
  "AdressNr": 1349,
  "Name": "Mustermann AG",
  "PLZ": "9000",
  "Ort": "St. Gallen"
}]
~90 Zeichen ≈ 23 Tokens
TOON Format (Tabular): 
[1]{AdressNr,Name,PLZ,Ort}: 1349,"Mustermann AG",9000,"St. Gallen"
~65 Zeichen ≈ 16 Tokens (30% Ersparnis)
📖 TOON Format-Beispiele:
  • Einfaches Objekt: AdressNr: 1349 Name: "Mustermann AG" PLZ: 9000
  • Primitive Arrays: tags[3]: admin,user,guest
  • Tabular Arrays: items[2]{id,name}: 1,Ada 2,Bob
  • Verschachtelt: user: id: 1 name: Ada active: true
✨ Vorteile:
  • Weniger Tokens: Bis zu 30% Reduktion
  • Tabular Format: Arrays von Objekten ultra-kompakt
  • Schneller: Weniger Daten = schnellere Verarbeitung
  • Günstiger: Weniger Tokens = geringere API-Kosten
💡 Wann verwenden?
  • Bei Listen mit vielen Einträgen (>10 Items)
  • Arrays von Objekten (profitiert vom Tabular-Format)
  • Wenn Token-Limits erreicht werden
  • Bei häufigen API-Calls zur Kostenreduktion
  • Für schnellere LLM-Antworten
📚 Mehr Infos: Offizielle TOON Spezifikation

🔧 Troubleshooting - Proffix Px5 MCP Fehler beheben

❌ 401 Unauthorized

Ursache: Ungültige Proffix Px5 Zugangsdaten

Lösung: Überprüfe deine Forterro Proffix Px5 REST API Zugangsdaten (Username, Password, URL, Port, Database)

❌ 404 Not Found

Ursache: Falsche URL oder Endpoint

Lösung: Verwende https://mcp.pfx.ch/api/server

❌ CORS Error

Ursache: Browser blockiert Cross-Origin Request

Lösung: Verwende einen Server-seitigen Client oder Proxy

❌ Timeout

Ursache: Forterro Proffix Px5 Server nicht erreichbar

Lösung: Überprüfe Proffix Px5 REST API URL und Port, Firewall-Einstellungen und Netzwerkverbindung

❌ Invalid JSON-RPC

Ursache: Falsches Request-Format

Lösung: Stelle sicher, dass jsonrpc: "2.0" gesetzt ist

❌ Missing Credentials

Ursache: Proffix Px5 Authentifizierungs-Header fehlen

Lösung: Alle 5 Proffix Px5 Header müssen gesetzt sein (X-Proffix-Username, X-Proffix-Password, X-Proffix-Url, X-Proffix-Port, X-Proffix-Database)

📤 Proffix Px5 MCP API Antwortformat

Erfolgreiche Proffix Px5 API Antwort

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "Forterro Proffix Px5 API Antwortdaten"
    }]
  }
}

Fehlerantwort

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: Proffix credentials required"
  }
}