@pilot-status/mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -2,24 +2,22 @@
 
 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.
+client (Claude Desktop, Cursor, the claude.ai connector, 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.
+- **streamable HTTP** — 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)).
 
 ## Install
 
 ```bash
-# Run straight from npm (no clone/build):
+# Run straight from npm (no install needed):
 npx @pilot-status/mcp-server stdio      # stdio transport (default)
 npx @pilot-status/mcp-server http       # streamable HTTP transport
 
@@ -42,8 +40,8 @@ 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).
+   (HTTP transport). claude.ai handles the login, so no API key is shared with
+   the client. See [Remote (OAuth)](#remote-oauth--claudeai-connector).
 
 Scope matters (same rules as the REST API):
 
@@ -55,9 +53,9 @@ Scope matters (same rules as the REST API):
   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.
+accept an optional `whatsappNumberId` argument 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.
@@ -103,39 +101,24 @@ See [`.env.example`](./.env.example). Key variables:
 | `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`). |
+| `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
+## HTTP endpoint
 
-```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
+When running the HTTP transport, the server exposes:
 
 - `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 \
+curl -s https://mcp.pilotstatuss.com/mcp \
   -H "content-type: application/json" \
   -H "accept: application/json, text/event-stream" \
   -H "x-api-key: ps_xxx" \
@@ -146,8 +129,8 @@ curl -s http://localhost:8787/mcp \
 
 ### Claude Desktop / Cursor (stdio)
 
-Use the published binary via `npx` (recommended) — add to the client's MCP
-config (e.g. `claude_desktop_config.json`):
+Use the published binary via `npx` — add to the client's MCP config (e.g.
+`claude_desktop_config.json`):
 
 ```json
 {
@@ -164,12 +147,9 @@ config (e.g. `claude_desktop_config.json`):
 }
 ```
 
-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:
+Point the client at the hosted URL and supply the API key as a header:
 
 ```json
 {
@@ -185,46 +165,19 @@ Point the client at the deployed URL and supply the API key as a header:
 
 ### 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
+For the [claude.ai](https://claude.ai) **Custom Connector**, point claude.ai at
+the hosted HTTPS URL and let it run the OAuth login — no API key is shared with
+the client.
 
-```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.
+1. In claude.ai → **Settings → Connectors → Add custom connector**, set the URL
+   to `https://mcp.pilotstatuss.com/mcp`.
+2. claude.ai fetches `GET /.well-known/oauth-protected-resource`, discovers the
+   authorization server, and runs the OAuth 2.1 login (Pilot Status SSO). The
+   resulting access token is sent on every `POST /mcp` as
+   `Authorization: Bearer <token>`.
+
+If you run your own instance, serve the HTTP transport at a public HTTPS URL and
+set `MCP_RESOURCE_URL` to that URL and `PILOT_STATUS_AUTH_SERVER_URL` to the
+Pilot Status backend (`https://pilotstatuss.com`). Leave `PILOT_STATUS_API_KEY`
+unset so unauthenticated requests return the `401` challenge that starts the
+OAuth flow.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pilot-status/mcp-server",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "type": "module",
     "description": "Model Context Protocol (MCP) server exposing the Pilot Status public /v1 API as tools. Supports stdio and streamable HTTP transports (with OAuth 2.1 for the claude.ai custom connector).",
     "license": "MIT",