lexware-office-mcp: Instructions file for Claude Code

Working guidelines for Claude

How to work in this repository. Read this before making changes. See SPECS.md for what the project is and does.

Golden rules

1. Nothing is enabled by default. This server talks to a live accounting system holding real business records. The tools.json policy file is the only thing that decides which tools exist, a tool it does not name is off, and an installation without the file offers none at all. Nothing may weaken that: no tool may register itself past the file, and no default may stand in for a decision nobody made. Never call a write tool against an account that has not been explicitly confirmed as a test account — call get_profile first and check the organization.
2. Virtual environment only. Never the global Python or pip. A uv-created .venv counts, so uv run ... satisfies this rule. Without uv, invoke the project interpreter directly:
   • .\.venv\Scripts\python.exe ... (PowerShell)
   • .venv/Scripts/python.exe ... (Bash on Windows)
3. English in the repo. All code, comments, docstrings and documentation are English. Conversation with the user may be German. One exception, and only one: the text a person reads on screen in configui/ is German, because that interface has exactly one audience and Lexware Office is sold for German companies only. Code, comments and docstrings there are English like everywhere else, and a message raised outside configui/ is quoted into the page rather than translated — a German paraphrase would be a second copy of a rule that lives in the code.
4. stdio is sacred. stdout carries the MCP JSON-RPC stream. Never print() to stdout from server or library code, log to stderr only.
5. One rate limiter. Every outbound request passes the single ratelimit.TokenBucket that client.py owns — retries and pagination follow-ups included. The upstream limit is global across all endpoints, so a second bucket anywhere is a bug. See SPECS.md section 10.1. A throwaway probe script is not an exception: build a LexwareClient rather than a bare httpx.AsyncClient, or the third request comes back 429 and the account has been told this key misbehaves.
6. Secrets never travel. The API key is never logged, never returned in a tool result, and redacted from error text. No real key, tenant ID, organization ID, voucher ID or customer record in any versioned file. Nor does a filesystem path of this machine. Anything handed to the client ends up in a model's context: a path carries a user name and a directory layout, and the caller cannot act on it anyway. Say what to set or which command to run, and let stderr name the file for the person sitting at the machine. The one exception is a path the caller supplied or asked for, such as a download's destination.
7. The repo stands on its own. State a convention as this project's decision. Do not reference the author's other repositories, local filesystem paths, or email addresses in versioned files.