Skip to content

CLAUDE.md

Latest commit

 

History

History
58 lines (41 loc) · 2.48 KB

CLAUDE.md

File metadata and controls

58 lines (41 loc) · 2.48 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server for the Fakturia billing/subscription management API.

Key Resources

  • Fakturia API docs: https://api.fakturia.de/documentation/
  • OpenAPI spec: docs/api/fakturia-openapi.json — full REST API spec (OpenAPI 3.0.1)
  • API base path: /api/v1/ — authenticated via api-key header
  • API domains: Customers, Contracts, Invoices, Items, Orders, Accounts, Subscriptions, CreditNotes, Webhooks, Reports, Activities, UserLogins, Discounts/Coupons

Project Structure

  • src/index.ts — entry point: env var validation, client init, tool registration, stdio transport
  • src/client.ts — FakturiaApiClient HTTP client (GET/POST/PUT/PATCH/DELETE), api-key header auth
  • src/tools/util.ts — shared helpers: errorResult(), jsonResult(), buildParams()
  • src/tools/*.ts — tool registrations organized by domain (one file per domain, 14 files, 123 tools total)
  • docs/api/ — Fakturia OpenAPI spec
  • bundle/ — esbuild single-file bundle (fakturia-mcp.mjs), checked into git

Build & Run

  • Node version: 24 (see .nvmrc)
  • Package manager: pnpm
  • pnpm build — compile TypeScript to dist/
  • pnpm bundle — compile + bundle to bundle/fakturia-mcp.mjs
  • pnpm start — run from compiled dist/

Environment Variables

  • FAKTURIA_API_HOST (required) — API base URL (e.g. https://api.fakturia.de)
  • FAKTURIA_API_KEY (required) — API key for authentication
  • FAKTURIA_API_INSECURE (optional) — set to 1 to disable TLS cert validation (dev only)

Commit Messages

<type>([scope]): <description>

Examples:

  • feat(contracts): add terminate and cancel tools
  • fix(client): handle 401 error responses correctly
  • refactor(invoices): extract shared filter params

Types: feat, fix, docs, style, refactor, test, config, chore, revert

Architecture

  • Each domain has a registerXTools(server, client) function that registers MCP tools via server.tool()
  • Tools use Zod schemas for parameter validation with .describe() for documentation
  • FakturiaApiClient handles auth, timeouts, and error parsing; tools only deal with paths/params/bodies
  • Errors are wrapped in FakturiaApiError and formatted via errorResult() for MCP-compatible responses
  • Reference the OpenAPI spec at docs/api/fakturia-openapi.json for endpoint details and schemas