Fehlerbehebung

Loesungen fuer haeufige Probleme bei der Arbeit mit FlowMCP-Schemas, Servern und Integrationen.

Schema-Validierungsfehler

Namespace-Formatfehler

Fehler: namespace must contain only lowercase letters

Das namespace-Feld akzeptiert nur Kleinbuchstaben a-z. Keine Zahlen, Bindestriche, Unterstriche oder Grossbuchstaben.

// Falsch
namespace: 'github-api'   // keine Bindestriche
namespace: 'api2'         // keine Zahlen
namespace: 'CoinGecko'    // keine Grossbuchstaben

// Richtig
namespace: 'github'
namespace: 'coingecko'

Versions-Feldfehler

Fehler: version must be a valid semver string

Das version-Feld muss ein vollstaendiger Semver-String ohne Praefix sein.

// Falsch
version: '2.0'        // Patch fehlt
version: 'v2.0.0'     // kein 'v'-Praefix
version: '2'           // kein Semver

// Richtig
version: '2.0.0'

Parameter-Strukturfehler

Fehler: parameter must have position and z fields

Jeder Parameter in v2.0.0 braucht einen position-Block und einen z-Block.

// Falsch - z-Block fehlt
parameters: [
    { position: { key: 'id', value: '{{ID}}', location: 'insert' } }
]

// Richtig
parameters: [
    {
        position: { key: 'id', value: '{{ID}}', location: 'insert' },
        z: { primitive: 'string()', options: [] }
    }
]

Route-Limit ueberschritten

Fehler: schema exceeds maximum of 8 routes

v2.0.0 begrenzt Schemas auf maximal 8 Routes. Grosse Schemas in mehrere Dateien aufteilen, gruppiert nach Endpunkt-Typ.

Fehlende Pflichtfelder

Fehler: main.root is required oder main.requiredServerParams is required

v2.0.0 erfordert mehrere Felder, die in v1 optional waren:

export const main = {
    namespace: 'provider',           // Erforderlich
    name: 'Display Name',            // Erforderlich
    description: 'What it does',     // Erforderlich
    version: '2.0.0',               // Erforderlich
    root: 'https://api.example.com', // Erforderlich
    requiredServerParams: [],        // Erforderlich (leeres Array wenn keine)
    requiredLibraries: [],           // Erforderlich (leeres Array wenn keine)
    headers: {},                     // Erforderlich (leeres Objekt wenn keine)
    routes: { ... }                  // Erforderlich (mindestens eine Route)
}

Server-Startprobleme

Port bereits belegt

Fehler: EADDRINUSE: address already in use :::3000

Ein anderer Prozess belegt den Port. Finden und stoppen:

lsof -i :3000
kill <PID>

# Oder anderen Port verwenden
PORT=3001 node server.mjs

Fehlende Umgebungsvariablen

Fehler: Required server parameter API_KEY is not set

Das Schema deklariert requiredServerParams, die in der Umgebung vorhanden sein muessen.

export API_KEY=your_key_here
# Oder inline uebergeben
API_KEY=your_key_here node server.mjs

MCP SDK Versionskonflikt

Fehler: Cannot find module '@modelcontextprotocol/sdk'

Kompatible MCP-SDK-Version sicherstellen:

npm ls @modelcontextprotocol/sdk
npm install @modelcontextprotocol/sdk@latest

API-Request-Fehler

401 Unauthorized

Die API hat die Authentifizierungs-Credentials abgelehnt.

Haeufige Ursachen:

API-Schluessel abgelaufen oder widerrufen
Falsches Header-Format (Bearer vs. token vs. API key)
Schluessel im falschen serverParams-Feld gesetzt

429 Rate Limited

Die API drosselt deine Requests.

Loesungen:

API-Dokumentation fuer Rate-Limit-Kontingente pruefen
Verzoegerungen zwischen Requests bei Batch-Operationen hinzufuegen
Bezahlten API-Tier fuer hoehere Limits verwenden
Antworten wenn moeglich cachen

Ungueltige JSON-Antwort

Fehler: Unexpected token < in JSON at position 0

Die API hat HTML oder XML statt JSON zurueckgegeben.

// Root-URL zeigt auf die API, nicht die Website
root: 'https://api.example.com'     // Richtig
root: 'https://www.example.com'     // Falsch - Website, nicht API

Claude Desktop Integration

MCP-Server erscheint nicht in Claude

Konfigurationsdatei-Speicherort pruefen:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Absolute Pfade in args verwenden
Claude Desktop komplett neu starten (beenden und neu oeffnen)

Tools erscheinen nicht nach Server-Start

Schemas ohne Fehler laden, indem der Server manuell im Terminal gestartet wird
Pruefen, dass loadSchema() fuer alle Schemas status: true zurueckgibt
Claude Desktop Logs auf MCP-bezogene Fehler pruefen

Handler-Probleme (v2.0.0)

Handler-Factory-Funktionsfehler

Fehler: handlers export must be a function

Der handlers-Export muss eine Factory-Funktion sein, kein einfaches Objekt.

// Falsch - einfaches Objekt
export const handlers = {
    routeName: { postProcess: ( { data } ) => data }
}

// Richtig - Factory-Funktion
export const handlers = ( { sharedLists, libraries } ) => ({
    routeName: {
        postProcess: ( { data } ) => {
            return data
        }
    }
})

Dependency-Injection-Fehler

Fehler: Library 'ethers' is not on the allowlist

Libraries muessen in requiredLibraries im main-Export deklariert werden.

export const main = {
    // ...
    requiredLibraries: [ 'ethers' ],
    // ...
}

Fehlermeldungs-Referenz

Schema-Fehler

Fehler	Ursache	Loesung
`namespace invalid`	Enthaelt nicht-Kleinbuchstaben	Nur `a-z` verwenden
`route missing method`	Route hat kein `method`-Feld	`method: 'GET'` hinzufuegen
`parameter missing z`	Parameter ohne Zod-Validierung	`z`-Block hinzufuegen
`serverParams not declared`	Header nutzt `{{KEY}}` aber `KEY` nicht in `requiredServerParams`	Zu `requiredServerParams` hinzufuegen
`handlers is not a function`	`handlers` als Objekt exportiert	In Factory-Funktion konvertieren

Laufzeitfehler

Fehler	Ursache	Loesung
`ECONNREFUSED`	Zielserver nicht erreichbar	API-Endpunkt-Erreichbarkeit pruefen
`ETIMEDOUT`	Request-Timeout	Netzwerk pruefen, Timeout erhoehen
`ENOTFOUND`	Ungueltiger Hostname	`root`-URL im Schema pruefen
`Invalid JSON`	Antwort ist kein gueltiges JSON	API-Endpunkt prueft JSON zurueck

Debug-Checkliste

Vor dem Melden eines Problems folgendes pruefen:

Schema validiert — FlowMCP.validateMain( { main } ) ausfuehren
Security-Scan besteht — FlowMCP.scanSecurity( { filePath } ) ausfuehren
Schema laedt — FlowMCP.loadSchema() ausfuehren und status: true pruefen
Umgebungsvariablen gesetzt — Alle requiredServerParams-Werte verfuegbar
API erreichbar — API-Endpunkt direkt mit curl testen
Node.js-Version — Node.js 22+ installiert (node --version)
Abhaengigkeiten installiert — npm ci fuer saubere Installation ausfuehren