{"_id":"@aiwerk/mcp-server-pingen","name":"@aiwerk/mcp-server-pingen","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aiwerk/mcp-server-pingen","version":"0.1.0","description":"Pingen hybrid mail MCP server — physical letters, mass-mailing batches, Swiss eBill","type":"module","main":"dist/src/server.js","bin":{"mcp-server-pingen":"dist/src/server.js"},"scripts":{"gen-version":"node scripts/gen-version.mjs","prebuild":"npm run gen-version","build":"tsc -p tsconfig.json","start":"node dist/src/server.js","predev":"npm run gen-version","dev":"tsc --watch","pretest":"npm run gen-version && bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","test":"vitest run","posttest":"bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","prepublishOnly":"bash $HOME/agent-memory/commons/scripts/prepublish-safety.sh && npm run build && npm test"},"engines":{"node":">=18.0.0"},"keywords":["mcp","mcp-server","pingen","swiss-mail","hybrid-mail","ebill","letters"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-pingen.git"},"homepage":"https://aiwerkmcp.com","bugs":{"url":"https://github.com/AIWerk/mcp-server-pingen/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.19.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.5.0","vitest":"^3.2.1"},"gitHead":"2b1495823dc56257284d872add1d30d673ca553b","_id":"@aiwerk/mcp-server-pingen@0.1.0","_nodeVersion":"18.19.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-l1Qbttn6MIc7MxF16EXsS24MvO0WQEkaZOtHXnmF7RDpAUJ5qTM6ggsZaDigxuHTets0byqV10oLoH/z9lgjkA==","shasum":"3a19469785c9fbb170fdb92fb1a5175d2348fc11","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-pingen/-/mcp-server-pingen-0.1.0.tgz","fileCount":15,"unpackedSize":63066,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHlHEgtolO2TihPys+t7qPMdelaZz6uek0uT9bhAO42OAiAModmHYBKpLMJyaasz3pSiAkq2nhFqLZoI8xpt9CfGqQ=="}]},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"directories":{},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-pingen_0.1.0_1780010849018_0.29172546297379975"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-28T23:27:28.913Z","0.1.0":"2026-05-28T23:27:29.178Z","modified":"2026-05-28T23:27:29.358Z"},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"description":"Pingen hybrid mail MCP server — physical letters, mass-mailing batches, Swiss eBill","homepage":"https://aiwerkmcp.com","keywords":["mcp","mcp-server","pingen","swiss-mail","hybrid-mail","ebill","letters"],"repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-pingen.git"},"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"bugs":{"url":"https://github.com/AIWerk/mcp-server-pingen/issues"},"license":"MIT","readme":"# @aiwerk/mcp-server-pingen\n\nPingen hybrid mail MCP server — send physical letters, mass-mailing batches, and Swiss eBill invoices via the Pingen API.\n\n## Tools (v0.1.0, 19 tools)\n\n### Letters (8)\n- `pingen_letter_list` — list letters with status/date filters and pagination\n- `pingen_letter_get` — fetch a single letter by UUID\n- `pingen_letter_calculate_price` — price estimate (currency, price) before sending\n- `pingen_letter_create` — upload PDF and create a draft letter (`auto_send` hard-forced to `false`)\n- `pingen_letter_edit` — update delivery settings or metadata on a draft letter\n- `pingen_letter_send` ⚠️ — trigger postal delivery (α-gate, bulk-capable)\n- `pingen_letter_cancel` ⚠️ — cancel a letter before printing (α-gate, bulk-capable)\n- `pingen_letter_delete` ⚠️ — soft-delete a letter (α-gate, bulk-capable)\n\n### Letter Events (1)\n- `pingen_letter_list_issues` — fetch validation issues for a letter (file errors, address errors)\n\n### Batches (5)\n- `pingen_batch_list` — list mass-mailing batches\n- `pingen_batch_get` — fetch batch details, optionally with embedded letters\n- `pingen_batch_create` — upload PDF and create a batch (`auto_send` hard-forced to `false`)\n- `pingen_batch_send` ⚠️ — trigger batch delivery (α-gate, bulk-capable)\n- `pingen_batch_cancel` ⚠️ — cancel a batch (α-gate, bulk-capable)\n\n### eBill (3)\n- `pingen_ebill_list` — list Swiss eBill submissions\n- `pingen_ebill_get` — fetch eBill details\n- `pingen_ebill_create` ⚠️ — submit PDF invoice to SIX eBill network (α-gate)\n\n### Organisations (2)\n- `pingen_organisation_list` — list organisations for this account\n- `pingen_organisation_get` — fetch organisation details and billing balance\n\n## α-gate (2-phase confirmation)\n\nTools marked ⚠️ require a 2-phase confirmation flow to prevent accidental billing charges or irreversible actions:\n\n**Phase 1** — call the tool without `confirm_token`:\n```json\n{ \"name\": \"pingen_letter_send\", \"arguments\": { \"id\": \"...\", \"delivery_product\": \"cheap\", ... } }\n```\nResponse includes `requires_confirmation: true`, a human-readable `summary` of the action, and a `confirm_token` (60s TTL, single-use).\n\n**Phase 2** — call again with the token:\n```json\n{ \"name\": \"pingen_letter_send\", \"arguments\": { \"id\": \"...\", \"delivery_product\": \"cheap\", ..., \"confirm_token\": \"<token>\" } }\n```\n\n**Bulk mode:** pass `ids: [\"uuid1\", \"uuid2\", ...]` instead of `id`. One `confirm_token` covers all items. Phase 2 uses `Promise.allSettled` — partial success is reported as `{ succeeded[], failed[], summary }`.\n\n## Configuration\n\n| Env var | Required | Default | Purpose |\n|---|---|---|---|\n| `PINGEN_CLIENT_ID` | yes | — | OAuth2 client ID from Pingen account settings |\n| `PINGEN_CLIENT_SECRET` | yes | — | OAuth2 client secret |\n| `PINGEN_ORGANISATION_ID` | no | auto-discovered | Organisation UUID — required for multi-org accounts |\n| `PINGEN_API_BASE_URL` | no | `https://api.pingen.com` | Staging override: `https://api-staging.pingen.com` |\n| `PINGEN_IDENTITY_BASE_URL` | no | `https://identity.pingen.com` | Staging override: `https://identity-staging.pingen.com` |\n| `PINGEN_API_TIMEOUT_MS` | no | `30000` | Per-request timeout in ms |\n\n**Multi-org accounts:** Pingen accounts with more than one organisation must set `PINGEN_ORGANISATION_ID` explicitly. If omitted, the server auto-discovers (throws with the list of available org IDs if multiple are found).\n\n## Install\n\n### Option 1 — Hosted (zero setup)\n\nNo local runtime, no env vars on your machine.\n\n1. Sign up at **[aiwerkmcp.com](https://aiwerkmcp.com)**.\n2. Install **Pingen** from the catalog and paste your `PINGEN_CLIENT_ID` + `PINGEN_CLIENT_SECRET`.\n3. Point your MCP client at your hosted endpoint:\n   ```\n   https://bridge.aiwerk.ch/u/<your-user-id>/mcp\n   ```\n\n### Option 2 — Self-hosted (npx)\n\n```bash\nPINGEN_CLIENT_ID=xxx PINGEN_CLIENT_SECRET=yyy npx @aiwerk/mcp-server-pingen\n```\n\nOr install globally:\n\n```bash\nnpm install -g @aiwerk/mcp-server-pingen\nPINGEN_CLIENT_ID=xxx PINGEN_CLIENT_SECRET=yyy mcp-server-pingen\n```\n\n## Typical letter flow\n\n```\n1. pingen_letter_calculate_price(country=\"CH\", paper_types=[\"normal\"], delivery_product=\"cheap\", ...)\n   → { currency: \"CHF\", price: 1.48 }\n\n2. pingen_letter_create(file_base64=<PDF>, file_name=\"invoice.pdf\", address_position=\"left\", ...)\n   → { id: \"uuid\", status: \"validating\" }\n\n3. pingen_letter_get(id=\"uuid\")  →  status: \"valid\"  (or \"action_required\" if address issues)\n\n4. pingen_letter_send(id=\"uuid\", delivery_product=\"cheap\", ...)\n   → { requires_confirmation: true, confirm_token: \"...\" }\n\n5. pingen_letter_send(id=\"uuid\", delivery_product=\"cheap\", ..., confirm_token=\"...\")\n   → { id: \"uuid\", status: \"sending\" }\n```\n\n## Error taxonomy\n\nErrors surface as MCP `isError: true` responses:\n\n- `Configuration error: …` — missing env var, invalid URL, α-gate token expired/invalid\n- `Auth error (401): …` — bad client credentials\n- `Pingen API error <status>: …` — HTTP 4xx/5xx from Pingen, includes JSON:API error detail\n- `Pingen API timeout: …` — request exceeded `PINGEN_API_TIMEOUT_MS`\n- `Network error: …` — DNS/connection failure\n\n## Build / dev notes\n\n- `src/version.ts` is generated from `package.json` by `scripts/gen-version.mjs` (runs as `prebuild`/`pretest`). File is committed so a fresh clone compiles immediately.\n- Staging: set `PINGEN_API_BASE_URL=https://api-staging.pingen.com` and `PINGEN_IDENTITY_BASE_URL=https://identity-staging.pingen.com`.\n\n## About AIWerk MCP\n\nPart of the **[AIWerk MCP platform](https://aiwerkmcp.com)** — curated, signed MCP recipes served either as npm packages for self-hosting or through our multi-tenant hosted bridge.\n\nOther AIWerk MCP servers:\n\n- [@aiwerk/mcp-server-wise](https://github.com/AIWerk/mcp-server-wise) — Wise multi-currency banking\n- [@aiwerk/mcp-server-imap](https://github.com/AIWerk/mcp-server-imap) — IMAP/SMTP email\n- [@aiwerk/mcp-server-cal](https://github.com/AIWerk/mcp-server-cal) — Cal.com scheduling\n\nBrowse the full catalog at [aiwerkmcp.com](https://aiwerkmcp.com).\n\n## Licence\n\nMIT © 2026 AIWerk\n","readmeFilename":"README.md","_rev":"1-417e6dac56ba0da2b0670396d86aa1b0"}