pop-mcp: Instructions file for Claude Code

pop-mcp — Project Context for Claude

What This Project Is

A TypeScript MCP (Model Context Protocol) server for the POP Cloud API, enabling LLMs (Claude, etc.) to generate, submit, and manage electronic invoices directly from AI assistants.

The server exposes invoice-generation, integration, status, validation, archival, and onboarding tools covering the maintained POP API surface, including SdI, Peppol, KSeF, ZUGFeRD, PDF, and Zoho.

---

Related Projects

These two sibling directories are the source of truth for the POP API:

• ../pop-cloud-api — The POP Cloud API backend (WordPress REST API, PHP)
• ../n8n-nodes-pop — n8n community nodes for POP (shows all API call patterns)

When in doubt about API behaviour, endpoint shapes, or field meanings: read those.

---

Architecture

src/
├── index.ts              stdio transport entry point
├── constants.ts          API base URLs + endpoint paths
├── types.ts              TypeScript interfaces (responses, errors)
├── client.ts             Axios client, auth (POP_API_KEY header), error handling
├── schemas/
│   └── invoice.ts        Full Zod schema for FatturaPA invoice data structure
└── tools/
    ├── invoices.ts       SdI, Peppol, PDF, KSeF, ZUGFeRD, and Zoho invoice actions
    ├── status.ts         pop_get_invoice_status, pop_get_peppol_document, pop_get_sdi_document
    └── advanced.ts       pop_verify_sdi_document, pop_preserve_document

Transport: stdio (for Claude Desktop and similar local clients)
Stack: TypeScript, @modelcontextprotocol/sdk, axios, zod

---

The 8 Tools

Tool	Endpoint	Plan
pop_create_sdi_invoice	POST /create-xml	Any
pop_create_peppol_invoice	POST /create-ubl	Any (Basic+ to submit)
pop_create_pdf_invoice	POST /create-pdf	Any (Basic+ for email)
pop_create_ksef_invoice	POST /create-ksef-xml	Any (KSeF setup for provider submission)
pop_create_zugferd_invoice	POST /create-zugferd	Any
pop_sync_zoho_document	POST /integration/zoho/sync	Zoho connector required
pop_get_invoice_status	POST /sdi/document-notifications	Any
pop_get_peppol_document	POST /peppol/document-get	Basic+
pop_get_sdi_document	POST /sdi/document-get	Basic+
pop_verify_sdi_document	POST /sdi/document-verify	Basic+
pop_preserve_document	POST /sdi/document-preserve	Basic+