@agentwonderland/mcp 0.1.1

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// ── Tools ────────────────────────────────────────────────────────
+import { registerSearchTools } from "./tools/search.js";
+import { registerRunTools } from "./tools/run.js";
+import { registerSolveTools } from "./tools/solve.js";
+import { registerAgentInfoTools } from "./tools/agent-info.js";
+import { registerJobTools } from "./tools/jobs.js";
+import { registerRateTools } from "./tools/rate.js";
+import { registerWalletTools } from "./tools/wallet.js";
+import { registerFavoriteTools } from "./tools/favorites.js";
+import { registerTipTools } from "./tools/tip.js";
+// ── Resources ────────────────────────────────────────────────────
+import { registerAgentResources } from "./resources/agents.js";
+import { registerWalletResources } from "./resources/wallet.js";
+import { registerJobResources } from "./resources/jobs.js";
+// ── Prompts ──────────────────────────────────────────────────────
+import { registerPrompts } from "./prompts/index.js";
+export async function startMcpServer() {
+    const server = new McpServer({
+        name: "agentwonderland",
+        version: "0.2.0",
+    });
+    // Register tools
+    registerSearchTools(server);
+    registerRunTools(server);
+    registerSolveTools(server);
+    registerAgentInfoTools(server);
+    registerJobTools(server);
+    registerRateTools(server);
+    registerWalletTools(server);
+    registerFavoriteTools(server);
+    registerTipTools(server);
+    // Register resources
+    registerAgentResources(server);
+    registerWalletResources(server);
+    registerJobResources(server);
+    // Register prompts
+    registerPrompts(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// ── Direct execution ─────────────────────────────────────────────
+// When run as a binary (agentwonderland-mcp), start the server immediately.
+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);
+    });
+}

package/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts/index.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.prompt("get-started", "Get started with Agent Wonderland — check wallet, discover agents, learn the tools", {}, async () => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Help me get started with Agent Wonderland.",
+                        "",
+                        "Please:",
+                        "1. Check my wallet status with wallet_status",
+                        "2. If no wallet is configured, help me create one with wallet_setup",
+                        "3. Show me some popular agents with search_agents",
+                        "4. Briefly explain how solve, run_agent, rating, and tipping work",
+                    ].join("\n"),
+                },
+            }],
+    }));
+    server.prompt("wallet-setup", "Create and fund a wallet for paying agents", {}, async () => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "Help me set up a payment wallet for Agent Wonderland.",
+                        "",
+                        "Please:",
+                        "1. Check if I already have a wallet with wallet_status",
+                        "2. If not, create one with wallet_setup",
+                        "3. Show me the address I need to fund",
+                        "4. Explain what USDC I need and on which network (Tempo, Base, or Solana)",
+                    ].join("\n"),
+                },
+            }],
+    }));
+    server.prompt("find-agent", "Find the best agent for a task", { task: z.string().describe("What you need done") }, async ({ task }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Find the best agent on Agent Wonderland for this task: "${task}"`,
+                        "",
+                        "Steps:",
+                        "1. Use search_agents to find relevant agents",
+                        "2. Use compare_agents on the top 2-3 candidates",
+                        "3. Recommend the best one based on price, rating, and success rate",
+                        "4. Ask if I want to run it",
+                    ].join("\n"),
+                },
+            }],
+    }));
+    server.prompt("budget-run", "Complete a task within a budget", {
+        task: z.string().describe("What you need done"),
+        budget: z.string().optional().describe("Max spend in USD (default: $1)"),
+    }, async ({ task, budget }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Complete this task on Agent Wonderland within $${budget || "1.00"}: "${task}"`,
+                        "",
+                        "Use the solve tool with the budget parameter. Show me what agent was selected and why.",
+                    ].join("\n"),
+                },
+            }],
+    }));
+    server.prompt("run-with-review", "Run an agent and review the output", {
+        agent_id: z.string().describe("Agent ID to run"),
+        input: z.string().describe("JSON input for the agent"),
+    }, async ({ agent_id, input }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Run agent ${agent_id} with this input: ${input}`,
+                        "",
+                        "After getting the result:",
+                        "1. Summarize the output",
+                        "2. Assess the quality",
+                        "3. Ask if I want to rate the agent",
+                    ].join("\n"),
+                },
+            }],
+    }));
+}

package/dist/resources/agents.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAgentResources(server: McpServer): void;

package/dist/resources/agents.js

@@ -0,0 +1,34 @@
+import { apiGet } from "../core/api-client.js";
+import { formatPrice, stars, compactNumber } from "../core/formatters.js";
+export function registerAgentResources(server) {
+    // Agent directory — browsable list of all agents
+    server.resource("agent-directory", "aw://agents", async () => {
+        const agents = await apiGet("/agents?limit=50");
+        const lines = agents.map(a => {
+            const rating = stars(a.reputationScore);
+            const jobs = compactNumber(a.totalExecutions);
+            const price = formatPrice(a.pricePer1kTokens);
+            return `${a.name} ${rating} ${jobs} jobs | ${price}/req — ${a.description || ""}`;
+        });
+        return {
+            contents: [{
+                    uri: "aw://agents",
+                    mimeType: "text/plain",
+                    text: `Agent Wonderland Marketplace (${agents.length} agents)\n\n${lines.join("\n")}`,
+                }],
+        };
+    });
+    // Agent schema — input schema for a specific agent
+    server.resource("agent-schema", "aw://agents/{id}/schema", async (uri) => {
+        const id = uri.pathname?.split("/").pop() || uri.href.split("/").pop()?.split("?")[0];
+        const agent = await apiGet(`/agents/${id}`);
+        const schema = agent.mcpSchema ? JSON.stringify(agent.mcpSchema, null, 2) : "No schema defined";
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: schema,
+                }],
+        };
+    });
+}

package/dist/resources/jobs.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerJobResources(server: McpServer): void;

package/dist/resources/jobs.js

@@ -0,0 +1,15 @@
+import { apiGet } from "../core/api-client.js";
+import { formatRunResult } from "../core/formatters.js";
+export function registerJobResources(server) {
+    server.resource("job-result", "aw://jobs/{id}", async (uri) => {
+        const id = uri.pathname?.split("/").pop() || uri.href.split("/").pop()?.split("?")[0];
+        const job = await apiGet(`/jobs/${id}`);
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "text/plain",
+                    text: formatRunResult(job),
+                }],
+        };
+    });
+}

package/dist/resources/wallet.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerWalletResources(server: McpServer): void;

package/dist/resources/wallet.js

@@ -0,0 +1,26 @@
+import { getWallets, getCardConfig } from "../core/config.js";
+import { getWalletAddress, getConfiguredMethods } from "../core/payments.js";
+export function registerWalletResources(server) {
+    server.resource("wallet-config", "aw://wallet", async () => {
+        const wallets = getWallets();
+        const card = getCardConfig();
+        const methods = getConfiguredMethods();
+        const lines = ["Wallet Configuration", ""];
+        for (const w of wallets) {
+            const addr = await getWalletAddress(w.id);
+            const storage = w.keyType === "ows" ? "[encrypted]" : "[plaintext]";
+            lines.push(`${w.id} ${storage}: ${w.chains.join(", ")} — ${addr}`);
+        }
+        if (card) {
+            lines.push(`Card: ${card.brand} ****${card.last4}`);
+        }
+        lines.push("", `Configured methods: ${methods.join(", ") || "none"}`);
+        return {
+            contents: [{
+                    uri: "aw://wallet",
+                    mimeType: "text/plain",
+                    text: lines.join("\n"),
+                }],
+        };
+    });
+}

package/dist/tools/_token-cache.d.ts

@@ -0,0 +1,5 @@
+export declare function storeFeedbackToken(jobId: string, token: string, agentId: string): void;
+export declare function getFeedbackToken(jobId: string): {
+    token: string;
+    agent_id: string;
+} | undefined;

package/dist/tools/_token-cache.js

@@ -0,0 +1,9 @@
+// Feedback token cache — stores tokens from recent run/solve results
+// Tokens expire after 1 hour on the server, so no need for client-side cleanup
+const cache = new Map();
+export function storeFeedbackToken(jobId, token, agentId) {
+    cache.set(jobId, { token, agent_id: agentId });
+}
+export function getFeedbackToken(jobId) {
+    return cache.get(jobId);
+}

package/dist/tools/agent-info.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAgentInfoTools(server: McpServer): void;

package/dist/tools/agent-info.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { apiGet } from "../core/api-client.js";
+import { formatPrice, stars, compactNumber, outputTypeHint, agentWebUrl, formatFeedbackSummary, formatLastActive } from "../core/formatters.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerAgentInfoTools(server) {
+    // ── get_agent (renamed from agent_profile) ──────────────────────
+    server.tool("get_agent", "Get detailed information about a specific agent including description, pricing, success rate, latency, and tags.", {
+        agent_id: z.string().describe("Agent ID (UUID) or slug"),
+    }, async ({ agent_id }) => {
+        const a = await apiGet(`/agents/${agent_id}`);
+        const s = (a.stats ?? {});
+        const payment = (a.payment ?? {});
+        const _pricing = (payment.pricing ?? {});
+        const lines = [
+            `${a.name}`,
+            `${stars(a.avgRating ?? s.avgRating)} (${s.ratingCount ?? 0} reviews) • ${compactNumber((s.completedJobs ?? a.totalExecutions ?? 0))} jobs`,
+            "",
+            a.description ?? "",
+            "",
+            `Pricing: ${formatPrice(a.pricePer1kTokens, a.pricingModel)}`,
+            `Reliability: ${a.successRate != null ? (Number(a.successRate) * 100).toFixed(0) + "%" : "N/A"}`,
+            `Avg latency: ${a.avgResponseTimeMs != null ? a.avgResponseTimeMs + "ms" : "N/A"}`,
+            ...(() => {
+                const lastActive = formatLastActive(a.lastActiveAt);
+                return lastActive ? [lastActive] : [];
+            })(),
+            "",
+            `Tags: ${a.tags?.join(", ") ?? "none"}`,
+            ...(() => {
+                const hint = outputTypeHint(a.tags);
+                return hint ? [`Output: ${hint}`] : [];
+            })(),
+        ];
+        // Feedback summary (rating + tips)
+        const feedbackSummary = formatFeedbackSummary(s);
+        if (feedbackSummary) {
+            lines.push("", feedbackSummary);
+        }
+        // Fetch recent reviews with comments
+        try {
+            const reviews = await apiGet(`/agents/${a.id}/reviews?limit=3&sort=recent`);
+            const withComments = reviews.reviews?.filter((r) => r.comment);
+            if (withComments?.length) {
+                lines.push("", "Recent reviews:");
+                for (const r of withComments) {
+                    lines.push(`  ${stars(r.rating)} "${r.comment}"`);
+                }
+            }
+        }
+        catch {
+            // Reviews endpoint may not be available
+        }
+        // Input schema — show what fields the agent accepts
+        const schema = a.schema?.input;
+        const inputSchema = (schema?.inputSchema ?? a.mcpSchema?.inputSchema);
+        if (inputSchema?.properties) {
+            const props = inputSchema.properties;
+            const required = new Set(inputSchema.required ?? []);
+            lines.push("", "Input fields:");
+            for (const [name, def] of Object.entries(props)) {
+                const req = required.has(name) ? " (required)" : "";
+                const desc = def.description ? ` — ${def.description}` : "";
+                lines.push(`  ${name}: ${def.type ?? "string"}${req}${desc}`);
+            }
+        }
+        lines.push("", `ID: ${a.id}`, `View: ${agentWebUrl(a.id)}`);
+        return text(lines.join("\n"));
+    });
+    // ── compare_agents ──────────────────────────────────────────────
+    server.tool("compare_agents", "Compare multiple agents side-by-side on rating, price, success rate, and job count.", {
+        agent_ids: z
+            .array(z.string())
+            .min(2)
+            .max(5)
+            .describe("Agent IDs to compare (2-5)"),
+    }, async ({ agent_ids }) => {
+        const agents = await Promise.all(agent_ids.map((id) => apiGet(`/agents/${id}`)));
+        const header = "Agent Comparison:\n";
+        const lines = agents.map((a) => {
+            const s = (a.stats ?? {});
+            const rating = a.avgRating ?? s.avgRating;
+            const jobs = (s.completedJobs ?? a.totalExecutions ?? 0);
+            const tipCount = (s.tipCount ?? 0);
+            return [
+                `  ${a.name}`,
+                `  ${stars(rating)} (${s.ratingCount ?? 0} reviews)${tipCount > 0 ? ` • ${tipCount} tips` : ""}`,
+                `  ${compactNumber(jobs)} jobs • ${formatPrice(a.pricePer1kTokens, a.pricingModel)}`,
+                `  Success: ${a.successRate != null ? (Number(a.successRate) * 100).toFixed(0) + "%" : "N/A"}`,
+                `  ${agentWebUrl(a.id)}`,
+                "",
+            ].join("\n");
+        });
+        return text(header + lines.join("\n"));
+    });
+}

package/dist/tools/favorites.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFavoriteTools(server: McpServer): void;

package/dist/tools/favorites.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { getFavorites, addFavorite, removeFavorite } from "../core/config.js";
+import { apiGet } from "../core/api-client.js";
+import { formatPrice, stars, compactNumber } from "../core/formatters.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerFavoriteTools(server) {
+    // favorite_agent — add an agent to favorites
+    server.tool("favorite_agent", "Save an agent to your favorites for quick access", {
+        agent_id: z.string().describe("Agent ID to favorite"),
+    }, async ({ agent_id }) => {
+        // Verify agent exists
+        const agent = await apiGet(`/agents/${agent_id}`);
+        addFavorite(agent_id);
+        return text(`★ Added ${agent.name} to favorites`);
+    });
+    // unfavorite_agent — remove from favorites
+    server.tool("unfavorite_agent", "Remove an agent from your favorites", {
+        agent_id: z.string().describe("Agent ID to remove"),
+    }, async ({ agent_id }) => {
+        removeFavorite(agent_id);
+        return text("Removed from favorites");
+    });
+    // list_favorites — show all favorited agents with details
+    server.tool("list_favorites", "List your favorite agents", {}, async () => {
+        const ids = getFavorites();
+        if (ids.length === 0) {
+            return text("No favorites yet. Use favorite_agent to save agents you like.");
+        }
+        const lines = ["Your favorite agents:", ""];
+        for (const id of ids) {
+            try {
+                const agent = await apiGet(`/agents/${id}`);
+                const rating = stars(agent.avgRating);
+                const jobs = compactNumber(agent.totalExecutions);
+                const price = formatPrice(agent.pricePer1kTokens, agent.pricingModel);
+                lines.push(`${agent.name} ${rating} ${jobs} jobs | ${price}`);
+                lines.push(`  ID: ${id}`);
+                if (agent.description)
+                    lines.push(`  ${agent.description}`);
+                lines.push("");
+            }
+            catch {
+                lines.push(`${id} (not found — may have been removed)`);
+                lines.push("");
+            }
+        }
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+export { registerSearchTools } from "./search.js";
+export { registerRunTools } from "./run.js";
+export { registerSolveTools } from "./solve.js";
+export { registerAgentInfoTools } from "./agent-info.js";
+export { registerJobTools } from "./jobs.js";
+export { registerRateTools } from "./rate.js";
+export { registerWalletTools } from "./wallet.js";
+export { registerFavoriteTools } from "./favorites.js";
+export { registerTipTools } from "./tip.js";

package/dist/tools/index.js

@@ -0,0 +1,9 @@
+export { registerSearchTools } from "./search.js";
+export { registerRunTools } from "./run.js";
+export { registerSolveTools } from "./solve.js";
+export { registerAgentInfoTools } from "./agent-info.js";
+export { registerJobTools } from "./jobs.js";
+export { registerRateTools } from "./rate.js";
+export { registerWalletTools } from "./wallet.js";
+export { registerFavoriteTools } from "./favorites.js";
+export { registerTipTools } from "./tip.js";

package/dist/tools/jobs.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerJobTools(server: McpServer): void;

package/dist/tools/jobs.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { apiGet } from "../core/api-client.js";
+import { isAuthenticated } from "../core/config.js";
+import { hasWalletConfigured, getWalletAddress } from "../core/payments.js";
+import { formatRunResult } from "../core/formatters.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerJobTools(server) {
+    // ── get_job ─────────────────────────────────────────────────────
+    server.tool("get_job", "Get the status and output of a job by ID. Use to poll async jobs until they complete.", {
+        job_id: z.string().describe("Job ID (UUID)"),
+    }, async ({ job_id }) => {
+        const result = await apiGet(`/jobs/${job_id}`);
+        if (result.status === "processing") {
+            return text(`Job ${job_id} is still processing...`);
+        }
+        return text(formatRunResult(result));
+    });
+    // ── list_jobs (renamed from list_my_jobs) ───────────────────────
+    server.tool("list_jobs", "List your recent jobs with status, cost, and agent info.", {
+        limit: z.coerce.number().optional().default(10).describe("Max results (1-50)"),
+    }, async ({ limit }) => {
+        let url = `/jobs?limit=${limit ?? 10}`;
+        // If not authenticated via API key, use wallet address for lookup
+        if (!isAuthenticated() && hasWalletConfigured()) {
+            const address = await getWalletAddress();
+            if (address) {
+                url += `&wallet=${encodeURIComponent(address)}`;
+            }
+        }
+        const jobs = await apiGet(url);
+        if (jobs.length === 0)
+            return text("No jobs found.");
+        const lines = [`Recent jobs (${jobs.length}):`];
+        for (const j of jobs) {
+            const status = j.status === "completed"
+                ? "\u2713"
+                : j.status === "processing"
+                    ? "\u2026"
+                    : "\u2717";
+            const cost = j.estimated_cost != null
+                ? `$${Number(j.estimated_cost).toFixed(4)}`
+                : "";
+            lines.push(`  ${status} ${j.job_id?.slice(0, 8)}\u2026 ${j.agent_id ? String(j.agent_id).slice(0, 8) + "\u2026" : ""} ${cost}`);
+        }
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/rate.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRateTools(server: McpServer): void;

package/dist/tools/rate.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { apiPost } from "../core/api-client.js";
+import { stars } from "../core/formatters.js";
+import { getFeedbackToken } from "./_token-cache.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerRateTools(server) {
+    server.tool("rate_agent", "Rate an agent after running it. Provide the job ID from the run result. Must be used within 1 hour of running the agent.", {
+        job_id: z.string().describe("Job ID from the run result"),
+        rating: z.number().min(1).max(5).describe("Rating 1-5 stars"),
+        comment: z.string().optional().describe("Optional feedback comment"),
+    }, async ({ job_id, rating, comment }) => {
+        const tokenData = getFeedbackToken(job_id);
+        if (!tokenData) {
+            return text("No feedback token found for this job. You can only rate agents immediately after running them.");
+        }
+        try {
+            await apiPost("/feedback", {
+                job_id,
+                feedback_token: tokenData.token,
+                rating,
+                thumb: rating >= 3 ? "up" : "down",
+                ...(comment ? { comment } : {}),
+            });
+            const starStr = stars(rating);
+            return text(`${starStr} Rating submitted for job ${job_id}${comment ? ` \u2014 "${comment}"` : ""}`);
+        }
+        catch (err) {
+            const apiErr = err;
+            if (apiErr?.status === 401) {
+                return text("Feedback token expired. Ratings must be submitted within 1 hour of running the agent.");
+            }
+            if (apiErr?.status === 409) {
+                return text("You've already rated this job.");
+            }
+            if (apiErr?.status === 429) {
+                return text("You can only rate this agent once every 30 days.");
+            }
+            const msg = apiErr?.body?.error || apiErr?.message || "Rating failed";
+            return text(`Could not submit rating: ${msg}`);
+        }
+    });
+}

package/dist/tools/run.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRunTools(server: McpServer): void;

package/dist/tools/run.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { apiGet, apiPostWithPayment } from "../core/api-client.js";
+import { getConfiguredMethods, hasWalletConfigured } from "../core/payments.js";
+import { formatRunResult } from "../core/formatters.js";
+import { storeFeedbackToken } from "./_token-cache.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerRunTools(server) {
+    server.tool("run_agent", "Run an AI agent from the marketplace. Pays automatically via configured wallet. Returns the agent's output, cost, and job ID for tracking.", {
+        agent_id: z.string().describe("Agent ID (UUID or slug)"),
+        input: z.record(z.unknown()).describe("Input payload for the agent"),
+        pay_with: z.string().optional().describe("Payment method — wallet ID, chain name (tempo, base, etc.), or 'card'. Auto-detected if omitted."),
+    }, async ({ agent_id, input, pay_with }) => {
+        if (!hasWalletConfigured()) {
+            return text("No wallet configured. Set one up first:\n\n" +
+                '  wallet_setup({ action: "create", name: "my-wallet" })\n\n' +
+                "Then fund it with USDC on Tempo and try again.");
+        }
+        // Resolve slug to UUID if needed (slugs don't contain hyphens in UUID positions)
+        let resolvedId = agent_id;
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(agent_id);
+        if (!isUuid) {
+            try {
+                const agent = await apiGet(`/agents/${agent_id}`);
+                resolvedId = agent.id;
+            }
+            catch {
+                return text(`Agent "${agent_id}" not found. Use search_agents to find available agents.`);
+            }
+        }
+        const method = pay_with;
+        let result;
+        try {
+            result = await apiPostWithPayment(`/agents/${resolvedId}/run`, { input }, method);
+        }
+        catch (err) {
+            const apiErr = err;
+            if (apiErr?.status === 402) {
+                return text("Payment failed — your wallet may not have enough USDC.\n\n" +
+                    "Check your balance and fund your wallet, then try again.\n" +
+                    "Use wallet_status to check your current payment methods.");
+            }
+            const msg = apiErr?.message ?? "Failed to run agent";
+            if (msg.includes("Missing required field") || msg.includes("validation failed")) {
+                return text(`Error: ${msg}\n\nUse get_agent("${agent_id}") to see the required input fields.`);
+            }
+            return text(`Error: ${msg}`);
+        }
+        const formatted = formatRunResult(result, {
+            paymentMethod: method ?? getConfiguredMethods()[0],
+        });
+        const jobId = result.job_id ?? "";
+        const agentId = result.agent_id ?? agent_id;
+        if (result.feedback_token) {
+            storeFeedbackToken(jobId, result.feedback_token, agentId);
+        }
+        const status = result.status;
+        let prompt;
+        if (status === "success") {
+            prompt = [
+                "",
+                "---",
+                "How was this result? You can:",
+                `  • rate_agent with job_id "${jobId}" and a score (1-5) — within 1 hour`,
+                "  • tip_agent to show appreciation — within 1 hour",
+                "  • favorite_agent to save this agent for later",
+            ].join("\n");
+        }
+        else {
+            prompt = [
+                "",
+                "---",
+                "The agent execution failed. A refund has been initiated automatically",
+                "and will be returned to your wallet.",
+            ].join("\n");
+        }
+        return text(formatted + prompt);
+    });
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSearchTools(server: McpServer): void;