beel-mcp: Instructions file for Codex

AGENTS.md — working on this repository with a coding agent

This is the BeeL MCP server: Spanish e-invoicing (VeriFactu) tools for LLM agents, derived from the public OpenAPI contract. Read README.md for what it does and CONTRIBUTING.md for the rules; this file is the short version an agent needs before touching code.

Commands

npm ci
npm test            # vitest — must stay green
npm run typecheck   # tsc for both the Node and the Worker configs
npm run lint        # eslint
npm run format      # prettier --write (CI runs format:check)
npm run build       # tsup + the MCP App bundle (dist/mcpapp/invoice-pdf.html)
npm run smoke       # boots dist/index.js and asserts tools/list
npm run tools:list  # every tool the server exposes, with its scopes

Where things live

• src/spec/ — loads the OpenAPI contract (openapi/public-api.yaml) and derives the operation manifest, and the compact schema declarations beel_schema_get serves (declarations.ts). The contract is synced from the API, never edited by hand.
• src/policy/ — which operations become tools (tool-policy.ts) and which scopes they need (scopes.ts). Least privilege: never add a scope no tool uses.
• src/guardrails/ — the fiscal invariants checked before a request leaves (validate.ts), the API usage guides as markdown (rules/), and the error catalogue (catalog.ts).
• src/rules/ — the fiscal rules catalogue, read from docs.beel.es/api/rules.json. snapshot.json is only its offline fallback, written by npm run sync:rules; never edit it, and never re-type a rule anywhere else.
• src/tools/ — API tools, docs tools, rules tools, the schema tool, workflow tools; src/prompts/ — the workflow prompts.
• src/server.ts — the MCP server (stdio and remote share it); src/index.ts — the stdio entrypoint.
• src/cf/ — the Cloudflare Worker: OAuth bridge (beel-handler.ts), token exchange, PDF relay. /mcp is a protected resource: every request without a token, initialize included, is answered by the OAuth provider with a 401 and its challenge. Deployment notes in DEPLOY.md.
• src/mcpapp/ — the invoice viewer MCP App and its CSP contract.
• tests/ — vitest; one file per module. A behaviour change without a test is not done.