sipgate-mcp 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## 0.5.0 - 2026-08-30
+- Add the final 32 tools for contacts, incoming blocklists, call/product
+  restrictions, history updates/deletes/CSV export, balance, portings,
+  account-wide sipgate.io settings, and webhook logs using the exact v2 paths,
+  verbs, query parameters, and request bodies.
+- Permit account-wide contact, blacklist, balance, porting, sipgate.io, and
+  webhook-log reads in user scope. Require `confirm_account_wide: true` for
+  account-wide contact/blacklist writes, sipgate.io updates in user scope, and
+  every porting cancellation.
+- Verify every single and bulk history mutation against owned history entries.
+  When user scope requests bulk deletion without IDs, enumerate both archived
+  and unarchived entries through owned connection IDs and send only those IDs;
+  never issue an unconstrained account-wide `DELETE /history`.
+- Return `{before, after}` for all new mutations, including explicit
+  no-read-back/deletion notes. Mark contact CSV import, contact/history
+  deletion, and porting cancellation as destructive or irreversible.
+- Add raw-text transport for contact/history CSV exports and explicit
+  403/404-unavailable results for sipgate.io settings and webhook logs.
+- Add 35 phoneline, voicemail/greeting, automated-recording, and faxline-
+  configuration tools covering every requested GET/POST/PUT/DELETE operation,
+  with exact v2 paths and payloads.
+- Add phoneline detail, anonymous-call blocking, attached-device, and parallel-
+  forwarding reads/writes; enforce authenticated-user, owned-phoneline,
+  owned-device, and nested-forwarding boundaries.
+- Add phoneline voicemail settings, greeting upload/activation/deletion,
+  transcription, global voicemail reads, and voicemail playback/recording call
+  sessions. Global results are filtered to voicemail IDs discovered under the
+  authenticated user's phonelines.
+- Add automated call-recording announcement and per-extension settings. User
+  scope accepts settings only for an owned phoneline or faxline extension. The
+  account-global announcement has no user ownership link, so its read/create/
+  delete operations require administrator account scope.
+- Add faxline creation, alias/deletion, caller-ID reads/writes, and tagline
+  updates with owned-faxline and owned-caller-number checks.
+- Return explicit `phonelinesAvailable: false` / `changed: false` results for
+  phoneline-only tools when sipgate returns 403/404, without attempting a
+  mutation. An available but empty phoneline collection still denies access.
+- Warn that voicemail call sessions and recording features may incur charges,
+  and that callers remain responsible for legally required recording consent.
+- Expand read-only registration to 47 read tools and the full write-enabled
+  surface to 129 tools. Add one definition and backend endpoint test per new
+  tool plus foreign-resource and phoneline-less access-policy coverage.
+- Add notification listing, creation, and deletion for call email/SMS, fax
+  email/SMS/report, incoming-SMS email, and voicemail email/SMS targets.
+- Expose established calls and add hangup, hold, mute, recording, transfer,
+  DTMF, and announcement controls with before/after call snapshots.
+- Add faxline and faxline-number reads plus chargeable fax send and resend
+  actions using sipgate's documented session payloads.
+- Restrict user-scoped active calls to participants matching owned devices or
+  phone numbers, verify nested notification IDs before deletion, and verify
+  faxline ownership for reads, notifications, sends, and resends. Unknown or
+  unreadable ownership fails closed.
+- Warn explicitly that fax transmission incurs charges and that call recording
+  can incur charges and requires participant consent in Germany.
+- Keep a shared emergency address from leaking or rewriting other users' data:
+  user scope filters foreign numbers out of an address's number list and
+  refuses to edit an address that other users' numbers are attached to.
+- Establish number ownership from the direct user-number endpoint as well as
+  routing, so quick dials that no phoneline or device routes can still be
+  updated and deleted by their owner.
+- Page through every owned number when deciding ownership instead of stopping
+  after 1000.
+- Redact PUK and ICCID values that arrive outside a credentials wrapper.
+- Establish active-call ownership from the participant sipgate marks as the
+  call owner. Being the remote party of another user's call is not ownership,
+  and a call without a marked owner is denied.
+- Verify that a resent fax belongs to the authenticated user, not just that the
+  faxline does.
+- Accept national phone formats for transfer targets and fax recipients, which
+  the API documents as plain strings.
+- Report the observed HTTP status when a phoneline or recording feature is
+  unavailable, so a denied token scope is no longer indistinguishable from an
+  account that simply has no phoneline layer.
+- Say explicitly when a phoneline change was applied but only its read-back was
+  denied, instead of reporting the feature as unavailable.
+- Accept an owned device as an automated-recording extension; sipgate documents
+  that feature for register endpoints, not only phonelines and faxlines.
+- Refuse to delete an automated-recording greeting other than the one currently
+  configured.
+- Refuse a history deletion whose entry list is present but empty. An empty
+  list serializes to no query parameter, which sipgate reads as "delete the
+  entire account history".
+- Enforce the account-wide confirmation inside SipgateBackend as well, not only
+  at the access-control boundary, since the backend is exported on its own.
+- Reject a bulk history update at sipgate's documented limit of 150 entries.
+- Strip query strings from webhook log URLs, which carry their credentials
+  there as plain strings that key-based redaction cannot see.
+
+- Add complete self-service tools for the requested sipgate v2 device surface:
+  device reads, updates and deletion; aliases; caller ID; local prefix; tariff
+  announcement; single-row display; external-device target/display settings;
+  password rotation; register/mobile/external device creation; and contingents.
+- Add direct user-number reads plus quick-dial validation, creation, updates,
+  and deletion without routing these operations through phonelines.
+- Add emergency-address listing, detail, number association, and updates for
+  assigning verified addresses to register devices.
+- Enforce every new user-scoped resource target against owned devices, owned
+  numbers (including the device fallback on phoneline-less accounts), or
+  addresses associated with an owned device/number. Unknown ownership fails
+  closed with an access-policy error; administrator account scope retains its
+  broader behavior.
+- Return `{before, after}` for all mutations, with explicit no-read-back notes
+  for creates and deletes. Redact credential containers and the one-time
+  password returned by device password rotation.
+- Expand read-only mode from seven to 47 read tools; write tools are never
+  registered in read-only mode.
+- Bump the package, CLI, and setup skill to version 0.5.0.
+
+## 0.4.0 - 2026-08-30
+
+- Treat a 403/404 from the phoneline endpoints as "feature absent" instead of a
+  hard failure. Accounts without a phoneline layer keep their numbers directly
+  on a device, and a single failing phoneline lookup previously took down
+  `list_numbers`, `call_history`, `get_routing`, and `get_settings`.
+- Resolve user numbers through the owning device when no phoneline layer
+  exists, and report the fallback via `source`, `phonelinesAvailable`, and
+  `numbersAvailable`.
+- Scope user call history to device IDs when no phoneline IDs are available, so
+  history is no longer silently empty or denied.
+- Accept an owned device as a routing destination in user scope. Numbers on
+  phoneline-less accounts point at a device, so the previous phoneline-only
+  check rejected every legitimate destination.
+- Read every page of account numbers instead of a single 1000-number page, so
+  ownership checks and pagination stay correct on large accounts.
+- Ask during interactive setup whether to register write tools instead of
+  silently defaulting to read-only. `--allow-writes` and the new `--read-only`
+  skip the question; a non-interactive run without either stays read-only.
+
 ## 0.3.1 - 2026-08-30
 
 - Fix Claude Code registration by using its unambiguous `mcp add-json` command

package/README.md

@@ -43,13 +43,18 @@ sipgate-mcp setup
 
 The setup stores the PAT token ID and token in macOS Keychain without placing
 either value in shell history or an MCP configuration file. It registers every
-installed supported client (Codex and Claude Code) in user/read-only mode.
+installed supported client (Codex and Claude Code) in user scope. An
+interactive setup asks whether to enable write tools; a non-interactive setup
+without a mode flag registers read-only.
 Those clients start and stop the stdio server automatically; `sipgate-mcp` does
 not run as a daemon and does not need to be started manually.
 
 Use `sipgate-mcp setup --client codex` or `--client claude` to configure only
-one client. Add `--allow-writes` only when agent-initiated account changes are
-deliberately wanted. `--dry-run` prints the secret-free registration commands
+one client. `--allow-writes` and `--read-only` pick the mode without being
+asked; write tools let the assistant place calls, send SMS/faxes, and configure
+routing, devices, phonelines, voicemail, greetings, recordings, faxlines,
+contacts, blocklists, call restrictions, history, portings, and sipgate.io.
+`--dry-run` prints the secret-free registration commands
 without changing the Keychain or client configuration. Repeated setup runs
 reuse existing Keychain credentials; use `--replace-credentials` only to rotate
 the stored PAT-ID and PAT.
@@ -104,7 +109,7 @@ addition to sipgate's own user role and PAT scopes:
 
 | Value | Behavior |
 | --- | --- |
-| `user` (default) | Resolves the authenticated user through `/authorization/userinfo`; returns only that user and their assigned numbers; forces user-specific device, routing, and settings reads; constrains call history to owned connection IDs; and validates every write target against owned numbers, phonelines, or devices. |
+| `user` (default) | Resolves the authenticated user through `/authorization/userinfo`; returns only that user and their assigned numbers, notifications, faxlines, phonelines, voicemails, greetings, and attached devices; forces user-specific device, routing, restriction, and settings reads; constrains history reads, exports, and mutations to owned connections/entries; and validates every write target against owned numbers, phonelines, nested voicemail/forwarding/greeting resources, devices, faxlines, notifications, or emergency addresses associated with an owned device/number. Account-wide contact, blacklist, porting-cancellation, and sipgate.io writes require `confirm_account_wide: true`; their reads are allowed and clearly labelled account-wide. |
 | `account` | Enables account-wide reads and writes. Startup fails unless `/users/{authenticatedUserId}` reports `admin: true`. Requires `users:read` for the administrator check. |
 
 Token scopes are permission ceilings, not role elevation. For example,
@@ -131,32 +136,165 @@ listed specific and parent scopes offered by the PAT UI when in doubt.
 | --- | --- | --- | --- |
 | `account_info` | Read | User: cached `/authorization/userinfo`; account: plus `GET /account` | Account: `account:read` (`userinfo` has no scope declaration in Swagger) |
 | `list_users` | Read | User: `GET /users/{self}`; account: `GET /users` | `users:read` |
-| `list_numbers` | Read | User: `GET /{self}/phonelines` and each phoneline's `/numbers`; account: `GET /numbers` | User: `phonelines:read`, `phonelines:numbers:read`; account: `numbers:read` |
+| `list_numbers` | Read | User: own phonelines, or owned devices plus paginated `GET /numbers` when phonelines are unavailable; account: `GET /numbers` | User: `phonelines:read`, `phonelines:numbers:read`; fallback: `devices:read`, `numbers:read`; account: `numbers:read` |
 | `list_devices` | Read | User: `GET /{self}/devices`; account: `GET /users`, `GET /{userId}/devices` | `devices:read`; account also needs `users:read` when `user_id` is omitted |
+| `get_device` | Read | Ownership `GET /{self}/devices`, then `GET /devices/{deviceId}` | `devices:read` |
+| `get_device_caller_id` | Read | Device ownership read, then `GET /devices/{deviceId}/callerid` | `devices:read`, `devices:callerid:read` |
+| `get_device_local_prefix` | Read | Device ownership read, then `GET /devices/{deviceId}/localprefix` | `devices:read`, `devices:localprefix:read` |
+| `get_device_tariff_announcement` | Read | Device ownership read, then `GET /devices/{deviceId}/tariffannouncement` | `devices:read`, `devices:tariffannouncement:read` |
+| `get_device_single_row_display` | Read | Device ownership read, then `GET /devices/{deviceId}/singlerowdisplay` | `devices:read`, `devices:singlerowdisplay:read` |
+| `get_device_contingents` | Read | Device/user ownership reads, then `GET /{userId}/devices/{deviceId}/contingents` | `devices:read` |
+| `list_user_numbers` | Read | `GET /{userId}/numbers`; this direct endpoint never uses phonelines | `numbers:read` |
+| `validate_quick_dial` | Read | `GET /numbers/quickdial/validation/{quickDialNumber}` | `numbers:read` |
+| `list_addresses` | Read | `GET /addresses`; user scope filters through owned device/number relationships | `addresses:read`; user ownership also needs `devices:read`, `numbers:read` and the applicable owned-number read scopes |
+| `get_address` | Read | Address ownership reads, then `GET /addresses/{addressId}` | `addresses:read`; user ownership also needs `devices:read`, `numbers:read` and the applicable owned-number read scopes |
+| `list_address_numbers` | Read | Address ownership reads, then `GET /addresses/{addressId}/numbers` | `numbers:read`, plus user ownership read scopes |
 | `get_routing` | Read | User: own phonelines, numbers, and forwardings; account: also `GET /numbers` and `GET /users` | `phonelines:read`, `phonelines:numbers:read`, `phonelines:forwardings:read`; account also needs `numbers:read` and, when `user_id` is omitted, `users:read` |
 | `call_history` | Read | User: ownership reads for own phonelines/devices, then filtered `GET /history`; account: `GET /history` | `history:read`; user also needs `phonelines:read`, `devices:read` |
+| `list_calls` | Read | `GET /calls`; user scope filters calls to participants matching an owned device ID or phone number | `rtcm:read`; user ownership also needs `devices:read`, `numbers:read` and applicable owned-number scopes |
+| `list_notifications` | Read | `GET /{userId}/notifications` | `notifications:read` |
+| `list_faxlines` | Read | `GET /{userId}/faxlines` | `faxlines:read` |
+| `list_faxline_numbers` | Read | User: faxline ownership read, then `GET /{userId}/faxlines/{faxlineId}/numbers`; account: direct `GET` | `faxlines:read`, `faxlines:numbers:read` |
+| `get_phoneline` | Read | Owned-phoneline lookup, then `GET /{userId}/phonelines/{phonelineId}` | `phonelines:read` |
+| `get_phoneline_block_anonymous` | Read | Owned-phoneline lookup, then `GET /{userId}/phonelines/{phonelineId}/blockanonymous` | `phonelines:read`, `phonelines:blockanonymous:read` |
+| `list_phoneline_devices` | Read | Owned-phoneline/device filtering, then `GET /{userId}/phonelines/{phonelineId}/devices` | `phonelines:read`, `phonelines:devices:read`; user filtering also needs `devices:read` |
+| `list_parallel_forwardings` | Read | Owned-phoneline lookup, then `GET /{userId}/phonelines/{phonelineId}/parallelforwardings` | `phonelines:read`, `phonelines:parallelforwardings:read` |
+| `list_phoneline_voicemails` | Read | Owned-phoneline lookup, then `GET /{userId}/phonelines/{phonelineId}/voicemails` | `phonelines:read`, `phonelines:voicemails:read` |
+| `list_voicemail_greetings` | Read | Owned phoneline/voicemail lookup, then `GET /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}/greetings` | `phonelines:read`, `phonelines:voicemails:read`, `phonelines:voicemails:greetings:read` |
+| `list_voicemails` | Read | `GET /voicemails`; user scope filters by voicemail IDs discovered under owned phonelines | `voicemails:read`; user filtering also needs `phonelines:read`, `phonelines:voicemails:read` |
+| `get_voicemail` | Read | Owned-voicemail lookup, then `GET /voicemails/{voicemailId}` | `voicemails:read`; user ownership also needs `phonelines:read`, `phonelines:voicemails:read` |
+| `list_autorecording_greetings` | Read | Account scope only: `GET /autorecordings/greetings`; the account-global resource has no user ownership link | `autorecording:greeting:read`; sipgate also requires administrator privileges and activated call recording |
+| `get_autorecording_settings` | Read | Owned phoneline/faxline extension lookup, then `GET /autorecordings/{extension}/settings` | `devices:read`; ownership also needs `phonelines:read`, `faxlines:read` |
+| `get_faxline_caller_id` | Read | Owned-faxline lookup, then `GET /{userId}/faxlines/{faxlineId}/callerid` | `faxlines:read` |
+| `create_phoneline` | Write/action | `POST /{userId}/phonelines`; 403/404 becomes a clean unavailable result | `phonelines:write` |
+| `update_phoneline_alias` | Write | Owned-phoneline before/after reads and `PUT /{userId}/phonelines/{phonelineId}` | `phonelines:read`, `phonelines:write` |
+| `delete_phoneline` | Write | Owned-phoneline before-state read and `DELETE /{userId}/phonelines/{phonelineId}` | `phonelines:read`, `phonelines:write` |
+| `set_phoneline_block_anonymous` | Write | Owned-phoneline setting reads and `PUT /{userId}/phonelines/{phonelineId}/blockanonymous` | `phonelines:read`, `phonelines:blockanonymous:read`, `phonelines:blockanonymous:write` |
+| `attach_device_to_phoneline` | Write/action | Owned phoneline/device reads, pre/post assignment reads, and `POST /{userId}/phonelines/{phonelineId}/devices` | `phonelines:read`, `phonelines:devices:read`, `phonelines:devices:write`, `devices:read` |
+| `detach_device_from_phoneline` | Write | Owned phoneline/device reads, pre/post assignment reads, and `DELETE /{userId}/phonelines/{phonelineId}/devices/{deviceId}` | `phonelines:read`, `phonelines:devices:read`, `phonelines:devices:write`, `devices:read` |
+| `create_parallel_forwarding` | Write/action | Owned-phoneline check, pre/post forwarding reads, and `POST /{userId}/phonelines/{phonelineId}/parallelforwardings` | `phonelines:read`, `phonelines:write`, `phonelines:parallelforwardings:read`, `phonelines:parallelforwardings:write` |
+| `update_parallel_forwarding` | Write | Verify forwarding in the owned phoneline, pre/post reads, and `PUT /{userId}/phonelines/{phonelineId}/parallelforwardings/{parallelForwardingId}` | `phonelines:read`, `phonelines:write`, `phonelines:parallelforwardings:read`, `phonelines:parallelforwardings:write` |
+| `delete_parallel_forwarding` | Write | Verify forwarding in the owned phoneline, pre/post reads, and `DELETE /{userId}/phonelines/{phonelineId}/parallelforwardings/{parallelForwardingId}` | `phonelines:read`, `phonelines:write`, `phonelines:parallelforwardings:read`, `phonelines:parallelforwardings:write` |
+| `update_voicemail` | Write | Verify voicemail in the owned phoneline, pre/post voicemail reads, and `PUT /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}` | `phonelines:read`, `phonelines:write`, `phonelines:voicemails:read`, `phonelines:voicemails:write` |
+| `create_voicemail_greeting` | Write/action | Verify owned voicemail, pre/post greeting reads, and `POST /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}/greetings` | `phonelines:read`, `phonelines:write`, `phonelines:voicemails:read`, `phonelines:voicemails:write`, `phonelines:voicemails:greetings:read`, `phonelines:voicemails:greetings:write` |
+| `update_voicemail_greeting` | Write | Verify greeting under the owned voicemail, pre/post reads, and `PUT /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}/greetings/{greetingId}` | Same phoneline/voicemail/greeting read/write scopes as greeting creation |
+| `delete_voicemail_greeting` | Write | Verify greeting under the owned voicemail, pre/post reads, and `DELETE /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}/greetings/{greetingId}` | Same phoneline/voicemail/greeting read/write scopes as greeting creation |
+| `set_voicemail_transcription` | Write | Verify owned voicemail, pre/post voicemail reads, and `PUT /{userId}/phonelines/{phonelineId}/voicemails/{voicemailId}/transcriptions` | `phonelines:read`, `phonelines:write`, `phonelines:voicemails:read`, `phonelines:voicemails:write` |
+| `play_voicemail` | Write/action | User: verify owned device and history/data entry; then `POST /sessions/voicemail/play` | `sessions:write`, `sessions:calls:write`; user ownership also needs `devices:read`, `history:read` and owned-connection scopes |
+| `record_voicemail_greeting` | Write/action | User: verify owned device and target voicemail; then `POST /sessions/voicemail/recording` | `sessions:write`, `sessions:calls:write`; user ownership also needs `devices:read`, `phonelines:read`, `phonelines:voicemails:read` |
+| `create_autorecording_greeting` | Write/action | Account scope only: pre/post `GET /autorecordings/greetings`, `POST /autorecordings/greetings` | `autorecording:greeting:read`, `autorecording:greeting:write`; sipgate requires administrator privileges and activated call recording |
+| `delete_autorecording_greeting` | Write | Account scope only: before-state read, then `DELETE /autorecordings/greetings/{greetingId}` | `autorecording:greeting:read`, `autorecording:greeting:write`; sipgate requires administrator privileges and activated call recording |
+| `set_autorecording_settings` | Write | Owned phoneline/faxline extension lookup, pre/post setting reads, and `PUT /autorecordings/{extension}/settings` | `devices:read`; ownership also needs `phonelines:read`, `faxlines:read` |
+| `create_faxline` | Write/action | `POST /{userId}/faxlines` | `faxlines:write` |
+| `update_faxline_alias` | Write | Owned-faxline pre/post list reads and `PUT /{userId}/faxlines/{faxlineId}` | `faxlines:read`, `faxlines:write` |
+| `delete_faxline` | Write | Owned-faxline before-state read and `DELETE /{userId}/faxlines/{faxlineId}` | `faxlines:read`, `faxlines:write` |
+| `set_faxline_caller_id` | Write | Owned faxline/number checks, pre/post caller-ID reads, and `PUT /{userId}/faxlines/{faxlineId}/callerid` | `faxlines:read`, `faxlines:write`, plus owned-number read scopes |
+| `set_faxline_tagline` | Write | Owned-faxline pre/post list reads and `PUT /{userId}/faxlines/{faxlineId}/tagline` | `faxlines:read`, `faxlines:write` |
 | `get_settings` | Read | `GET /users[/userId]`, `GET /{userId}/devices`, `GET /{userId}/phonelines[/phonelineId]` | `users:read`, `devices:read`, `phonelines:read` |
+| `list_contacts` | Read, account-wide | `GET /contacts` with phone, scope, and pagination filters | `contacts:read` |
+| `get_contact` | Read, account-wide | `GET /contacts/{contactId}` | `contacts:read` |
+| `list_internal_contacts` | Read, account-wide | Deprecated `GET /contacts/internal` compatibility route | `contacts:read` |
+| `export_contacts_csv` | Read, account-wide | `GET /contacts/csv` and return CSV text | `contacts:read` |
+| `get_contacts_vcard` | Read, account-wide | `GET /contacts/vcard` with structured-vCard filters | `contacts:read` |
+| `create_contact` | Write/action, account-wide | `POST /contacts`; user scope requires `confirm_account_wide: true` | `contacts:write` |
+| `update_contact` | Write, account-wide | Before/after `GET /contacts/{contactId}`, then `PUT` on the same path; confirmation required in user scope | `contacts:read`, `contacts:write` |
+| `delete_contact` | Destructive write, account-wide | Before-state `GET`, then `DELETE /contacts/{contactid}`; confirmation required in user scope | `contacts:read`, `contacts:write` |
+| `delete_contacts` | Destructive write, account-wide | Before-state contact reads, then `DELETE /contacts`; omitted filters delete all; confirmation required in user scope | `contacts:read`, `contacts:write` |
+| `import_contacts_csv` | Destructive write/action, account-wide | Pre/post `GET /contacts`, then `POST /contacts/import/csv`; confirmation required in user scope | `contacts:read`, `contacts:write` |
+| `put_contacts_vcard` | Write, account-wide | Pre/post `GET /contacts/vcard`, then `PUT /contacts/vcard`; supplied IDs are overwritten; confirmation required in user scope | `contacts:read`, `contacts:write` |
+| `list_incoming_blacklist` | Read, account-wide | `GET /blacklist/incoming` | `blacklist:read` |
+| `add_incoming_blacklist` | Write/action, account-wide | Pre/post blacklist reads, then `POST /blacklist/incoming`; confirmation required in user scope | `blacklist:read`, `blacklist:write` |
+| `remove_incoming_blacklist` | Write, account-wide | Before-state blacklist read, then `DELETE /blacklist/incoming/{phoneNumber}`; confirmation required in user scope | `blacklist:read`, `blacklist:write` |
+| `list_call_restrictions` | Read | User scope forces the authenticated ID in `GET /callrestrictions`; account scope accepts selected IDs | `callrestrictions:read` |
+| `set_call_restriction` | Write | Pre/post restriction reads, then `POST /{authenticatedUserId}/callrestrictions/{restriction}` | `callrestrictions:read`, `callrestrictions:write` |
+| `list_restrictions` | Read | `GET /restrictions`; user scope accepts only the authenticated user ID | Swagger declares the internal scope |
+| `export_history` | Read | User: owned-connection-filtered `GET /history/export`; account: filtered or account-wide export | `history:read`; user ownership also needs `phonelines:read`, `devices:read` |
+| `set_history_read` | Write | Owned-entry check, pre/post `GET /history/{entryId}`, then `PUT /history/{entryId}/read` | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `set_history_note` | Write | Owned-entry check, pre/post entry reads, then `PUT /history/{entryId}/note` | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `set_history_archive` | Write | Owned-entry check, pre/post entry reads, then `PUT /history/{entryId}/archive` | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `update_history_entry` | Write | Owned-entry check, pre/post entry reads, then `PUT /history/{entryId}` | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `delete_history_entry` | Destructive write | Owned-entry and before-state reads, then `DELETE /history/{entryId}` | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `update_history_entries` | Write | Verify every entry, read before/after state, then `PUT /history` with fewer than 150 entries | `history:read`, `history:write`; user ownership also needs connection read scopes |
+| `delete_history_entries` | Destructive write | `DELETE /history`; user scope expands omission to IDs enumerated through owned connection filters and never sends an unconstrained delete | `history:read`, `history:write`; user ownership also needs `phonelines:read`, `devices:read` |
+| `get_balance` | Read, account-wide | `GET /balance` | `balance:read` |
+| `list_portings` | Read, account-wide | `GET /portings` | `portings:read` |
+| `get_porting` | Read, account-wide | `GET /portings/{portingId}` | `portings:read` |
+| `cancel_porting` | Destructive write, account-wide | Before-state `GET`, then `DELETE /portings/{portingId}`; always requires `confirm_account_wide: true` | `portings:read`, `portings:write` |
+| `get_sipgateio_settings` | Read, account-wide | `GET /settings/sipgateio`; 403/404 returns an unavailable result | `settings:read`, `settings:sipgateio:read` |
+| `update_sipgateio_settings` | Write, account-wide | Pre/post settings reads, then `PUT /settings/sipgateio`; confirmation required in user scope | `settings:read`, `settings:write`, `settings:sipgateio:read`, `settings:sipgateio:write` |
+| `list_webhook_logs` | Read, account-wide | `GET /log/webhooks`; 403/404 returns an unavailable result | `log:webhooks:read` |
 | `set_number_routing` | Write | User: pre/post reads through own phonelines; account: pre/post `GET /numbers`; all modes: `PUT /numbers/{numberId}` | `numbers:write`; user also needs `phonelines:read`, `phonelines:numbers:read`; account needs `numbers:read` |
 | `set_forwarding` | Write | User: phoneline ownership read; then pre/post forwarding reads and `PUT` | `phonelines:read`, `phonelines:write`, `phonelines:forwardings:read`, `phonelines:forwardings:write` |
 | `set_dnd` | Write | User: device ownership read; then pre/post `GET /devices/{deviceId}` and `PUT` | `devices:read`, `devices:write` |
+| `update_device` | Write | Device and optional emergency-address ownership reads; pre/post `GET` plus `PUT /devices/{deviceId}` | `devices:read`, `devices:write`; address ownership may also need `numbers:read` and owned-number read scopes |
+| `delete_device` | Write | Device ownership and before-state reads, then `DELETE /devices/{deviceId}` | `devices:read`, `devices:write` |
+| `set_device_alias` | Write | Device ownership read; pre/post device reads and `PUT /devices/{deviceId}/alias` | `devices:read`, `devices:write` |
+| `set_device_caller_id` | Write | Device and caller-number ownership reads; pre/post caller-ID reads and `PUT /devices/{deviceId}/callerid` | `devices:read`, `devices:write`, `devices:callerid:read`, `devices:callerid:write`, plus owned-number read scopes |
+| `set_device_local_prefix` | Write | Device ownership read; pre/post setting reads and `PUT /devices/{deviceId}/localprefix` | `devices:read`, `devices:write`, `devices:localprefix:read`, `devices:localprefix:write` |
+| `set_device_tariff_announcement` | Write | Device ownership read; pre/post setting reads and `PUT /devices/{deviceId}/tariffannouncement` | `devices:read`, `devices:write`, `devices:tariffannouncement:read`, `devices:tariffannouncement:write` |
+| `set_device_single_row_display` | Write | Device ownership read; pre/post setting reads and `PUT /devices/{deviceId}/singlerowdisplay` | `devices:read`, `devices:write`, `devices:singlerowdisplay:read`, `devices:singlerowdisplay:write` |
+| `set_external_device_target_number` | Write | Device ownership read; pre/post device reads and `PUT /devices/{deviceId}/external/targetnumber` | `devices:read`, `devices:write` |
+| `set_external_device_incoming_call_display` | Write | Device ownership read; pre/post device reads and `PUT /devices/{deviceId}/external/incomingcalldisplay` | `devices:read`, `devices:write` |
+| `change_device_password` | Write/action | Device ownership/before-state reads, then `POST /devices/{deviceId}/credentials/password`; the response is redacted | `devices:read`, `devices:write` |
+| `create_register_device` | Write/action | `POST /{userId}/devices/register` | `devices:write` |
+| `create_mobile_device` | Write/action | `POST /{userId}/devices/mobile` | `devices:write` |
+| `create_external_device` | Write/action | `POST /{userId}/devices/external` | `devices:write` |
+| `create_quick_dial` | Write/action | `POST /numbers/quickdial` | `numbers:write` |
+| `update_quick_dial` | Write | Owned-number before/after reads and `PUT /numbers/quickdial/{quickdialId}` | `numbers:read`, `numbers:write`, plus applicable owned-number read scopes |
+| `delete_quick_dial` | Write | Owned-number before-state read and `DELETE /numbers/quickdial/{numberId}` | `numbers:read`, `numbers:write`, plus applicable owned-number read scopes |
+| `update_address` | Write | Address ownership and pre/post address reads, then `PUT /addresses/{addressId}` | `addresses:read`, `addresses:write`, plus user ownership read scopes |
 | `send_sms` | Write/action | `GET /{userId}/sms`, pre/post `GET /history`, `POST /sessions/sms` | `sms:read`, `history:read`, `sessions:write`, `sessions:sms:write` |
 | `initiate_call` | Write/action | User: device/number ownership reads, then `POST /sessions/calls`; account: pre/post `GET /calls` plus `POST` | `sessions:write`, `sessions:calls:write`; user also needs `devices:read`, `phonelines:read`, `phonelines:numbers:read`; account needs `rtcm:read` |
-
-Every write tool reads current state first and returns a JSON object with `before` and `after`. SMS history can update asynchronously, and `/calls` only contains established calls, so those action snapshots also include an acceptance/session marker.
+| `create_call_email_notification` | Write/action | User: endpoint ownership reads; all modes: pre/post `GET /{userId}/notifications`, `POST /{userId}/notifications/call/email` | `notifications:read`, `notifications:write`; user also needs `devices:read` or `phonelines:read` |
+| `create_call_sms_notification` | Write/action | User: endpoint ownership reads; all modes: pre/post notification reads, `POST /{userId}/notifications/call/sms` | `notifications:read`, `notifications:write`; user also needs `devices:read` or `phonelines:read` |
+| `create_fax_email_notification` | Write/action | User: faxline ownership read; all modes: pre/post notification reads, `POST /{userId}/notifications/fax/email` | `notifications:read`, `notifications:write`; user also needs `faxlines:read` |
+| `create_fax_sms_notification` | Write/action | User: faxline ownership read; all modes: pre/post notification reads, `POST /{userId}/notifications/fax/sms` | `notifications:read`, `notifications:write`; user also needs `faxlines:read` |
+| `create_fax_report_notification` | Write/action | User: faxline ownership read; all modes: pre/post notification reads, `POST /{userId}/notifications/fax/report` | `notifications:read`, `notifications:write`; user also needs `faxlines:read` |
+| `create_sms_email_notification` | Write/action | Pre/post notification reads, `POST /{userId}/notifications/sms/email` | `notifications:read`, `notifications:write` |
+| `create_voicemail_email_notification` | Write/action | Pre/post notification reads, `POST /{userId}/notifications/voicemail/email` | `notifications:read`, `notifications:write` |
+| `create_voicemail_sms_notification` | Write/action | Pre/post notification reads, `POST /{userId}/notifications/voicemail/sms` | `notifications:read`, `notifications:write` |
+| `delete_notification` | Write | User: verify the nested ID in `GET /{userId}/notifications`; all modes: before/after notification reads and `DELETE /{userId}/notifications/{notificationId}` | `notifications:read`, `notifications:write` |
+| `hangup_call` | Write | User: participant ownership read; all modes: before/after `GET /calls`, `DELETE /calls/{callId}` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `set_call_hold` | Write | User: participant ownership read; before/after `GET /calls`, `PUT /calls/{callId}/hold` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `set_call_muted` | Write | User: participant ownership read; before/after `GET /calls`, `PUT /calls/{callId}/muted` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `set_call_recording` | Write | User: participant ownership read; before/after `GET /calls`, `PUT /calls/{callId}/recording` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `transfer_call` | Write/action | User: call-participant and optional caller-ID ownership reads; before/after `GET /calls`, `POST /calls/{callId}/transfer` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `send_call_dtmf` | Write/action | User: participant ownership read; before/after `GET /calls`, `POST /calls/{callId}/dtmf` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `start_call_announcement` | Write/action | User: participant ownership read; before/after `GET /calls`, `POST /calls/{callId}/announcements` | `rtcm:read`, `rtcm:write`; user also needs owned-device/number read scopes |
+| `send_fax` | Write/action | User: faxline ownership read; `POST /sessions/fax` | `sessions:write`, `sessions:fax:write`; user also needs `faxlines:read` |
+| `resend_fax` | Write/action | User: required faxline ownership read; `POST /sessions/fax/resend` | `sessions:write`, `sessions:fax:write`; user also needs `faxlines:read` |
+
+Every write tool returns a JSON object with `before` and `after`. Where a resource can be read, the tool reads current state first and reads it back after the change. Fax send/resend, voicemail playback/recording, and contact creation use `before: null` and return an explicit no-read-back note where sipgate exposes no synchronous identity/state; deletes return the previous state and a deletion marker. SMS history can update asynchronously, and `/calls` only contains established calls.
 
 ### Tool notes
 
 - `list_devices` resolves devices through users because the documented account-wide route is `GET /{userId}/devices`; the live v2 Swagger document does not define `GET /devices`.
-- User scope resolves assigned numbers through the authenticated user's phonelines and never calls account-wide `GET /users` or `GET /numbers` for read tools.
+- `list_user_numbers` calls the documented direct `GET /{userId}/numbers` endpoint and never uses phonelines. Ownership checks retain the device-based fallback required by accounts without a phoneline layer.
+- Every phoneline-dependent tool treats sipgate HTTP 403/404 as feature absence. On accounts where numbers hang directly from a device, reads return `phonelinesAvailable: false` and writes return `changed: false` without attempting the mutation. An available but empty phoneline list still denies every supplied phoneline ID.
+- User scope establishes nested ownership from the documented collections: parallel forwardings under an owned phoneline, voicemails under an owned phoneline, greetings under an owned voicemail, and attached devices that are independently owned. Global `/voicemails` results are filtered to those discovered IDs.
+- Voicemail playback requires an owned device and an owned history/data entry in user scope. The live Swagger request field is spelled `datadId`; the MCP exposes the clearer `data_id` and maps it without changing the API payload. Voicemail greeting recording requires an owned device and target voicemail in user scope.
+- Automated recording settings accept only an extension found in the authenticated user's phonelines or faxlines. The automated-recording greeting is account-global and has no user ownership relationship, so its read/create/delete tools fail closed in user scope and require administrator account scope. sipgate additionally requires activated call recording.
+- User scope never calls account-wide `GET /users`. It calls paginated account `GET /numbers` only for the device-based ownership fallback when phonelines are unavailable.
 - User-scoped number-routing snapshots are also resolved through owned phonelines, and user-scoped Click2Dial deliberately omits account-wide `/calls` snapshots.
+- User-scoped `list_calls` and every live-call mutation read the account-wide `/calls` feed but expose or operate on a call only when at least one participant's `participantId` matches an owned device or `phoneNumber` matches an owned phone number. A missing, unknown, or unreadable match fails closed. sipgate's Swagger does not expose a separate call-owner user or device field.
+- Notification IDs live inside the nested email/SMS/report target arrays returned by `GET /{userId}/notifications`; deletion verifies that nested ID before sending the request. Call-notification endpoints are checked against owned devices/phonelines, and fax notifications against owned faxlines.
+- Fax send and resend actions incur charges. In user scope `resend_fax` requires `faxline_id` even though sipgate marks it optional, because omitting it leaves no documented ownership relationship that can be verified before the chargeable action.
+- Contacts and the incoming blacklist are account-wide sipgate resources. Their reads remain available in user scope, but every write requires `confirm_account_wide: true`; CSV import and contact/history deletion are described as destructive. Porting cancellation always requires the same explicit confirmation and is irreversible through v2.
+- Every single-entry history mutation verifies `connectionIds` against the authenticated user's owned device/phoneline IDs. User-scoped bulk updates verify every entry. An omitted ID list on bulk deletion is expanded by paging both archived and unarchived history through owned connection filters, then deleting only those IDs; an unconstrained `DELETE /history` is never sent in user scope.
+- `set_call_restriction` never accepts a user ID: the backend resolves `/authorization/userinfo` and posts only to `/{authenticatedUserId}/callrestrictions/{restriction}`. `list_call_restrictions` and `list_restrictions` reject foreign users in user scope.
+- Balance, portings, global sipgate.io settings, and webhook logs are account-wide reads that remain visible in user scope. Updating global sipgate.io settings requires account-wide confirmation in user scope. sipgate.io settings/log endpoints translate 403/404 into explicit unavailable results.
+- Call and automated recording can incur charges and are legally sensitive. In Germany the caller is responsible for obtaining consent from every participant; changing or disabling an announcement does not remove that responsibility. Voicemail playback/recording initiates a call and may also incur charges.
+- Address IDs are exposed as integers because sipgate declares every address path parameter as `int32`. In user scope an address is visible or mutable only when an owned device references it, an owned number contains its `addressId`, or `/addresses/{addressId}/numbers` contains an owned number.
+- Device creation can affect billing, and changing an address can deactivate associated telephone numbers depending on country. Every write-tool description advertises the account change and potential charges.
+- Device password rotation intentionally redacts the complete credential container, including sipgate's one-time password response.
 - Number routing uses sipgate's documented `endpointId`. Obtain existing IDs from the read tools; a phoneline ID such as `p0` is the documented example.
 - `set_forwarding` replaces the complete phoneline forwarding list. Pass `forwardings: []` to remove all forwardings. A `timeout` of `0` represents immediate forwarding.
 - `send_sms` refuses to post unless `GET /{userId}/sms` returns the requested (or first available) SMS extension.
-- sipgate documents `POST /sessions/calls` as the classic-PBX Click2Dial route. The API documentation points Neo PBX accounts to `/calls`; supporting that distinct call workflow is left for a future compatibility pass.
+- sipgate documents `POST /sessions/calls` as the classic-PBX Click2Dial route. Live established-call reads and controls use `/calls`; starting a new Neo PBX call through the separate `POST /calls` shape is outside this batch.
 
 ## Read-only mode
 
-Set `SIPGATE_MCP_READONLY=1` to register only the seven read tools. Write tools are absent from `tools/list`, rather than merely failing when called.
+Set `SIPGATE_MCP_READONLY=1` to register only the 47 read tools. Write tools are absent from `tools/list`, rather than merely failing when called.
 
 ```bash
 export SIPGATE_MCP_READONLY=1
@@ -263,7 +401,11 @@ MCP stdio server
 - `sipgate-mcp setup` delegates secret entry directly to the macOS Keychain
   prompt. Secret values are never passed as command-line arguments and are not
   written to Codex or Claude configuration.
-- User scope is the default and validates user IDs plus number, phoneline, device, call, and history ownership before delegation.
+- User scope is the default and validates user IDs plus number, phoneline,
+  nested voicemail/greeting/forwarding, device, faxline, call, recording-
+  extension, and history ownership before delegation. Bulk history deletion is
+  expanded to owned entry IDs, and account-wide writes require explicit
+  confirmation where documented above.
 - Account scope fails startup unless the authenticated sipgate user reports `admin: true`.
 - The Basic Auth header exists only in memory and is sent only to the fixed sipgate API base URL.
 - API error bodies are discarded. User-facing errors never include request headers, response bodies, or credentials.
@@ -295,7 +437,7 @@ Maintainer setup and the one-time first-publish procedure are documented in
 
 ## API provenance and limitations
 
-The endpoint paths, query parameters, request bodies, response models, and scope names were checked against sipgate's live public [REST API v2 Swagger document](https://api.sipgate.com/v2/swagger.json) and [Swagger UI](https://api.sipgate.com/v2/doc) on 2026-08-29. PAT Basic Auth was checked against sipgate's public authentication guide. No authenticated production account was available during development, so real-account behavior remains to be confirmed with the smoke test above—especially product-specific availability, eventual history updates, and classic versus Neo PBX calling.
+The endpoint paths, query parameters, request bodies, response models, and scope names were checked against sipgate's live public [REST API v2 Swagger document](https://api.sipgate.com/v2/swagger.json) and [Swagger UI](https://api.sipgate.com/v2/doc) on 2026-08-30. PAT Basic Auth was checked against sipgate's public authentication guide. No authenticated production account was available during development, so real-account behavior remains to be confirmed with the smoke test above—especially product-specific availability, eventual history updates, and classic versus Neo PBX calling.
 
 ## Roadmap
 

package/SKILL.md

@@ -2,7 +2,7 @@
 name: sipgate-mcp
 description: Install and securely configure the sipgate MCP server when a user asks to set up or connect a sipgate account to Codex or Claude. Do not use for ordinary sipgate product questions.
 metadata:
-  version: "0.3.1"
+  version: "0.5.0"
 ---
 
 # Set up sipgate MCP
@@ -10,19 +10,19 @@ metadata:
 Install the matching CLI version with one available package manager:
 
 ```bash
-vp install -g sipgate-mcp@0.3.1
+vp install -g sipgate-mcp@0.5.0
 ```
 
 ```bash
-npm install -g sipgate-mcp@0.3.1
+npm install -g sipgate-mcp@0.5.0
 ```
 
 ```bash
-pnpm add -g sipgate-mcp@0.3.1
+pnpm add -g sipgate-mcp@0.5.0
 ```
 
 Run only one install command. Confirm that `sipgate-mcp --version` reports
-`0.3.1` before continuing.
+`0.5.0` before continuing.
 
 ## Security boundary
 
@@ -32,8 +32,36 @@ Run only one install command. Confirm that `sipgate-mcp --version` reports
   files, logs, or issue reports.
 - The local server uses a sipgate Personal Access Token. A sipgate OAuth API
   client ID and secret are not substitutes for this local setup.
-- Keep the first setup user-scoped and read-only. Do not enable write tools or
+- Keep setup user-scoped. Let the setup prompt decide read-only versus write
+  tools, and do not pass `--allow-writes` on the user's behalf. Never enable
   account-wide administrator access without an explicit user request.
+- The automated-recording greeting is account-global and intentionally fails
+  closed in user scope; its read/create/delete tools require explicitly
+  requested administrator account scope.
+- User scope remains the resource boundary for write tools: device IDs,
+  phone-number IDs, emergency-address IDs, notification IDs, live-call
+  participants, phonelines, nested parallel forwardings, voicemails and
+  greetings, attached devices, faxlines, and automated-recording extensions
+  are checked against the authenticated user's ownership before account
+  changes are sent.
+- Contacts and the incoming blacklist are account-wide resources. In user
+  scope, never call one of their write tools unless the user explicitly agrees
+  to the account-wide effect and the call includes
+  `confirm_account_wide: true`. The same confirmation is always required to
+  cancel a number porting, and user-scoped sipgate.io settings updates require
+  it as well.
+- History writes are limited to owned entries. An omitted ID list for bulk
+  deletion is expanded to entries from owned connection IDs; never work around
+  that boundary with account scope unless the user explicitly requested
+  administrator-wide access.
+- Never display device credentials. Password rotation deliberately redacts the
+  one-time password returned by sipgate.
+- Fax send/resend and call-initiating voicemail playback/recording actions may
+  incur charges. Call and automated recording are legally sensitive; in
+  Germany the caller is responsible for obtaining every participant's consent,
+  even when the recording announcement is off.
+- Contact CSV imports and history/contact deletions are destructive. Cancelling
+  a number porting is irreversible through the v2 API.
 - Do not remove or replace an existing MCP configuration without the user's
   approval.
 
@@ -54,8 +82,26 @@ sipgate-mcp setup --client claude
 
 Omit `--client` only when both installed clients should be configured. The
 setup delegates PAT entry directly to macOS Keychain and registers a
-user-scoped, read-only stdio server. The client starts and stops that process;
-do not launch `sipgate-mcp` as a daemon.
+user-scoped stdio server. Its interactive prompt asks whether write tools should
+be enabled; do not answer that choice on the user's behalf. The client starts
+and stops that process, so do not launch `sipgate-mcp` as a daemon.
+
+Version 0.5.0 adds user-scoped device, quick-dial, user-number, emergency-
+address, notification, live-call-control, phoneline, voicemail/greeting,
+automated-recording, fax, contact, blacklist, restriction, history-management,
+porting, balance, and sipgate.io self-service. It supports accounts without
+phonelines: direct number reads use `/{userId}/numbers`, ownership checks retain
+the device-based number fallback, and phoneline-only tools return an explicit
+unavailable result instead of surfacing sipgate's 403. Active calls are
+filtered by participants matching owned devices or numbers; nested voicemail,
+greeting, forwarding, attached-device, faxline, and recording-extension IDs
+are verified before use. History updates/deletes and exports are constrained to
+owned connection IDs; account-wide contacts/blacklist writes and sipgate.io
+updates require explicit confirmation in user scope, as does porting
+cancellation. Device/faxline/phoneline creation, fax transmission, call
+sessions, recording, and other writes may incur charges or carry legal
+consequences, and address changes can deactivate associated numbers depending
+on country.
 
 When credentials already exist in Keychain, setup reuses them without another
 prompt. Use `--replace-credentials` only when the user explicitly wants to