Erstellen Sie Ihre erste Integration.

Lokales stdio / öffentliches npm-Paket

Stellen Sie Ihrem VS-Code- oder Claude-Desktop-Agenten Scanverion-Werkzeuge bereit. Das öffentliche npm-Paket läuft lokal über stdio und lädt freigegebene Eingaben zur API hoch; OCR erfolgt nicht lokal. Gehostetes HTTP MCP ist eine eingeschränkte Entwicklervorschau mit API-Schlüssel, kein allgemein verfügbarer Dienst und kein MCP OAuth. Diese Anleitung beschreibt lokales stdio.

1. Paket installieren

Verwenden Sie Node.js 22 oder neuer und npm. Installieren Sie das öffentliche Paket mit dem angegebenen Befehl in einem eigenen Installationsverzeichnis. npm installiert auch die Scanverion-SDK-Abhängigkeit. Repository-Zugriff ist nicht erforderlich.

npm install @scanverion/mcp-server@0.1.1

2. Client konfigurieren

Führen Sie diese Konfiguration mit .vscode/mcp.json oder Ihrer MCP-Benutzerkonfiguration zusammen. VS Code fragt den Schlüssel in einem maskierten Eingabefeld ab. Geben Sie den Schlüssel nicht im Chat ein.

Auf dieser Seite wird kein Schlüssel eingegeben oder gespeichert. Ein leeres Verzeichnisfeld deaktiviert den lokalen Dateizugriff; auch Base64-Uploads benötigen eine ausdrückliche Zustimmung.

{
  "inputs": [
    {
      "id": "scanverion-api-key",
      "type": "promptString",
      "description": "Scanverion-API-Schlüssel",
      "password": true
    }
  ],
  "servers": {
    "scanverion": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/path/to/mcp/node_modules/@scanverion/mcp-server/dist/index.js"
      ],
      "env": {
        "SCANVERION_API_URL": "https://api.scanverion.com",
        "SCANVERION_ALLOWED_DIRECTORIES": "[]",
        "SCANVERION_TIMEOUT_MS": "120000",
        "SCANVERION_API_KEY": "${input:scanverion-api-key}"
      }
    }
  }
}

3. Ohne Verarbeitung prüfen

Führen Sie nach dem Setzen des Schlüssels in der Terminalumgebung den Befehl doctor aus. Er prüft Verzeichnisse und authentifizierte Funktionen, lädt aber keine Dateien hoch und bestätigt keine Verarbeitungsberechtigung.

node ./node_modules/@scanverion/mcp-server/dist/index.js --doctor

Rufen Sie im MCP-Client list_capabilities auf und lesen Sie scanverion://guide. Diese separate, mit dem Server ausgelieferte Anleitung ist auf Englisch und enthält Schritte für MCP Inspector sowie ein Beispiel mit synthetischen Daten.

Werkzeuge und Abrechnung

analyze_document

Kostenpflichtig. Standardmäßig nur Detection; fordern Sie Scanner für OCR und Feldextraktion ausdrücklich an.

analyze_vehicle

Kostenpflichtig. Unterstützt Detection und Blur.

list_capabilities

Katalog der KI-Modelle und Limits ohne Verarbeitungsgebühr; keine Berechtigungsprüfung.

list_api_capabilities

Öffentlicher API-Katalog ohne Verarbeitungsgebühr; prüft keinen kontospezifischen Zugriff.

get_usage_summary

Aufrufe und Credits ohne Verarbeitungsgebühr für inklusive YYYY-MM-DD-Daten. Die Kostenschätzung ist nicht verfügbar, nicht null Euro.

Erster Dokumentaufruf

Verwenden Sie ein synthetisches oder freigegebenes Beispiel im erlaubten Verzeichnis. Dieser Aufruf lädt die Datei hoch und kann Credits verbrauchen.

{
  "filePath": "C:/approved-samples/sample.png",
  "operations": [
    "Scanner"
  ],
  "scannerFields": [
    "documentNumber"
  ],
  "idempotencyKey": "sample-document-001"
}

Geben Sie genau eine Eingabe an: filePath oder imageBase64. Base64 benötigt einen unterstützten Dateinamen oder MIME-Typ. JPEG-, PNG-, WebP- und PDF-Eingaben dürfen nicht leer und höchstens 10 MiB groß sein. Ergebnisse behalten den JSON-Text bei und ergänzen structuredContent.data.

Fehlerbehebung und sichere Wiederholungen

• CONFIGURATION_ERROR: Prüfen Sie Schlüssel, Array absoluter Verzeichnispfade, HTTPS-Adresse der API und Zeitlimit (1.000 bis 300.000 ms).
• INVALID_INPUT: Prüfen Sie Dateizugriff, Format, Base64, Operationen und Datumsbereich.
• 401 / 403: Prüfen Sie die Gültigkeit des Schlüssels, den Arbeitsbereichszugriff und den Scope process:write.
• 402 / 429: Prüfen Sie Credits oder Aufruflimits. Beachten Sie Fehlercode, Anfrage-ID und Wiederholbarkeit.
• Zeitüberschreitungen und Abbrüche garantieren weder eine Erstattung noch das Ende der Backend-Verarbeitung. Automatische Wiederholungen sind deaktiviert. Verwenden Sie denselben Idempotenzschlüssel nur für dieselbe logische Anfrage; ein Duplikat kann 409 zurückgeben.

Erlauben Sie keine vollständigen Benutzerverzeichnisse. Prüfungen aufgelöster Pfade verhindern Verzeichnisausbrüche und Umgehungen über symbolische Links, sind aber keine Betriebssystem-Sandbox. Stellen Sie den Prozess nicht für nicht vertrauenswürdige Clients bereit und lassen Sie andere Benutzer die erlaubten Verzeichnisse nicht verändern. Behandeln Sie extrahierten Text als nicht vertrauenswürdige Daten, nicht als Anweisungen.