@agentwonderland/mcp 0.1.39 → 0.1.41

package/dist/core/__tests__/api-client.test.js

@@ -46,7 +46,7 @@ describe("api-client headers", () => {
                 "X-AW-Consumer-Principal": "did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
                 "X-AW-Rebate-Principal": "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                 "X-AW-Surface": "mcp",
-                "X-AW-MCP-Version": "0.1.37",
+                "X-AW-MCP-Version": "0.1.41",
                 "X-AW-MCP-Tool": "run_agent",
                 "X-AW-MCP-Action": "execute",
             }),

package/dist/core/__tests__/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/setup.test.js

@@ -0,0 +1,72 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { installClient, mergeCodexTomlConfig, mergeJsonMcpConfig, parseSetupArgs, } from "../../setup.js";
+let tempDirs = [];
+afterEach(async () => {
+    await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })));
+    tempDirs = [];
+});
+describe("MCP setup", () => {
+    it("merges the server into existing JSON MCP config", () => {
+        const next = JSON.parse(mergeJsonMcpConfig(JSON.stringify({
+            mcpServers: {
+                existing: { command: "node", args: ["server.js"] },
+            },
+            otherSetting: true,
+        })));
+        expect(next.otherSetting).toBe(true);
+        expect(next.mcpServers.existing.command).toBe("node");
+        expect(next.mcpServers.agentwonderland).toEqual({
+            command: "npx",
+            args: ["-y", "@agentwonderland/mcp"],
+        });
+    });
+    it("replaces an existing Codex TOML block without disturbing other servers", () => {
+        const next = mergeCodexTomlConfig([
+            "[mcp_servers.other]",
+            'command = "node"',
+            'args = ["other.js"]',
+            "",
+            "[mcp_servers.agentwonderland]",
+            'command = "old"',
+            'args = ["old"]',
+            "",
+            "[model_provider.openai]",
+            'name = "OpenAI"',
+            "",
+        ].join("\n"));
+        expect(next).toContain("[mcp_servers.other]");
+        expect(next).toContain("[mcp_servers.agentwonderland]");
+        expect(next).toContain('command = "npx"');
+        expect(next).toContain('args = ["-y", "@agentwonderland/mcp"]');
+        expect(next).not.toContain('command = "old"');
+        expect(next).toContain("[model_provider.openai]");
+    });
+    it("writes config and creates a backup when updating", async () => {
+        const dir = await mkdtemp(path.join(tmpdir(), "aw-mcp-setup-"));
+        tempDirs.push(dir);
+        const configPath = path.join(dir, "mcp.json");
+        await writeFile(configPath, JSON.stringify({ mcpServers: { old: { command: "node" } } }), "utf8");
+        const client = {
+            id: "cursor",
+            name: "Cursor",
+            path: configPath,
+            format: "json",
+            detected: true,
+            note: "test",
+        };
+        const result = await installClient(client);
+        const written = JSON.parse(await readFile(configPath, "utf8"));
+        expect(result.status).toBe("updated");
+        expect(result.backupPath).toBeTruthy();
+        expect(written.mcpServers.agentwonderland.args).toEqual(["-y", "@agentwonderland/mcp"]);
+    });
+    it("parses client selection flags", () => {
+        expect(parseSetupArgs(["--clients", "codex,cursor", "--yes"])).toEqual({
+            clients: ["codex", "cursor"],
+            yes: true,
+        });
+    });
+});

package/dist/core/api-client.js

@@ -12,7 +12,7 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
-const MCP_VERSION = "0.1.37";
+const MCP_VERSION = "0.1.41";
 function inferToolHeaders(path, method) {
     if (path === "/solve") {
         return { "X-AW-MCP-Tool": "solve", "X-AW-MCP-Action": method === "POST" ? "execute" : "view" };

package/dist/index.js

@@ -21,6 +21,8 @@ import { registerWalletResources } from "./resources/wallet.js";
 import { registerJobResources } from "./resources/jobs.js";
 // ── Prompts ──────────────────────────────────────────────────────
 import { registerPrompts } from "./prompts/index.js";
+import { runSetupCli } from "./setup.js";
+const PACKAGE_VERSION = "0.1.41";
 export async function startMcpServer() {
     const server = new McpServer({
         name: "agentwonderland",
@@ -93,8 +95,50 @@ export async function startMcpServer() {
 const isCli = process.argv[1]?.endsWith("agentwonderland-mcp") ||
     process.argv[1]?.includes("packages/mcp");
 if (isCli) {
-    startMcpServer().catch((err) => {
-        console.error("MCP server error:", err);
-        process.exit(1);
-    });
+    const args = process.argv.slice(2);
+    if (args[0] === "setup" || args[0] === "install" || args[0] === "configure") {
+        runSetupCli(args.slice(1)).catch((err) => {
+            console.error("Setup failed:", err instanceof Error ? err.message : err);
+            process.exit(1);
+        });
+    }
+    else if (args.includes("--help") || args.includes("-h")) {
+        console.log([
+            "Agent Wonderland MCP server",
+            "",
+            "Usage:",
+            "  npx @agentwonderland/mcp setup      Configure MCP clients",
+            "  npx @agentwonderland/mcp            Start the stdio MCP server",
+            "",
+            "The bare command starts a stdio MCP server. It is meant to be launched by",
+            "Codex, Cursor, Claude Desktop, or another MCP client. When run directly",
+            "in a terminal it waits silently for MCP JSON-RPC messages on stdin.",
+            "",
+            "MCP client config:",
+            '  { "mcpServers": { "agentwonderland": { "command": "npx", "args": ["-y", "@agentwonderland/mcp"] } } }',
+            "",
+            "Options:",
+            "  -h, --help     Show this help",
+            "  -v, --version  Show package version",
+        ].join("\n"));
+        process.exit(0);
+    }
+    else if (args.includes("--version") || args.includes("-v")) {
+        console.log(PACKAGE_VERSION);
+        process.exit(0);
+    }
+    else {
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            console.error([
+                "Agent Wonderland MCP server is running.",
+                "This process speaks MCP over stdio, so it waits for a client instead of printing a prompt.",
+                "Add it to an MCP client config, or press Ctrl+C to stop.",
+                "Run `npx @agentwonderland/mcp setup` to configure your MCP clients.",
+            ].join("\n"));
+        }
+        startMcpServer().catch((err) => {
+            console.error("MCP server error:", err);
+            process.exit(1);
+        });
+    }
 }

package/dist/setup.d.ts

@@ -0,0 +1,36 @@
+export declare const SERVER_NAME = "agentwonderland";
+export declare const SERVER_CONFIG: {
+    command: string;
+    args: string[];
+};
+export type SetupClientId = "codex" | "claude-code" | "claude-desktop" | "cursor" | "antigravity";
+type ConfigFormat = "json" | "toml" | "claude-code-cli";
+export type SetupClient = {
+    id: SetupClientId;
+    name: string;
+    path: string;
+    format: ConfigFormat;
+    detected: boolean;
+    note: string;
+};
+export type SetupOptions = {
+    all?: boolean;
+    yes?: boolean;
+    clients?: SetupClientId[];
+    dryRun?: boolean;
+};
+export type InstallResult = {
+    client: SetupClient;
+    status: "created" | "updated" | "unchanged" | "skipped" | "failed";
+    backupPath?: string;
+    message?: string;
+};
+export declare function runSetupCli(args?: string[]): Promise<void>;
+export declare function parseSetupArgs(args: string[]): SetupOptions & {
+    help?: boolean;
+};
+export declare function getSetupClients(home?: string, env?: NodeJS.ProcessEnv): SetupClient[];
+export declare function installClient(client: SetupClient, options?: SetupOptions): Promise<InstallResult>;
+export declare function mergeJsonMcpConfig(existing: string): string;
+export declare function mergeCodexTomlConfig(existing: string): string;
+export {};

package/dist/setup.js

@@ -0,0 +1,346 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync } from "node:child_process";
+export const SERVER_NAME = "agentwonderland";
+export const SERVER_CONFIG = {
+    command: "npx",
+    args: ["-y", "@agentwonderland/mcp"],
+};
+const CLIENT_ORDER = [
+    "codex",
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "antigravity",
+];
+const CLIENT_LABELS = {
+    codex: "Codex",
+    "claude-code": "Claude Code",
+    "claude-desktop": "Claude Desktop",
+    cursor: "Cursor",
+    antigravity: "Google Antigravity",
+};
+export async function runSetupCli(args = process.argv.slice(2)) {
+    const options = parseSetupArgs(args);
+    if (options.help) {
+        printSetupHelp();
+        return;
+    }
+    const clients = getSetupClients();
+    const selected = await chooseClients(clients, options);
+    if (selected.length === 0) {
+        console.log("No MCP clients selected. Nothing changed.");
+        printManualConfig();
+        return;
+    }
+    console.log("");
+    console.log("Agent Wonderland will add this MCP server entry:");
+    console.log(JSON.stringify({ mcpServers: { [SERVER_NAME]: SERVER_CONFIG } }, null, 2));
+    console.log("");
+    const results = [];
+    for (const client of selected) {
+        results.push(await installClient(client, options));
+    }
+    printResults(results, options);
+}
+export function parseSetupArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else if (arg === "--all") {
+            options.all = true;
+        }
+        else if (arg === "--yes" || arg === "-y") {
+            options.yes = true;
+        }
+        else if (arg === "--dry-run") {
+            options.dryRun = true;
+        }
+        else if (arg === "--clients") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--clients requires a comma-separated value");
+            options.clients = parseClientList(value);
+            index++;
+        }
+        else if (arg.startsWith("--clients=")) {
+            options.clients = parseClientList(arg.slice("--clients=".length));
+        }
+        else {
+            throw new Error(`Unknown setup option: ${arg}`);
+        }
+    }
+    return options;
+}
+function parseClientList(value) {
+    const selected = value
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+    const invalid = selected.filter((item) => !CLIENT_ORDER.includes(item));
+    if (invalid.length > 0) {
+        throw new Error(`Unknown client(s): ${invalid.join(", ")}`);
+    }
+    return selected;
+}
+export function getSetupClients(home = homedir(), env = process.env) {
+    const appData = env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    const isWindows = platform() === "win32";
+    const isMac = platform() === "darwin";
+    const claudeDesktopPath = isMac
+        ? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+        : isWindows
+            ? path.join(appData, "Claude", "claude_desktop_config.json")
+            : path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    const clients = [
+        {
+            id: "codex",
+            name: CLIENT_LABELS.codex,
+            path: path.join(home, ".codex", "config.toml"),
+            format: "toml",
+            detected: existsSync(path.join(home, ".codex")) || commandExists("codex"),
+            note: "Global Codex CLI/Desktop config",
+        },
+        {
+            id: "claude-code",
+            name: CLIENT_LABELS["claude-code"],
+            path: "claude mcp add-json --scope user",
+            format: "claude-code-cli",
+            detected: commandExists("claude"),
+            note: "Claude Code user-scope MCP config via the Claude CLI",
+        },
+        {
+            id: "claude-desktop",
+            name: CLIENT_LABELS["claude-desktop"],
+            path: claudeDesktopPath,
+            format: "json",
+            detected: existsSync(claudeDesktopPath) || existsSync(path.dirname(claudeDesktopPath)),
+            note: "Claude Desktop developer config",
+        },
+        {
+            id: "cursor",
+            name: CLIENT_LABELS.cursor,
+            path: path.join(home, ".cursor", "mcp.json"),
+            format: "json",
+            detected: existsSync(path.join(home, ".cursor")),
+            note: "Global Cursor MCP config",
+        },
+        {
+            id: "antigravity",
+            name: CLIENT_LABELS.antigravity,
+            path: path.join(home, ".gemini", "antigravity", "mcp_config.json"),
+            format: "json",
+            detected: existsSync(path.join(home, ".gemini", "antigravity")),
+            note: "Antigravity raw MCP config",
+        },
+    ];
+    return clients;
+}
+async function chooseClients(clients, options) {
+    if (options.clients?.length) {
+        return clients.filter((client) => options.clients?.includes(client.id));
+    }
+    if (options.all) {
+        return clients;
+    }
+    const detected = clients.filter((client) => client.detected);
+    if (options.yes) {
+        return detected.length > 0 ? detected : clients.filter((client) => client.id === "codex");
+    }
+    console.log("Agent Wonderland MCP setup");
+    console.log("");
+    console.log("Detected clients:");
+    for (const client of clients) {
+        const marker = client.detected ? "found" : "not found";
+        console.log(`  ${client.id.padEnd(15)} ${marker.padEnd(9)} ${client.path}`);
+    }
+    console.log("");
+    const rl = createInterface({ input, output });
+    try {
+        const selected = [];
+        for (const client of clients) {
+            const defaultAnswer = client.detected ? "Y/n" : "y/N";
+            const answer = (await rl.question(`Install for ${client.name}? (${defaultAnswer}) `)).trim().toLowerCase();
+            const yes = answer === ""
+                ? client.detected
+                : answer === "y" || answer === "yes";
+            if (yes)
+                selected.push(client);
+        }
+        return selected;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function installClient(client, options = {}) {
+    try {
+        if (client.format === "claude-code-cli") {
+            return installClaudeCode(client, options);
+        }
+        const existing = await readExisting(client.path);
+        const next = client.format === "json"
+            ? mergeJsonMcpConfig(existing)
+            : mergeCodexTomlConfig(existing);
+        if (next === existing) {
+            return { client, status: "unchanged", message: "already configured" };
+        }
+        const backupPath = existing ? `${client.path}.bak-${timestamp()}` : undefined;
+        if (!options.dryRun) {
+            await mkdir(path.dirname(client.path), { recursive: true });
+            if (backupPath) {
+                await writeFile(backupPath, existing, "utf8");
+            }
+            await writeFile(client.path, next, "utf8");
+        }
+        return {
+            client,
+            status: existing ? "updated" : "created",
+            backupPath,
+        };
+    }
+    catch (error) {
+        return {
+            client,
+            status: "failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function installClaudeCode(client, options) {
+    if (!commandExists("claude")) {
+        return {
+            client,
+            status: "failed",
+            message: [
+                "Claude Code CLI was not found on PATH.",
+                "Run manually after installing Claude Code:",
+                `claude mcp add-json ${SERVER_NAME} '${JSON.stringify({ type: "stdio", ...SERVER_CONFIG })}' --scope user`,
+            ].join(" "),
+        };
+    }
+    if (!options.dryRun) {
+        execFileSync("claude", [
+            "mcp",
+            "add-json",
+            SERVER_NAME,
+            JSON.stringify({ type: "stdio", ...SERVER_CONFIG }),
+            "--scope",
+            "user",
+        ], { stdio: "pipe" });
+    }
+    return {
+        client,
+        status: options.dryRun ? "skipped" : "updated",
+        message: options.dryRun ? "would run Claude Code CLI installer" : "installed with Claude Code CLI",
+    };
+}
+async function readExisting(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+export function mergeJsonMcpConfig(existing) {
+    const parsed = existing.trim()
+        ? JSON.parse(existing)
+        : {};
+    const mcpServers = typeof parsed.mcpServers === "object" && parsed.mcpServers !== null && !Array.isArray(parsed.mcpServers)
+        ? parsed.mcpServers
+        : {};
+    const next = {
+        ...parsed,
+        mcpServers: {
+            ...mcpServers,
+            [SERVER_NAME]: SERVER_CONFIG,
+        },
+    };
+    return `${JSON.stringify(next, null, 2)}\n`;
+}
+export function mergeCodexTomlConfig(existing) {
+    const block = [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `command = "npx"`,
+        `args = ["-y", "@agentwonderland/mcp"]`,
+        "",
+    ].join("\n");
+    const pattern = new RegExp(`\\n?\\[mcp_servers\\.${SERVER_NAME.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\n\\[[^\\]]+\\]|$)`);
+    const trimmed = existing.trimEnd();
+    if (!trimmed)
+        return block;
+    if (pattern.test(trimmed)) {
+        const next = trimmed.replace(pattern, `\n${block.trimEnd()}`);
+        return `${next.trimEnd()}\n`;
+    }
+    return `${trimmed}\n\n${block}`;
+}
+function printResults(results, options) {
+    console.log(options.dryRun ? "Dry run complete:" : "Setup complete:");
+    for (const result of results) {
+        const suffix = result.backupPath ? ` (backup: ${result.backupPath})` : "";
+        const detail = result.message ? ` - ${result.message}` : "";
+        console.log(`  ${result.status.padEnd(9)} ${result.client.name}: ${result.client.path}${suffix}${detail}`);
+    }
+    console.log("");
+    console.log("Restart any clients you updated, then ask your coding agent:");
+    console.log('  "Check my Agent Wonderland wallet status."');
+    console.log("");
+    console.log("If no wallet is configured yet, ask:");
+    console.log('  "Set up payment for Agent Wonderland."');
+}
+function printSetupHelp() {
+    console.log([
+        "Agent Wonderland MCP setup",
+        "",
+        "Usage:",
+        "  npx @agentwonderland/mcp setup",
+        "  npx @agentwonderland/mcp setup --clients codex,claude-code",
+        "  npx @agentwonderland/mcp setup --all --yes",
+        "",
+        "Supported clients:",
+        `  ${CLIENT_ORDER.join(", ")}`,
+        "",
+        "Options:",
+        "  --clients <list>  Comma-separated client ids",
+        "  --all             Offer/install every supported config target",
+        "  -y, --yes         Accept defaults without prompts",
+        "  --dry-run         Show what would be changed without writing files",
+        "  -h, --help        Show this help",
+    ].join("\n"));
+}
+function printManualConfig() {
+    console.log("");
+    console.log("Manual MCP config:");
+    console.log(JSON.stringify({ mcpServers: { [SERVER_NAME]: SERVER_CONFIG } }, null, 2));
+}
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function commandExists(command) {
+    try {
+        if (platform() === "win32") {
+            execFileSync("where", [command], { stdio: "ignore" });
+        }
+        else {
+            execFileSync("sh", ["-lc", `command -v ${shellQuote(command)}`], { stdio: "ignore" });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {
-    "agentwonderland-mcp": "./dist/index.js"
+    "agentwonderland-mcp": "dist/index.js"
   },
   "exports": {
     ".": {

package/src/core/__tests__/api-client.test.ts

@@ -72,7 +72,7 @@ describe("api-client headers", () => {
           "X-AW-Rebate-Principal":
             "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
           "X-AW-Surface": "mcp",
-          "X-AW-MCP-Version": "0.1.37",
+          "X-AW-MCP-Version": "0.1.41",
           "X-AW-MCP-Tool": "run_agent",
           "X-AW-MCP-Action": "execute",
         }),

package/src/core/__tests__/setup.test.ts

@@ -0,0 +1,88 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  installClient,
+  mergeCodexTomlConfig,
+  mergeJsonMcpConfig,
+  parseSetupArgs,
+  type SetupClient,
+} from "../../setup.js";
+
+let tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })));
+  tempDirs = [];
+});
+
+describe("MCP setup", () => {
+  it("merges the server into existing JSON MCP config", () => {
+    const next = JSON.parse(mergeJsonMcpConfig(JSON.stringify({
+      mcpServers: {
+        existing: { command: "node", args: ["server.js"] },
+      },
+      otherSetting: true,
+    })));
+
+    expect(next.otherSetting).toBe(true);
+    expect(next.mcpServers.existing.command).toBe("node");
+    expect(next.mcpServers.agentwonderland).toEqual({
+      command: "npx",
+      args: ["-y", "@agentwonderland/mcp"],
+    });
+  });
+
+  it("replaces an existing Codex TOML block without disturbing other servers", () => {
+    const next = mergeCodexTomlConfig([
+      "[mcp_servers.other]",
+      'command = "node"',
+      'args = ["other.js"]',
+      "",
+      "[mcp_servers.agentwonderland]",
+      'command = "old"',
+      'args = ["old"]',
+      "",
+      "[model_provider.openai]",
+      'name = "OpenAI"',
+      "",
+    ].join("\n"));
+
+    expect(next).toContain("[mcp_servers.other]");
+    expect(next).toContain("[mcp_servers.agentwonderland]");
+    expect(next).toContain('command = "npx"');
+    expect(next).toContain('args = ["-y", "@agentwonderland/mcp"]');
+    expect(next).not.toContain('command = "old"');
+    expect(next).toContain("[model_provider.openai]");
+  });
+
+  it("writes config and creates a backup when updating", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "aw-mcp-setup-"));
+    tempDirs.push(dir);
+    const configPath = path.join(dir, "mcp.json");
+    await writeFile(configPath, JSON.stringify({ mcpServers: { old: { command: "node" } } }), "utf8");
+    const client: SetupClient = {
+      id: "cursor",
+      name: "Cursor",
+      path: configPath,
+      format: "json",
+      detected: true,
+      note: "test",
+    };
+
+    const result = await installClient(client);
+    const written = JSON.parse(await readFile(configPath, "utf8"));
+
+    expect(result.status).toBe("updated");
+    expect(result.backupPath).toBeTruthy();
+    expect(written.mcpServers.agentwonderland.args).toEqual(["-y", "@agentwonderland/mcp"]);
+  });
+
+  it("parses client selection flags", () => {
+    expect(parseSetupArgs(["--clients", "codex,cursor", "--yes"])).toEqual({
+      clients: ["codex", "cursor"],
+      yes: true,
+    });
+  });
+});

package/src/core/api-client.ts

@@ -29,7 +29,7 @@ interface RequestOptions {
   extraHeaders?: Record<string, string>;
 }
 
-const MCP_VERSION = "0.1.37";
+const MCP_VERSION = "0.1.41";
 
 function inferToolHeaders(path: string, method: string): Record<string, string> {
   if (path === "/solve") {

package/src/index.ts

@@ -25,6 +25,9 @@ import { registerJobResources } from "./resources/jobs.js";
 
 // ── Prompts ──────────────────────────────────────────────────────
 import { registerPrompts } from "./prompts/index.js";
+import { runSetupCli } from "./setup.js";
+
+const PACKAGE_VERSION = "0.1.41";
 
 export async function startMcpServer(): Promise<void> {
   const server = new McpServer(
@@ -108,8 +111,49 @@ const isCli =
   process.argv[1]?.includes("packages/mcp");
 
 if (isCli) {
-  startMcpServer().catch((err) => {
-    console.error("MCP server error:", err);
-    process.exit(1);
-  });
+  const args = process.argv.slice(2);
+
+  if (args[0] === "setup" || args[0] === "install" || args[0] === "configure") {
+    runSetupCli(args.slice(1)).catch((err) => {
+      console.error("Setup failed:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    });
+  } else if (args.includes("--help") || args.includes("-h")) {
+    console.log([
+      "Agent Wonderland MCP server",
+      "",
+      "Usage:",
+      "  npx @agentwonderland/mcp setup      Configure MCP clients",
+      "  npx @agentwonderland/mcp            Start the stdio MCP server",
+      "",
+      "The bare command starts a stdio MCP server. It is meant to be launched by",
+      "Codex, Cursor, Claude Desktop, or another MCP client. When run directly",
+      "in a terminal it waits silently for MCP JSON-RPC messages on stdin.",
+      "",
+      "MCP client config:",
+      '  { "mcpServers": { "agentwonderland": { "command": "npx", "args": ["-y", "@agentwonderland/mcp"] } } }',
+      "",
+      "Options:",
+      "  -h, --help     Show this help",
+      "  -v, --version  Show package version",
+    ].join("\n"));
+    process.exit(0);
+  } else if (args.includes("--version") || args.includes("-v")) {
+    console.log(PACKAGE_VERSION);
+    process.exit(0);
+  } else {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      console.error([
+        "Agent Wonderland MCP server is running.",
+        "This process speaks MCP over stdio, so it waits for a client instead of printing a prompt.",
+        "Add it to an MCP client config, or press Ctrl+C to stop.",
+        "Run `npx @agentwonderland/mcp setup` to configure your MCP clients.",
+      ].join("\n"));
+    }
+
+    startMcpServer().catch((err) => {
+      console.error("MCP server error:", err);
+      process.exit(1);
+    });
+  }
 }

package/src/setup.ts

@@ -0,0 +1,411 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync } from "node:child_process";
+
+export const SERVER_NAME = "agentwonderland";
+export const SERVER_CONFIG = {
+  command: "npx",
+  args: ["-y", "@agentwonderland/mcp"],
+};
+
+export type SetupClientId =
+  | "codex"
+  | "claude-code"
+  | "claude-desktop"
+  | "cursor"
+  | "antigravity";
+
+type ConfigFormat = "json" | "toml" | "claude-code-cli";
+
+export type SetupClient = {
+  id: SetupClientId;
+  name: string;
+  path: string;
+  format: ConfigFormat;
+  detected: boolean;
+  note: string;
+};
+
+export type SetupOptions = {
+  all?: boolean;
+  yes?: boolean;
+  clients?: SetupClientId[];
+  dryRun?: boolean;
+};
+
+export type InstallResult = {
+  client: SetupClient;
+  status: "created" | "updated" | "unchanged" | "skipped" | "failed";
+  backupPath?: string;
+  message?: string;
+};
+
+const CLIENT_ORDER: SetupClientId[] = [
+  "codex",
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "antigravity",
+];
+
+const CLIENT_LABELS: Record<SetupClientId, string> = {
+  codex: "Codex",
+  "claude-code": "Claude Code",
+  "claude-desktop": "Claude Desktop",
+  cursor: "Cursor",
+  antigravity: "Google Antigravity",
+};
+
+export async function runSetupCli(args: string[] = process.argv.slice(2)): Promise<void> {
+  const options = parseSetupArgs(args);
+  if (options.help) {
+    printSetupHelp();
+    return;
+  }
+
+  const clients = getSetupClients();
+  const selected = await chooseClients(clients, options);
+
+  if (selected.length === 0) {
+    console.log("No MCP clients selected. Nothing changed.");
+    printManualConfig();
+    return;
+  }
+
+  console.log("");
+  console.log("Agent Wonderland will add this MCP server entry:");
+  console.log(JSON.stringify({ mcpServers: { [SERVER_NAME]: SERVER_CONFIG } }, null, 2));
+  console.log("");
+
+  const results: InstallResult[] = [];
+  for (const client of selected) {
+    results.push(await installClient(client, options));
+  }
+
+  printResults(results, options);
+}
+
+export function parseSetupArgs(args: string[]): SetupOptions & { help?: boolean } {
+  const options: SetupOptions & { help?: boolean } = {};
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--all") {
+      options.all = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--clients") {
+      const value = args[index + 1];
+      if (!value) throw new Error("--clients requires a comma-separated value");
+      options.clients = parseClientList(value);
+      index++;
+    } else if (arg.startsWith("--clients=")) {
+      options.clients = parseClientList(arg.slice("--clients=".length));
+    } else {
+      throw new Error(`Unknown setup option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parseClientList(value: string): SetupClientId[] {
+  const selected = value
+    .split(",")
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean) as SetupClientId[];
+  const invalid = selected.filter((item) => !CLIENT_ORDER.includes(item));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown client(s): ${invalid.join(", ")}`);
+  }
+  return selected;
+}
+
+export function getSetupClients(home = homedir(), env = process.env): SetupClient[] {
+  const appData = env.APPDATA ?? path.join(home, "AppData", "Roaming");
+  const isWindows = platform() === "win32";
+  const isMac = platform() === "darwin";
+  const claudeDesktopPath = isMac
+    ? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    : isWindows
+      ? path.join(appData, "Claude", "claude_desktop_config.json")
+      : path.join(home, ".config", "Claude", "claude_desktop_config.json");
+
+  const clients: SetupClient[] = [
+    {
+      id: "codex",
+      name: CLIENT_LABELS.codex,
+      path: path.join(home, ".codex", "config.toml"),
+      format: "toml",
+      detected: existsSync(path.join(home, ".codex")) || commandExists("codex"),
+      note: "Global Codex CLI/Desktop config",
+    },
+    {
+      id: "claude-code",
+      name: CLIENT_LABELS["claude-code"],
+      path: "claude mcp add-json --scope user",
+      format: "claude-code-cli",
+      detected: commandExists("claude"),
+      note: "Claude Code user-scope MCP config via the Claude CLI",
+    },
+    {
+      id: "claude-desktop",
+      name: CLIENT_LABELS["claude-desktop"],
+      path: claudeDesktopPath,
+      format: "json",
+      detected: existsSync(claudeDesktopPath) || existsSync(path.dirname(claudeDesktopPath)),
+      note: "Claude Desktop developer config",
+    },
+    {
+      id: "cursor",
+      name: CLIENT_LABELS.cursor,
+      path: path.join(home, ".cursor", "mcp.json"),
+      format: "json",
+      detected: existsSync(path.join(home, ".cursor")),
+      note: "Global Cursor MCP config",
+    },
+    {
+      id: "antigravity",
+      name: CLIENT_LABELS.antigravity,
+      path: path.join(home, ".gemini", "antigravity", "mcp_config.json"),
+      format: "json",
+      detected: existsSync(path.join(home, ".gemini", "antigravity")),
+      note: "Antigravity raw MCP config",
+    },
+  ];
+
+  return clients;
+}
+
+async function chooseClients(
+  clients: SetupClient[],
+  options: SetupOptions,
+): Promise<SetupClient[]> {
+  if (options.clients?.length) {
+    return clients.filter((client) => options.clients?.includes(client.id));
+  }
+
+  if (options.all) {
+    return clients;
+  }
+
+  const detected = clients.filter((client) => client.detected);
+  if (options.yes) {
+    return detected.length > 0 ? detected : clients.filter((client) => client.id === "codex");
+  }
+
+  console.log("Agent Wonderland MCP setup");
+  console.log("");
+  console.log("Detected clients:");
+  for (const client of clients) {
+    const marker = client.detected ? "found" : "not found";
+    console.log(`  ${client.id.padEnd(15)} ${marker.padEnd(9)} ${client.path}`);
+  }
+  console.log("");
+
+  const rl = createInterface({ input, output });
+  try {
+    const selected: SetupClient[] = [];
+    for (const client of clients) {
+      const defaultAnswer = client.detected ? "Y/n" : "y/N";
+      const answer = (await rl.question(`Install for ${client.name}? (${defaultAnswer}) `)).trim().toLowerCase();
+      const yes = answer === ""
+        ? client.detected
+        : answer === "y" || answer === "yes";
+      if (yes) selected.push(client);
+    }
+    return selected;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function installClient(client: SetupClient, options: SetupOptions = {}): Promise<InstallResult> {
+  try {
+    if (client.format === "claude-code-cli") {
+      return installClaudeCode(client, options);
+    }
+
+    const existing = await readExisting(client.path);
+    const next = client.format === "json"
+      ? mergeJsonMcpConfig(existing)
+      : mergeCodexTomlConfig(existing);
+
+    if (next === existing) {
+      return { client, status: "unchanged", message: "already configured" };
+    }
+
+    const backupPath = existing ? `${client.path}.bak-${timestamp()}` : undefined;
+    if (!options.dryRun) {
+      await mkdir(path.dirname(client.path), { recursive: true });
+      if (backupPath) {
+        await writeFile(backupPath, existing, "utf8");
+      }
+      await writeFile(client.path, next, "utf8");
+    }
+
+    return {
+      client,
+      status: existing ? "updated" : "created",
+      backupPath,
+    };
+  } catch (error) {
+    return {
+      client,
+      status: "failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function installClaudeCode(client: SetupClient, options: SetupOptions): InstallResult {
+  if (!commandExists("claude")) {
+    return {
+      client,
+      status: "failed",
+      message: [
+        "Claude Code CLI was not found on PATH.",
+        "Run manually after installing Claude Code:",
+        `claude mcp add-json ${SERVER_NAME} '${JSON.stringify({ type: "stdio", ...SERVER_CONFIG })}' --scope user`,
+      ].join(" "),
+    };
+  }
+
+  if (!options.dryRun) {
+    execFileSync("claude", [
+      "mcp",
+      "add-json",
+      SERVER_NAME,
+      JSON.stringify({ type: "stdio", ...SERVER_CONFIG }),
+      "--scope",
+      "user",
+    ], { stdio: "pipe" });
+  }
+
+  return {
+    client,
+    status: options.dryRun ? "skipped" : "updated",
+    message: options.dryRun ? "would run Claude Code CLI installer" : "installed with Claude Code CLI",
+  };
+}
+
+async function readExisting(filePath: string): Promise<string> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+export function mergeJsonMcpConfig(existing: string): string {
+  const parsed = existing.trim()
+    ? JSON.parse(existing) as Record<string, unknown>
+    : {};
+
+  const mcpServers = typeof parsed.mcpServers === "object" && parsed.mcpServers !== null && !Array.isArray(parsed.mcpServers)
+    ? parsed.mcpServers as Record<string, unknown>
+    : {};
+
+  const next = {
+    ...parsed,
+    mcpServers: {
+      ...mcpServers,
+      [SERVER_NAME]: SERVER_CONFIG,
+    },
+  };
+
+  return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+export function mergeCodexTomlConfig(existing: string): string {
+  const block = [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = "npx"`,
+    `args = ["-y", "@agentwonderland/mcp"]`,
+    "",
+  ].join("\n");
+
+  const pattern = new RegExp(
+    `\\n?\\[mcp_servers\\.${SERVER_NAME.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\n\\[[^\\]]+\\]|$)`,
+  );
+
+  const trimmed = existing.trimEnd();
+  if (!trimmed) return block;
+  if (pattern.test(trimmed)) {
+    const next = trimmed.replace(pattern, `\n${block.trimEnd()}`);
+    return `${next.trimEnd()}\n`;
+  }
+  return `${trimmed}\n\n${block}`;
+}
+
+function printResults(results: InstallResult[], options: SetupOptions): void {
+  console.log(options.dryRun ? "Dry run complete:" : "Setup complete:");
+  for (const result of results) {
+    const suffix = result.backupPath ? ` (backup: ${result.backupPath})` : "";
+    const detail = result.message ? ` - ${result.message}` : "";
+    console.log(`  ${result.status.padEnd(9)} ${result.client.name}: ${result.client.path}${suffix}${detail}`);
+  }
+  console.log("");
+  console.log("Restart any clients you updated, then ask your coding agent:");
+  console.log('  "Check my Agent Wonderland wallet status."');
+  console.log("");
+  console.log("If no wallet is configured yet, ask:");
+  console.log('  "Set up payment for Agent Wonderland."');
+}
+
+function printSetupHelp(): void {
+  console.log([
+    "Agent Wonderland MCP setup",
+    "",
+    "Usage:",
+    "  npx @agentwonderland/mcp setup",
+    "  npx @agentwonderland/mcp setup --clients codex,claude-code",
+    "  npx @agentwonderland/mcp setup --all --yes",
+    "",
+    "Supported clients:",
+    `  ${CLIENT_ORDER.join(", ")}`,
+    "",
+    "Options:",
+    "  --clients <list>  Comma-separated client ids",
+    "  --all             Offer/install every supported config target",
+    "  -y, --yes         Accept defaults without prompts",
+    "  --dry-run         Show what would be changed without writing files",
+    "  -h, --help        Show this help",
+  ].join("\n"));
+}
+
+function printManualConfig(): void {
+  console.log("");
+  console.log("Manual MCP config:");
+  console.log(JSON.stringify({ mcpServers: { [SERVER_NAME]: SERVER_CONFIG } }, null, 2));
+}
+
+function timestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function commandExists(command: string): boolean {
+  try {
+    if (platform() === "win32") {
+      execFileSync("where", [command], { stdio: "ignore" });
+    } else {
+      execFileSync("sh", ["-lc", `command -v ${shellQuote(command)}`], { stdio: "ignore" });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}