frihet-mcp AGENTS.md

Frihet MCP Server

Open-source MCP server for Frihet ERP. TypeScript, Node >= 20, MIT license. Distributed via npm + Cloudflare Worker (mcp.frihet.io) + Smithery + Anthropic registry.

Build & Test

npm install                      # Install deps
npm run build                    # tsc → dist/
npm test                         # Run native node test suite
npm start                        # Run server via stdio (local debug)

Pre-commit: npm run build must succeed. npm test must pass.

Code Style

• TypeScript strict mode (strict: true)
• ES2022 target, NodeNext module resolution
• Tools use the established canonical snake_case names, such as create_invoice
• Return human-readable MCP content plus outputSchema-valid structuredContent
• Zod schemas on inputSchema (strict)
• Preserve actionable, sanitized API errors through the shared error helpers
• One tool per logical operation — no batching unless explicit
• Async/await throughout, no callbacks
• Logger from src/logger.ts — never console.log in tool code
• Observability: every tool wrapped via src/observability.ts (Langfuse)

Conventions

• Commit messages: feat(tools): add <family> CRUD / fix(invoices): handle null totals
• Branch names: feat/<descriptive-slug>
• Atomic commits — one tool family per commit minimum
• Update README.md tool count badge when adding tools
• Tool descriptions are concise and bilingual (English / Spanish)
• Test fixtures in src/__tests__/fixtures/

Testing standards

• Every mutating tool must have at least 1 idempotency test
• Every tool must have at least 1 schema rejection test (bad input)
• Every tool must have at least 1 happy path test
• Coverage target: > 80% lines, 100% on auth/scope branches

Gotchas

• NEVER mutate process.env — read once into config object
• API client must respect Idempotency-Key — propagate from tool input when present
• Don't log full request bodies — PII (NIF/IBAN/email). Use mask() from logger
• Cloudflare Worker is a separate deployment surface — pinging the Worker is not a substitute for testing the npm package locally
• MCP SDK breaking changes — pin @modelcontextprotocol/sdk minor; major bumps require manual review
• Postinstall script — node scripts/postinstall.js || true runs harmlessly. Do not make required