McProxy CLAUDE.md

McProxy — rules for working in this repo

Reasoning for every rule below lives in docs/ARCHITECTURE.md (section numbers noted). Read there before changing behavior these rules protect.

Trust boundary (§1)

• No tool handler builds a content: [...] literal. Use untrustedResult / plainResult / errorResult from src/shared/tools/untrusted.ts — nothing else.
• Every mutating tool's description carries the literal all-caps word MUTATES, and has a matching entry in AUDITED_MUTATING (scripts/test-mcp-trust.ts). The suite asserts the two sets are exactly equal, in both directions.
• Provider error text reaches a user only through sanitizeErrorMessage (src/shared/redact.ts, re-exported from untrusted.ts). Never surface a raw caught error.

.env (§3, §4)

• src/connectors/env-file.ts is the only module that writes .env. Never fs.writeFile it directly from anywhere else.
• envPrefix on a descriptor is always a literal you choose — never derive it from id (an id may contain a hyphen, which isn't legal in an env var name).
• The three naming forms ({PREFIX}_ACCOUNTS, legacy adoption, bare singleton) are read in strict precedence and never merged. Don't try to make them cooperate.

Paths and roles (§7, §8)

• Never capture baseDir() / tokenDir() in a module-level const/let/var. Both are functions — call them at the point of use, every time. scripts/test-boundaries.ts check (c) scans for violations of this.
• Every write under ~/.mcproxy goes through src/shared/secure-fs.ts's helpers. Don't hand-roll fs.writeFile/fs.mkdir against that tree — the mode traps documented there are real.

Connectors (§2, §5, §6)

• A probe must never answer from a cache, and must never reject — encode every failure (missing config, a rejected credential, a network error) into the returned ProbeResult.
• Identity is recorded only by an explicit act (Confirm identity, or a successful reconnect) — never inferred from an ordinary Test call.
• A descriptor may not claim more instance-plurality (multiInstance: true) than its client actually implements. If the real client only ever holds one credential, the descriptor says so.
• Absence is a state, not a default: no status record means "never checked," never ok. Don't invent a default-healthy fallback anywhere in this layer.