front-mcp: Instructions file for Codex

Repository guidance

Purpose

This strict TypeScript MCP server exposes Front resources over stdio, validates inputs with Zod, and applies policy, sanitization, logging, rate-limit, retry, and authentication controls.

Front operations can create, update, assign, send, import, merge, grant, remove, and delete. Treat every non-read action as an external mutation requiring explicit user authority regardless of policy.

Architecture

• src/index.ts owns CLI handling, configuration, authentication selection, diagnostics, and stdio.
• src/server.ts constructs services, registers all tools, and binds MCP request handlers.
• src/tools/ validates tool arguments, evaluates policy, and formats/sanitizes responses.
• src/services/ maps resource actions to Front API requests.
• src/client/ owns HTTP, OAuth, token storage, retry, and rate limiting.
• src/policy/default-policy.ts classifies actions; src/policy/engine.ts resolves decisions.
• src/schemas/ is the Zod contract for Front resources and tool inputs.
• tests/unit/ and tests/integration/ use mocks; scripts/live-test*.js contact a real Front account.
• docs/TOOL_REFERENCE.md is generated by scripts/generate-tool-docs.js.

Preserve the dependency direction tools -> services -> client; lower layers must not import upward.

Setup and verification

Use Node 20 or newer. CI uses the committed lockfile and runs:

npm ci
npm run lint
npm run type-check
npm test
npm run build
npm run smoke

• Run focused Vitest files while iterating, then the relevant full gates.
• npm run build compiles TypeScript and runs the postbuild script.
• npm run smoke expects dist/index.js already to exist; the package script does not build first.
• npm run generate-docs overwrites docs/TOOL_REFERENCE.md; review it when its sources change.
• Do not install dependencies or execute gates when the task is instruction-only.

Implementation conventions

• Keep TypeScript strict; do not add any, ts-ignore, or stdout logging.
• stdout is reserved for MCP protocol messages; use the repository logger, which writes to stderr.
• Add tests for every behavior change, including schema, service, tool, and policy layers as affected.
• New resources need a policy classification, schema, service, tool registration, server registration, and corresponding tests.
• Keep exact dependency pins unless a deliberate upgrade validates all supported Node versions.
• Preserve HTTPS-only requests, retry/rate-limit behavior, token-file permissions, redaction, and sanitization boundaries.