PowerOffice MCP for Codex

Lokaler MCP-Server für den sicheren Zugriff von Codex auf die PowerOffice Go API v2 mit Read-only- und explizit bestätigten Write-Operationen. Der Server arbeitet mit der DEMO API, verwendet OAuth 2.0 Client Credentials und stellt kleine, explizit eingeschränkte Tools anstelle eines universellen HTTP-Proxys bereit.

Was bereits verfügbar ist

• poweroffice_configuration_status — prüft, ob eine Konfiguration vorhanden ist, ohne die Schlüsselwerte offenzulegen.

• poweroffice_connection_info — prüft die Verbindung und gibt verfügbare Integrationen/Berechtigungen zurück.

• poweroffice_search_customers — sucht Kunden mit Filtern und Paginierung.

• poweroffice_get_customer — ruft einen einzelnen Kunden anhand der numerischen ID ab.

• poweroffice_list_general_ledger_accounts — liest den Kontenplan.

• poweroffice_list_account_transactions — liest Buchungen für einen erforderlichen Datumsbereich.

• poweroffice_create_customer — erstellt einen Kunden nach confirm=true.

• poweroffice_update_customer — wendet nach confirm=true einen zulässigen JSON Patch auf den Kunden an.

• poweroffice_create_general_ledger_account — erstellt ein Konto nach confirm=true.

• poweroffice_update_general_ledger_account — wendet nach confirm=true einen zulässigen JSON Patch auf das Konto an.

Read-Tools bleiben Read-only. Write-Tools ändern Daten nur bei explizitem confirm=true; Operationen zum Löschen, Buchen und Senden von Dokumenten sind in dieser Phase nicht enthalten.

Related MCP server: SceneBoard MCP for Codex

Voraussetzungen

• Node.js 22 oder neuer

• pnpm 11

• PowerOffice application key, client key und subscription key

• die erforderlichen Access Roles für die aufgerufenen Endpunkte

Installation

pnpm install
cp .env.example .env.local
pnpm build
pnpm test

Füllen Sie .env.local lokal aus:

PO_ENV=demo
PO_APPLICATION_KEY=...
PO_CLIENT_KEY=...
PO_SUBSCRIPTION_KEY=...
PO_USER_AGENT=poweroffice-mcp/0.1 your-email@example.com

.env.local ist von Git ausgeschlossen. Senden Sie keine Schlüssel in den Chat und fügen Sie sie nicht zu .codex/config.toml hinzu.

Verbindung zu Codex

Die Projektdatei .codex/config.toml startet bereits das gebaute dist/index.js über STDIO. Sie liest .env.local, falls die Datei existiert, und kann die aufgeführten Variablen auch aus der Umgebung des Codex-Prozesses beziehen.

Starten Sie nach pnpm build die Codex-Aufgabe für dieses Projekt neu. Beginnen Sie mit einem Aufruf von poweroffice_configuration_status, dann poweroffice_connection_info.

Lokale Entwicklung

pnpm dev
pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Der Server schreibt nur MCP-Nachrichten nach stdout; Startfehler gehen nach stderr. Token werden mit einem Puffer vor ihrem Ablauf zwischengespeichert; bei 401 wird das Token einmal erneuert, und bei 429 werden für Read-Anfragen bis zu zwei Wiederholungen mit einer Verzögerung von mindestens einer Sekunde durchgeführt. Write-Anfragen werden nicht automatisch wiederholt, um keine Duplikate zu erzeugen. Die Gesamtrate der Anfragen ist durch den Wert PO_MAX_REQUESTS_PER_SECOND begrenzt und darf 10 nicht überschreiten.

Umgebungsvariablen

Für die Produktion stellen Sie PO_ENV=production um; Token-URL und API-URL werden vom Code gewählt und nicht vom Benutzer eingegeben.

Grenzen des MVP

• Nur PowerOffice API v2 und Transport STDIO.

• Keine Webhooks, kein automatisches Durchblättern aller Seiten, keine Operationen zum Löschen, Buchen und Senden von Dokumenten.

• Write-Tools sind auf Customers und GeneralLedgerAccounts beschränkt und erfordern confirm=true.

• Das Feld Fields kann überschrieben werden, aber standardmäßig fordert der Server kompakte Datensätze an.

• Die nächste Seite wird immer explizit über pageNumber angefordert; die Metadaten des Headers X-Pagination werden zusammen mit dem Ergebnis zurückgegeben.

Dokumentation: PowerOffice Developer Portal, MCP in Codex.