@magnetoagents/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magneto contributors
+
+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,115 @@
+# `@magnetoagents/mcp`
+
+Stdio MCP server for Magneto computers. Implements the same tools as the hosted remote endpoint at `/mcp` against the public Worker API (`/api/v1` + `sk_live_*`).
+
+The installed command is **`magneto-mcp`**. Protocol is `2025-03-26`. `serverInfo.version` is the `package.json` `version` field (not a hand-synced literal).
+
+## Install
+
+| Method | Command |
+|--------|---------|
+| npm (global) | `npm install -g @magnetoagents/mcp` |
+| npx | `npx @magnetoagents/mcp` |
+| from-source | `cd packages/mcp && npm ci && npm run build` then `node dist/stdio.js` / `npm link` |
+
+The first registry publish waits on the `@magneto` npm org + `NPM_TOKEN` repo secret. Until then, use from-source.
+
+## Quickstart (Claude Code, stdio)
+
+About 90 seconds after you have an `sk_live_*` key (mint in the dashboard):
+
+```bash
+export MAGNETO_API_KEY=sk_live_…
+# optional: MAGNETO_API_BASE=http://localhost:${FRONTEND_PORT:-3000}
+claude mcp add magneto --env MAGNETO_API_KEY="$MAGNETO_API_KEY" -- magneto-mcp
+```
+
+From-source, after `npm ci && npm run build` in `packages/mcp`:
+
+```bash
+claude mcp add magneto --env MAGNETO_API_KEY=sk_live_… -- \
+  node /absolute/path/to/magneto-app/packages/mcp/dist/stdio.js
+```
+
+## Versioning (v0.x)
+
+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.
+
+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
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MAGNETO_API_KEY` | yes* | Workspace key (`sk_live_…`) |
+| `MAGNETO_API_BASE` | no | Origin or `…/api/v1` (default `https://magnetoapp.io`) |
+
+\*Falls back to `~/.magneto/credentials.json` from `magneto login` if env is unset. Missing key does not fail `initialize` / `ping`.
+
+## Scope filter (account-first, degrade to full list)
+
+On the first `tools/list`, stdio calls `GET /account` and caches `key.scopes` for the process.
+
+- If that succeeds, the listed tools are filtered to those whose `requiredScope` is in the cached array. A key without `exec` never sees `bash`.
+- If it fails (401, `Missing scope: account`, network), stdio logs a one-line stderr warning and returns the **full catalog**. `tools/call` then surfaces HTTP `{ detail }` as `isError: true`.
+- A forced `tools/call` of a tool hidden by the cached scopes returns the same 403 tool-error (`{ "detail": "Missing scope: …", "status": 403 }`) **without** fetching.
+
+Hosted `/mcp` always filters from `requireApiKey` scopes. Stdio may disagree with hosted `tools/list` only when `GET /account` fails.
+
+## Claude Code (stdio)
+
+```bash
+claude mcp add magneto --env MAGNETO_API_KEY=sk_live_… -- \
+  node /absolute/path/to/magneto-app/packages/mcp/dist/stdio.js
+```
+
+Or with a local base:
+
+```bash
+claude mcp add magneto \
+  --env MAGNETO_API_KEY=sk_live_… \
+  --env MAGNETO_API_BASE=http://localhost:3000 -- \
+  node ./packages/mcp/dist/stdio.js
+```
+
+## Hosted remote MCP (preferred for remote clients)
+
+Production: `https://magnetoapp.io/mcp`  
+Local: `http://localhost:${FRONTEND_PORT:-3000}/mcp` (rewrites to `/api/mcp`)
+
+```bash
+claude mcp add --transport http magneto https://magnetoapp.io/mcp
+# Configure Authorization: Bearer sk_live_… per client version
+```
+
+## Tools
+
+Duplicate-with-test catalog: `src/tool-catalog.ts` must match `app/client/src/lib/mcp/tool-catalog.ts` (parity test in the client package).
+
+| Tool | Scope | Notes |
+|------|--------|--------|
+| `create` | computers | Force workspace from key; client `workspace_id` is omitted |
+| `list` | computers | Minting user scope |
+| `get` | computers | Computer detail |
+| `start` / `stop` / `restart` | computers | Lifecycle |
+| `delete` | computers | **DESTRUCTIVE.** `confirm` must equal the computer name |
+| `resize` | computers | Desktop grow-only; agent/shrink → 422 |
+| `uptime` | computers | Optional `window_seconds` |
+| `gateway_url` | computers | 60-s URL. Desktop `/desk`, agent `/connect`. Do not log `url` |
+| `screenshot` | computers | Desktop → action API; agent → structured status |
+| `action` | computers | One tool, ten GUI actions; agent → structured status |
+| `bash` | **exec** | Opt-in (not in `DEFAULT_SCOPES`). Desktop and agent |
+| `run` | runs | Desktop CU only. Burns CU cap / BYO. Concurrent-run ceiling |
+| `stop_run` | runs | `{ run_id }` |
+| `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=` |
+| `list_templates` | catalog | Marketplace templates |
+| `list_files` | files | Workspace files |
+| `account` | account | Self-budget snapshot |
+| `chat` | runs | Non-stream `POST /chat/completions`. Desktop only. Same CU cap |
+
+`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" }`.
+
+Zero runtime dependencies. Catalog layout is **duplicate-with-test** (not a workspace package).

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** Read this package's version from package.json (works from src/, dist/, and an installed tarball). */
+export declare function readPackageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+/** Read this package's version from package.json (works from src/, dist/, and an installed tarball). */
+export function readPackageVersion() {
+    const raw = fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error('package.json is missing a version');
+    }
+    return parsed.version;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+export declare function api(method: string, pathSuffix: string, body?: unknown): Promise<{
+    ok: boolean;
+    status: number;
+    data: unknown;
+}>;
+export declare function callTool(name: string, args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare function handleRpc(msg: {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}): Promise<unknown | null>;
+export declare function resetStdioState(): void;

package/dist/stdio.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP stdio bridge for Magneto (#110 / #439).
+ *
+ * Speaks JSON-RPC MCP over stdin/stdout and implements tools against the
+ * public Worker `/api/v1` surface (same as CLI / remote MCP).
+ *
+ * Env:
+ *   MAGNETO_API_KEY   — required (sk_live_*)
+ *   MAGNETO_API_BASE  — origin or …/api/v1 (default https://magnetoapp.io)
+ *
+ * Scope filter: first tools/list calls GET /account and caches key.scopes.
+ * If that fails (401, missing account scope, network), degrade to the full
+ * catalog and let tools/call surface HTTP { detail } as isError.
+ *
+ * Publish is workflow_dispatch on npm-publish.yml (inert until NPM_TOKEN).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { pathToFileURL } from 'node:url';
+import { findToolDef, listToolsForScopes, missingScopePayload, MCP_PROTOCOL_VERSION, MCP_SERVER_VERSION, MCP_TOOL_CATALOG, } from './tool-catalog.js';
+import { callToolHttp } from './tool-http.js';
+function normalizeApiBase(input) {
+    const fallback = 'https://magnetoapp.io/api/v1';
+    const raw = (input ?? process.env.MAGNETO_API_BASE ?? process.env.MAGNETO_BASE_URL ?? fallback)
+        .trim()
+        .replace(/\/+$/, '');
+    if (!raw)
+        return fallback;
+    if (raw.endsWith('/api/v1'))
+        return raw;
+    if (raw.endsWith('/api'))
+        return `${raw}/v1`;
+    return `${raw}/api/v1`;
+}
+function resolveApiKey() {
+    const env = process.env.MAGNETO_API_KEY?.trim();
+    if (env)
+        return env;
+    try {
+        const file = path.join(os.homedir(), '.magneto', 'credentials.json');
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed.api_key?.trim())
+            return parsed.api_key.trim();
+    }
+    catch {
+        // ignore
+    }
+    throw new Error('MAGNETO_API_KEY not set and ~/.magneto/credentials.json missing');
+}
+const API_BASE = normalizeApiBase();
+let warnedMissingKey = false;
+let cachedScopes = null;
+let accountFetched = false;
+function currentApiKey() {
+    try {
+        return resolveApiKey();
+    }
+    catch (err) {
+        if (!warnedMissingKey) {
+            warnedMissingKey = true;
+            process.stderr.write(`[magneto-mcp] warning: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        return '';
+    }
+}
+export async function api(method, pathSuffix, body) {
+    const key = currentApiKey();
+    if (!key) {
+        return { ok: false, status: 401, data: { detail: 'MAGNETO_API_KEY not configured' } };
+    }
+    const res = await fetch(`${API_BASE}${pathSuffix}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${key}`,
+            Accept: 'application/json',
+            ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let data = text;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        // keep text
+    }
+    return { ok: res.ok, status: res.status, data };
+}
+function listedTools() {
+    const source = cachedScopes != null ? listToolsForScopes(cachedScopes) : MCP_TOOL_CATALOG;
+    return source.map(({ name, description, inputSchema }) => ({
+        name,
+        description,
+        inputSchema,
+    }));
+}
+async function ensureScopeCache() {
+    if (accountFetched)
+        return;
+    accountFetched = true;
+    const r = await api('GET', '/account');
+    if (r.ok && r.data && typeof r.data === 'object') {
+        const scopes = r.data.key?.scopes;
+        if (Array.isArray(scopes) && scopes.every((s) => typeof s === 'string')) {
+            cachedScopes = scopes;
+            return;
+        }
+    }
+    cachedScopes = null;
+    process.stderr.write('[magneto-mcp] warning: GET /account failed; listing all tools (per-call errors still apply)\n');
+}
+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) {
+    const def = findToolDef(name);
+    if (cachedScopes != null && def && !cachedScopes.includes(def.requiredScope)) {
+        return toolText(missingScopePayload(def.requiredScope), true);
+    }
+    return callToolHttp(api, name, args);
+}
+export async function handleRpc(msg) {
+    const id = msg.id ?? null;
+    if (msg.method?.startsWith('notifications/'))
+        return null;
+    switch (msg.method) {
+        case 'initialize':
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    protocolVersion: MCP_PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'magneto-mcp', version: MCP_SERVER_VERSION },
+                },
+            };
+        case 'ping':
+            return { jsonrpc: '2.0', id, result: {} };
+        case 'tools/list':
+            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);
+            return { jsonrpc: '2.0', id, result };
+        }
+        default:
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `Method not found: ${msg.method}` },
+            };
+    }
+}
+export function resetStdioState() {
+    cachedScopes = null;
+    accountFetched = false;
+    warnedMissingKey = false;
+}
+function writeMessage(msg) {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function isMain() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(path.resolve(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+function startStdio() {
+    const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            writeMessage({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error' },
+            });
+            return;
+        }
+        void handleRpc(msg)
+            .then((result) => {
+            if (result != null)
+                writeMessage(result);
+        })
+            .catch((err) => {
+            process.stderr.write(`[magneto-mcp] ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    });
+}
+if (isMain())
+    startStdio();

package/dist/tool-catalog.d.ts

@@ -0,0 +1,23 @@
+export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+export declare const MCP_SERVER_VERSION: string;
+export type McpToolKind = 'both' | 'desktop-gui' | 'desktop-cu' | 'agent-ok';
+export type McpToolDef = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    requiredScope: 'computers' | 'exec' | 'runs' | 'files' | 'catalog' | 'account';
+    kinds: McpToolKind;
+    specMethod: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    specPath: string;
+};
+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[];
+export declare function listToolsForScopes(scopes: readonly string[]): McpToolDef[];
+export declare function findToolDef(name: string): McpToolDef | undefined;
+export declare function missingScopePayload(requiredScope: string): {
+    detail: string;
+    status: 403;
+};
+export declare const MCP_TOOL_NAMES: string[];
+export type McpToolName = (typeof MCP_TOOL_NAMES)[number];
+export declare const MCP_TOOL_SCOPES: Record<string, McpToolDef['requiredScope']>;

package/dist/tool-catalog.js

@@ -0,0 +1,431 @@
+// Plain-data MCP tool catalog (#439). Duplicate of app/client/src/lib/mcp/tool-catalog.ts.
+// Zero Worker imports. Keep in lockstep (registry-parity.test.ts).
+import { readPackageVersion } from './package-version.js';
+export const MCP_PROTOCOL_VERSION = '2025-03-26';
+export const MCP_SERVER_VERSION = readPackageVersion();
+export const DESKTOP_ACTION_ENUM = [
+    'screenshot',
+    'click',
+    'double_click',
+    'right_click',
+    'move',
+    'type',
+    'key',
+    'scroll',
+    'drag',
+    'wait',
+];
+export const MCP_TOOL_CATALOG = [
+    {
+        name: 'create',
+        description: 'Create a Magneto computer in the API key workspace. Scope computers. Works for both desktop and agent flavors (default flavor is agent; use flavor=desktop for CU machines). workspace_id is forced from the key; client-supplied workspace_id is ignored.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Optional display name' },
+                flavor: {
+                    type: 'string',
+                    enum: ['agent', 'desktop'],
+                    description: 'Computer flavor (default agent)',
+                },
+                template_id: { type: 'number', description: 'Optional agent template id' },
+                vcpu: { type: 'number' },
+                ram_gb: { type: 'number' },
+                disk_gb: { type: 'number' },
+                image: { type: 'string' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers',
+    },
+    {
+        name: 'list',
+        description: 'List computers for the API key minting user. Scope computers. Returns both desktop and agent computers.',
+        inputSchema: { type: 'object', properties: {} },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/computers',
+    },
+    {
+        name: 'get',
+        description: 'Get one computer by id. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: { computer_id: { type: 'string' } },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/computers/{id}',
+    },
+    {
+        name: 'start',
+        description: 'Start a stopped computer. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: { computer_id: { type: 'string' } },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/start',
+    },
+    {
+        name: 'stop',
+        description: 'Stop a computer. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: { computer_id: { type: 'string' } },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/stop',
+    },
+    {
+        name: 'restart',
+        description: 'Restart a running or degraded computer. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: { computer_id: { type: 'string' } },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/restart',
+    },
+    {
+        name: 'delete',
+        description: 'DESTRUCTIVE. Irreversible deprovision. confirm must equal the computer name. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'confirm'],
+            properties: {
+                computer_id: { type: 'string' },
+                confirm: { type: 'string', description: 'Must equal the computer name' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'delete',
+        specPath: '/computers/{id}',
+    },
+    {
+        name: 'resize',
+        description: 'Resize a desktop computer (grow-only: vcpu, ram_gb, disk_gb). Scope computers. Desktop grow-only; agent or shrink returns 422 passthrough.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                vcpu: { type: 'number' },
+                ram_gb: { type: 'number' },
+                disk_gb: { type: 'number' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/resize',
+    },
+    {
+        name: 'uptime',
+        description: 'Get Fly Prometheus uptime for a computer. Scope computers. Works for both desktop and agent computers. Optional window_seconds.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                window_seconds: { type: 'number' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/computers/{id}/uptime',
+    },
+    {
+        name: 'gateway_url',
+        description: 'Mint a 60-second signed gateway URL. Scope computers. Desktop uses /desk; agent uses /connect. target=terminal is desktop-only. Do not log the url.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                target: { type: 'string', enum: ['desktop', 'terminal'] },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/gateway',
+    },
+    {
+        name: 'screenshot',
+        description: 'Take a screenshot of a desktop computer. Scope computers. Desktop-gui: real screenshot. Agent computers return structured status (screenshot: null, no action call).',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: { computer_id: { type: 'string', description: 'Computer id' } },
+        },
+        requiredScope: 'computers',
+        kinds: 'desktop-gui',
+        specMethod: 'post',
+        specPath: '/computers/{id}/actions/{action}',
+    },
+    {
+        name: 'action',
+        description: 'Dispatch one desktop GUI action (screenshot, click, double_click, right_click, move, type, key, scroll, drag, wait). Scope computers. Desktop-gui only. Agent computers return structured status (action: null, no helper call).',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'action'],
+            properties: {
+                computer_id: { type: 'string' },
+                action: {
+                    type: 'string',
+                    enum: [
+                        'screenshot',
+                        'click',
+                        'double_click',
+                        'right_click',
+                        'move',
+                        'type',
+                        'key',
+                        'scroll',
+                        'drag',
+                        'wait',
+                    ],
+                },
+                params: { type: 'object', additionalProperties: true },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'desktop-gui',
+        specMethod: 'post',
+        specPath: '/computers/{id}/actions/{action}',
+    },
+    {
+        name: 'bash',
+        description: 'Run a shell command on a computer. Scope exec (opt-in, not in DEFAULT_SCOPES). Allowed on desktop and agent. Output capped 1 MiB; timeout 1–300 s.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'command'],
+            properties: {
+                computer_id: { type: 'string' },
+                command: { type: 'string' },
+                timeout: { type: 'number' },
+            },
+        },
+        requiredScope: 'exec',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/bash',
+    },
+    {
+        name: 'run',
+        description: 'Run a computer-use instruction on a desktop computer (streaming CU loop). Scope runs. Desktop only. Burns the platform CU spend cap or the single named BYO secret. Concurrent-run ceiling applies (429). Agent computers return 422.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'instruction'],
+            properties: {
+                computer_id: { type: 'string' },
+                instruction: { type: 'string' },
+                model: { type: 'string' },
+                max_steps: { type: 'number' },
+            },
+        },
+        requiredScope: 'runs',
+        kinds: 'desktop-cu',
+        specMethod: 'post',
+        specPath: '/computers/{id}/computer-use/run',
+    },
+    {
+        name: 'stop_run',
+        description: 'Hard-stop a computer-use run. Scope runs. Desktop-cu. Body run_id. 404 if already finished.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'run_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                run_id: { type: 'string' },
+            },
+        },
+        requiredScope: 'runs',
+        kinds: 'desktop-cu',
+        specMethod: 'post',
+        specPath: '/computers/{id}/computer-use/stop',
+    },
+    {
+        name: 'list_runs',
+        description: 'List computer-use run history for a computer. Scope runs. Desktop-cu. Optional limit and offset.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                limit: { type: 'number' },
+                offset: { type: 'number' },
+            },
+        },
+        requiredScope: 'runs',
+        kinds: 'desktop-cu',
+        specMethod: 'get',
+        specPath: '/computers/{id}/runs',
+    },
+    {
+        name: 'get_run',
+        description: 'Get a computer-use run and its step events. Scope runs. Desktop-cu. Signed screenshot URLs are credentials — do not log them.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'run_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                run_id: { type: 'string' },
+            },
+        },
+        requiredScope: 'runs',
+        kinds: 'desktop-cu',
+        specMethod: 'get',
+        specPath: '/computers/{id}/runs/{runId}',
+    },
+    {
+        name: 'install_skill',
+        description: 'Install a marketplace skill onto a computer by numeric skill_id. Scope computers. Works for both desktop and agent computers.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'skill_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                skill_id: { type: 'number' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'post',
+        specPath: '/computers/{id}/skills',
+    },
+    {
+        name: 'uninstall_skill',
+        description: 'Uninstall a marketplace skill from a computer. Scope computers. Works for both desktop and agent computers. Missing install is a no-op.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id', 'skill_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                skill_id: { type: 'number' },
+            },
+        },
+        requiredScope: 'computers',
+        kinds: 'both',
+        specMethod: 'delete',
+        specPath: '/computers/{id}/skills/{skillId}',
+    },
+    {
+        name: 'list_skills',
+        description: 'List marketplace skills (GET /skills). Scope catalog. Not the per-computer installed list. REST has no search query.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skip: { type: 'number' },
+                limit: { type: 'number' },
+            },
+        },
+        requiredScope: 'catalog',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/skills',
+    },
+    {
+        name: 'search_marketplace',
+        description: 'Search the marketplace skill page in-tool (name/description filter). Scope catalog. REST has no ?q= — this is a tool-side filter over GET /skills. A numeric query also fetches GET /skills/{id}.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string' },
+                skip: { type: 'number' },
+                limit: { type: 'number' },
+            },
+        },
+        requiredScope: 'catalog',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/skills',
+    },
+    {
+        name: 'list_templates',
+        description: 'List marketplace computer templates. Scope catalog.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skip: { type: 'number' },
+                limit: { type: 'number' },
+                category: { type: 'string' },
+                featured: { type: 'boolean' },
+            },
+        },
+        requiredScope: 'catalog',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/templates',
+    },
+    {
+        name: 'list_files',
+        description: 'List workspace files. Scope files.',
+        inputSchema: { type: 'object', properties: {} },
+        requiredScope: 'files',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/files',
+    },
+    {
+        name: 'account',
+        description: 'Read-only self-budget snapshot (workspace, subscription, CU/LLM usage, key scopes). Scope account.',
+        inputSchema: { type: 'object', properties: {} },
+        requiredScope: 'account',
+        kinds: 'both',
+        specMethod: 'get',
+        specPath: '/account',
+    },
+    {
+        name: 'chat',
+        description: 'OpenAI-compatible chat completion over computer-use (non-stream). Scope runs. Desktop only. Burns the platform CU spend cap or the single named BYO secret. Concurrent-run ceiling applies (429). Accepts messages or a single instruction. stream is coerced to false. Agent computers return 422.',
+        inputSchema: {
+            type: 'object',
+            required: ['computer_id'],
+            properties: {
+                computer_id: { type: 'string' },
+                messages: { type: 'array', items: { type: 'object' } },
+                instruction: {
+                    type: 'string',
+                    description: 'Shorthand: wrapped as a single user message when messages is omitted',
+                },
+                model: { type: 'string' },
+                max_steps: { type: 'number' },
+                include_thinking: { type: 'boolean' },
+                stream: { type: 'boolean', description: 'Ignored; MCP always runs non-stream' },
+            },
+        },
+        requiredScope: 'runs',
+        kinds: 'desktop-cu',
+        specMethod: 'post',
+        specPath: '/chat/completions',
+    },
+];
+export function listToolsForScopes(scopes) {
+    return MCP_TOOL_CATALOG.filter((tool) => scopes.includes(tool.requiredScope));
+}
+export function findToolDef(name) {
+    return MCP_TOOL_CATALOG.find((tool) => tool.name === name);
+}
+export function missingScopePayload(requiredScope) {
+    return { detail: `Missing scope: ${requiredScope}`, status: 403 };
+}
+export const MCP_TOOL_NAMES = MCP_TOOL_CATALOG.map((tool) => tool.name);
+export const MCP_TOOL_SCOPES = Object.fromEntries(MCP_TOOL_CATALOG.map((tool) => [tool.name, tool.requiredScope]));

package/dist/tool-http.d.ts

@@ -0,0 +1,12 @@
+export type ApiFn = (method: string, pathSuffix: string, body?: unknown) => Promise<{
+    ok: boolean;
+    status: number;
+    data: unknown;
+}>;
+export declare function callToolHttp(api: ApiFn, name: string, args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tool-http.js

@@ -0,0 +1,282 @@
+// Stdio MCP HTTP map (#439). Speaks /api/v1 only — no Worker imports.
+import { findToolDef, missingScopePayload } from './tool-catalog.js';
+function toolText(payload, isError = false) {
+    const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+    return { content: [{ type: 'text', text }], isError };
+}
+function kindOf(data) {
+    return String(data?.kind ?? 'agent').toLowerCase();
+}
+function enc(value) {
+    return encodeURIComponent(value);
+}
+export async function callToolHttp(api, name, args) {
+    const def = findToolDef(name);
+    if (!def)
+        return toolText({ detail: `Unknown tool: ${name}` }, true);
+    switch (name) {
+        case 'list': {
+            const r = await api('GET', '/computers');
+            return toolText(r.data, !r.ok);
+        }
+        case 'create': {
+            const body = {};
+            if (args.name != null)
+                body.name = args.name;
+            if (args.flavor != null)
+                body.flavor = args.flavor;
+            if (args.template_id != null)
+                body.template_id = args.template_id;
+            if (args.vcpu != null)
+                body.vcpu = args.vcpu;
+            if (args.ram_gb != null)
+                body.ram_gb = args.ram_gb;
+            if (args.disk_gb != null)
+                body.disk_gb = args.disk_gb;
+            if (args.image != null)
+                body.image = args.image;
+            const r = await api('POST', '/computers', body);
+            return toolText(r.data, !r.ok);
+        }
+        case 'get': {
+            const r = await api('GET', `/computers/${enc(String(args.computer_id ?? ''))}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'start': {
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/start`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'stop': {
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/stop`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'restart': {
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/restart`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'delete': {
+            if (!args.confirm || typeof args.confirm !== 'string') {
+                return toolText({ detail: 'confirm is required and must equal the computer name', status: 400 }, true);
+            }
+            const r = await api('DELETE', `/computers/${enc(String(args.computer_id ?? ''))}?confirm=${enc(args.confirm)}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'resize': {
+            const body = {};
+            if (args.vcpu != null)
+                body.vcpu = args.vcpu;
+            if (args.ram_gb != null)
+                body.ram_gb = args.ram_gb;
+            if (args.disk_gb != null)
+                body.disk_gb = args.disk_gb;
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/resize`, body);
+            return toolText(r.data, !r.ok);
+        }
+        case 'uptime': {
+            const qs = typeof args.window_seconds === 'number' ? `?window_seconds=${args.window_seconds}` : '';
+            const r = await api('GET', `/computers/${enc(String(args.computer_id ?? ''))}/uptime${qs}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'gateway_url': {
+            const target = typeof args.target === 'string' ? args.target : 'desktop';
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/gateway?target=${enc(target)}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'screenshot': {
+            const id = String(args.computer_id ?? '');
+            const detail = await api('GET', `/computers/${enc(id)}`);
+            if (!detail.ok)
+                return toolText(detail.data, true);
+            if (kindOf(detail.data) !== 'desktop') {
+                return toolText({
+                    kind: kindOf(detail.data),
+                    state: detail.data?.state ?? null,
+                    id,
+                    message: 'Screenshot only for desktop computers; agent status returned.',
+                    screenshot: null,
+                });
+            }
+            const r = await api('POST', `/computers/${enc(id)}/actions/screenshot`, { params: {} });
+            return toolText(r.data, !r.ok);
+        }
+        case 'action': {
+            const id = String(args.computer_id ?? '');
+            const action = String(args.action ?? '');
+            const allowed = [
+                'screenshot',
+                'click',
+                'double_click',
+                'right_click',
+                'move',
+                'type',
+                'key',
+                'scroll',
+                'drag',
+                'wait',
+            ];
+            if (!allowed.includes(action)) {
+                return toolText({ detail: 'Invalid action', status: 400 }, true);
+            }
+            const detail = await api('GET', `/computers/${enc(id)}`);
+            if (!detail.ok)
+                return toolText(detail.data, true);
+            if (kindOf(detail.data) !== 'desktop') {
+                return toolText({
+                    kind: kindOf(detail.data),
+                    state: detail.data?.state ?? null,
+                    id,
+                    message: 'Desktop GUI actions are only available for desktop computers.',
+                    action: null,
+                });
+            }
+            const params = args.params && typeof args.params === 'object' && !Array.isArray(args.params)
+                ? args.params
+                : {};
+            const r = await api('POST', `/computers/${enc(id)}/actions/${enc(action)}`, { params });
+            return toolText(r.data, !r.ok);
+        }
+        case 'bash': {
+            const body = { command: args.command };
+            if (args.timeout != null)
+                body.timeout = args.timeout;
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/bash`, body);
+            return toolText(r.data, !r.ok);
+        }
+        case 'run': {
+            const id = String(args.computer_id ?? '');
+            const detail = await api('GET', `/computers/${enc(id)}`);
+            if (!detail.ok)
+                return toolText(detail.data, true);
+            if (kindOf(detail.data) !== 'desktop') {
+                return toolText({
+                    detail: 'computer-use/run is only supported on desktop computers. Agent machines use the agent chat/gateway surface instead.',
+                }, true);
+            }
+            const body = { instruction: args.instruction };
+            if (args.model != null)
+                body.model = args.model;
+            if (args.max_steps != null)
+                body.max_steps = args.max_steps;
+            const r = await api('POST', `/computers/${enc(id)}/computer-use/run`, body);
+            return toolText(r.data, !r.ok);
+        }
+        case 'stop_run': {
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/computer-use/stop`, { run_id: args.run_id });
+            return toolText(r.data, !r.ok);
+        }
+        case 'list_runs': {
+            const params = new URLSearchParams();
+            if (typeof args.limit === 'number')
+                params.set('limit', String(args.limit));
+            if (typeof args.offset === 'number')
+                params.set('offset', String(args.offset));
+            const qs = params.toString() ? `?${params.toString()}` : '';
+            const r = await api('GET', `/computers/${enc(String(args.computer_id ?? ''))}/runs${qs}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'get_run': {
+            const r = await api('GET', `/computers/${enc(String(args.computer_id ?? ''))}/runs/${enc(String(args.run_id ?? ''))}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'install_skill': {
+            const r = await api('POST', `/computers/${enc(String(args.computer_id ?? ''))}/skills`, {
+                skill_id: Number(args.skill_id),
+            });
+            return toolText(r.data, !r.ok);
+        }
+        case 'uninstall_skill': {
+            const r = await api('DELETE', `/computers/${enc(String(args.computer_id ?? ''))}/skills/${enc(String(args.skill_id ?? ''))}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'list_skills': {
+            const params = new URLSearchParams();
+            if (typeof args.skip === 'number')
+                params.set('skip', String(args.skip));
+            if (typeof args.limit === 'number')
+                params.set('limit', String(args.limit));
+            const qs = params.toString() ? `?${params.toString()}` : '';
+            const r = await api('GET', `/skills${qs}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'search_marketplace': {
+            const params = new URLSearchParams();
+            if (typeof args.skip === 'number')
+                params.set('skip', String(args.skip));
+            if (typeof args.limit === 'number')
+                params.set('limit', String(args.limit));
+            const qs = params.toString() ? `?${params.toString()}` : '';
+            const page = await api('GET', `/skills${qs}`);
+            if (!page.ok)
+                return toolText(page.data, true);
+            const query = typeof args.query === 'string' ? args.query : '';
+            const rows = Array.isArray(page.data) ? page.data : [];
+            const needle = query.toLowerCase();
+            const items = query
+                ? rows.filter((row) => {
+                    const rec = row;
+                    return (String(rec.name ?? '')
+                        .toLowerCase()
+                        .includes(needle) ||
+                        String(rec.description ?? '')
+                            .toLowerCase()
+                            .includes(needle));
+                })
+                : rows;
+            const numeric = Number(query);
+            if (query !== '' && Number.isFinite(numeric) && Number.isInteger(numeric)) {
+                const exact = await api('GET', `/skills/${enc(String(numeric))}`);
+                return toolText({ items, exact: exact.ok ? exact.data : null });
+            }
+            return toolText({ items });
+        }
+        case 'list_templates': {
+            const params = new URLSearchParams();
+            if (typeof args.skip === 'number')
+                params.set('skip', String(args.skip));
+            if (typeof args.limit === 'number')
+                params.set('limit', String(args.limit));
+            if (typeof args.category === 'string')
+                params.set('category', args.category);
+            if (typeof args.featured === 'boolean')
+                params.set('featured', String(args.featured));
+            const qs = params.toString() ? `?${params.toString()}` : '';
+            const r = await api('GET', `/templates${qs}`);
+            return toolText(r.data, !r.ok);
+        }
+        case 'list_files': {
+            const r = await api('GET', '/files');
+            return toolText(r.data, !r.ok);
+        }
+        case 'account': {
+            const r = await api('GET', '/account');
+            return toolText(r.data, !r.ok);
+        }
+        case 'chat': {
+            const id = String(args.computer_id ?? '');
+            const detail = await api('GET', `/computers/${enc(id)}`);
+            if (!detail.ok)
+                return toolText(detail.data, true);
+            if (kindOf(detail.data) !== 'desktop') {
+                return toolText({
+                    detail: 'computer-use/run is only supported on desktop computers. Agent machines use the agent chat/gateway surface instead.',
+                }, true);
+            }
+            const body = { computer_id: id, stream: false };
+            if (Array.isArray(args.messages))
+                body.messages = args.messages;
+            else if (typeof args.instruction === 'string') {
+                body.messages = [{ role: 'user', content: args.instruction }];
+            }
+            if (args.model != null)
+                body.model = args.model;
+            if (args.max_steps != null)
+                body.max_steps = args.max_steps;
+            if (args.include_thinking != null)
+                body.include_thinking = args.include_thinking;
+            const r = await api('POST', '/chat/completions', body);
+            return toolText(r.data, !r.ok);
+        }
+        default:
+            return toolText(missingScopePayload(def.requiredScope), true);
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@magnetoagents/mcp",
+  "version": "0.2.0",
+  "description": "Magneto MCP stdio server — drive computers via sk_live_* against /api/v1 (or remote /mcp)",
+  "type": "module",
+  "bin": {
+    "magneto-mcp": "./dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vargasjons/magneto-app.git",
+    "directory": "packages/mcp"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false
+}