Willi MaKo MCP Service

Konzeptueller Überblick

Das Model Context Protocol (MCP) ermöglicht einen standardisierten Zugriff auf Tools und Datenquellen für Copiloten, IDEs und Automatisierung. Der Willi-MaKo MCP Service bildet das gesamte API-Angebot der Plattform ab, verwaltet Authentifizierung automatisch und stellt strukturierte JSON-Antworten für nachgelagerte Agenten bereit.

• Einheitlicher Zugang zu Willi-MaKo Workflows

  Login, Session-Erzeugung, Chat, Reasoning und Artefakte werden über konsistente Tool-Aufrufe orchestriert.

• Streamfähiger HTTP-Transport

  Kompatibel mit MCP-fähigen IDEs und Desktop-Clients dank bidirektionaler Streaming-Verbindungen.

• Stateful Sessions

  Token- und Session-Caches ermöglichen mehrschrittige Automationen ohne zusätzliche Authentifizierungsrunden.

Architektur

Der MCP Service nutzt einen streamfähigen HTTP-Transport (Standard-Port 7337) aus dem @modelcontextprotocol/sdk und integriert den typisierten WilliMakoClient. Token-Caches und Session-Tracker sichern den Zustand zwischen Aufrufen, bevor Anfragen an die Willi-MaKo API v2 weitergeleitet werden.

┌──────────────────────────────────────────────────────────────┐
│      MCP-aware Agent (IDE, CLI, Chat Client, Automation)      │
└───────────────▲───────────────────────────┬──────────────────┘
                │ HTTP/JSON (MCP protocol)  │
                │                           │
        ┌───────┴───────────────────────────▼──────────────────┐
        │           Willi-Mako MCP Service Transport           │
        │   (Streamable HTTP transport on port 7337 by default)│
        └───────▲───────────────────────────┬──────────────────┘
                │                           │
         ┌──────┴──────┐              ┌─────┴────────────────┐
         │ Token cache │              │  WilliMakoClient SDK │
         │ & session   │              │  (REST calls, retries │
         │ tracker     │              │   typed responses)    │
         └──────▲──────┘              └────────▲─────────────┘
                │                                │
          ┌─────┴────────────────────────────────▼──────┐
          │      Willi-Mako API v2 (stromhaltig.de)     │
          └─────────────────────────────────────────────┘

Authentifizierung & Autorisierung

Alle Flows benötigen ein gültiges Willi-MaKo Access-Token. Der Transport unterstützt mehrere Mechanismen und verwaltet die Persistenz pro Verbindung.

Tokens werden pro MCP-Transport gespeichert, sodass mehrstufige Workflows ohne erneute Authentifizierung ausgeführt werden können. Der willi-mako-login-Tool-Aufruf kann Tokens persistieren oder mit{ persistToken: false } rein transient halten.

Wird keine sessionId übergeben, merkt sich der Dienst die zuletzt aktive Session und stellt sie den nachfolgenden Tool-Aufrufen bereit – ideal für Chat-, Reasoning- oder Retrieval-Ketten.

Verfügbare Tools & Ressourcen

Weitere Helfer-Tools (z. B. Dokumentations- und Kontakt-Shortcuts) sind im Quellcode des MCP Servers unter src/demos/mcp-server.ts dokumentiert.

MCP Service lokal betreiben

Voraussetzungen: Node.js ≥ 18, installierter willi-mako-client (global oder via npx) sowie ein gültiges Willi-MaKo Token oder Credentials.

• Schnellstart

  npx willi-mako-client mcp startet den lokalen MCP Server auf http://localhost:7337/mcp.

• Global installieren

  npm install -g [email protected] && willi-mako mcp

• Konfiguration

  Nutzen Sie --base-url, --token oder die Umgebungsvariable WILLI_MAKO_TOKEN für alternative Umgebungen und Tokens.

• PM2 Wrapper

  Die CommonJS-Shim bin/willi-mako.cjs ermöglicht einen PM2-Start ohne ERR_REQUIRE_ESM (pm2 start --name willi-mako-mcp willi-mako -- mcp).

• Docker

  docker run -e WILLI_MAKO_TOKEN=$WILLI_MAKO_TOKEN -p 7337:7337 ghcr.io/energychain/willi-mako-client:0.3.4 willi-mako mcp --port 7337

Deployment-Muster für die Produktion

Öffentlicher Hosted Endpoint

• Basis-URL

  https://mcp.stromhaltig.de/ mit Transportpfad /mcp

• Token-Injektion

  Per Header oder als erstes URL-Segment – Token wird aus Logs entfernt.

• TLS & Rate-Limits

  HTTPS mit modernen Cipher Suites, Standard-Willi-MaKo Rate Limits.

• Einsatzszenarien

  Für schnelle Experimente oder als dauerhaft verwalteter Integrationspunkt.

MCP Clients integrieren

Konfigurieren Sie MCP-fähige Clients in wenigen Schritten – unabhängig davon, ob Sie lokal oder über den Hosted Endpoint verbinden.

• Transport definieren

  HTTP/streamable mit URL http://localhost:7337/mcp oder https://mcp.stromhaltig.de/mcp.

• Credentials bereitstellen

  Per Bearer-Header oder via willi-mako-login Tool.

• Tools entdecken

  Die meisten Clients bieten automatische Tool-Listen mit willi-mako-* Prefix.

• Session aufbauen

  Einmal willi-mako-create-session ausführen und Folge-Calls auf derselben Verbindung nutzen.

• Ergebnisse sichern

  Artefakt-Tools nutzen, um JSON/EDI-Ausgaben direkt in Willi-MaKo zu speichern.

Beispiel: VS Code MCP Client

{
  "mcpServers": {
    "willi-mako": {
      "transport": "streamable",
      "url": "https://mcp.stromhaltig.de/<WILLI_MAKO_TOKEN>/mcp"
    }
  }
}

Beispiel: Claude Desktop

• Integrationen → MCP Servers öffnen

  Neuen Server mit URL https://mcp.stromhaltig.de/mcp anlegen.

• Header setzen

  Authorization: Bearer <WILLI_MAKO_TOKEN> oder Token in der URL einbetten.

• Tool Palette

  Mit /tool willi-mako-create-session eine Session initialisieren.

Observability & Troubleshooting

• Strukturierte Logs

  Emoji-präfixierte Logs für Verbindungen und Tool-Aufrufe, einsehbar via pm2 logs.

• Fehlerbehandlung

  API-Fehler werden als MCP Error Responses mit ErrorCode annotiert.

• Token-Cache

  Basic-Auth Cache invalidiert abgelaufene Tokens automatisch; Login erneut ausführen bei Rotation.

• Session-Reset

  Transport-Disconnect löscht In-Memory Sessions – willi-mako-create-session erneut aufrufen.

• PM2 Shim

  Bei ERR_REQUIRE_ESM auf willi-mako-client ≥ 0.3.4 upgraden (enthält CommonJS Wrapper).

Security-Empfehlungen

• Token schützen

  Tokens in URLs gelten als sensibel – Logs und History überprüfen.

• Rotation

  WILLI_MAKO_TOKEN regelmäßig wechseln und least-privilege beachten.

• Netzwerkabsicherung

  Eigene Deployments per Firewall/VPN eingrenzen, Token-Persistenz in Shared Environments deaktivieren.

• Monitoring

  API Usage Dashboards nutzen, um Anomalien frühzeitig zu erkennen.

Code-Beispiele

1. MCP-Handshake (curl)

curl -X POST https://mcp.stromhaltig.de/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <WILLI_MAKO_TOKEN>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

2. Tools auflisten

curl -X POST https://mcp.stromhaltig.de/tools/list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <WILLI_MAKO_TOKEN>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

3. Tool ausführen (Suche)

curl -X POST https://mcp.stromhaltig.de/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <WILLI_MAKO_TOKEN>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "willi-mako-semantic-search",
      "arguments": {
        "query": "Wie funktioniert der Lieferantenwechsel?",
        "top_k": 2
      }
    }
  }'

JavaScript / Node.js Beispiel

const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.WILLI_MAKO_TOKEN}`
};

// 1. Initialize
await fetch('https://mcp.stromhaltig.de/mcp', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {}
  })
});

// 2. List tools
await fetch('https://mcp.stromhaltig.de/tools/list', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/list',
    params: {}
  })
});

// 3. Call semantic search
const response = await fetch('https://mcp.stromhaltig.de/tools/call', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 3,
    method: 'tools/call',
    params: {
      name: 'willi-mako-semantic-search',
      arguments: {
        query: 'Was bedeutet der Fehlercode Z08?',
        top_k: 3
      }
    }
  })
});

const data = await response.json();
console.log(data.result);