lxw-cli 0.1.2__tar.gz → 0.4.0__tar.gz

{lxw_cli-0.1.2 → lxw_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lxw-cli
-Version: 0.1.2
+Version: 0.4.0
 Summary: Inoffizielles CLI/TUI/MCP-Tool für die Lexware Office API (vormals lexoffice)
 Project-URL: Homepage, https://github.com/OEM-Mrks/lxw-cli
 Project-URL: Documentation, https://developers.lexware.io/
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Office/Business :: Financial :: Accounting
 Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
 Requires-Dist: fastmcp>=2.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.6
@@ -87,6 +88,26 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie
 Ab dem nächsten cmd-Fenster reicht dann überall einfach `lxw`. Der API-Key
 wird beim ersten Start abgefragt und unter `%APPDATA%\lexware\.env` gespeichert.
 
+### Update
+
+Auf die neueste Version von PyPI:
+
+```bash
+uv tool upgrade lxw-cli        # oder: pipx upgrade lxw-cli
+lxw --version                  # Kontrolle
+```
+
+Sieht uv eine frisch veröffentlichte Version noch nicht (das PyPI-CDN braucht
+nach einem Release ein paar Minuten) oder ist das Tool auf eine exakte Version
+gepinnt, hilft ein Neu-Install auf `latest`:
+
+```bash
+uv tool install --force lxw-cli@latest
+```
+
+Der MCP-Server für Claude nutzt das Update automatisch mit — bereits laufende
+Claude-Sessions müssen dafür einmal neu gestartet werden.
+
 ### Aus dem Quellcode (Entwicklung)
 
 ```bash
@@ -96,6 +117,15 @@ uv venv && source .venv/bin/activate
 uv pip install -e ".[dev]"
 ```
 
+Lokalen Arbeitsstand ohne Release als globales `lxw` installieren:
+
+```bash
+uv tool install --force --reinstall .
+```
+
+(`--reinstall` ist nötig — bei unveränderter Versionsnummer nimmt uv sonst
+den gecachten Build.)
+
 ## API-Key konfigurieren
 
 Lege einen API-Key in deinem Lexware-Account an: <https://app.lexware.de/addons/public-api>
@@ -377,11 +407,21 @@ Claude erkennt die Tools automatisch und ruft sie auf.
 
 ### Verfügbare MCP-Tools
 
-26 Tools mit identischem Verhalten wie die CLI-Befehle:
+31 Tools mit identischem Verhalten wie die CLI-Befehle:
+
+- **Info**: `version` (meldet die laufende Version + Build-Zeitstempel — nützlich, wenn eine Client-UI wie ChatGPT eine gecachte/alte Version anzeigt)
+- **Belegkette (weiterführen)**: `continue_document` führt einen Beleg in den Folgebeleg fort und hält beide verknüpft (`precedingSalesVoucherId`). Der Quelltyp wird automatisch erkannt (Belegnummer oder id). Unterstützte Wege (wie in Lexware):
+  - **Angebot** → Auftrag · Lieferschein · Rechnung
+  - **Auftrag** → Lieferschein · Rechnung
+  - **Lieferschein** → Rechnung
+  - **Rechnung** → Lieferschein · Rechnungskorrektur
 
+  Inhalte (Kunde, Positionen, Texte) werden übernommen, der Folgebeleg entsteht als Entwurf. Für Rechnung/Rechnungskorrektur muss der Ausgangsbeleg **festgeschrieben** sein (sonst klare Meldung statt HTTP 406). **Abschlagsrechnung** und **Serienrechnung** sind über die Lexware-API nicht erstellbar — das meldet das Tool klar.
 - **Lesen**: `profile`, `list_invoices`, `get_invoice`, `download_invoice_pdf`, `list_contacts`, `get_contact`, `list_vouchers`, `get_voucher`, `list_articles`, `get_article`, `list_quotations`, `get_quotation`, `download_quotation_pdf`, `list_order_confirmations`, `get_order_confirmation`, `download_order_confirmation_pdf`, `list_delivery_notes`, `get_delivery_note`, `download_delivery_note_pdf`
 - **Belege als Draft anlegen**: `create_invoice_draft`, `create_voucher_draft`, `create_quotation_draft`, `create_order_confirmation_draft`, `create_delivery_note_draft`
 - **Stammdaten anlegen** (kein Draft): `create_contact`, `create_article`
+- **Stammdaten bearbeiten** (Teil-Update mit Auto-Merge + automatischem `version`-Handling): `update_contact`, `update_article`. Es werden nur die übergebenen Felder geändert; verschachtelte Objekte werden feldweise zusammengeführt, Listen komplett ersetzt. (Kontakt-`archived` ist in der Lexware-API read-only und kann nicht per API gesetzt werden. Firmen-Kontakte mit **mehr als einem Ansprechpartner** lassen sich per Lexware-API grundsätzlich nicht aktualisieren — `update_contact` meldet das klar, statt eines rohen HTTP 406.)
+- **Funktionswunsch melden**: `request_feature` erstellt einen **unverbindlichen** Feature-Wunsch als fertigen Text (`subject`/`body`) samt Anbieter-Adresse (`to` = david@oemedia.de). Der Server **versendet nichts** — der Nutzer kopiert den Text und schickt ihn selbst per E-Mail. Dies ist ein Endkundenprodukt: der Assistent baut keine Funktionen selbst, sondern bietet bei fehlenden Funktionen nur diesen Weg an.
 
 Alle document-Tools (`get_*`, `download_*_pdf`) akzeptieren UUID **oder** Belegnummer (z.B. `FB2600682`). PDFs landen in `~/Downloads/lexware/`.
 
@@ -403,6 +443,55 @@ lxw mcp uninstall-desktop         # aus Claude Desktop entfernen
 lxw mcp serve                     # läuft direkt — wird von Claude intern aufgerufen
 ```
 
+### Multi-User-Server (HTTP) — ein Server, jeder mit eigenem Key
+
+Neben dem lokalen stdio-Modus gibt es `lxw-mcp-http`: einen zentralen
+MCP-Server für mehrere Nutzer, bei dem **jeder seinen eigenen Lexware-API-Key
+mitbringt**. Der Server speichert keine Keys — er ist ein zustandsloser Proxy.
+
+```bash
+LXW_MCP_PUBLIC_URL=https://mcp.example.com \
+LXW_MCP_SECRET='ein-langes-zufaelliges-secret' \
+lxw-mcp-http    # lauscht auf 127.0.0.1:8788 (LXW_MCP_HOST/LXW_MCP_PORT)
+```
+
+Zwei Wege, den eigenen Key mitzubringen:
+
+1. **Direkt als Bearer-Header** (Claude Code, Cursor, Skripte — alles, was
+   eigene Header kann). Der Key bleibt in der lokalen Client-Config:
+
+   ```bash
+   claude mcp add lexware --transport http https://mcp.example.com/mcp \
+     --header "Authorization: Bearer ${LEXWARE_API_KEY}"
+   ```
+
+2. **OAuth** (claude.ai, ChatGPT — Clients ohne Header-Support): Beim
+   Verbinden öffnet sich eine Consent-Seite des Servers, auf der man einmalig
+   seinen Lexware-Key eingibt. Der Server prüft ihn gegen die Lexware-API und
+   stellt ein Zugriffstoken aus, in dem der Key **verschlüsselt eingebettet**
+   ist (Fernet, `LXW_MCP_SECRET`). Das Token liegt beim Client auf dem Gerät
+   des Nutzers; der Server entschlüsselt es nur pro Request und persistiert
+   ausschließlich die OAuth-Client-Registrierungen (`LXW_MCP_DATA_DIR`,
+   Standard `~/.config/lexware/mcp/`).
+
+Hinweise für den Betrieb:
+
+- `LXW_MCP_SECRET` **fest setzen** — ohne festes Secret werden alle Tokens
+  bei jedem Neustart ungültig. Rotieren des Secrets invalidiert bewusst alle
+  ausgestellten Tokens.
+- Vor den Server gehört ein HTTPS-Reverse-Proxy (Caddy, nginx, Cloudflare
+  Tunnel, `tailscale serve`, …); `LXW_MCP_PUBLIC_URL` ist die von außen
+  sichtbare Basis-URL (sie steht in den OAuth-Metadaten).
+- PDF-Downloads liefern über HTTP das PDF als Binärinhalt zurück (statt eines
+  Pfads auf der Server-Platte wie im stdio-Modus).
+- Tokens laufen nach 24 h ab; Clients erneuern sie automatisch per
+  Refresh-Token. Ein geleaktes Token wird wirkungslos, sobald der zugehörige
+  Lexware-Key unter <https://app.lexware.de/addons/public-api> widerrufen wird.
+
+`request_feature` braucht keine Konfiguration: es liefert nur einen fertigen
+Text + die Empfänger-Adresse (`david@oemedia.de`) zurück, den der Nutzer selbst
+per E-Mail sendet. Der Server verschickt nichts.
+
 ## Out of Scope (v1)
 
 Bewusst nicht enthalten:

{lxw_cli-0.1.2 → lxw_cli-0.4.0}/README.md

@@ -52,6 +52,26 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie
 Ab dem nächsten cmd-Fenster reicht dann überall einfach `lxw`. Der API-Key
 wird beim ersten Start abgefragt und unter `%APPDATA%\lexware\.env` gespeichert.
 
+### Update
+
+Auf die neueste Version von PyPI:
+
+```bash
+uv tool upgrade lxw-cli        # oder: pipx upgrade lxw-cli
+lxw --version                  # Kontrolle
+```
+
+Sieht uv eine frisch veröffentlichte Version noch nicht (das PyPI-CDN braucht
+nach einem Release ein paar Minuten) oder ist das Tool auf eine exakte Version
+gepinnt, hilft ein Neu-Install auf `latest`:
+
+```bash
+uv tool install --force lxw-cli@latest
+```
+
+Der MCP-Server für Claude nutzt das Update automatisch mit — bereits laufende
+Claude-Sessions müssen dafür einmal neu gestartet werden.
+
 ### Aus dem Quellcode (Entwicklung)
 
 ```bash
@@ -61,6 +81,15 @@ uv venv && source .venv/bin/activate
 uv pip install -e ".[dev]"
 ```
 
+Lokalen Arbeitsstand ohne Release als globales `lxw` installieren:
+
+```bash
+uv tool install --force --reinstall .
+```
+
+(`--reinstall` ist nötig — bei unveränderter Versionsnummer nimmt uv sonst
+den gecachten Build.)
+
 ## API-Key konfigurieren
 
 Lege einen API-Key in deinem Lexware-Account an: <https://app.lexware.de/addons/public-api>
@@ -342,11 +371,21 @@ Claude erkennt die Tools automatisch und ruft sie auf.
 
 ### Verfügbare MCP-Tools
 
-26 Tools mit identischem Verhalten wie die CLI-Befehle:
+31 Tools mit identischem Verhalten wie die CLI-Befehle:
+
+- **Info**: `version` (meldet die laufende Version + Build-Zeitstempel — nützlich, wenn eine Client-UI wie ChatGPT eine gecachte/alte Version anzeigt)
+- **Belegkette (weiterführen)**: `continue_document` führt einen Beleg in den Folgebeleg fort und hält beide verknüpft (`precedingSalesVoucherId`). Der Quelltyp wird automatisch erkannt (Belegnummer oder id). Unterstützte Wege (wie in Lexware):
+  - **Angebot** → Auftrag · Lieferschein · Rechnung
+  - **Auftrag** → Lieferschein · Rechnung
+  - **Lieferschein** → Rechnung
+  - **Rechnung** → Lieferschein · Rechnungskorrektur
 
+  Inhalte (Kunde, Positionen, Texte) werden übernommen, der Folgebeleg entsteht als Entwurf. Für Rechnung/Rechnungskorrektur muss der Ausgangsbeleg **festgeschrieben** sein (sonst klare Meldung statt HTTP 406). **Abschlagsrechnung** und **Serienrechnung** sind über die Lexware-API nicht erstellbar — das meldet das Tool klar.
 - **Lesen**: `profile`, `list_invoices`, `get_invoice`, `download_invoice_pdf`, `list_contacts`, `get_contact`, `list_vouchers`, `get_voucher`, `list_articles`, `get_article`, `list_quotations`, `get_quotation`, `download_quotation_pdf`, `list_order_confirmations`, `get_order_confirmation`, `download_order_confirmation_pdf`, `list_delivery_notes`, `get_delivery_note`, `download_delivery_note_pdf`
 - **Belege als Draft anlegen**: `create_invoice_draft`, `create_voucher_draft`, `create_quotation_draft`, `create_order_confirmation_draft`, `create_delivery_note_draft`
 - **Stammdaten anlegen** (kein Draft): `create_contact`, `create_article`
+- **Stammdaten bearbeiten** (Teil-Update mit Auto-Merge + automatischem `version`-Handling): `update_contact`, `update_article`. Es werden nur die übergebenen Felder geändert; verschachtelte Objekte werden feldweise zusammengeführt, Listen komplett ersetzt. (Kontakt-`archived` ist in der Lexware-API read-only und kann nicht per API gesetzt werden. Firmen-Kontakte mit **mehr als einem Ansprechpartner** lassen sich per Lexware-API grundsätzlich nicht aktualisieren — `update_contact` meldet das klar, statt eines rohen HTTP 406.)
+- **Funktionswunsch melden**: `request_feature` erstellt einen **unverbindlichen** Feature-Wunsch als fertigen Text (`subject`/`body`) samt Anbieter-Adresse (`to` = david@oemedia.de). Der Server **versendet nichts** — der Nutzer kopiert den Text und schickt ihn selbst per E-Mail. Dies ist ein Endkundenprodukt: der Assistent baut keine Funktionen selbst, sondern bietet bei fehlenden Funktionen nur diesen Weg an.
 
 Alle document-Tools (`get_*`, `download_*_pdf`) akzeptieren UUID **oder** Belegnummer (z.B. `FB2600682`). PDFs landen in `~/Downloads/lexware/`.
 
@@ -368,6 +407,55 @@ lxw mcp uninstall-desktop         # aus Claude Desktop entfernen
 lxw mcp serve                     # läuft direkt — wird von Claude intern aufgerufen
 ```
 
+### Multi-User-Server (HTTP) — ein Server, jeder mit eigenem Key
+
+Neben dem lokalen stdio-Modus gibt es `lxw-mcp-http`: einen zentralen
+MCP-Server für mehrere Nutzer, bei dem **jeder seinen eigenen Lexware-API-Key
+mitbringt**. Der Server speichert keine Keys — er ist ein zustandsloser Proxy.
+
+```bash
+LXW_MCP_PUBLIC_URL=https://mcp.example.com \
+LXW_MCP_SECRET='ein-langes-zufaelliges-secret' \
+lxw-mcp-http    # lauscht auf 127.0.0.1:8788 (LXW_MCP_HOST/LXW_MCP_PORT)
+```
+
+Zwei Wege, den eigenen Key mitzubringen:
+
+1. **Direkt als Bearer-Header** (Claude Code, Cursor, Skripte — alles, was
+   eigene Header kann). Der Key bleibt in der lokalen Client-Config:
+
+   ```bash
+   claude mcp add lexware --transport http https://mcp.example.com/mcp \
+     --header "Authorization: Bearer ${LEXWARE_API_KEY}"
+   ```
+
+2. **OAuth** (claude.ai, ChatGPT — Clients ohne Header-Support): Beim
+   Verbinden öffnet sich eine Consent-Seite des Servers, auf der man einmalig
+   seinen Lexware-Key eingibt. Der Server prüft ihn gegen die Lexware-API und
+   stellt ein Zugriffstoken aus, in dem der Key **verschlüsselt eingebettet**
+   ist (Fernet, `LXW_MCP_SECRET`). Das Token liegt beim Client auf dem Gerät
+   des Nutzers; der Server entschlüsselt es nur pro Request und persistiert
+   ausschließlich die OAuth-Client-Registrierungen (`LXW_MCP_DATA_DIR`,
+   Standard `~/.config/lexware/mcp/`).
+
+Hinweise für den Betrieb:
+
+- `LXW_MCP_SECRET` **fest setzen** — ohne festes Secret werden alle Tokens
+  bei jedem Neustart ungültig. Rotieren des Secrets invalidiert bewusst alle
+  ausgestellten Tokens.
+- Vor den Server gehört ein HTTPS-Reverse-Proxy (Caddy, nginx, Cloudflare
+  Tunnel, `tailscale serve`, …); `LXW_MCP_PUBLIC_URL` ist die von außen
+  sichtbare Basis-URL (sie steht in den OAuth-Metadaten).
+- PDF-Downloads liefern über HTTP das PDF als Binärinhalt zurück (statt eines
+  Pfads auf der Server-Platte wie im stdio-Modus).
+- Tokens laufen nach 24 h ab; Clients erneuern sie automatisch per
+  Refresh-Token. Ein geleaktes Token wird wirkungslos, sobald der zugehörige
+  Lexware-Key unter <https://app.lexware.de/addons/public-api> widerrufen wird.
+
+`request_feature` braucht keine Konfiguration: es liefert nur einen fertigen
+Text + die Empfänger-Adresse (`david@oemedia.de`) zurück, den der Nutzer selbst
+per E-Mail sendet. Der Server verschickt nichts.
+
 ## Out of Scope (v1)
 
 Bewusst nicht enthalten:

{lxw_cli-0.1.2 → lxw_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lxw-cli"
-version = "0.1.2"
+version = "0.4.0"
 description = "Inoffizielles CLI/TUI/MCP-Tool für die Lexware Office API (vormals lexoffice)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,7 @@ dependencies = [
     "python-dotenv>=1.0",
     "fastmcp>=2.10",
     "textual>=0.58",
+    "cryptography>=42",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +45,7 @@ dev = [
 [project.scripts]
 lxw = "lxw_cli.cli:_run"
 lxw-mcp = "lxw_cli.mcp_server:run"
+lxw-mcp-http = "lxw_cli.mcp_server:run_http"
 lxw-tui = "lxw_cli.tui.app:run"
 
 [project.urls]

{lxw_cli-0.1.2 → lxw_cli-0.4.0}/src/lxw_cli/commands/mcp.py

@@ -21,25 +21,46 @@ app = typer.Typer(no_args_is_help=True)
 MCP_NAME = "lexware"
 
 
+def _desktop_config_dirs() -> list[Path]:
+    """Candidate directories for Claude Desktop's configuration, per platform.
+
+    On Windows the classic install uses %APPDATA%\\Claude; the Microsoft-Store
+    build (MSIX) virtualizes AppData under
+    %LOCALAPPDATA%\\Packages\\Claude_<hash>\\LocalCache\\Roaming\\Claude.
+    """
+    if sys.platform == "darwin":
+        return [Path.home() / "Library" / "Application Support" / "Claude"]
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        root = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
+        dirs = [root / "Claude"]
+        local = os.environ.get("LOCALAPPDATA")
+        lroot = Path(local) if local else Path.home() / "AppData" / "Local"
+        dirs += sorted((lroot / "Packages").glob("Claude_*/LocalCache/Roaming/Claude"))
+        return dirs
+    return [Path.home() / ".config" / "Claude"]
+
+
 def desktop_config_path() -> Path:
     """Location of Claude Desktop's `claude_desktop_config.json`.
 
     Claude Desktop (and Cowork) read MCP servers from this file — registering
     via `claude mcp add` only covers Claude Code. `CLAUDE_DESKTOP_CONFIG`
-    overrides the path (mostly for tests).
+    overrides the path (mostly for tests). Among the platform candidates the
+    one already holding a config file wins, then the first existing directory,
+    then the classic default.
     """
     override = os.environ.get("CLAUDE_DESKTOP_CONFIG")
     if override:
         return Path(override).expanduser()
-    if sys.platform == "darwin":
-        return Path.home() / "Library" / "Application Support" / "Claude" / (
-            "claude_desktop_config.json"
-        )
-    if sys.platform == "win32":
-        appdata = os.environ.get("APPDATA")
-        root = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
-        return root / "Claude" / "claude_desktop_config.json"
-    return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+    candidates = _desktop_config_dirs()
+    for d in candidates:
+        if (d / "claude_desktop_config.json").is_file():
+            return d / "claude_desktop_config.json"
+    for d in candidates:
+        if d.is_dir():
+            return d / "claude_desktop_config.json"
+    return candidates[0] / "claude_desktop_config.json"
 
 
 def _load_desktop_config(path: Path) -> dict[str, Any]:

{lxw_cli-0.1.2 → lxw_cli-0.4.0}/src/lxw_cli/core/client.py

@@ -125,8 +125,10 @@ class LexwareClient:
     def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
         return self._request("GET", path, params=params).json()
 
-    def post(self, path: str, json_body: Any) -> Any:
-        return self._request("POST", path, json=json_body).json()
+    def post(
+        self, path: str, json_body: Any, params: dict[str, Any] | None = None
+    ) -> Any:
+        return self._request("POST", path, params=params, json=json_body).json()
 
     def put(self, path: str, json_body: Any) -> Any:
         return self._request("PUT", path, json=json_body).json()