@magnetoagents/mcp 0.2.1 → 0.3.0

package/README.md

@@ -14,6 +14,10 @@ The installed command is **`magneto-mcp`**. Protocol is `2025-03-26`. `serverInf
 
 The first registry publish waits on the `@magneto` npm org + `NPM_TOKEN` repo secret. Until then, use from-source.
 
+## CLI flags
+
+With no arguments, `magneto-mcp` starts the stdio MCP server. `-h` / `--help` print usage. `--version` prints the package version.
+
 ## Quickstart (Claude Code, stdio)
 
 About 90 seconds after you have an `sk_live_*` key (mint in the dashboard):
@@ -35,6 +39,8 @@ claude mcp add magneto --env MAGNETO_API_KEY=sk_live_… -- \
 
 Bump this package's `package.json` `version` by hand (patch = fix, minor = additive or breaking while major is 0). That field is the single source for `serverInfo.version`. Publish is `workflow_dispatch` on `.github/workflows/npm-publish.yml`, not a git tag.
 
+**0.3.0** is additive: `tools/list` advertises `_meta.x402` per tool, and `tools/call` may include `_meta["x402/payment"]` / `_meta["x402/payment-response"]`. Existing clients that ignore unknown keys keep working.
+
 Bumping this package's version also requires bumping the hosted `MCP_SERVER_VERSION` literal in `app/client/src/lib/mcp/tool-catalog.ts` so `registry-parity.test.ts` stays green. Hosted MCP is not a published package; the duplicate-with-test catalog is the lockstep.
 
 ## Environment
@@ -104,7 +110,7 @@ Duplicate-with-test catalog: `src/tool-catalog.ts` must match `app/client/src/li
 | `list_runs` / `get_run` | runs | History; do not log signed screenshot URLs |
 | `install_skill` / `uninstall_skill` | computers | Marketplace skill on a computer |
 | `list_skills` | catalog | `GET /skills` (not installed-on-computer) |
-| `search_marketplace` | catalog | Tool-side filter; REST has no `?q=` |
+| `search_marketplace` | catalog | Tool-side filter over the fetched `skip`/`limit` page (REST has no `?q=`) |
 | `list_templates` | catalog | Marketplace templates |
 | `list_files` | files | Workspace files |
 | `account` | account | Self-budget snapshot |
@@ -112,4 +118,19 @@ Duplicate-with-test catalog: `src/tool-catalog.ts` must match `app/client/src/li
 
 `tools/call` of a hidden or unauthorized tool is a JSON-RPC **result** with `isError: true` (not HTTP 403). Revoking the key fails subsequent HTTP calls with `403` `{ "detail": "API key revoked" }`.
 
+## Paying with x402 (MCP)
+
+Magneto prices MCP tools with the same x402 v2 dual-rail as `/api/v1`. Entitled keys (active subscription, owned skill, or a prior `payment-identifier` already settled) never see a challenge. `account` is `'free'`. Live charging requires the Worker `X402_ENABLED=true` (wrangler stays `false` until an operator flips it).
+
+| Direction | Hosted `/mcp` (native `_meta`) | Stdio `@magnetoagents/mcp` (header bridge) |
+|---|---|---|
+| Challenge | JSON-RPC **result**, HTTP **200**: `isError: true`, `{detail}` in `content`, `_meta["x402/payment"]` = decoded v2 `{x402Version, accepted, error}` | Same JSON-RPC `_meta` toward the MCP client. Stdio translates REST `402` + `PAYMENT-REQUIRED` into `_meta["x402/payment"]`. |
+| Retry | `params._meta["x402/payment"]` = signed v2 payload (object or base64url string) | Same inbound `_meta`. Stdio sets outbound `PAYMENT-SIGNATURE` (and optional `PAYMENT-IDENTIFIER`) against `/api/v1`. |
+| Receipt | result `_meta["x402/payment-response"]` | REST `PAYMENT-RESPONSE` decoded into the same `_meta` key. |
+| Bare 402 (budget / PAYG ceiling) | `isError: true`, `{detail}`, **no** `_meta["x402/payment"]` | Same: HTTP 402 without `PAYMENT-REQUIRED` does not grow payment `_meta`. |
+
+Hosted `/mcp` never returns HTTP 402 for a payable tool — the envelope stays JSON-RPC 200. Stdio does not reimplement `requirePayment`; REST already gates `/api/v1`.
+
+`tools/list` includes `_meta.x402` on every tool (`'free'` is a declaration, never an omission).
+
 Zero runtime dependencies. Catalog layout is **duplicate-with-test** (not a workspace package).

package/dist/cli-front.d.ts

@@ -0,0 +1,18 @@
+export declare const CLAUDE_PLUGIN_HINT = "<claude-code-hint v=\"1\" type=\"plugin\" value=\"magneto@claude-plugins-official\" />";
+export type MagnetoMcpCliAction = 'serve' | 'help' | 'version' | 'unknown';
+export type CliIo = {
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    exit: (code: number) => void;
+    startStdio: () => void;
+};
+export declare function shouldEmitClaudePluginHint(env: NodeJS.ProcessEnv): boolean;
+export declare function parseMagnetoMcpArgs(argvSlice2: string[]): MagnetoMcpCliAction;
+export declare function usageText(): string;
+export declare function runMagnetoMcpCli(io: CliIo): void;

package/dist/cli-front.js

@@ -0,0 +1,79 @@
+/**
+ * Human/Bash-facing argv front for magneto-mcp (#611).
+ *
+ * Bare invocation still serves stdio MCP. --help / --version / unknown-arg
+ * print and exit; those paths may emit Claude Code's plugin-hint tag
+ * (inert until an official marketplace listing exists).
+ */
+import { readPackageVersion } from './package-version.js';
+export const CLAUDE_PLUGIN_HINT = '<claude-code-hint v="1" type="plugin" value="magneto@claude-plugins-official" />';
+export function shouldEmitClaudePluginHint(env) {
+    return Boolean(env.CLAUDECODE || env.CLAUDE_CODE_CHILD_SESSION);
+}
+export function parseMagnetoMcpArgs(argvSlice2) {
+    if (argvSlice2.length === 0)
+        return 'serve';
+    if (argvSlice2.length === 1 && (argvSlice2[0] === '--help' || argvSlice2[0] === '-h')) {
+        return 'help';
+    }
+    if (argvSlice2.length === 1 && argvSlice2[0] === '--version') {
+        return 'version';
+    }
+    return 'unknown';
+}
+export function usageText() {
+    return [
+        'magneto-mcp — Magneto stdio MCP server',
+        '',
+        'JSON-RPC over stdin/stdout against /api/v1 (same tools as hosted /mcp).',
+        '',
+        'Usage:',
+        '  magneto-mcp              Start the stdio MCP server',
+        '  magneto-mcp -h, --help   Print this help',
+        '  magneto-mcp --version    Print the package version',
+        '',
+        'Environment:',
+        '  MAGNETO_API_KEY    Required. Workspace key (sk_live_*). Falls back to',
+        '                     ~/.magneto/credentials.json if unset.',
+        '  MAGNETO_API_BASE   Optional. Origin or …/api/v1 (default https://magnetoapp.io)',
+        '',
+        'Docs: https://magnetoapp.io/developers/claude',
+        '',
+    ].join('\n');
+}
+function maybeEmitHint(io) {
+    if (shouldEmitClaudePluginHint(io.env)) {
+        io.stderr.write(`${CLAUDE_PLUGIN_HINT}\n`);
+    }
+}
+function unknownToken(argvSlice2) {
+    const first = argvSlice2[0];
+    if (first === undefined || first === '')
+        return '(empty)';
+    return first;
+}
+export function runMagnetoMcpCli(io) {
+    const argvSlice2 = io.argv.slice(2);
+    const action = parseMagnetoMcpArgs(argvSlice2);
+    switch (action) {
+        case 'serve':
+            io.startStdio();
+            return;
+        case 'help':
+            io.stdout.write(usageText());
+            maybeEmitHint(io);
+            io.exit(0);
+            return;
+        case 'version':
+            io.stdout.write(`${readPackageVersion()}\n`);
+            maybeEmitHint(io);
+            io.exit(0);
+            return;
+        case 'unknown':
+            io.stderr.write(`error: unknown argument: ${unknownToken(argvSlice2)}\n`);
+            io.stderr.write(usageText());
+            maybeEmitHint(io);
+            io.exit(1);
+            return;
+    }
+}

package/dist/payment-bridge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stdio header ↔ MCP `_meta` bridge (Issue 9 / #489).
+ *
+ * Hosted `/mcp` speaks `_meta` natively. Stdio talks HTTP `/api/v1`, so this
+ * module translates `PAYMENT-*` headers to/from the same JSON-RPC `_meta`
+ * keys. Zero Worker imports.
+ */
+export type ApiResult = {
+    ok: boolean;
+    status: number;
+    data: unknown;
+    headers: Headers;
+};
+export type ApiFn = (method: string, pathSuffix: string, body?: unknown, extraHeaders?: Record<string, string>) => Promise<ApiResult>;
+export type McpToolCallResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+export declare function paymentHeadersFromMeta(meta?: Record<string, unknown>): Record<string, string>;
+export declare function wrapApiForPayment(api: ApiFn, meta?: Record<string, unknown>): {
+    api: ApiFn;
+    lastHeaders: () => Headers | null;
+};
+export declare function attachPaymentMeta(result: McpToolCallResult, headers: Headers | null | undefined): McpToolCallResult;

package/dist/payment-bridge.js

@@ -0,0 +1,90 @@
+/**
+ * Stdio header ↔ MCP `_meta` bridge (Issue 9 / #489).
+ *
+ * Hosted `/mcp` speaks `_meta` natively. Stdio talks HTTP `/api/v1`, so this
+ * module translates `PAYMENT-*` headers to/from the same JSON-RPC `_meta`
+ * keys. Zero Worker imports.
+ */
+function asNonEmptyString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function toBase64Url(json) {
+    return Buffer.from(JSON.stringify(json), 'utf8').toString('base64url');
+}
+function fromBase64Url(header) {
+    return JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+}
+function identifierFromPayload(payload) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const obj = payload;
+    const direct = asNonEmptyString(obj.paymentIdentifier) ??
+        asNonEmptyString(obj['payment-identifier']);
+    if (direct)
+        return direct;
+    const ext = obj.extensions;
+    if (ext && typeof ext === 'object') {
+        return asNonEmptyString(ext['payment-identifier']);
+    }
+    return null;
+}
+function headerGet(headers, name) {
+    return headers.get(name) ?? headers.get(name.toLowerCase());
+}
+export function paymentHeadersFromMeta(meta) {
+    const headers = {};
+    if (!meta || typeof meta !== 'object')
+        return headers;
+    const payment = meta['x402/payment'];
+    if (typeof payment === 'string' && payment.trim()) {
+        headers['PAYMENT-SIGNATURE'] = payment.trim();
+    }
+    else if (payment && typeof payment === 'object') {
+        headers['PAYMENT-SIGNATURE'] = toBase64Url(payment);
+    }
+    const identifier = asNonEmptyString(meta['payment-identifier']) ??
+        asNonEmptyString(meta.paymentIdentifier) ??
+        identifierFromPayload(payment);
+    if (identifier)
+        headers['PAYMENT-IDENTIFIER'] = identifier;
+    return headers;
+}
+export function wrapApiForPayment(api, meta) {
+    let last = null;
+    const extra = paymentHeadersFromMeta(meta);
+    const wrapped = async (method, pathSuffix, body, extraHeaders) => {
+        const result = await api(method, pathSuffix, body, { ...extra, ...extraHeaders });
+        last = result.headers;
+        return result;
+    };
+    return { api: wrapped, lastHeaders: () => last };
+}
+export function attachPaymentMeta(result, headers) {
+    if (!headers)
+        return result;
+    const required = headerGet(headers, 'PAYMENT-REQUIRED');
+    const response = headerGet(headers, 'PAYMENT-RESPONSE');
+    const meta = { ...result._meta };
+    if (required) {
+        try {
+            meta['x402/payment'] = fromBase64Url(required);
+        }
+        catch {
+            // ignore undecodable
+        }
+    }
+    if (response) {
+        try {
+            meta['x402/payment-response'] = fromBase64Url(response);
+        }
+        catch {
+            // ignore undecodable
+        }
+    }
+    if (Object.keys(meta).length === 0)
+        return result;
+    return { ...result, _meta: meta };
+}

package/dist/project-output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Project a bind payload onto an MCP outputSchema.
+ * additionalProperties omitted or false → pick declared properties only.
+ * additionalProperties true → opaque object (pass through).
+ * Arrays map `items`; non-array input becomes []. Null is preserved; undefined is dropped.
+ */
+export declare function projectToOutputSchema(data: unknown, schema: Record<string, unknown>): unknown;

package/dist/project-output.js

@@ -0,0 +1,47 @@
+/**
+ * Project a bind payload onto an MCP outputSchema.
+ * additionalProperties omitted or false → pick declared properties only.
+ * additionalProperties true → opaque object (pass through).
+ * Arrays map `items`; non-array input becomes []. Null is preserved; undefined is dropped.
+ */
+export function projectToOutputSchema(data, schema) {
+    if (data === undefined)
+        return undefined;
+    if (data === null)
+        return null;
+    const typeField = schema.type;
+    const types = Array.isArray(typeField)
+        ? typeField
+        : typeField === undefined
+            ? []
+            : [typeField];
+    const allowsArray = types.length === 0 || types.includes('array');
+    const allowsObject = types.length === 0 || types.includes('object');
+    if (allowsArray && schema.items != null && (types.includes('array') || Array.isArray(data))) {
+        if (!Array.isArray(data))
+            return [];
+        const itemSchema = schema.items;
+        return data.map((item) => projectToOutputSchema(item, itemSchema));
+    }
+    if (allowsObject && typeof data === 'object' && !Array.isArray(data)) {
+        if (schema.additionalProperties === true) {
+            return data;
+        }
+        const props = schema.properties;
+        if (!props || typeof props !== 'object' || Array.isArray(props)) {
+            return {};
+        }
+        const rec = data;
+        const out = {};
+        for (const key of Object.keys(props)) {
+            if (!Object.prototype.hasOwnProperty.call(rec, key))
+                continue;
+            const value = rec[key];
+            if (value === undefined)
+                continue;
+            out[key] = projectToOutputSchema(value, props[key]);
+        }
+        return out;
+    }
+    return data;
+}

package/dist/stdio.d.ts

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-export declare function api(method: string, pathSuffix: string, body?: unknown): Promise<{
+export declare function api(method: string, pathSuffix: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<{
     ok: boolean;
     status: number;
     data: unknown;
+    headers: Headers;
 }>;
-export declare function callTool(name: string, args: Record<string, unknown>): Promise<{
-    content: Array<{
+export declare function callTool(name: string, args: Record<string, unknown>, meta?: Record<string, unknown>): Promise<import("./payment-bridge.js").McpToolCallResult | {
+    content: {
         type: "text";
         text: string;
-    }>;
-    isError?: boolean;
+    }[];
+    isError: boolean;
 }>;
 export declare function handleRpc(msg: {
     jsonrpc?: string;

package/dist/stdio.js

@@ -20,7 +20,8 @@ import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
-import { findToolDef, listToolsForScopes, missingScopePayload, MCP_PROTOCOL_VERSION, MCP_SERVER_VERSION, MCP_TOOL_CATALOG, } from './tool-catalog.js';
+import { findToolDef, listToolsForScopes, missingScopePayload, MCP_PROTOCOL_VERSION, MCP_SERVER_INSTRUCTIONS, MCP_SERVER_VERSION, MCP_TOOL_CATALOG, toListedTool, } from './tool-catalog.js';
+import { runMagnetoMcpCli } from './cli-front.js';
 import { callToolHttp } from './tool-http.js';
 function normalizeApiBase(input) {
     const fallback = 'https://magnetoapp.io/api/v1';
@@ -66,10 +67,15 @@ function currentApiKey() {
         return '';
     }
 }
-export async function api(method, pathSuffix, body) {
+export async function api(method, pathSuffix, body, extraHeaders) {
     const key = currentApiKey();
     if (!key) {
-        return { ok: false, status: 401, data: { detail: 'MAGNETO_API_KEY not configured' } };
+        return {
+            ok: false,
+            status: 401,
+            data: { detail: 'MAGNETO_API_KEY not configured' },
+            headers: new Headers(),
+        };
     }
     const res = await fetch(`${API_BASE}${pathSuffix}`, {
         method,
@@ -77,6 +83,7 @@ export async function api(method, pathSuffix, body) {
             Authorization: `Bearer ${key}`,
             Accept: 'application/json',
             ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            ...extraHeaders,
         },
         body: body !== undefined ? JSON.stringify(body) : undefined,
     });
@@ -88,15 +95,11 @@ export async function api(method, pathSuffix, body) {
     catch {
         // keep text
     }
-    return { ok: res.ok, status: res.status, data };
+    return { ok: res.ok, status: res.status, data, headers: res.headers };
 }
 function listedTools() {
     const source = cachedScopes != null ? listToolsForScopes(cachedScopes) : MCP_TOOL_CATALOG;
-    return source.map(({ name, description, inputSchema }) => ({
-        name,
-        description,
-        inputSchema,
-    }));
+    return source.map(toListedTool);
 }
 async function ensureScopeCache() {
     if (accountFetched)
@@ -117,12 +120,12 @@ function toolText(payload, isError = false) {
     const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
     return { content: [{ type: 'text', text }], isError };
 }
-export async function callTool(name, args) {
+export async function callTool(name, args, meta) {
     const def = findToolDef(name);
     if (cachedScopes != null && def && !cachedScopes.includes(def.requiredScope)) {
         return toolText(missingScopePayload(def.requiredScope), true);
     }
-    return callToolHttp(api, name, args);
+    return callToolHttp(api, name, args, meta);
 }
 export async function handleRpc(msg) {
     const id = msg.id ?? null;
@@ -137,6 +140,7 @@ export async function handleRpc(msg) {
                     protocolVersion: MCP_PROTOCOL_VERSION,
                     capabilities: { tools: {} },
                     serverInfo: { name: 'magneto-mcp', version: MCP_SERVER_VERSION },
+                    instructions: MCP_SERVER_INSTRUCTIONS,
                 },
             };
         case 'ping':
@@ -145,9 +149,13 @@ export async function handleRpc(msg) {
             await ensureScopeCache();
             return { jsonrpc: '2.0', id, result: { tools: listedTools() } };
         case 'tools/call': {
-            const name = String(msg.params?.name ?? '');
-            const args = msg.params?.arguments ?? {};
-            const result = await callTool(name, args);
+            const params = (msg.params ?? {});
+            const name = String(params.name ?? '');
+            const args = params.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+            const meta = params._meta && typeof params._meta === 'object' && !Array.isArray(params._meta)
+                ? params._meta
+                : undefined;
+            const result = await callTool(name, args, meta);
             return { jsonrpc: '2.0', id, result };
         }
         default:
@@ -206,5 +214,13 @@ function startStdio() {
         });
     });
 }
-if (isMain())
-    startStdio();
+if (isMain()) {
+    runMagnetoMcpCli({
+        argv: process.argv,
+        env: process.env,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        exit: (code) => process.exit(code),
+        startStdio,
+    });
+}

package/dist/tool-catalog.d.ts

@@ -1,14 +1,50 @@
 export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
 export declare const MCP_SERVER_VERSION: string;
+/** ChatGPT reads this at initialize (InitializeResult.instructions). Front-load D3. */
+export declare const MCP_SERVER_INSTRUCTIONS = "Magneto is an account companion. Never attempt to purchase, subscribe, or upgrade inside this plugin. If the user wants a plan, a marketplace skill purchase, credits, or checkout, describe the option and link to https://magnetoapp.io \u2014 never a checkout, upgrade, or payment deep-link. Runs and computer lifecycle actions bill the linked Magneto account's existing plan.\n\nTypical flow: search or list the catalog (list_skills, search_marketplace, list_templates) \u2192 list or get the user's computers \u2192 create or start a computer if needed \u2192 install_skill only when the account already owns that skill \u2192 run a computer-use instruction \u2192 review with list_runs / get_run. Call get before a write when the computer id is uncertain.\n\nDo not call bash, action, screenshot, gateway_url, chat, or any payment tool. Do not mint gateway credentials. If a skill is unowned or paid, refuse to install and point at https://magnetoapp.io. If the account's plan does not cover an action, name the state and point at https://magnetoapp.io as information \u2014 never an upgrade CTA.";
 export type McpToolKind = 'both' | 'desktop-gui' | 'desktop-cu' | 'agent-ok';
+export type McpToolAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    openWorldHint: boolean;
+};
+export type PriceScheme = 'exact' | 'upto' | 'quote';
+export type PricedEntry = {
+    scheme: PriceScheme;
+    usd?: number;
+    note?: string;
+    /** Catalog-read pilot only (D14). Data parity with hosted PRICES. */
+    keyless?: true;
+};
+export type PriceEntry = PricedEntry | 'free';
 export type McpToolDef = {
     name: string;
+    title: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations: McpToolAnnotations;
     requiredScope: 'computers' | 'exec' | 'runs' | 'files' | 'catalog' | 'account';
     kinds: McpToolKind;
     specMethod: 'get' | 'post' | 'put' | 'patch' | 'delete';
     specPath: string;
+    x402: PriceEntry;
+};
+export declare const HINT_READ: McpToolAnnotations;
+export declare const HINT_WRITE: McpToolAnnotations;
+export declare const HINT_DESTRUCTIVE: McpToolAnnotations;
+export declare const HINT_OPEN_WORLD: McpToolAnnotations;
+export declare const HINT_BASH: McpToolAnnotations;
+export declare function toListedTool(def: McpToolDef): {
+    _meta: {
+        x402: PriceEntry;
+    };
+    outputSchema?: Record<string, unknown> | undefined;
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: McpToolAnnotations;
 };
 export declare const DESKTOP_ACTION_ENUM: readonly ["screenshot", "click", "double_click", "right_click", "move", "type", "key", "scroll", "drag", "wait"];
 export declare const MCP_TOOL_CATALOG: McpToolDef[];