paperless-mcp: Skill for Claude Code

Logging Standard

Logging Standard

Scope

This standard governs first-party code only — src/paperless_mcp/ and tests/. Two categories of log output are explicitly out of scope; do not try to make them conform, silence them, or reformat them:

• pvl-core's request-logging middleware: emits conforming event key=value records for every MCP message (request_started / request_completed / request_failed keyed by method=, and the tool_call_* vocabulary carrying tool=<name>). Governed by fastmcp-pvl-core; no first-party code needed.
• Third-party loggers — uvicorn.access, uvicorn.error, mcp.server.lowlevel.server, httpx, httpcore, docket.worker: configure_logging_from_env governs them for the whole family, and a second rule on the same logger in this repository would only conflict with it. What it does: mcp.server.lowlevel.server, httpx and httpcore sit at WARNING (or the configured level, if stricter) at every level above DEBUG, and at NOTSET under DEBUG so they reappear. uvicorn.access is filtered, not levelled: it stays at NOTSET, only failed requests (status 400 and above) pass below DEBUG, every status passes at DEBUG, and at every level the query string is stripped and a /transfer/<token> segment is redacted — a credential in a request line is not a preference. uvicorn.error is never demoted (it carries bind failures). docket.worker is capped at INFO under DEBUG so its poll loop does not flood the stream.

Framework

• Standard library logging throughout. Every module: logger = logging.getLogger(__name__).
• No print() for operational output. No third-party logging libraries; there is no structlog here, and the JSON output below is pvl-core's formatter over ordinary LogRecords.
• pvl-core's middleware handles tool invocation, timing and error logging automatically.
• pvl-core owns the root logger. cli._root and make_server() call configure_logging_from_env("PAPERLESS_MCP", verbose=...); it installs the one console handler chain at root, switches FastMCP's own handlers off so fastmcp.* propagates into that chain, and is idempotent (its own handlers are replaced on every call, any other root handler — OTLP, file, syslog — is left alone). Never attach a handler yourself: a second console handler renders every line twice. Everything it writes goes to stderr; stdout is the protocol channel under stdio transport.