@mindops/zapsign-mcp

Model Context Protocol-Server, der die ZapSign REST-API als MCP-Werkzeuge bereitstellt. Binden Sie ihn in jeden MCP-fähigen Host ein (Claude Desktop, VS Code, Cursor, Ihre eigene SDK-App) und lassen Sie ein LLM Dokumentenabläufe steuern: Dokumente erstellen, Unterzeichner verwalten, DOCX-Vorlagen ausfüllen, Hintergrundprüfungen durchführen, Webhooks verwalten.

Was abgedeckt ist

Die Werkzeuge sind nach ZapSign-Ressourcen gruppiert. Die Sammlung entspricht eins-zu-eins der öffentlichen REST-API; jedes Werkzeug kapselt genau einen Endpunkt.

• Dokumente – aus PDF-URL / Base64 / Vorlage erstellen, auflisten, Details, aktualisieren, löschen, Sortierung neu anordnen, Signaturen platzieren, oneclick, Zusatzdokumente, Unterzeichner-Aktivitätsprotokoll

• Unterzeichner – hinzufügen, aktualisieren, Details, löschen, Sammelunterzeichnungen, ablehnen, Ablehnung durch Benutzer, Autorisierungsversuche zurücksetzen, Benachrichtigungen erneut senden, Verifizierungsdetails, Signaturgruppen

• Vorlagen – aus DOCX erstellen, Formularfelder aktualisieren, auflisten, Details, aktualisieren, löschen

• Benutzer – erstellen, auflisten, löschen, Planinformationen

• Webhooks – erstellen, löschen (Ereignis-Payloads sind Referenzdokumente, keine API-Endpunkte)

• Auth (JWT) – Token abrufen, Token aktualisieren (Alternative zu statischem API-Token)

• Hintergrundprüfungen – Person-/Firmenprüfung erstellen, auflisten, Details

• Zeitstempel – Zeitstempel auf ein signiertes PDF oder auf ein beliebiges PDF ohne Veränderung der Signaturen anwenden

• Validierung – ein signiertes PDF verifizieren

• Partner – Partnerunternehmensverwaltung, Zahlungsstatus aktualisieren, CSV-Bericht zur Planauslastung

Installation

Fortlaufend nach der Veröffentlichung im Registry:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

Lokale Installation (vor der Veröffentlichung)

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

Erstveröffentlichung

Das Paket richtet sich an den @mindops-Scoping auf npmjs.org mit restricted-Zugriff. Zum Veröffentlichen:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

Falls die @mindops-Organisation auf npm noch nicht existiert, erstellen Sie sie zuerst unter https://www.npmjs.com/org/create.

Konfiguration

Erstellen Sie eine .env-Datei (oder setzen Sie Umgebungsvariablen in Ihrer MCP-Host-Konfiguration):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

Empfohlen: ein permanentes Token des Systembenutzers (Configurações → Tokens im ZapSign-Panel). Benutzergebundene Token laufen ab und unterbrechen die Automatisierung.

Verwendung von einem MCP-Host

Claude Desktop / Claude Code

Fügen Sie es Ihrer MCP-Konfiguration hinzu (typischerweise ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

Gleiche Struktur – fügen Sie es in den MCP-Servers-Bereich Ihrer Einstellungen ein.

Lokal während der Entwicklung

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

Der Server spricht stdio; verbinden Sie ihn mit einem beliebigen MCP-Client, um die Werkzeuge zu untersuchen.

Namenskonventionen für Werkzeuge

• Snake_case-Namen gemäß der ZapSign-Ressourcen-Terminologie (create_document, add_signer, delete_template usw.)

• Feldnamen in Werkzeugeingaben folgen der API-Schreibweise von ZapSign (phone_country, phone_number, auth_mode, url_pdf ...), damit der Anfragekörper exakt dem entspricht, was die API erwartet.

• Pfadparameter erscheinen als Top-Level-Felder mit demselben Namen (doc_token, signer_token, template_token).

Entwicklung

npm install
npm run typecheck
npm run build

Fügen Sie neue Endpunkte hinzu, indem Sie eine Definition in src/tools/<resource>.ts erstellen und npm run build erneut ausführen. Jedes Werkzeug ist ein dünner Wrapper:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

Der Helper übernimmt die Formatierung der Fehlerhülle und die JSON-Serialisierung für den MCP-Transport.

Versionierung

Dieses Paket folgt der ZapSign-v1-API. ZapSign versioniert seine Endpunkte hinter /api/v1/. Sobald v2 erscheint, erhält dieser Server ein paralleles Modul anstatt v1 zu ersetzen.

Lizenz

Proprietär (MindOps-intern). Kontaktieren Sie MindOps vor einem Redistributieren.