{
  "markdown": "<!-- mcp-name: io.github.popapidev/pop-mcp -->\n\n# pop-mcp\n\nMCP (Model Context Protocol) server for **POP** — enabling LLMs to generate, submit, and manage Italian e-invoices (FatturaPA/SdI), Peppol, KSeF, ZUGFeRD/Factur-X, and PDF invoices directly from AI assistants.\n\n> **npm:** `@getpopapi/pop-mcp` · **Remote:** `https://mcp.popapi.io/mcp`\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green)](https://nodejs.org/)\n\n---\n\n## Remote MCP (HTTP) — fastest way to get started\n\nDon't want to install anything? `pop-mcp` runs as a hosted, multi-tenant MCP server at:\n\n```\nhttps://mcp.popapi.io/mcp\n```\n\nHead to [popapi.io](https://popapi.io) to grab a license key, then point any MCP-speaking client at\nthat URL with your key as a Bearer token. No local install, no `POP_API_KEY` env var, no build step\n— this is the recommended way to try `pop-mcp` for most people. Use the local stdio setup below only\nif you specifically need a Claude Desktop config running a process on your own machine.\n\n### How it works\n\nThis endpoint speaks MCP **2026-07-28**, which is fully stateless: there is no `initialize`\nhandshake and no session to open or track. Every request is self-contained — it names its own\nprotocol version and capabilities — and the server answers it independently. Because of that,\nthis is a **multi-tenant** endpoint: it never reads a fixed `POP_API_KEY` from its own environment.\nEvery request must carry your own POP license key as a Bearer token:\n\n```\nAuthorization: Bearer <your_license_key>\n```\n\nA missing or malformed `Authorization` header returns a `401` with `error_code: \"unauthorized_user\"`\nbefore any POP API call is made. An invalid-but-well-formed key is passed straight through to POP's\nAPI and surfaces whatever error POP returns (`unauthorized_user`, `insufficient_level`, etc.) — the\nserver does not re-validate keys itself.\n\nAny modern MCP HTTP client can connect: Claude (remote connector), the OpenAI Responses API, n8n,\n[MCP Inspector](https://github.com/modelcontextprotocol/inspector), or a custom integration — not\njust Claude Desktop. All invoice, status, advanced, and onboarding tools are available; onboarding\ntools use their own `onboarding_token` per call and don't require the Bearer key.\n\n### Example with curl\n\nDiscover the server's supported protocol versions and capabilities (optional — clients can also\njust call `tools/list` or `tools/call` directly and handle a version-negotiation error inline):\n\n```bash\ncurl -X POST https://mcp.popapi.io/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer your_license_key_here\" \\\n  -H \"MCP-Protocol-Version: 2026-07-28\" \\\n  -H \"Mcp-Method: server/discover\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"server/discover\",\n    \"params\": { \"_meta\": { \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\", \"io.modelcontextprotocol/clientCapabilities\": {} } }\n  }'\n```\n\nList the available tools — every request is self-contained, so `_meta` (protocol version + client\ncapabilities) travels on every call, not just the first one:\n\n```bash\ncurl -X POST https://mcp.popapi.io/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer your_license_key_here\" \\\n  -H \"MCP-Protocol-Version: 2026-07-28\" \\\n  -H \"Mcp-Method: tools/list\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/list\",\n    \"params\": { \"_meta\": { \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\", \"io.modelcontextprotocol/clientCapabilities\": {} } }\n  }'\n```\n\nThe tool catalog is identical for every license key, so `tools/list` and `server/discover`\nresponses carry a one-hour public cache hint (`ttlMs: 3600000, cacheScope: \"public\"`) — clients and\ngateways may cache them across tenants.\n\n> **`MCP-Protocol-Version` and `Mcp-Method` are required on every request** (per SEP-2243), and must\n> match the body's `_meta.protocolVersion` and `method` exactly, or the server rejects the request\n> with a `400` and JSON-RPC error `-32020` (`HeaderMismatch`). `tools/call` requests additionally\n> require an `Mcp-Name` header matching `params.name`.\n\n### Example with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\nConfigure it to connect to `https://mcp.popapi.io/mcp` with header\n`Authorization: Bearer <your_license_key>`.\n\nThis endpoint runs as a Vercel serverless function (`api/mcp.ts` → `src/mcpHandler.ts`). To run it\nlocally: `npx vercel dev` (requires `vercel link` to the project first).\n\n---\n\n## What is POP?\n\n[POP](https://popapi.io) is a cloud service for electronic invoice generation and delivery, supporting:\n\n- 🇮🇹 **Italian e-invoicing (FatturaPA/SdI)** — compliant with D.Lgs. 127/2015\n- 🇪🇺 **Peppol** — pan-European cross-border B2B invoicing (UBL 2.1)\n- 📄 **PDF invoices** — branded, with email delivery\n- ✅ **Validation** — fiscal codes, VAT numbers, document pre-submission checks\n- 🗄️ **Preservation** — Italian legal archival (conservazione sostitutiva)\n\n---\n\n## Tools Available (11 total)\n\n### Invoice Creation\n| Tool | Endpoint | Plan |\n|------|----------|------|\n| `pop_create_sdi_invoice` | POST `/create-xml` | Any |\n| `pop_create_peppol_invoice` | POST `/create-ubl` | Any (Basic+ to submit) |\n| `pop_create_pdf_invoice` | POST `/create-pdf` | Any (Basic+ for email) |\n| `pop_create_ksef_invoice` | POST `/create-ksef-xml` | Any (KSeF setup for provider submission) |\n| `pop_create_zugferd_invoice` | POST `/create-zugferd` | Any |\n| `pop_sync_zoho_document` | POST `/integration/zoho/sync` | Zoho connector required |\n\n### Status & Retrieval\n| Tool | Endpoint | Plan |\n|------|----------|------|\n| `pop_get_invoice_status` | POST `/sdi/document-notifications` | Any |\n| `pop_get_peppol_document` | POST `/peppol/document-get` | Basic+ |\n| `pop_get_sdi_document` | POST `/sdi/document-get` | Basic+ |\n\n### Validation & Advanced SdI\n| Tool | Endpoint | Plan |\n|------|----------|------|\n| `pop_verify_sdi_document` | POST `/sdi/document-verify` | Basic+ |\n| `pop_preserve_document` | POST `/sdi/document-preserve` | Basic+ |\n\n---\n\n## Prerequisites\n\n- Node.js >= 20\n- A [POP](https://popapi.io) license key\n- For SdI/Peppol submission: active integration on your POP account (Basic/Growth plan)\n\n---\n\n## Authentication\n\n### Get Your License Key\n\n> **New to POP?** Visit [popapi.io](https://popapi.io) to create your account and get your license key.\n\nAPI-only users can activate their account and obtain a `license_key` with this flow:\n\n1. Open [https://popapi.io/otp-login/](https://popapi.io/otp-login/)\n2. Enter your email address\n3. Receive a one-time password (OTP) by email and enter it\n4. Complete the configuration wizard\n5. Open [https://popapi.io/](https://popapi.io/) → **Account > API**\n6. Copy the default generated `license_key`\n\n### Key Management\n\n- Your account includes one default `license_key`, visible under **Account > API**\n- You can generate additional keys linked to the same account from that same page\n- Every `license_key` must be treated as a secret credential — do not commit it to source control\n\n### Recommended First Steps\n\n1. Get your `license_key`\n2. Test it with `GET /account-profile`\n3. Send one document-generation request with a real payload\n4. Add optional delivery integrations only after local generation works\n\n---\n\n## Installation\n\n### From npm (recommended)\n\n```bash\nnpm install -g @getpopapi/pop-mcp\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/getpopapi/pop-mcp\ncd pop-mcp\nnpm install\nnpm run build\n```\n\n---\n\n## Configuration\n\nSet your POP license key as an environment variable:\n\n```bash\nexport POP_API_KEY=your_license_key_here\n```\n\nOptional — use the staging environment:\n\n```bash\nexport POP_ENVIRONMENT=staging\n```\n\n---\n\n## Claude Desktop Setup\n\nAdd to your `claude_desktop_config.json`:\n\n**If installed from npm:**\n\n```json\n{\n  \"mcpServers\": {\n    \"pop\": {\n      \"command\": \"pop-mcp\",\n      \"env\": {\n        \"POP_API_KEY\": \"your_license_key_here\"\n      }\n    }\n  }\n}\n```\n\n**If running from source:**\n\n```json\n{\n  \"mcpServers\": {\n    \"pop\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/pop-mcp/dist/cli.js\"],\n      \"env\": {\n        \"POP_API_KEY\": \"your_license_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n---\n\n## Tool Reference\n\nThe `license_key` is always injected automatically from `POP_API_KEY` — never pass it manually.\n\n### `pop_create_sdi_invoice`\n\nGenerate an Italian FatturaPA XML document. Optionally submit it to the SdI (Sistema di Interscambio).\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `data` | object | ✅ | Full invoice data (see Invoice Data Structure) |\n| `submit_to_sdi` | boolean | — | Set `true` to submit to SdI. Requires Basic+ plan with active SdI integration. Default: `false` |\n| `integration` | object | — | Override integration config. Overrides `submit_to_sdi` if set. |\n| `environment` | string | — | Target environment (e.g. `\"sandbox\"`) |\n\n**Integration options for `integration.use`:**\n- `\"sdi-via-pop\"` or `\"sdi\"` — Submit via POP SdI\n- `\"pop-to-webhook\"` — Deliver to a webhook (requires `id`)\n- `\"fatture-in-cloud\"` — Deliver to Fatture in Cloud\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"user_agent\": \"pop-mcp\",\n  \"user_agent_version\": \"1.0.0\",\n  \"data\": { \"...invoice fields...\" },\n  \"integration\": { \"use\": \"sdi-via-pop\", \"action\": \"create\" }\n}\n```\n\n> `integration` is omitted when `submit_to_sdi` is `false` and no override is provided (XML-only generation).\n\n---\n\n### `pop_create_peppol_invoice`\n\nGenerate a Peppol UBL 2.1 document. Optionally submit it to the Peppol network.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `data` | object | ✅ | Full invoice data. `customer_type` must be `\"company\"` or `\"freelance\"` |\n| `submit_to_peppol` | boolean | — | Set `true` to submit to the Peppol network. Requires Basic+ plan. Default: `false` |\n| `integration` | object | — | Override integration config |\n| `environment` | string | — | Target environment |\n\n**Integration options for `integration.use`:**\n- `\"peppol-via-pop\"` or `\"peppol\"` — Submit via POP Peppol\n- `\"pop-to-webhook\"` — Deliver to a webhook (requires `id`)\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"user_agent\": \"pop-mcp\",\n  \"user_agent_version\": \"1.0.0\",\n  \"data\": { \"...invoice fields...\" },\n  \"integration\": { \"use\": \"peppol-via-pop\", \"action\": \"create\" }\n}\n```\n\n---\n\n### `pop_create_pdf_invoice`\n\nGenerate a branded PDF invoice. Optionally email it to up to 3 recipients.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `data` | object | ✅ | Invoice data. Must include `data.pdf` for PDF-specific settings |\n| `send_email` | boolean | — | Set `true` to email the PDF (requires `data.pdf.email_invoice`, Basic+ plan). Default: `false` |\n| `environment` | string | — | Target environment |\n\n**`data.pdf` fields:**\n\n| Field | Description |\n|-------|-------------|\n| `doc_type_title` | Title shown on document (e.g. `\"Invoice\"`, `\"Receipt\"`) |\n| `logo_url` | Company logo URL (HTTPS) |\n| `head.store_info_address` | Supplier address string in header |\n| `head.billing[]` | Customer billing address array |\n| `head.shipping[]` | Shipping address array (optional) |\n| `email_invoice.to` | Up to 3 recipient email addresses |\n| `email_invoice.from` | Reply-to address |\n| `footer_text` | Custom footer message |\n| `total_tax` | Total tax amount as string |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"user_agent\": \"pop-mcp\",\n  \"user_agent_version\": \"1.0.0\",\n  \"data\": {\n    \"...invoice fields...\",\n    \"pdf\": {\n      \"doc_type_title\": \"Invoice\",\n      \"logo_url\": \"https://example.com/logo.png\",\n      \"head\": { \"store_info_address\": \"Via Roma 1, 00100 Roma IT\", \"billing\": [] },\n      \"total_tax\": \"22.00\",\n      \"email_invoice\": { \"to\": [\"customer@example.com\"] }\n    }\n  }\n}\n```\n\n---\n\n### `pop_create_ksef_invoice`\n\nGenerate a Polish KSeF FA(3) XML invoice or credit note. Optionally submit it through a configured KSeF provider integration.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `data` | object | ✅ | Full invoice data for KSeF FA(3) generation |\n| `integration` | object | — | Optional KSeF provider submission config: `{ use: \"ksef\" \\| \"ksef-via-pop\", action }` |\n| `environment` | string | — | Target environment (e.g. `\"sandbox\"`) |\n\n**Domain rules specific to KSeF:**\n- Poland only — `transfer_lender.personal_data.tax_id_vat.country_id` must be `\"PL\"` with a 10-digit NIP as `id_code`\n- `customer_type` must be `\"company\"` or `\"freelance\"` (no private individuals)\n- `nature` is **always required** at the top level for KSeF (unlike SdI/Peppol, where it's only required at 0% VAT) — reuses the same SdI nature codes (`N1`, `N2.1`, `N2.2`, `N3.1`, `N3.2`, `N4`, ...) to derive KSeF's internal fiscal variant\n- `transmitter_data` is not used (SdI-only concept)\n- `payment_data.payment_details` only accepts `MP01`, `MP02`/`MP03`, `MP05`, `MP08` — other payment method codes are rejected at generation time\n- Base XML generation is available on any plan; provider submission via `integration.use: \"ksef\"` requires a Basic+ plan and the supplier already enrolled as a KSeF legal entity in the POP dashboard\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"user_agent\": \"pop-mcp\",\n  \"user_agent_version\": \"1.0.0\",\n  \"data\": { \"...invoice fields...\", \"nature\": \"N1\" },\n  \"integration\": { \"use\": \"ksef\", \"action\": \"create\" }\n}\n```\n\n> `integration` is omitted entirely for local XML-only generation (no provider submission).\n\n**Returns:** raw FA(3) XML (`application/xml`) for local generation, or JSON (with a UUID) when submitted through a provider integration.\n\n---\n\n### `pop_create_zugferd_invoice`\n\nGenerate a ZUGFeRD/Factur-X document package: a visual PDF, an EN16931 CII XML, and a hybrid PDF/A-3 with the XML embedded.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `data` | object | ✅ | Full invoice data for ZUGFeRD/Factur-X generation |\n| `environment` | string | — | Target environment (e.g. `\"sandbox\"`) |\n\nThis tool has no `integration` parameter — ZUGFeRD generation is local only, with no submit/delivery step.\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"user_agent\": \"pop-mcp\",\n  \"user_agent_version\": \"1.0.0\",\n  \"data\": { \"...invoice fields...\" }\n}\n```\n\n**Returns:** JSON with generation metadata and three Base64-encoded attachments:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"valid\": true,\n    \"profile\": \"EN16931\",\n    \"attachments\": {\n      \"pdf\": { \"filename\": \"...\", \"mime\": \"application/pdf\", \"content_base64\": \"...\" },\n      \"xml\": { \"filename\": \"...\", \"mime\": \"application/xml\", \"content_base64\": \"...\" },\n      \"hybrid_pdf\": { \"filename\": \"...\", \"mime\": \"application/pdf\", \"content_base64\": \"...\" }\n    },\n    \"validation\": { \"...\": \"...\" },\n    \"errors\": [],\n    \"warnings\": []\n  }\n}\n```\n\n---\n\n### `pop_get_invoice_status`\n\nRetrieve the SdI processing status and notifications for a submitted invoice.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string (UUID) | ✅ | Invoice UUID returned by `pop_create_sdi_invoice` when `submit_to_sdi=true` |\n| `response_format` | `\"markdown\"` \\| `\"json\"` | — | Output format. Default: `\"markdown\"` |\n| `environment` | string | — | Target environment |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"integration\": { \"uuid\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" }\n}\n```\n\n**SdI notification statuses:** `pending` · `accepted` · `rejected` · `delivery`\n\n> SdI processing is asynchronous and can take minutes to hours. Retry if no notifications are returned yet.\n\n---\n\n### `pop_get_peppol_document`\n\nRetrieve a Peppol document from the network by UUID.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string (UUID) | ✅ | Peppol document UUID from `pop_create_peppol_invoice` |\n| `zone` | string (2 chars) | — | Country code of the Peppol access point (e.g. `\"BE\"` for Belgium). Required for some regions. |\n| `response_format` | `\"markdown\"` \\| `\"json\"` | — | Output format. Default: `\"markdown\"` |\n| `environment` | string | — | Target environment |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"integration\": { \"uuid\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\", \"zone\": \"IT\" }\n}\n```\n\n> `zone` is omitted from the payload if not provided.\n\n---\n\n### `pop_get_sdi_document`\n\nRetrieve an archived SdI (FatturaPA) document from POP storage by UUID.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string (UUID) | ✅ | SdI document UUID |\n| `response_format` | `\"markdown\"` \\| `\"json\"` | — | Output format. Default: `\"markdown\"` |\n| `environment` | string | — | Target environment |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"integration\": { \"uuid\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" }\n}\n```\n\nRequires: Basic+ plan with active SdI integration.\n\n---\n\n### `pop_verify_sdi_document`\n\nValidate an SdI XML document for compliance before submission. Does not submit the document.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `xml_base64` | string | ✅ | The SdI XML document encoded as a Base64 string |\n| `environment` | string | — | Target environment |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"skip_business_check\": true,\n  \"integration\": { \"xml\": \"<base64-encoded-xml-string>\" }\n}\n```\n\n**Validation checks performed:** XML schema conformance · fiscal code format · VAT number validity · required field presence · amount consistency\n\nRequires: Basic+ plan with active SdI integration and registered business.\n\n---\n\n### `pop_preserve_document`\n\nArchive an SdI document in certified long-term digital storage (conservazione sostitutiva). Italian law requires invoices to be preserved for 10 years.\n\n**MCP inputs:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string (UUID) | ✅ | UUID of the SdI document to archive |\n| `environment` | string | — | Target environment |\n\n**API payload sent:**\n\n```json\n{\n  \"license_key\": \"YOUR_LICENSE_KEY\",\n  \"integration\": { \"uuid\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\" }\n}\n```\n\n> **Important:** Only call this tool when `pop_get_invoice_status` returns status `RC` (Ricevuta di Consegna) or `MC` (Mancata Consegna). Do not call for statuses `NS`, `EC`, `SE`, or `DT`.\n\nRequires: Basic+ plan with active SdI integration.\n\n---\n\n## Usage Examples\n\n### Generate a Simple Italian Invoice (XML Only)\n\nAsk your AI assistant:\n\n> \"Create a FatturaPA invoice for 1000€ + 22% VAT to Rossi SRL (VAT IT12345678901, Milan). My company is Bianchi SRL (VAT IT98765432109, Rome), using payment method bank transfer to IBAN IT60X0542811101000000123456.\"\n\n### Submit Invoice to SdI\n\n> \"Create and submit to SdI an invoice #45 for consulting services, 500€ + 22% VAT to customer Mario Rossi (fiscal code RSSMRA80A01H501U) in Rome.\"\n\n### Check Invoice Status After Submission\n\n> \"What's the status of SdI invoice with UUID abc123-def456-...?\"\n\n### Generate PDF with Email Delivery\n\n> \"Create a PDF invoice for order #123 and email it to customer@example.com.\"\n\n### Verify SdI Document Before Sending\n\n> \"Verify SdI document with UUID abc123-... for compliance before submission.\"\n\n---\n\n## Plan Requirements\n\n| Feature | Free | Basic/Growth | Pro |\n|---------|------|-------------|-----|\n| XML generation (local) | ✅ | ✅ | ✅ |\n| PDF generation | ✅ | ✅ | ✅ |\n| SdI submission | ❌ | ✅ | ✅ |\n| Peppol submission | ❌ | ✅ | ✅ |\n| PDF email delivery | ❌ | ✅ | ✅ |\n| SdI document verification | ❌ | ✅ | ✅ |\n| Document preservation | ❌ | ✅ | ✅ |\n\n---\n\n## Testing\n\n### MCP Inspector (Interactive)\n\n```bash\nnpm run inspector\n# or\nnpx @modelcontextprotocol/inspector dist/cli.js\n```\n\n### Quick Smoke Test\n\n```bash\nPOP_API_KEY=your_key node -e \"\nimport('./dist/cli.js').catch(e => {\n  if (e.message.includes('stdin')) process.exit(0);\n  console.error(e); process.exit(1);\n});\n\"\n```\n\n### Test Tool Schema Listing\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | POP_API_KEY=test node dist/cli.js\n```\n\n---\n\n## Development\n\n```bash\n# Run with auto-reload\nnpm run dev\n\n# Build\nnpm run build\n\n# Clean build artifacts\nnpm run clean\n```\n\n---\n\n## Invoice Data Structure\n\nThe `data` parameter for invoice creation follows the FatturaPA structure:\n\n```\ndata\n├── id                    Invoice/order ID (numeric)\n├── filename              Output filename without extension (e.g. 'IT99900088876_00009')\n├── type                  \"invoice\" | \"credit_note\"\n├── version               \"FPR12\" | \"FPA12\"\n├── sdi_type              7-char SDI code ('0000000' for private individuals)\n├── customer_type         \"private\" | \"company\" | \"freelance\" | \"pa\"\n├── nature                VAT exemption code (required when rate is 0%, e.g. 'N2.1', 'N6.1')\n├── transmitter_data\n│   ├── transmitter_id    { country_id, id_code }\n│   ├── progressive       Transmission progressive ID (e.g. '00001')\n│   ├── transmitter_format  \"FPR12\" | \"FPA12\"\n│   ├── sdi_code          7-char code\n│   ├── transmitter_contact { phone, email }\n│   └── recipient_pec     PEC email (alternative to sdi_code)\n├── transfer_lender       Supplier/seller\n│   ├── personal_data     { tax_id_vat: { country_id, id_code, tax_regime }, company_name }\n│   ├── place             { address, zip_code, city, province_id, country_id }\n│   └── contact           { phone, email }\n├── transferee_client     Customer/buyer\n│   ├── personal_data     { tax_id_vat, tax_id_code (fiscal code for IT private), company_name }\n│   └── place             { address, zip_code, city, province_id, country_id }\n├── invoice_body\n│   ├── general_data      { doc_type (TD01|TD04), date (YYYY-MM-DD), invoice_number, currency }\n│   └── total_document_amount\n├── order_items[]\n│   ├── description, quantity, unit\n│   ├── unit_price, total_price\n│   ├── rate              VAT rate as string (e.g. '22.00')\n│   ├── total_tax         VAT amount (number)\n│   └── item_type         \"product\" | \"shipping\" | \"fee\"\n├── payment_data\n│   ├── terms_payment     TP01 (instalment) | TP02 (full) | TP03 (advance)\n│   ├── payment_details   MP01 (Cash) | MP02 (Check) | MP05 (Bank Transfer) | MP08 (Credit Card) | ...\n│   ├── payment_amount\n│   ├── beneficiary       Required for MP05 (bank transfer)\n│   ├── financial_institution  Required for MP05\n│   └── iban              Required for MP05\n├── purchase_order_data   (optional) { id, date }\n├── connected_invoice_data[]  (required for credit notes) { id, date }\n├── overrides             (optional) { language, bollo_force_apply }\n└── pdf                   (only for pop_create_pdf_invoice)\n    ├── doc_type_title\n    ├── logo_url\n    ├── head              { store_info_address, billing[], shipping[] }\n    ├── total_tax\n    ├── email_invoice     { to[] (max 3), from }\n    └── footer_text\n```\n\n---\n\n## Error Reference\n\n| Error Code | Meaning | Solution |\n|-----------|---------|---------|\n| `unauthorized_user` | Invalid license key | Check `POP_API_KEY` |\n| `insufficient_level` | Plan too low | Upgrade POP plan |\n| `business_not_registered` | No business profile | Register on popapi.io |\n| `integration_inactive` | SdI/Peppol not enabled | Activate on popapi.io |\n| `pop_api_email_limit` | >3 email recipients | Reduce to max 3 |\n| `pop_api_email_not_allowed` | Plan doesn't allow email | Upgrade to Basic+ |\n\n---\n\n## Related Projects\n\n- [n8n-nodes-pop](https://github.com/getpopapi/n8n-nodes-pop) — n8n community nodes for POP\n- [POP](https://popapi.io) — Official website\n- [API Documentation](https://documenter.getpostman.com/view/41622997/2sAYkLmGT8) — Postman docs\n\n---\n\n## License\n\nMIT © [getpopapi](https://github.com/getpopapi)\n",
  "bytes": 24413,
  "sha": "0cce7d8dc6cf986a56954d1232869cfa8ba6a89643b4f05cefa50ade0149b823",
  "repo_slug": "getpopapi/pop-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_popapidev_pop_mcp_cd64a257/readme"
}