Multi-Tenant Invoice Autofill MCP Server

Ein Python-Backend-Dienst, der LLMs mit Funktionsaufruf- oder MCP-Unterstützung (Claude, Gemini, GPT usw.) in die Lage versetzt, Rechnungen im Auftrag von Mandanten in der Digital Invoicing Software automatisch auszufüllen und zu speichern.

Funktionen

• Duale Transportunterstützung: Bereitgestellt über das Standard-MCP-Protokoll (stdio / Streamable HTTP) und die REST-API (FastAPI) mit OpenAPI-Schema.

• Multi-Tenancy & Authentifizierung: Verschlüsselung der Zugangsdaten pro Mandant, benutzerdefinierte MCP-API-Schlüssel und isoliertes Sitzungsmanagement.

• Robuster Adapter: Gekapselter HTTP-Adapter, der Browser-Header nachbildet, mit reaktivem Sitzungs-Refresh und dynamischem Parsen von Cookie-Ablaufzeiten.

• Idempotenz & Nebenläufigkeit: Deduplizierung über Dokument-Hash und verteilte Redis-Sperren pro Mandant (lock:tenant:{id}).

• Datenschutz an erster Stelle: Verpflichtende strukturierte Protokoll-Schwärzungsschicht, die Passwörter, Cookies, Schlüssel und Tokens bereinigt.

• Keine festkodierten Werte: Keine Zugangsdaten oder Geschäftsidentitäten in Code, Kommentaren oder Tests; vollständige synthetische Testdatengenerierung.

Related MCP server: Invoice MCP Server

Lokale Voraussetzungen

• Python 3.12+

• Docker & Docker Compose (für lokale Postgres- & Redis-Instanzen)

Erste Schritte

1. Umgebung einrichten

Kopieren Sie .env.example in .env und legen Sie die lokalen Variablen fest:

cp .env.example .env

2. Lokale Datenbank & Redis starten

docker-compose up -d

3. Abhängigkeiten installieren

python -m venv .venv
# Windows:
.\.venv\Scripts\pip install -r requirements.txt
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt

4. Migrationen ausführen

.\.venv\Scripts\alembic upgrade head

5. Server starten

# Start FastAPI REST server:
.\.venv\Scripts\uvicorn mcp_digitalinvoice.main:app --reload --port 8000

# Run MCP stdio server:
.\.venv\Scripts\python -m mcp_digitalinvoice.mcp_server.server

Sicherheit

[!CAUTION] Verwaltung des Verschlüsselungsschlüssels: Die Umgebungsvariable ENCRYPTION_KEY muss auf einen sicheren, 32 Byte großen, Base64-kodierten Fernet-Schlüssel gesetzt werden. Der Anwendungsstart schlägt sofort fehl, wenn ENCRYPTION_KEY nicht bereitgestellt wird. Wenn ein Verschlüsselungsschlüssel jemals zur Verschlüsselung echter Mandantendaten verwendet wurde und der Verdacht besteht, dass er offengelegt wurde, müssen diese Daten mit einem neu generierten Schlüssel erneut verschlüsselt werden, da der alte Schlüssel als kompromittiert betrachtet werden muss.

Arbeitsabläufe

Mandanten-Onboarding (connect_account)

1. Rufen Sie connect_account mit der Anmelde-E-Mail, dem Passwort und dem Firmennamen des Mandanten in der Digital Invoicing Software auf.

2. Der Server verschlüsselt die Zugangsdaten, validiert sie über eine erste Anmeldung und gibt einen eindeutigen mcp_api_key zurück.

3. Stellen Sie diesen mcp_api_key dem LLM (als Bearer-Token oder Header) für nachfolgende Tool-Aufrufe bereit.

Rechnungs-Autofill (fill_invoice)

Das LLM ruft fill_invoice mit dem extrahierten Rechnungs-JSON-Payload auf (buyer, items, meta). Der Dienst validiert Pflichtfelder, erzwingt die sequenzielle Verarbeitung einzelner Dokumente, prüft die Idempotenz, ermittelt die Mandantensitzung, bildet den Payload auf die nachgelagerte Struktur ab und erstellt den Rechnungsentwurf.

Tests ausführen

.\.venv\Scripts\pytest -v tests/