Testing
How to try a change beyond pnpm check: the HTTP mode, the Claude Desktop extension, the
keychain, fixtures, live tests against a trial account and the tool-selection evals. It is for
contributors; what each test layer covers is in
Builds and tests.
HTTP mode
The remote mode (--http) is documented for operators in Remote mode. To run it
locally in bearer mode against a trial account:
pnpm buildexport SEVDESK_HTTP_AUTH=bearerexport SEVDESK_HTTP_BEARER_TOKEN="$(node dist/index.js generate-secret)"export SEVDESK_API_TOKEN_FILE=~/.config/sevdesk-trial.tokennode dist/index.js --http # or from source: pnpm dev --httpIt listens on http://127.0.0.1:8080/mcp (SEVDESK_HTTP_PORT changes the port). Connect a client
with the bearer header, for example Claude Code:
claude mcp add --transport http sevdesk-dev http://127.0.0.1:8080/mcp \ --header "Authorization: Bearer $SEVDESK_HTTP_BEARER_TOKEN"Pass the flag as pnpm dev --http, not pnpm dev -- --http: pnpm hands the -- on to the
server, which refuses unknown arguments. Plain http on loopback is for development only: browsers
share cookies across the ports of a host, so another local web server could receive the approval
inbox's session cookie. Try the inbox in a browser profile you use for nothing else.
OAuth mode works locally too, with a loopback public URL
(SEVDESK_HTTP_PUBLIC_URL=http://localhost:8080, SEVDESK_HTTP_SECRET, SEVDESK_OAUTH_ACCOUNTS);
claude.ai cannot reach it, so the end-to-end check with claude.ai runs through a tunnel
(Remote check).
- HTTP smoke test:
pnpm build && node scripts/smoke-http.ts --bin dist/index.jsstarts the built server in bearer mode on a free port (with a dummy sevDesk token, so nothing reaches sevDesk) and checks the health endpoint, the 401s, the Host and Origin refusals, the MCP handshake on both protocol eras and a clean shutdown. Against a running server, withSEVDESK_HTTP_BEARER_TOKENexported (the script reads the token from the environment only, so it never shows up in the process list):node scripts/smoke-http.ts --url http://127.0.0.1:8080. - The image:
docker build -t mcp-server-sevdesk:dev ., then run it read-only as in the Docker quick start and point the smoke test at it with--url. CI does the same in itsdockerjob. - Tests: unit tests in
test/unit/http/(OAuth intest/unit/http/oauth/), integration tests on a real socket intest/integration/http-*.test.ts(bearer, OAuth with the real SDK client, the full flow through the approval inbox) andtest/integration/cross-account.test.ts; helpers for the consent and inbox pages intest/helpers/. Every module with secrets has a test with a captured logger or response that asserts no secret appears; keep it that way.
The Claude Desktop extension
pnpm mcpb builds the .mcpb bundle into build/: it bundles the server with all its
dependencies into one file (tsdown.mcpb.config.ts), generates the manifest's tool list, writes
the license notices of every bundled package, validates and packs the bundle with the mcpb
library, and then starts the unpacked server the way Claude Desktop does. The CI job mcpb runs
it on every pull request and uploads the bundle as an artifact; the release job publish-mcpb
attaches it to the GitHub release with a provenance attestation.
The checked-in server.json is the npm/OCI template. publish-registry waits for publish-mcpb,
downloads the public release bundle, and runs scripts/prepare-registry.ts with plain Node to add
its MCPB URL and SHA-256 to the server.json it publishes. It checks the bundle's name and manifest
version before writing; no dependency install runs in that privileged job. The MCPB entry is
generated at publication time because release-please cannot know the hash of a future asset.
The generator's tests validate against the official schema pinned by server.json (snapshot and
provenance in spec/mcp-registry/). To dry-run the same preparation after pnpm mcpb:
version="$(node -p 'require("./package.json").version')"node scripts/prepare-registry.ts "$version" "v$version" \ "build/mcp-server-sevdesk-$version.mcpb" build/registry/server.jsonChange the extension's settings only in mcpb/manifest.json. Keep its JSON.stringify layout
(release-please rewrites the file when it bumps the version, so Prettier ignores it), and give
every optional setting a default: Claude Desktop passes an empty setting without one as the
literal ${user_config.…}, and the build refuses such a manifest. The setting keys are part of the
compatibility contract, because Claude Desktop stores the user's values
under them. To try a build, open build/mcp-server-sevdesk-<version>.mcpb in Claude Desktop.
Keychain and profiles
The keychain code (src/safety/keychain.ts) takes an injected spawn, so tests never run
security, secret-tool or Windows PowerShell; the profile code takes an injected platform,
user id and home folder. A real round trip is a manual check: token set, token check, a
server start with SEVDESK_API_TOKEN_KEYCHAIN set to a throwaway label, then token delete
(the commands are described in Profiles and keychain).
On Windows, from a clean PowerShell session in the repository (use a new throwaway label and paste the token only at the hidden prompt):
pnpm buildnode dist/index.js token set windows-check-11node dist/index.js token check windows-check-11$env:SEVDESK_API_TOKEN_KEYCHAIN = 'windows-check-11'node dist/index.js --stdio# After the startup message, stop the server with Ctrl+C, then:Remove-Item Env:SEVDESK_API_TOKEN_KEYCHAINnode dist/index.js token delete windows-check-11node dist/index.js token check windows-check-11 # must report no stored tokenRepeat token set before deletion to check replacement, and confirm no token appears in the
output or PowerShell process arguments. PasswordVault requires Windows PowerShell's
FullLanguage mode; Constrained Language Mode must give a safe refusal, never bypass the policy
(ADR 0009).
Fixtures
Fixtures live in test/fixtures/ and record their provenance (spec, community or recorded,
plus date and bookkeeping system version). Recorded fixtures must be scrubbed of personal data and
tokens before committing; the recorder does this, but review the diff anyway.
Live tests
sevDesk has no sandbox: every write is real, and finalized documents cannot be deleted. The live
tooling therefore reads only a short list of variables (SEVDESK_API_TOKEN or
SEVDESK_API_TOKEN_FILE, SEVDESK_BASE_URL, SEVDESK_RATE_LIMIT, SEVDESK_TIMEOUT_MS) and
ignores tier switches from your shell.
pnpm test:livecalls every read tool through the real server against your account, in read-only mode (the HTTP client refuses any data-changing request), and checks that each answers without an error and with schema-valid output. Without a token every test is skipped with the reason. It runs from its own config (vitest.live.config.ts) and never inpnpm test.SEVDESK_LIVE_LIFECYCLE=1 SEVDESK_LIVE_I_UNDERSTAND_WRITES=1 pnpm test:liveadds a write scenario through the write tools (contact, draft, finalize, payments, reminder, cancellation, credit note). Trial accounts only: it refuses accounts that already hold many records, e-mails nothing unlessSEVDESK_LIVE_EMAIL_TOnames your own address, tags what it creates (MCP-E2E <run id>) and prints a cleanup list.pnpm probe --out report.mdchecks the open questions ofspec/deviations.mdagainst the API and reports each finding with scrubbed evidence;--allow-writes(plusSEVDESK_LIVE_I_UNDERSTAND_WRITES=1) adds probes that create their own tagged test data;--probe-email <your address>adds one e-mail probe to that address only.pnpm probe --listshows every probe.pnpm fixtures:recordrecords scrubbed read responses as fixtures (read-only;--dry-runlists the requests).
The step-by-step runbook for a recording session on a free trial account, including what to commit
and what never to commit, is the Recording session runbook. The manual
workflow Live E2E runs pnpm test:live in CI behind the protected live environment.
Tool-selection evals
test/evals/ checks which tool a model picks first for about 70 German and English requests.
pnpm evals replays recorded model answers (no API key, no cost); cases without a recording are
skipped as "stale cassette". A cassette is keyed on the whole request, which contains every tool
of its configuration: changing any tool's name, description or schema, or the server
instructions, stales every case of that configuration. Re-record with
ANTHROPIC_API_KEY=… pnpm evals:record (about $1–2 per full run) and commit the cassettes; when
you rename a tool, also update the expected tool names in test/evals/cases.ts. On pull requests
that touch tools, .github/workflows/evals.yml only replays them, without secrets or cost.
Recording is a local step, run before a release or after description changes, never in CI. The
evals are informative, not a required check. Details:
test/evals/README.md.