mongodb-memory-mcp: Instructions file for Claude Code

CLAUDE.md — MongoDB Memory MCP

Operating notes for anyone — an AI coding session or a human contributor — working in this repository. Read this before touching anything: it is the accumulated set of decisions and conventions the code cannot state for itself.

0. Hard rules — violate none of these

1. All Node tooling runs inside a container, never on the host. No host node, npm, npx, tsc, vitest or eslint. Use ./scripts/ndocker.sh <cmd> from the project root, or docker compose ... run --rm app <cmd>. The wrapper pins HOME, the XDG directories, TMPDIR and the npm cache to paths under the bind-mounted project (.container-home/ and .npm-cache/, both gitignored), so tooling never writes outside the repository.
2. .env is never committed and never read directly. .env.example is the checked-in template. Config reaches the process through the environment (env_file in compose, --env-file, or exported vars); src/config/env.ts reads process.env and nothing else.
3. Index definitions are code. They live in src/db/index-definitions/*.json and are applied by npm run db:indexes. Never create or edit a search index in the Atlas UI — the UI is not the source of truth and cloud Atlas would immediately drift from Atlas Local.
4. Chunks never live in an array on the parent document. They are their own collection (unbounded-array anti-pattern; also the 16MB document limit and the fact that a vector index cannot index an array of subdocuments usefully).
5. Every /api/* route requires the bearer token, reads included. This is a product decision, not an oversight: the process is network-reachable and an unauthenticated read surface hands the whole knowledge base to anyone who can reach the port. The direct consequence is that the server-rendered web pages call KnowledgeService in-process rather than fetching /api/*, so no token ever reaches a browser. /healthz, /readyz and static assets are the only open routes.