@pilot-status/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pilot Status
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# @pilot-status/mcp-server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
+exposes the **Pilot Status public `/v1` API** as MCP tools, so any MCP-capable
+client (Claude Desktop, Cursor, custom agents, …) can send WhatsApp messages,
+manage numbers/templates, read conversations, and more — using a Pilot Status
+API key.
+
+It speaks two transports:
+
+- **stdio** — for local clients that spawn the server as a child process. The
+  API key is read once from `PILOT_STATUS_API_KEY`.
+- **streamable HTTP** — deployable; clients connect over HTTP and authenticate
+  either with an `x-api-key` header **or** with an OAuth 2.1 bearer token (for
+  the [claude.ai custom connector](#remote-oauth--claudeai-connector)). Runs
+  stateless (a fresh MCP session per request), so it scales horizontally behind
+  a load balancer.
+
+## Install
+
+```bash
+# Run straight from npm (no clone/build):
+npx @pilot-status/mcp-server stdio      # stdio transport (default)
+npx @pilot-status/mcp-server http       # streamable HTTP transport
+
+# Or install the binary globally:
+npm install -g @pilot-status/mcp-server
+pilot-status-mcp stdio
+```
+
+The published package exposes the `pilot-status-mcp` bin. Configuration is via
+environment variables (see [`.env.example`](./.env.example) / [Configuration](#configuration)):
+
+```bash
+PILOT_STATUS_API_KEY=ps_xxx npx @pilot-status/mcp-server stdio
+```
+
+## Authentication
+
+There are two ways to authenticate against the public `/v1` API:
+
+1. **API key** (`x-api-key`) — a `ps_*` key, used by stdio and by HTTP clients
+   that send the header themselves.
+2. **OAuth 2.1 bearer token** — used by the claude.ai custom connector
+   (HTTP transport). The token is forwarded verbatim to `/v1`; this server does
+   not verify it. See [Remote (OAuth)](#remote-oauth--claudeai-connector).
+
+Scope matters (same rules as the REST API):
+
+- **Number-scoped key** → per-number action/data tools: `messages_*`,
+  `conversations_list`, `groups_list`, `newsletters_list`, `templates_*`,
+  `analytics_dashboard`, `api_keys_*`, `numbers_*`.
+- **Tenant-scoped key** → tenant-wide tools: `branding_*`,
+  `subscription_extra_numbers_*`. (Number-scoped keys get HTTP 403 on these,
+  surfaced as a tool error.)
+
+Under an OAuth/tenant token there is no number scope, so number-scoped tools
+accept an optional `whatsappNumberId` argument. It is sent as the
+`x-whatsapp-number-id` header so the backend can resolve the target number; it
+is ignored when the API key is already scoped to a single number.
+
+Token-based pairing/connect routes (interactive browser flows) are intentionally
+**not** exposed as tools.
+
+## Tools
+
+| Tool | Endpoint |
+| --- | --- |
+| `messages_send` | `POST /v1/messages/send` |
+| `message_get` | `GET /v1/messages/{id}` |
+| `messages_cancel` | `DELETE /v1/messages/cancel` |
+| `messages_group` | `GET /v1/messages/group` |
+| `messages_unread` | `GET /v1/messages/unread` |
+| `conversations_list` | `GET /v1/conversations` |
+| `groups_list` | `GET /v1/groups` |
+| `newsletters_list` | `GET /v1/newsletters` |
+| `numbers_list` | `GET /v1/numbers` |
+| `numbers_create` | `POST /v1/numbers` |
+| `numbers_delete` | `DELETE /v1/numbers/{id}` |
+| `numbers_status` | `GET /v1/numbers/{id}/status` |
+| `templates_list` | `GET /v1/templates` |
+| `templates_create` | `POST /v1/templates` |
+| `templates_get` | `GET /v1/templates/{id}` |
+| `templates_update` | `PUT /v1/templates/{id}` |
+| `branding_get` | `GET /v1/branding` |
+| `branding_upsert` | `PUT /v1/branding` |
+| `analytics_dashboard` | `GET /v1/analytics/dashboard` |
+| `api_keys_list` | `GET /v1/api-keys` |
+| `api_keys_create` | `POST /v1/api-keys` |
+| `subscription_extra_numbers_get` | `GET /v1/subscription/extra-numbers` |
+| `subscription_extra_numbers_add` | `POST /v1/subscription/extra-numbers` |
+
+> Privacy: when a number's privacy mode is `RELAY_ONLY`, the read tools
+> (`messages_group`, `messages_unread`, `conversations_list`) return empty
+> results; `STORE_X_DAYS` limits results to the retention window.
+
+## Configuration
+
+See [`.env.example`](./.env.example). Key variables:
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `PILOT_STATUS_API_URL` | `https://pilotstatuss.com` | Public API base URL (no trailing slash). |
+| `PILOT_STATUS_API_KEY` | — | `ps_*` key. Required for stdio; optional fallback for HTTP. |
+| `PILOT_STATUS_API_KEY_ID` | — | Optional `x-api-key-id` companion. |
+| `MCP_RESOURCE_URL` | `https://mcp.pilotstatuss.com` | Public URL of THIS server (OAuth `resource`). |
+| `PILOT_STATUS_AUTH_SERVER_URL` | `https://pilotstatuss.com` | OAuth authorization server (the backend). |
+| `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. |
+| `PORT` | `8787` | HTTP transport port. |
+| `HOST` | `0.0.0.0` | HTTP transport bind host. |
+
+## Running
+
+```bash
+npm install            # from the repo root (workspaces)
+npm --workspace @pilot-status/mcp-server run build
+
+# stdio (default)
+PILOT_STATUS_API_KEY=ps_xxx node apps/mcp-server/dist/index.js
+
+# streamable HTTP
+MCP_TRANSPORT=http PORT=8787 node apps/mcp-server/dist/index.js
+# or:  node apps/mcp-server/dist/index.js http
+```
+
+Dev mode (no build): `npm --workspace @pilot-status/mcp-server run dev`.
+
+### HTTP endpoint
+
+- `POST /mcp` — JSON-RPC over Streamable HTTP. Authenticate with `x-api-key:
+  ps_xxx` **or** `Authorization: Bearer <oauth-token>`. With no credentials it
+  replies `401` + `WWW-Authenticate`, which starts the OAuth flow.
+- `GET /.well-known/oauth-protected-resource` — OAuth 2.1 protected-resource
+  metadata (RFC 9728); points discovery at the authorization server.
+- `GET /health` — liveness probe.
+
+```bash
+curl -s http://localhost:8787/mcp \
+  -H "content-type: application/json" \
+  -H "accept: application/json, text/event-stream" \
+  -H "x-api-key: ps_xxx" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+## Configuring MCP clients
+
+### Claude Desktop / Cursor (stdio)
+
+Use the published binary via `npx` (recommended) — add to the client's MCP
+config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pilot-status": {
+      "command": "npx",
+      "args": ["-y", "@pilot-status/mcp-server", "stdio"],
+      "env": {
+        "PILOT_STATUS_API_KEY": "ps_your_key_here",
+        "PILOT_STATUS_API_URL": "https://pilotstatuss.com"
+      }
+    }
+  }
+}
+```
+
+Or point `command`/`args` at a local build
+(`node /absolute/path/to/apps/mcp-server/dist/index.js`).
+
+### Remote / HTTP clients (API key)
+
+Point the client at the deployed URL and supply the API key as a header:
+
+```json
+{
+  "mcpServers": {
+    "pilot-status": {
+      "type": "http",
+      "url": "https://mcp.pilotstatuss.com/mcp",
+      "headers": { "x-api-key": "ps_your_key_here" }
+    }
+  }
+}
+```
+
+### Remote (OAuth) — claude.ai connector
+
+For the [claude.ai](https://claude.ai) **Custom Connector**, deploy this server
+(HTTP transport) at a public HTTPS URL and let claude.ai run the OAuth login —
+no API key is shared with the client.
+
+1. Deploy with `MCP_TRANSPORT=http` and set:
+   - `MCP_RESOURCE_URL` — the public URL of this server, e.g.
+     `https://mcp.pilotstatuss.com`.
+   - `PILOT_STATUS_AUTH_SERVER_URL` — the Pilot Status backend, e.g.
+     `https://pilotstatuss.com` (the default).
+   - Leave `PILOT_STATUS_API_KEY` **unset** so unauthenticated requests return a
+     `401` challenge (otherwise the env key would short-circuit OAuth).
+2. In claude.ai → **Settings → Connectors → Add custom connector**, set the URL
+   to `https://mcp.pilotstatuss.com/mcp`.
+3. claude.ai fetches `GET /.well-known/oauth-protected-resource`, discovers the
+   authorization server (`PILOT_STATUS_AUTH_SERVER_URL`), and runs the OAuth
+   2.1 login (Pilot Status SSO). The resulting access token is sent on every
+   `POST /mcp` as `Authorization: Bearer <token>`.
+
+This server is a **dumb forwarder**: it does not verify the token. It forwards
+the bearer token to the public `/v1` API, which validates it. If `/v1` rejects
+the token (`401`), the response is relayed as `401` + `WWW-Authenticate` so the
+client re-authenticates. The authorization server itself (`/api/oauth/*` and
+`/.well-known/oauth-authorization-server`) lives in the Pilot Status backend.
+
+## Deployment
+
+`MCP_TRANSPORT=http` behind HTTPS at `MCP_RESOURCE_URL`. A container image +
+generator entry + Traefik host (`mcp.pilotstatuss.com`) and the backend
+authorization-server endpoints are tracked as follow-up tasks. The server is
+stateless, so it can run with multiple replicas behind the load balancer.
+
+## Tests
+
+```bash
+npm --workspace @pilot-status/mcp-server test
+```
+
+Covers the API client (header injection, bearer/OAuth mode, the
+`x-whatsapp-number-id` selector, query building, HTTP error mapping), the HTTP
+transport (protected-resource metadata, the unauthenticated `401` +
+`WWW-Authenticate` challenge, CORS) and tool registration (every public endpoint
+registered, argument dispatch, number-selector threading, error wrapping).
+`fetch` is mocked for the unit tests — no external network access required.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Pilot Status MCP server entrypoint.
+ *
+ * Selects a transport from CLI args / env (see {@link resolveConfig}):
+ *   - stdio (default): single-tenant; API key from PILOT_STATUS_API_KEY.
+ *   - http: deployable; API key per-request from the `x-api-key` header
+ *     (falls back to PILOT_STATUS_API_KEY if set).
+ *
+ * Usage:
+ *   pilot-status-mcp                # stdio
+ *   pilot-status-mcp http           # streamable HTTP on PORT (default 8787)
+ *   MCP_TRANSPORT=http PORT=8787 node dist/index.js
+ */
+import { resolveConfig } from "./lib/config.js";
+async function main() {
+    const config = resolveConfig();
+    if (config.transport === "http") {
+        const { startHttpServer } = await import("./lib/http-transport.js");
+        await startHttpServer(config);
+        return;
+    }
+    // stdio transport
+    if (!config.apiKey && !config.apiKeyId) {
+        console.error("[mcp] PILOT_STATUS_API_KEY is required for the stdio transport. " +
+            "Set it in the environment (or use the HTTP transport with per-request keys).");
+        process.exit(1);
+    }
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const { buildServer } = await import("./lib/server.js");
+    const server = buildServer({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+        apiKeyId: config.apiKeyId,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for the JSON-RPC protocol; log to stderr.
+    console.error(`[mcp] Pilot Status MCP server (stdio) connected → ${config.baseUrl}/v1`);
+}
+main().catch((err) => {
+    console.error("[mcp] fatal:", err instanceof Error ? err.stack ?? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,KAAK,UAAU,IAAI;IACf,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAE/B,IAAI,MAAM,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACpE,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;QAC9B,OAAO;IACX,CAAC;IAED,kBAAkB;IAClB,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrC,OAAO,CAAC,KAAK,CACT,kEAAkE;YAC9D,8EAA8E,CACrF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CACzC,2CAA2C,CAC9C,CAAC;IACF,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAExD,MAAM,MAAM,GAAG,WAAW,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC5B,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,+DAA+D;IAC/D,OAAO,CAAC,KAAK,CACT,qDAAqD,MAAM,CAAC,OAAO,KAAK,CAC3E,CAAC;AACN,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/lib/api-client.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Thin HTTP client for the Pilot Status public `/v1` API.
+ *
+ * - Targets `PILOT_STATUS_API_URL` (default https://pilotstatuss.com); every
+ *   public endpoint lives under the `/v1` prefix (the backend rewrites `/v1/*`
+ *   to its internal `/api/v1/*` routes).
+ * Authentication is one of two modes:
+ *   - **API key** — `x-api-key` (+ optional `x-api-key-id`) from a constructor
+ *     value (stdio mode) or a per-request override (HTTP `x-api-key` header).
+ *   - **Bearer** — an OAuth 2.1 access token, forwarded verbatim as
+ *     `Authorization: Bearer <token>` (and `x-api-key` is NOT sent). The public
+ *     `/v1` API validates the token; this client never inspects it.
+ *
+ * Optionally a WhatsApp number selector (`x-whatsapp-number-id`) is attached so
+ * the backend can resolve number-scope under a tenant-wide OAuth token.
+ *
+ * - Normalizes upstream errors (400/401/403/404/409/422/429/5xx) into a single
+ *   {@link ApiError} carrying status + machine `code` + details so MCP tools can
+ *   surface a clean message to the model.
+ */
+export interface ApiClientOptions {
+    /** Base URL without trailing slash (e.g. https://pilotstatuss.com). */
+    baseUrl: string;
+    /** Default `x-api-key` value (stdio). Optional in HTTP mode. */
+    apiKey?: string;
+    /** Optional `x-api-key-id` companion header. */
+    apiKeyId?: string;
+    /**
+     * OAuth 2.1 bearer token. When set it takes precedence over `apiKey`:
+     * the client sends `Authorization: Bearer <token>` and omits `x-api-key`.
+     */
+    bearer?: string;
+    /** Default WhatsApp number selector → `x-whatsapp-number-id` header. */
+    numberId?: string;
+    /** Fetch implementation (defaults to global fetch; overridable in tests). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Invoked when an upstream request made in *bearer* mode returns HTTP 401,
+     * so the HTTP transport can relay a `WWW-Authenticate` challenge and trigger
+     * the client to re-authenticate.
+     */
+    onBearerUnauthorized?: () => void;
+}
+export interface RequestOptions {
+    /** Query-string parameters (undefined/null entries are skipped). */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** JSON request body (serialized for non-GET requests). */
+    body?: unknown;
+    /** Per-request `x-api-key` override (HTTP transport). Wins over the default. */
+    apiKey?: string;
+    /** Per-request `x-api-key-id` override. */
+    apiKeyId?: string;
+    /** Per-request bearer token override. Wins over the default. */
+    bearer?: string;
+    /** Per-request WhatsApp number selector → `x-whatsapp-number-id` header. */
+    numberId?: string;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    /** Raw parsed response body (object or string), when available. */
+    readonly body?: unknown;
+    constructor(args: {
+        message: string;
+        status: number;
+        code?: string;
+        details?: unknown;
+        body?: unknown;
+    });
+    toJSON(): {
+        details?: {} | null | undefined;
+        code?: string | undefined;
+        error: string;
+        status: number;
+    };
+}
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly apiKeyId?;
+    private readonly bearer?;
+    private readonly numberId?;
+    private readonly onBearerUnauthorized?;
+    private readonly fetchImpl;
+    constructor(options: ApiClientOptions);
+    /**
+     * Return a shallow clone of this client that attaches the given WhatsApp
+     * number selector (`x-whatsapp-number-id`) to every request — so a single
+     * tool call can scope tenant-wide credentials (OAuth token or tenant key)
+     * to one number without mutating the shared client.
+     */
+    withNumber(numberId: string): ApiClient;
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/lib/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC3B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAgBD,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,IAAI,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,OAAO,CAAC;KAClB;IASD,MAAM;;;;;;CAQT;AAkBD,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,gBAAgB;IAiBrC;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS;IAYjC,OAAO,CAAC,CAAC,GAAG,OAAO,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,CAAC,CAAC;IAyFb,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;CAG9E"}

package/dist/lib/api-client.js

@@ -0,0 +1,204 @@
+/**
+ * Thin HTTP client for the Pilot Status public `/v1` API.
+ *
+ * - Targets `PILOT_STATUS_API_URL` (default https://pilotstatuss.com); every
+ *   public endpoint lives under the `/v1` prefix (the backend rewrites `/v1/*`
+ *   to its internal `/api/v1/*` routes).
+ * Authentication is one of two modes:
+ *   - **API key** — `x-api-key` (+ optional `x-api-key-id`) from a constructor
+ *     value (stdio mode) or a per-request override (HTTP `x-api-key` header).
+ *   - **Bearer** — an OAuth 2.1 access token, forwarded verbatim as
+ *     `Authorization: Bearer <token>` (and `x-api-key` is NOT sent). The public
+ *     `/v1` API validates the token; this client never inspects it.
+ *
+ * Optionally a WhatsApp number selector (`x-whatsapp-number-id`) is attached so
+ * the backend can resolve number-scope under a tenant-wide OAuth token.
+ *
+ * - Normalizes upstream errors (400/401/403/404/409/422/429/5xx) into a single
+ *   {@link ApiError} carrying status + machine `code` + details so MCP tools can
+ *   surface a clean message to the model.
+ */
+/** A friendly hint per HTTP status, prepended to the upstream error message. */
+const STATUS_HINTS = {
+    400: "Bad request",
+    401: "Unauthorized (check your API key)",
+    403: "Forbidden (wrong API key scope for this endpoint)",
+    404: "Not found",
+    409: "Conflict",
+    422: "Unprocessable (billing or validation)",
+    429: "Rate limited",
+    500: "Server error",
+    502: "Upstream provider error",
+    503: "Service unavailable",
+};
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    /** Raw parsed response body (object or string), when available. */
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = "ApiError";
+        this.status = args.status;
+        this.code = args.code;
+        this.details = args.details;
+        this.body = args.body;
+    }
+    toJSON() {
+        return {
+            error: this.message,
+            status: this.status,
+            ...(this.code ? { code: this.code } : {}),
+            ...(this.details !== undefined ? { details: this.details } : {}),
+        };
+    }
+}
+function buildUrl(baseUrl, path, query) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${baseUrl}${normalizedPath}`);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+export class ApiClient {
+    baseUrl;
+    apiKey;
+    apiKeyId;
+    bearer;
+    numberId;
+    onBearerUnauthorized;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.apiKeyId = options.apiKeyId;
+        this.bearer = options.bearer;
+        this.numberId = options.numberId;
+        this.onBearerUnauthorized = options.onBearerUnauthorized;
+        const f = options.fetchImpl ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new Error("No fetch implementation available. Use Node 18+ or pass fetchImpl.");
+        }
+        // Bind so `this` inside undici/native fetch stays correct.
+        this.fetchImpl = f.bind(globalThis);
+    }
+    /**
+     * Return a shallow clone of this client that attaches the given WhatsApp
+     * number selector (`x-whatsapp-number-id`) to every request — so a single
+     * tool call can scope tenant-wide credentials (OAuth token or tenant key)
+     * to one number without mutating the shared client.
+     */
+    withNumber(numberId) {
+        return new ApiClient({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            apiKeyId: this.apiKeyId,
+            bearer: this.bearer,
+            numberId,
+            fetchImpl: this.fetchImpl,
+            onBearerUnauthorized: this.onBearerUnauthorized,
+        });
+    }
+    async request(method, path, options = {}) {
+        const bearer = options.bearer ?? this.bearer;
+        const apiKey = options.apiKey ?? this.apiKey;
+        const apiKeyId = options.apiKeyId ?? this.apiKeyId;
+        const numberId = options.numberId ?? this.numberId;
+        const usingBearer = Boolean(bearer);
+        if (!usingBearer && !apiKey && !apiKeyId) {
+            throw new ApiError({
+                message: "Missing credentials. Provide an OAuth bearer token, set PILOT_STATUS_API_KEY (stdio), or send an x-api-key header (HTTP).",
+                status: 401,
+                code: "MISSING_API_KEY",
+            });
+        }
+        const headers = {
+            accept: "application/json",
+            "user-agent": "pilot-status-mcp-server",
+        };
+        if (usingBearer) {
+            // Bearer mode: forward the OAuth token verbatim; never send x-api-key.
+            headers["authorization"] = `Bearer ${bearer}`;
+        }
+        else {
+            if (apiKey)
+                headers["x-api-key"] = apiKey;
+            if (apiKeyId)
+                headers["x-api-key-id"] = apiKeyId;
+        }
+        if (numberId)
+            headers["x-whatsapp-number-id"] = numberId;
+        const hasBody = options.body !== undefined && method.toUpperCase() !== "GET";
+        if (hasBody)
+            headers["content-type"] = "application/json";
+        const url = buildUrl(this.baseUrl, path, options.query);
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: hasBody ? JSON.stringify(options.body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new ApiError({
+                message: `Network error calling ${method} ${path}: ${err instanceof Error ? err.message : String(err)}`,
+                status: 0,
+                code: "NETWORK_ERROR",
+            });
+        }
+        const text = await res.text();
+        let parsed = undefined;
+        if (text.length) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            const bodyObj = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : undefined;
+            const upstreamMessage = (typeof bodyObj?.error === "string" && bodyObj.error) ||
+                (typeof bodyObj?.message === "string" && bodyObj.message) ||
+                (typeof parsed === "string" && parsed) ||
+                res.statusText ||
+                "Request failed";
+            // In bearer mode, surface an upstream 401 so the HTTP transport can
+            // emit a WWW-Authenticate challenge and the client can re-auth.
+            if (usingBearer && res.status === 401) {
+                this.onBearerUnauthorized?.();
+            }
+            const hint = STATUS_HINTS[res.status] ?? `HTTP ${res.status}`;
+            throw new ApiError({
+                message: `${hint}: ${upstreamMessage}`,
+                status: res.status,
+                code: typeof bodyObj?.code === "string" ? bodyObj.code : undefined,
+                details: bodyObj?.details,
+                body: parsed,
+            });
+        }
+        return parsed;
+    }
+    get(path, options = {}) {
+        return this.request("GET", path, options);
+    }
+    post(path, options = {}) {
+        return this.request("POST", path, options);
+    }
+    put(path, options = {}) {
+        return this.request("PUT", path, options);
+    }
+    delete(path, options = {}) {
+        return this.request("DELETE", path, options);
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/lib/api-client.js.map

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