sipgate-mcp 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.1 - 2026-08-30
+
+- Fix Claude Code registration by using its unambiguous `mcp add-json` command
+  instead of the variadic `--env` parser.
+- Clearly map macOS Keychain's generic `password data` prompts to sipgate's
+  PAT-ID and PAT labels.
+- Reuse existing Keychain credentials on repeated setup runs and add
+  `--replace-credentials` for deliberate rotation.
+
+## 0.3.0 - 2026-08-30
+
+- Add `sipgate-mcp setup` for interactive PAT storage in macOS Keychain.
+- Register installed Codex and Claude Code clients with a secret-free launch
+  command, user scope, and read-only mode by default.
+- Load Keychain credentials automatically when environment credentials are
+  absent, while keeping environment variables as an explicit override.
+- Add setup dry-run and opt-in write-mode flags.
+- Add a versioned agent skill and README bootstrap link for guided setup.
+- Add `sipgate-mcp --version` and verify that CLI, package, and skill versions
+  remain synchronized.
+
 ## 0.2.0 - 2026-08-30
 
 - Default to MCP-level user scope resolved from sipgate's authenticated user.

package/README.md

@@ -2,7 +2,7 @@
 
 `sipgate-mcp` is an open-source, self-hosted Model Context Protocol server for inspecting and configuring a sipgate account. It exposes the sipgate REST API v2 as focused tools for agents such as Claude Code, Claude Desktop, and Codex.
 
-Version 0.2 defaults to user-scoped access: tools are constrained to the
+Version 0.2 and later default to user-scoped access: tools are constrained to the
 authenticated sipgate user's resources. Account-wide access is an explicit
 administrator-only mode.
 
@@ -10,6 +10,17 @@ The server uses stdio only. It does not start an HTTP server or route credential
 through a third-party service. It sends authentication only from the local MCP
 process directly to `https://api.sipgate.com/v2`.
 
+## Agent-assisted setup
+
+Tell Codex or Claude:
+
+> Set up sipgate MCP by following
+> https://raw.githubusercontent.com/wiesson/sipgate-mcp/main/SKILL.md
+
+The linked, versioned [`SKILL.md`](SKILL.md) tells the agent how to install and
+verify the matching package without asking for credentials in chat. Secret
+entry remains an interactive local Keychain step controlled by the user.
+
 ## Requirements
 
 - Node.js 22 or newer
@@ -24,13 +35,43 @@ pnpm add --global sipgate-mcp
 vp install --global sipgate-mcp
 ```
 
-Then start it with:
+On macOS, run the interactive setup once:
 
 ```bash
-export SIPGATE_TOKEN_ID="your-token-id"
-export SIPGATE_TOKEN="your-token"
+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.
+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
+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.
+
+During first setup, macOS calls both secure inputs `password data`. The setup
+labels the steps explicitly: enter the sipgate **PAT-ID** twice in step 1, then
+the sipgate **PAT** twice in step 2. Input remains hidden while typing.
+
+Secure interactive storage currently supports macOS. Environment variables
+remain available for Linux, Windows, containers, CI, and password-manager
+wrappers. To avoid putting literal credentials in shell history, read them
+interactively:
+
+```bash
+printf "sipgate PAT token ID: "
+IFS= read -r SIPGATE_TOKEN_ID
+printf "sipgate PAT token: "
+IFS= read -rs SIPGATE_TOKEN
+printf "\n"
+export SIPGATE_TOKEN_ID SIPGATE_TOKEN
 export SIPGATE_MCP_SCOPE="user"
-sipgate-mcp
+export SIPGATE_MCP_READONLY="1"
 ```
 
 For clients that manage MCP commands on demand, `npx -y sipgate-mcp` remains
@@ -41,11 +82,20 @@ supported without a global installation.
 1. Open [sipgate Personal Access Tokens](https://app.sipgate.com/personal-access-token).
 2. Select **Add token**, give the token a recognizable name, and select the scopes needed for the tools you intend to use.
 3. Copy both the token ID and token. sipgate displays the token itself only once.
-4. Put them in the environment as `SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN` before starting your MCP client.
+4. Run `sipgate-mcp setup` on macOS, or provide them as `SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN` in the MCP process environment.
 
 sipgate PAT authentication uses HTTP Basic Auth with `token-id:token` as the credential pair. `sipgate-mcp` constructs that header in memory. See sipgate's [authentication guide](https://en.sipgate.io/rest-api/authentication).
 
-Do not put either value in this repository, an MCP config committed to source control, command output, or an issue report.
+Do not put either value in this repository, an MCP config committed to source control, shell command arguments, command output, or an issue report.
+
+The separate **API Clients** screen in the sipgate account creates OAuth 2.0
+client credentials for an application that redirects users through sipgate's
+authorization flow. Those client credentials are not PAT replacements and are
+not used by the local stdio setup. They are relevant to a future hosted/remote
+MCP, which would need a registered redirect URI, user consent, access-token
+refresh, and secure per-user token storage. See sipgate's [OAuth authentication
+flow](https://en.sipgate.io/rest-api/authentication#oauth2) and [API client
+management](https://en.sipgate.io/rest-api/managing-third-party-clients).
 
 ## MCP access scopes
 
@@ -116,7 +166,10 @@ npx -y sipgate-mcp
 
 ## MCP client configuration
 
-Set `SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN` in the environment that launches the MCP client. The examples keep secret values out of configuration files.
+The recommended macOS path is `sipgate-mcp setup`. The following manual
+examples are useful for other platforms and custom launchers. Set
+`SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN` in the environment that launches the MCP
+client; the examples keep secret values out of configuration files.
 
 ### Claude Code
 
@@ -205,7 +258,11 @@ MCP stdio server
 
 ## Security
 
-- PAT values are read only from `SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN`.
+- PAT values are read from `SIPGATE_TOKEN_ID` and `SIPGATE_TOKEN`, or from the
+  current user's macOS Keychain when both variables are absent.
+- `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.
 - 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.

package/SKILL.md

@@ -0,0 +1,91 @@
+---
+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"
+---
+
+# Set up sipgate MCP
+
+Install the matching CLI version with one available package manager:
+
+```bash
+vp install -g sipgate-mcp@0.3.1
+```
+
+```bash
+npm install -g sipgate-mcp@0.3.1
+```
+
+```bash
+pnpm add -g sipgate-mcp@0.3.1
+```
+
+Run only one install command. Confirm that `sipgate-mcp --version` reports
+`0.3.1` before continuing.
+
+## Security boundary
+
+- Never ask the user to paste a sipgate PAT, token, client secret, or other
+  credential into chat.
+- Never place credentials in command arguments, MCP configuration, repository
+  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
+  account-wide administrator access without an explicit user request.
+- Do not remove or replace an existing MCP configuration without the user's
+  approval.
+
+## Configure
+
+On macOS, run the interactive setup for the MCP client the user is currently
+using:
+
+```bash
+sipgate-mcp setup --client codex
+```
+
+or:
+
+```bash
+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.
+
+When credentials already exist in Keychain, setup reuses them without another
+prompt. Use `--replace-credentials` only when the user explicitly wants to
+rotate or replace the stored PAT-ID and PAT.
+
+If the Keychain prompt cannot be presented in the current environment, ask the
+user to run the setup command in their local interactive terminal. Do not ask
+them to provide the credential to the agent instead. On Linux or Windows,
+follow the secret-free environment or password-manager launcher guidance in
+the project README rather than inventing a plaintext credential file.
+
+If setup reports that an MCP server named `sipgate` already exists, inspect it
+with `codex mcp get sipgate` or `claude mcp get sipgate`. Explain the conflict
+and request approval before removing or replacing that configuration.
+
+## Verify
+
+Use the applicable client command:
+
+```bash
+codex mcp get sipgate
+```
+
+```bash
+claude mcp get sipgate
+```
+
+Ask the user to restart the client when required, open `/mcp`, and test with:
+
+> Use sipgate read-only. Check the connection and list my phone numbers.
+
+Do not enable `--allow-writes` merely to make a failed read test pass. Diagnose
+installation, credentials, client registration, and PAT read scopes first.

package/dist/config.d.ts

@@ -1,9 +1,10 @@
 import type { AccessScope } from "./backend/telephony-backend.js";
+import { type SipgateCredentials } from "./credentials.js";
 export interface ServerConfig {
     accessScope: AccessScope;
     tokenId: string;
     token: string;
     readonly: boolean;
 }
-export declare function loadConfig(env?: NodeJS.ProcessEnv): ServerConfig;
+export declare function loadConfig(env?: NodeJS.ProcessEnv, storedCredentialLoader?: () => SipgateCredentials | undefined): ServerConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAgB7E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,UAAU,CACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,sBAAsB,GAAE,MAAM,kBAAkB,GAAG,SAAiC,GACnF,YAAY,CAwBd"}

package/dist/config.js

@@ -1,8 +1,13 @@
-export function loadConfig(env = process.env) {
-    const tokenId = env.SIPGATE_TOKEN_ID;
-    const token = env.SIPGATE_TOKEN;
+import { loadStoredCredentials, } from "./credentials.js";
+export function loadConfig(env = process.env, storedCredentialLoader = loadStoredCredentials) {
+    const hasEnvironmentCredential = Boolean(env.SIPGATE_TOKEN_ID || env.SIPGATE_TOKEN);
+    const storedCredentials = hasEnvironmentCredential
+        ? undefined
+        : storedCredentialLoader();
+    const tokenId = env.SIPGATE_TOKEN_ID ?? storedCredentials?.tokenId;
+    const token = env.SIPGATE_TOKEN ?? storedCredentials?.token;
     if (!tokenId || !token) {
-        throw new Error("Both SIPGATE_TOKEN_ID and SIPGATE_TOKEN must be set.");
+        throw new Error("Credentials are missing. Run 'sipgate-mcp setup' or set both SIPGATE_TOKEN_ID and SIPGATE_TOKEN.");
     }
     const accessScope = env.SIPGATE_MCP_SCOPE ?? "user";
     if (accessScope !== "user" && accessScope !== "account") {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,UAAU,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC7D,MAAM,OAAO,GAAG,GAAG,CAAC,gBAAgB,CAAC;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC;IAChC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,WAAW,GAAG,GAAG,CAAC,iBAAiB,IAAI,MAAM,CAAC;IACpD,IAAI,WAAW,KAAK,MAAM,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO;QACL,WAAW;QACX,OAAO;QACP,KAAK;QACL,QAAQ,EAAE,GAAG,CAAC,oBAAoB,KAAK,GAAG;KAC3C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,GAEtB,MAAM,kBAAkB,CAAC;AAS1B,MAAM,UAAU,UAAU,CACxB,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,sBAAsB,GAAyC,qBAAqB;IAEpF,MAAM,wBAAwB,GAAG,OAAO,CACtC,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,aAAa,CAC1C,CAAC;IACF,MAAM,iBAAiB,GAAG,wBAAwB;QAChD,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,sBAAsB,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,gBAAgB,IAAI,iBAAiB,EAAE,OAAO,CAAC;IACnE,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,IAAI,iBAAiB,EAAE,KAAK,CAAC;IAC5D,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,GAAG,CAAC,iBAAiB,IAAI,MAAM,CAAC;IACpD,IAAI,WAAW,KAAK,MAAM,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO;QACL,WAAW;QACX,OAAO;QACP,KAAK;QACL,QAAQ,EAAE,GAAG,CAAC,oBAAoB,KAAK,GAAG;KAC3C,CAAC;AACJ,CAAC"}

package/dist/credentials.d.ts

@@ -0,0 +1,13 @@
+export interface SipgateCredentials {
+    tokenId: string;
+    token: string;
+}
+export declare const MACOS_KEYCHAIN_SERVICE = "sipgate-mcp";
+export declare const MACOS_KEYCHAIN_TOKEN_ID_ACCOUNT = "pat-token-id";
+export declare const MACOS_KEYCHAIN_TOKEN_ACCOUNT = "pat-token";
+type KeychainReader = (account: string) => string;
+type KeychainWriter = (account: string, label: string) => void;
+export declare function loadStoredCredentials(platform?: NodeJS.Platform, readKeychain?: KeychainReader): SipgateCredentials | undefined;
+export declare function storeCredentialsInteractively(platform?: NodeJS.Platform, writeKeychain?: KeychainWriter, output?: Pick<NodeJS.WriteStream, "write">): void;
+export {};
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AACpD,eAAO,MAAM,+BAA+B,iBAAiB,CAAC;AAC9D,eAAO,MAAM,4BAA4B,cAAc,CAAC;AAExD,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAClD,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AA0C/D,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,YAAY,GAAE,cAAsC,GACnD,kBAAkB,GAAG,SAAS,CAehC;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,aAAa,GAAE,cAAsC,EACrD,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,GACzD,IAAI,CAmBN"}

package/dist/credentials.js

@@ -0,0 +1,63 @@
+import { execFileSync, spawnSync } from "node:child_process";
+export const MACOS_KEYCHAIN_SERVICE = "sipgate-mcp";
+export const MACOS_KEYCHAIN_TOKEN_ID_ACCOUNT = "pat-token-id";
+export const MACOS_KEYCHAIN_TOKEN_ACCOUNT = "pat-token";
+function defaultKeychainReader(account) {
+    return execFileSync("/usr/bin/security", [
+        "find-generic-password",
+        "-s",
+        MACOS_KEYCHAIN_SERVICE,
+        "-a",
+        account,
+        "-w",
+    ], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function defaultKeychainWriter(account, label) {
+    const result = spawnSync("/usr/bin/security", [
+        "add-generic-password",
+        "-a",
+        account,
+        "-s",
+        MACOS_KEYCHAIN_SERVICE,
+        "-l",
+        label,
+        "-U",
+        "-w",
+    ], { stdio: "inherit" });
+    if (result.error || result.status !== 0) {
+        throw new Error("macOS Keychain did not store the credential.");
+    }
+}
+export function loadStoredCredentials(platform = process.platform, readKeychain = defaultKeychainReader) {
+    if (platform !== "darwin") {
+        return undefined;
+    }
+    try {
+        const tokenId = readKeychain(MACOS_KEYCHAIN_TOKEN_ID_ACCOUNT).trim();
+        const token = readKeychain(MACOS_KEYCHAIN_TOKEN_ACCOUNT).trim();
+        if (!tokenId || !token) {
+            return undefined;
+        }
+        return { tokenId, token };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function storeCredentialsInteractively(platform = process.platform, writeKeychain = defaultKeychainWriter, output = process.stderr) {
+    if (platform !== "darwin") {
+        throw new Error("Secure interactive setup currently supports macOS Keychain only. Use SIPGATE_TOKEN_ID and SIPGATE_TOKEN on this platform.");
+    }
+    output.write("\n[1/2] sipgate PAT-ID\n" +
+        "The following macOS Keychain prompt calls this value 'password data'.\n" +
+        "Enter the PAT-ID twice. Input is hidden while typing.\n");
+    writeKeychain(MACOS_KEYCHAIN_TOKEN_ID_ACCOUNT, "sipgate PAT-ID");
+    output.write("\n[2/2] sipgate PAT\n" +
+        "The following macOS Keychain prompt again calls this value 'password data'.\n" +
+        "Enter the PAT twice. Input is hidden while typing.\n");
+    writeKeychain(MACOS_KEYCHAIN_TOKEN_ACCOUNT, "sipgate PAT");
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAO7D,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC;AACpD,MAAM,CAAC,MAAM,+BAA+B,GAAG,cAAc,CAAC;AAC9D,MAAM,CAAC,MAAM,4BAA4B,GAAG,WAAW,CAAC;AAKxD,SAAS,qBAAqB,CAAC,OAAe;IAC5C,OAAO,YAAY,CACjB,mBAAmB,EACnB;QACE,uBAAuB;QACvB,IAAI;QACJ,sBAAsB;QACtB,IAAI;QACJ,OAAO;QACP,IAAI;KACL,EACD;QACE,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;KACpC,CACF,CAAC,IAAI,EAAE,CAAC;AACX,CAAC;AAED,SAAS,qBAAqB,CAAC,OAAe,EAAE,KAAa;IAC3D,MAAM,MAAM,GAAG,SAAS,CACtB,mBAAmB,EACnB;QACE,sBAAsB;QACtB,IAAI;QACJ,OAAO;QACP,IAAI;QACJ,sBAAsB;QACtB,IAAI;QACJ,KAAK;QACL,IAAI;QACJ,IAAI;KACL,EACD,EAAE,KAAK,EAAE,SAAS,EAAE,CACrB,CAAC;IAEF,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,QAAQ,GAAoB,OAAO,CAAC,QAAQ,EAC5C,YAAY,GAAmB,qBAAqB;IAEpD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,MAAM,KAAK,GAAG,YAAY,CAAC,4BAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;QAChE,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,QAAQ,GAAoB,OAAO,CAAC,QAAQ,EAC5C,aAAa,GAAmB,qBAAqB,EACrD,MAAM,GAAsC,OAAO,CAAC,MAAM;IAE1D,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,2HAA2H,CAC5H,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,KAAK,CACV,0BAA0B;QAC1B,yEAAyE;QACzE,yDAAyD,CAC1D,CAAC;IACF,aAAa,CAAC,+BAA+B,EAAE,gBAAgB,CAAC,CAAC;IACjE,MAAM,CAAC,KAAK,CACV,uBAAuB;QACvB,+EAA+E;QAC/E,sDAAsD,CACvD,CAAC;IACF,aAAa,CAAC,4BAA4B,EAAE,aAAa,CAAC,CAAC;AAC7D,CAAC"}

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 export declare function main(): Promise<void>;
+export declare function runCli(args?: string[]): Promise<void>;
 export declare function isMainModule(moduleUrl: string, entrypoint: string | undefined): boolean;
 export { SipgateBackend } from "./backend/sipgate-backend.js";
 export { AccessPolicyError, createAccessControlledBackend, } from "./backend/access-controlled-backend.js";
 export { SipgateApiError, SipgateClient } from "./backend/sipgate-client.js";
 export type { AccessScope, AuthenticatedUserContext, TelephonyBackend, } from "./backend/telephony-backend.js";
 export { createServer } from "./server.js";
+export { loadStoredCredentials, storeCredentialsInteractively, } from "./credentials.js";
+export { buildRegistrationCommand, parseSetupArgs, runSetup } from "./setup.js";
 export { createToolDefinitions } from "./tools/definitions.js";
+export { VERSION } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAaA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAUvF;AAUD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EACV,WAAW,EACX,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAeA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1C;AAED,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlF;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAUvF;AAaD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EACV,WAAW,EACX,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -7,6 +7,8 @@ import { SipgateBackend } from "./backend/sipgate-backend.js";
 import { SipgateClient } from "./backend/sipgate-client.js";
 import { loadConfig } from "./config.js";
 import { createServer } from "./server.js";
+import { runSetup, SETUP_HELP, SetupError } from "./setup.js";
+import { VERSION } from "./version.js";
 export async function main() {
     const config = loadConfig();
     const client = new SipgateClient({ tokenId: config.tokenId, token: config.token });
@@ -15,6 +17,29 @@ export async function main() {
     const server = createServer(backend, config.readonly, config.accessScope);
     await server.connect(new StdioServerTransport());
 }
+export async function runCli(args = process.argv.slice(2)) {
+    const command = args[0];
+    if (command === "setup") {
+        if (args[1] === "--help" || args[1] === "-h") {
+            process.stdout.write(SETUP_HELP);
+            return;
+        }
+        runSetup(args.slice(1));
+        return;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(SETUP_HELP);
+        return;
+    }
+    if (command === "--version" || command === "-V" || command === "version") {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    if (command) {
+        throw new SetupError(`Unknown command: ${command}`);
+    }
+    await main();
+}
 export function isMainModule(moduleUrl, entrypoint) {
     if (!entrypoint) {
         return false;
@@ -27,9 +52,11 @@ export function isMainModule(moduleUrl, entrypoint) {
     }
 }
 if (isMainModule(import.meta.url, process.argv[1])) {
-    main().catch((error) => {
-        const detail = error instanceof AccessPolicyError ? ` ${error.message}` : "";
-        console.error(`sipgate-mcp failed to start.${detail} Check the required environment variables and MCP client configuration.`);
+    runCli().catch((error) => {
+        const detail = error instanceof AccessPolicyError || error instanceof SetupError
+            ? ` ${error.message}`
+            : "";
+        console.error(`sipgate-mcp failed.${detail} Check credentials and MCP client configuration.`);
         process.exitCode = 1;
     });
 }
@@ -37,5 +64,8 @@ export { SipgateBackend } from "./backend/sipgate-backend.js";
 export { AccessPolicyError, createAccessControlledBackend, } from "./backend/access-controlled-backend.js";
 export { SipgateApiError, SipgateClient } from "./backend/sipgate-client.js";
 export { createServer } from "./server.js";
+export { loadStoredCredentials, storeCredentialsInteractively, } from "./credentials.js";
+export { buildRegistrationCommand, parseSetupArgs, runSetup } from "./setup.js";
 export { createToolDefinitions } from "./tools/definitions.js";
+export { VERSION } from "./version.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACnF,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,6BAA6B,CAAC,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACxF,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1E,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,UAA8B;IAC5E,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,KAAK,YAAY,CAAC,UAAU,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,YAAY,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,KAAK,YAAY,iBAAiB,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,+BAA+B,MAAM,yEAAyE,CAAC,CAAC;QAC9H,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,6BAA6B,GAC9B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAM7E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/setup.d.ts

@@ -0,0 +1,20 @@
+import { type SipgateCredentials } from "./credentials.js";
+export type SetupClient = "codex" | "claude";
+export interface SetupOptions {
+    allowWrites: boolean;
+    clients: SetupClient[];
+    dryRun: boolean;
+    replaceCredentials: boolean;
+}
+export interface ClientCommand {
+    command: string;
+    args: string[];
+}
+export declare class SetupError extends Error {
+}
+export declare function parseSetupArgs(args: string[]): SetupOptions;
+export declare function buildRegistrationCommand(client: SetupClient, nodeExecutable: string, entrypoint: string, allowWrites: boolean): ClientCommand;
+export declare function ensureStoredCredentials(replaceCredentials: boolean, loadCredentials?: () => SipgateCredentials | undefined, storeCredentials?: () => void, output?: Pick<NodeJS.WriteStream, "write">): void;
+export declare function runSetup(args: string[], entrypointArgument?: string | undefined): void;
+export declare const SETUP_HELP = "Usage:\n  sipgate-mcp                    Start the MCP stdio server\n  sipgate-mcp setup [options]    Store credentials and register MCP clients\n  sipgate-mcp --version          Print the installed version\n\nSetup options:\n  --client codex|claude          Register only this client (repeatable)\n  --allow-writes                 Register write tools; default is read-only\n  --replace-credentials          Replace an existing PAT-ID and PAT in Keychain\n  --dry-run                      Print registration commands without changing anything\n";
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAwC3D;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GACnB,aAAa,CA4Cf;AAED,wBAAgB,uBAAuB,CACrC,kBAAkB,EAAE,OAAO,EAC3B,eAAe,GAAE,MAAM,kBAAkB,GAAG,SAAiC,EAC7E,gBAAgB,GAAE,MAAM,IAAoC,EAC5D,MAAM,GAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAkB,GACzD,IAAI,CAQN;AAoBD,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EAAE,EACd,kBAAkB,GAAE,MAAM,GAAG,SAA2B,GACvD,IAAI,CA+DN;AAED,eAAO,MAAM,UAAU,siBAUtB,CAAC"}

package/dist/setup.js

@@ -0,0 +1,167 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { loadStoredCredentials, storeCredentialsInteractively, } from "./credentials.js";
+export class SetupError extends Error {
+}
+export function parseSetupArgs(args) {
+    const clients = [];
+    let allowWrites = false;
+    let dryRun = false;
+    let replaceCredentials = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--allow-writes") {
+            allowWrites = true;
+            continue;
+        }
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (argument === "--replace-credentials") {
+            replaceCredentials = true;
+            continue;
+        }
+        if (argument === "--client") {
+            const client = args[index + 1];
+            if (client !== "codex" && client !== "claude") {
+                throw new SetupError("--client must be either 'codex' or 'claude'.");
+            }
+            if (!clients.includes(client)) {
+                clients.push(client);
+            }
+            index += 1;
+            continue;
+        }
+        throw new SetupError(`Unknown setup option: ${argument ?? ""}`);
+    }
+    return {
+        allowWrites,
+        clients: clients.length > 0 ? clients : ["codex", "claude"],
+        dryRun,
+        replaceCredentials,
+    };
+}
+export function buildRegistrationCommand(client, nodeExecutable, entrypoint, allowWrites) {
+    const modeEnvironment = [
+        "SIPGATE_MCP_SCOPE=user",
+        `SIPGATE_MCP_READONLY=${allowWrites ? "0" : "1"}`,
+    ];
+    if (client === "codex") {
+        return {
+            command: "codex",
+            args: [
+                "mcp",
+                "add",
+                "sipgate",
+                "--env",
+                modeEnvironment[0],
+                "--env",
+                modeEnvironment[1],
+                "--",
+                nodeExecutable,
+                entrypoint,
+            ],
+        };
+    }
+    const configuration = {
+        type: "stdio",
+        command: nodeExecutable,
+        args: [entrypoint],
+        env: {
+            SIPGATE_MCP_SCOPE: "user",
+            SIPGATE_MCP_READONLY: allowWrites ? "0" : "1",
+        },
+    };
+    return {
+        command: "claude",
+        args: [
+            "mcp",
+            "add-json",
+            "--scope",
+            "user",
+            "sipgate",
+            JSON.stringify(configuration),
+        ],
+    };
+}
+export function ensureStoredCredentials(replaceCredentials, loadCredentials = loadStoredCredentials, storeCredentials = storeCredentialsInteractively, output = process.stderr) {
+    if (!replaceCredentials && loadCredentials()) {
+        output.write("Using the existing sipgate PAT-ID and PAT from macOS Keychain.\n");
+        return;
+    }
+    storeCredentials();
+}
+function isCommandAvailable(command) {
+    const result = spawnSync(command, ["--version"], { stdio: "ignore" });
+    return !result.error && result.status === 0;
+}
+function isAlreadyConfigured(client) {
+    const result = spawnSync(client, ["mcp", "get", "sipgate"], {
+        stdio: "ignore",
+    });
+    return !result.error && result.status === 0;
+}
+function shellDisplay(command) {
+    return [command.command, ...command.args]
+        .map((part) => (/^[A-Za-z0-9_./:=+-]+$/.test(part) ? part : JSON.stringify(part)))
+        .join(" ");
+}
+export function runSetup(args, entrypointArgument = process.argv[1]) {
+    const options = parseSetupArgs(args);
+    if (!entrypointArgument) {
+        throw new SetupError("Could not determine the sipgate-mcp entrypoint.");
+    }
+    const entrypoint = resolve(entrypointArgument);
+    const commands = options.clients.map((client) => ({
+        client,
+        registration: buildRegistrationCommand(client, process.execPath, entrypoint, options.allowWrites),
+    }));
+    if (options.dryRun) {
+        process.stdout.write("Dry run: no credentials or MCP configurations were changed.\n");
+        for (const { registration } of commands) {
+            process.stdout.write(`${shellDisplay(registration)}\n`);
+        }
+        return;
+    }
+    process.stderr.write("sipgate-mcp stores the PAT-ID and PAT in macOS Keychain. Secret values are not written to MCP configuration or shell history.\n");
+    try {
+        ensureStoredCredentials(options.replaceCredentials);
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.message
+            : "Secure credential storage failed.";
+        throw new SetupError(message);
+    }
+    for (const { client, registration } of commands) {
+        if (!isCommandAvailable(client)) {
+            process.stderr.write(`Skipping ${client}: command not found.\n`);
+            continue;
+        }
+        if (isAlreadyConfigured(client)) {
+            process.stderr.write(`Skipping ${client}: an MCP server named 'sipgate' is already configured. Remove it first to replace its launch command.\n`);
+            continue;
+        }
+        const result = spawnSync(registration.command, registration.args, {
+            stdio: "inherit",
+        });
+        if (result.error || result.status !== 0) {
+            throw new SetupError(`Could not register sipgate-mcp with ${client}.`);
+        }
+        process.stderr.write(`Registered sipgate-mcp with ${client} in user scope (${options.allowWrites ? "writes enabled" : "read-only"}).\n`);
+    }
+    process.stderr.write("Setup complete. Restart Codex or Claude, open /mcp, and ask it to list your sipgate numbers.\n");
+}
+export const SETUP_HELP = `Usage:
+  sipgate-mcp                    Start the MCP stdio server
+  sipgate-mcp setup [options]    Store credentials and register MCP clients
+  sipgate-mcp --version          Print the installed version
+
+Setup options:
+  --client codex|claude          Register only this client (repeatable)
+  --allow-writes                 Register write tools; default is read-only
+  --replace-credentials          Replace an existing PAT-ID and PAT in Keychain
+  --dry-run                      Print registration commands without changing anything
+`;
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.3.1";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.3.1";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sipgate-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A self-hosted MCP server for configuring sipgate accounts through the sipgate REST API v2",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "SKILL.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"