paybot-mcp 0.3.3 → 0.3.4

package/README.md

@@ -8,6 +8,25 @@ MCP server for [PayBot](https://paybotcore.com) — payment tools for AI agents
 npm install paybot-mcp paybot-sdk
 ```
 
+## Get your API key
+
+`PAYBOT_API_KEY` is required — without it every tool call fails with a 401. The fastest way to get a key is one `PayBotClient.signup()` call (from `paybot-sdk`) against the hosted facilitator at `https://api.paybotcore.com`:
+
+```bash
+node -e "import('paybot-sdk').then(async ({ PayBotClient }) => {
+  const a = await PayBotClient.signup('you@example.com', 'a-strong-password', { botId: 'my-agent' });
+  console.log(a.apiKey); // pb_live_... — printed ONLY once, save it now
+})"
+```
+
+This single call registers your operator account, creates the API key, **and registers the bot** (`botId`). Put the printed key into `PAYBOT_API_KEY` in the MCP config below, and reuse the same bot id as `PAYBOT_BOT_ID`.
+
+Notes:
+
+- The key is printed **only once** — store it securely; it cannot be retrieved later.
+- Because `signup()` already registered your bot, calling the `paybot_register` tool with the same bot id returns `409 ALREADY_EXISTS`. Use `paybot_register` only for **additional** bots.
+- Full auth flow (login, extra API keys, self-hosted facilitators): see the [paybot-sdk README → Get your API key](https://github.com/RBKunnela/paybot-sdk#get-your-api-key).
+
 ## Usage with Claude Desktop
 
 Add to `claude_desktop_config.json`:
@@ -49,11 +68,13 @@ Add to `claude_desktop_config.json`:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `PAYBOT_API_KEY` | PayBot API key | (required) |
+| `PAYBOT_API_KEY` | PayBot API key (see [Get your API key](#get-your-api-key)) | (required) |
 | `PAYBOT_FACILITATOR_URL` | Facilitator server URL | `https://api.paybotcore.com` |
 | `PAYBOT_BOT_ID` | Default bot identifier | `mcp-agent` |
 | `PAYBOT_WALLET_KEY` | Wallet private key for real payments | (optional) |
 
+If `PAYBOT_API_KEY` is unset or empty, the server still boots (so the MCP handshake succeeds) but prints a warning to stderr at startup, and every tool call will fail with an authentication error until a key is configured. Omitting `PAYBOT_WALLET_KEY` keeps the underlying SDK in mock mode (no on-chain settlement).
+
 ## Available Tools
 
 | Tool | Description |

package/dist/config-warnings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module config-warnings
+ *
+ * Startup configuration warnings for the PayBot MCP server.
+ *
+ * The server intentionally boots with zero environment variables (MCP stdio
+ * servers must complete the protocol handshake even when misconfigured), which
+ * means a missing API key only surfaces as a 401 at the FIRST tool call. This
+ * module makes that failure visible at boot instead, by emitting a one-line
+ * warning to stderr — stdout is reserved for the MCP protocol stream.
+ *
+ * Dependencies: none (pure function over an env snapshot)
+ * Used by: src/index.ts (stdio entry point, before transport connect)
+ */
+/**
+ * Warn once at boot when no usable PayBot API key is configured.
+ *
+ * Mirrors the env resolution used by `getClient()` in server.ts — the
+ * effective key is `PAYBOT_API_KEY ?? API_KEY` — so the warning fires exactly
+ * when a later tool call would fail with an authentication error. It never
+ * throws and never exits: booting must always succeed so the MCP client can
+ * connect and read tool descriptions.
+ *
+ * @param env - Environment snapshot to inspect (defaults to `process.env`).
+ * @param warn - Sink for the warning line (defaults to `console.error`, i.e.
+ *   stderr — never stdout, which carries MCP protocol frames).
+ * @returns `true` when a warning was emitted, `false` when a key is present.
+ *
+ * @example
+ * warnIfApiKeyMissing();
+ * // stderr: [paybot-mcp] PAYBOT_API_KEY is not set — tool calls will fail with 401. ...
+ */
+export declare function warnIfApiKeyMissing(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): boolean;
+//# sourceMappingURL=config-warnings.d.ts.map

package/dist/config-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-warnings.d.ts","sourceRoot":"","sources":["../src/config-warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAoB,GAC9C,OAAO,CAaT"}

package/dist/config-warnings.js

@@ -0,0 +1,45 @@
+/**
+ * @module config-warnings
+ *
+ * Startup configuration warnings for the PayBot MCP server.
+ *
+ * The server intentionally boots with zero environment variables (MCP stdio
+ * servers must complete the protocol handshake even when misconfigured), which
+ * means a missing API key only surfaces as a 401 at the FIRST tool call. This
+ * module makes that failure visible at boot instead, by emitting a one-line
+ * warning to stderr — stdout is reserved for the MCP protocol stream.
+ *
+ * Dependencies: none (pure function over an env snapshot)
+ * Used by: src/index.ts (stdio entry point, before transport connect)
+ */
+/**
+ * Warn once at boot when no usable PayBot API key is configured.
+ *
+ * Mirrors the env resolution used by `getClient()` in server.ts — the
+ * effective key is `PAYBOT_API_KEY ?? API_KEY` — so the warning fires exactly
+ * when a later tool call would fail with an authentication error. It never
+ * throws and never exits: booting must always succeed so the MCP client can
+ * connect and read tool descriptions.
+ *
+ * @param env - Environment snapshot to inspect (defaults to `process.env`).
+ * @param warn - Sink for the warning line (defaults to `console.error`, i.e.
+ *   stderr — never stdout, which carries MCP protocol frames).
+ * @returns `true` when a warning was emitted, `false` when a key is present.
+ *
+ * @example
+ * warnIfApiKeyMissing();
+ * // stderr: [paybot-mcp] PAYBOT_API_KEY is not set — tool calls will fail with 401. ...
+ */
+export function warnIfApiKeyMissing(env = process.env, warn = console.error) {
+    // Same precedence as server.ts getClient(): an empty PAYBOT_API_KEY does
+    // NOT fall through to API_KEY (`??` only skips undefined/null), so an
+    // empty string here is a real misconfiguration worth warning about.
+    const apiKey = env.PAYBOT_API_KEY ?? env.API_KEY;
+    if (apiKey === undefined || apiKey.trim() === '') {
+        warn('[paybot-mcp] PAYBOT_API_KEY is not set — tool calls will fail with 401. ' +
+            'See README → Get your API key.');
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=config-warnings.js.map

package/dist/config-warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-warnings.js","sourceRoot":"","sources":["../src/config-warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAyB,OAAO,CAAC,GAAG,EACpC,OAAkC,OAAO,CAAC,KAAK;IAE/C,yEAAyE;IACzE,sEAAsE;IACtE,oEAAoE;IACpE,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,OAAO,CAAC;IACjD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,IAAI,CACF,0EAA0E;YACxE,gCAAgC,CACnC,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.js

@@ -22,6 +22,11 @@
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMcpServer } from './server.js';
+import { warnIfApiKeyMissing } from './config-warnings.js';
+// Surface a missing API key at boot (stderr) instead of at the first tool
+// call. Warn-only by design: the server must still boot so the MCP handshake
+// succeeds and the client can read tool descriptions.
+warnIfApiKeyMissing();
 const server = createMcpServer();
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,0EAA0E;AAC1E,6EAA6E;AAC7E,sDAAsD;AACtD,mBAAmB,EAAE,CAAC;AAEtB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;AACjC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybot-mcp",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "PayBot MCP Server - Payment tools for AI agents via Model Context Protocol",
   "type": "module",
   "main": "dist/index.js",