mercury402-mcp 0.1.2 → 0.1.3

package/dist/client.js

@@ -17,6 +17,15 @@ const HOW_TO_PAY = [
     'Sign an EIP-3009 transferWithAuthorization for the quoted amount to pay_to, base64-encode an x402 PaymentPayload, and resend the same request with a PAYMENT-SIGNATURE header. Any x402-compatible client/wallet can do this.',
     'Or enable paid mode in this MCP server: set MERCURY402_PAYER_PRIVATE_KEY to a funded Base hot wallet (and optionally MERCURY402_MAX_PRICE_USD), then call get_endpoint_data again.',
 ];
+// A hosted (publicly exposed) server refuses to boot with a payer key, and a remote caller
+// cannot set its env vars, so it must not suggest enabling paid mode on itself.
+export const HOSTED_HOW_TO_PAY = [
+    HOW_TO_PAY[0],
+    HOW_TO_PAY[1],
+    'To pay automatically, run mercury402-mcp locally (npx -y mercury402-mcp) with MERCURY402_PAYER_PRIVATE_KEY set to a funded Base hot wallet you control.',
+];
+export const LOCAL_NO_PAYER_REASON = 'Payment required. Paid mode is disabled (MERCURY402_PAYER_PRIVATE_KEY not set).';
+export const HOSTED_NO_PAYER_REASON = 'Payment required. This hosted endpoint is discovery-only and never pays on your behalf.';
 async function readBody(res) {
     const text = await res.text();
     if (!text)
@@ -63,7 +72,7 @@ export class MercuryClient {
             reason,
             quote: payable ? toQuote(payable) : options[0],
             all_options: options,
-            how_to_pay: HOW_TO_PAY,
+            how_to_pay: this.opts.hosted ? HOSTED_HOW_TO_PAY : HOW_TO_PAY,
             raw_body: body,
         };
     }
@@ -84,7 +93,7 @@ export class MercuryClient {
         const reqs = parsePaymentRequired(first.headers, firstBody);
         const payer = this.opts.payer;
         if (!payer) {
-            return this.paymentRequired(url, 'Payment required. Paid mode is disabled (MERCURY402_PAYER_PRIVATE_KEY not set).', reqs, firstBody);
+            return this.paymentRequired(url, this.opts.hosted ? HOSTED_NO_PAYER_REASON : LOCAL_NO_PAYER_REASON, reqs, firstBody);
         }
         if (!pay) {
             return this.paymentRequired(url, 'Payment required. Not paying because pay=false was requested.', reqs, firstBody);

package/dist/http.js

@@ -28,6 +28,35 @@ export function hostnameOf(hostHeader) {
     }
     return h.split(':')[0];
 }
+/**
+ * The first setting that makes the HTTP server publicly reachable, or undefined when it is
+ * loopback-only. Single source of truth for "public exposure": the paid-mode boot guard
+ * refuses to start on it, and the caller-facing payment text switches to hosted wording.
+ */
+export function publicExposure(config) {
+    if (!LOOPBACK_BINDS.has(config.httpHost))
+        return { kind: 'bind', host: config.httpHost };
+    const publicHost = config.httpAllowedHosts.map(hostnameOf).find((h) => !LOOPBACK_HOSTNAMES.includes(h));
+    if (publicHost)
+        return { kind: 'allowed_host', host: publicHost };
+    if (config.httpTrustProxy)
+        return { kind: 'trust_proxy' };
+    if (config.publicUrl)
+        return { kind: 'public_url' };
+    return undefined;
+}
+function paidModeRefusal(exposure) {
+    switch (exposure.kind) {
+        case 'bind':
+            return 'Refusing to serve paid mode over HTTP on a non-loopback host (MCP_HTTP_HOST). Use stdio or 127.0.0.1.';
+        case 'allowed_host':
+            return `Refusing to serve paid mode with a public MCP_HTTP_ALLOWED_HOSTS entry (${exposure.host}): anyone who can reach it could spend the payer wallet.`;
+        case 'trust_proxy':
+            return 'Refusing to serve paid mode with MCP_HTTP_TRUST_PROXY: a proxy in front of the server means others can reach it.';
+        case 'public_url':
+            return 'Refusing to serve paid mode with MCP_PUBLIC_URL set: a public endpoint must run in free mode.';
+    }
+}
 /**
  * Paid mode signs payments from a hot wallet, and HTTP has no auth: anyone who can
  * reach the endpoint could spend it. So paid mode is allowed only on a loopback bind
@@ -36,19 +65,9 @@ export function hostnameOf(hostHeader) {
 export function assertSafeHttpConfig(config, paid = !!config.payerPrivateKey) {
     if (!paid)
         return;
-    if (!LOOPBACK_BINDS.has(config.httpHost)) {
-        throw new Error('Refusing to serve paid mode over HTTP on a non-loopback host (MCP_HTTP_HOST). Use stdio or 127.0.0.1.');
-    }
-    const publicHost = config.httpAllowedHosts.map(hostnameOf).find((h) => !LOOPBACK_HOSTNAMES.includes(h));
-    if (publicHost) {
-        throw new Error(`Refusing to serve paid mode with a public MCP_HTTP_ALLOWED_HOSTS entry (${publicHost}): anyone who can reach it could spend the payer wallet.`);
-    }
-    if (config.httpTrustProxy) {
-        throw new Error('Refusing to serve paid mode with MCP_HTTP_TRUST_PROXY: a proxy in front of the server means others can reach it.');
-    }
-    if (config.publicUrl) {
-        throw new Error('Refusing to serve paid mode with MCP_PUBLIC_URL set: a public endpoint must run in free mode.');
-    }
+    const exposure = publicExposure(config);
+    if (exposure)
+        throw new Error(paidModeRefusal(exposure));
 }
 /** Fixed-window counter per key. take() returns 0 when allowed, else seconds until the window resets. */
 export class FixedWindowLimiter {
@@ -128,6 +147,8 @@ export function createHttpServer(config, options = {}) {
     const deps = options.deps ?? {};
     const paid = !!(deps.payer ?? config.payerPrivateKey);
     assertSafeHttpConfig(config, paid);
+    // Same predicate as the boot guard: a publicly reachable server tells callers it never pays.
+    const hosted = publicExposure(config) !== undefined;
     const log = options.log ?? (() => { });
     const allowedHosts = new Set([...LOOPBACK_HOSTNAMES, ...config.httpAllowedHosts.map(hostnameOf)]);
     const perIp = new FixedWindowLimiter(config.httpRateLimitPerMin, 60_000, options.now);
@@ -167,7 +188,7 @@ export function createHttpServer(config, options = {}) {
             return send(res, 400, rpcError(-32700, 'Parse error'));
         }
         stats.mcp_requests++;
-        const server = createMercuryServer(config, deps);
+        const server = createMercuryServer(config, deps, { hosted });
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
         res.on('close', () => {
             void transport.close();

package/dist/server.js

@@ -4,7 +4,17 @@ import { CATALOG, resolveRequest } from './catalog.js';
 import { MercuryClient } from './client.js';
 import { createEvmPayer } from './payment.js';
 export const SERVER_NAME = 'mercury402';
-export const SERVER_VERSION = '0.1.2';
+export const SERVER_VERSION = '0.1.3';
+const GET_ENDPOINT_DATA_USAGE = 'Use list_endpoints first to find paths and parameters. Path params can be inline ("/v1/fred/UNRATE") or passed in params ' +
+    '("/v1/fred/{series_id}" + {"series_id":"UNRATE"}). Other params go to the query string (GET) or JSON body (POST).';
+export const LOCAL_GET_ENDPOINT_DATA_DESCRIPTION = 'Call a Mercury402 endpoint on the live API. Without paid mode, endpoints return HTTP 402 and this tool returns ' +
+    'the price and x402 payment instructions instead of data. With paid mode enabled (MERCURY402_PAYER_PRIVATE_KEY), ' +
+    'it pays in USDC on Base (capped by MERCURY402_MAX_PRICE_USD) and returns the data. ' +
+    GET_ENDPOINT_DATA_USAGE;
+export const HOSTED_GET_ENDPOINT_DATA_DESCRIPTION = 'Call a Mercury402 endpoint on the live API. This hosted endpoint is discovery-only: endpoints return HTTP 402 and this ' +
+    'tool returns the price and x402 payment instructions instead of data. Pay with your own x402 client, or run ' +
+    'mercury402-mcp locally (npx -y mercury402-mcp) with your own wallet. ' +
+    GET_ENDPOINT_DATA_USAGE;
 function json(value) {
     return JSON.stringify(value, null, 2);
 }
@@ -26,7 +36,7 @@ function formatCallResult(result) {
             return textResult(`ERROR (HTTP ${result.http_status}) ${result.url}\n\n${json(result)}`, true);
     }
 }
-export function createMercuryServer(config, deps = {}) {
+export function createMercuryServer(config, deps = {}, options = {}) {
     const catalog = deps.catalog ?? CATALOG;
     const payer = deps.payer ?? (config.payerPrivateKey ? createEvmPayer(config.payerPrivateKey) : undefined);
     const client = new MercuryClient({
@@ -35,6 +45,7 @@ export function createMercuryServer(config, deps = {}) {
         payer,
         maxPriceUsd: config.maxPriceUsd,
         timeoutMs: config.timeoutMs,
+        hosted: options.hosted,
     });
     const categories = [...new Set(catalog.endpoints.map((e) => e.category))].sort();
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
@@ -64,11 +75,7 @@ export function createMercuryServer(config, deps = {}) {
     });
     server.registerTool('get_endpoint_data', {
         title: 'Call a Mercury402 endpoint',
-        description: 'Call a Mercury402 endpoint on the live API. Without paid mode, endpoints return HTTP 402 and this tool returns ' +
-            'the price and x402 payment instructions instead of data. With paid mode enabled (MERCURY402_PAYER_PRIVATE_KEY), ' +
-            'it pays in USDC on Base (capped by MERCURY402_MAX_PRICE_USD) and returns the data. ' +
-            'Use list_endpoints first to find paths and parameters. Path params can be inline ("/v1/fred/UNRATE") or passed in params ' +
-            '("/v1/fred/{series_id}" + {"series_id":"UNRATE"}). Other params go to the query string (GET) or JSON body (POST).',
+        description: options.hosted ? HOSTED_GET_ENDPOINT_DATA_DESCRIPTION : LOCAL_GET_ENDPOINT_DATA_DESCRIPTION,
         inputSchema: {
             path: z.string().describe('Endpoint path, e.g. "/v1/treasury/yield-curve/daily-snapshot" or "/v1/fred/UNRATE"'),
             params: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury402-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server for Mercury402: discover and call 78 pay-per-call (x402, USDC on Base) financial data endpoints — Treasury, FRED, forex, yield spreads, breakeven inflation, macro composites",
   "license": "MIT",
   "author": "Mercury402",