@gatesolve/mcp-server 0.1.1 → 0.2.1

package/dist/index.js

@@ -5,31 +5,44 @@ import { z } from "zod";
 const GATESOLVE_API = process.env.GATESOLVE_API_URL || "https://gatesolve.dev";
 const server = new McpServer({
     name: "gatesolve",
-    version: "0.1.0",
+    version: "0.2.0",
 });
 // Tool: solve_captcha
-server.tool("solve_captcha", "Solve a CAPTCHA using GateSolve. Supports Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha. Payment is handled via x402 micropayments (USDC on Base network).", {
+server.tool("solve_captcha", "Solve a CAPTCHA using GateSolve. Supports Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha. Uses async submit-poll flow. Requires GATESOLVE_API_KEY env var (free tier: 100 solves) or paymentToken for MPP.", {
     type: z
         .enum(["cloudflare-turnstile", "recaptcha-v2", "recaptcha-v3", "hcaptcha"])
         .describe("The type of CAPTCHA to solve"),
     siteKey: z.string().describe("The site key / widget key for the CAPTCHA"),
     pageUrl: z.string().url().describe("The URL of the page containing the CAPTCHA"),
+    callbackUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Optional webhook URL to receive result instead of polling"),
     paymentToken: z
         .string()
         .optional()
-        .describe("x402 payment token (USDC on Base). If omitted, returns payment requirements."),
-}, async ({ type, siteKey, pageUrl, paymentToken }) => {
+        .describe("x402 payment token (USDC on Base). If omitted, uses API key free tier."),
+}, async ({ type, siteKey, pageUrl, callbackUrl, paymentToken }) => {
     try {
+        const apiKey = process.env.GATESOLVE_API_KEY;
         const headers = {
             "Content-Type": "application/json",
         };
+        if (apiKey) {
+            headers["Authorization"] = `Bearer ${apiKey}`;
+        }
         if (paymentToken) {
             headers["X-402-Pay"] = paymentToken;
         }
-        const response = await fetch(`${GATESOLVE_API}/api/v1/solve`, {
+        // Submit solve request
+        const body = { type, siteKey, pageUrl };
+        if (callbackUrl)
+            body.callbackUrl = callbackUrl;
+        const response = await fetch(`${GATESOLVE_API}/api/solve`, {
             method: "POST",
             headers,
-            body: JSON.stringify({ type, siteKey, pageUrl }),
+            body: JSON.stringify(body),
         });
         const data = await response.json();
         if (response.status === 402) {
@@ -37,26 +50,70 @@ server.tool("solve_captcha", "Solve a CAPTCHA using GateSolve. Supports Cloudfla
                 content: [
                     {
                         type: "text",
-                        text: `Payment required to solve this CAPTCHA.\n\nPayment details:\n- Network: ${data.accepts?.network || "base"}\n- Token: ${data.accepts?.token || "USDC"}\n- Amount: ${data.accepts?.amount || "0.02"} USDC\n- Receiver: ${data.accepts?.receiver}\n- Protocol: x402 v${data.x402Version || "1.0"}\n\nProvide the payment token in the 'paymentToken' parameter to complete the solve.`,
+                        text: `Authentication required.\n\nSet GATESOLVE_API_KEY env var to your gs_xxx key (get one free at POST ${GATESOLVE_API}/api/waitlist).\n\nOr use MPP payment: ${data.mpp?.endpoint || `${GATESOLVE_API}/api/mpp/solve`}`,
+                    },
+                ],
+            };
+        }
+        if (response.status === 401) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid API key. Get a free one: POST ${GATESOLVE_API}/api/waitlist with {"email": "your@email.com"}`,
                     },
                 ],
+                isError: true,
             };
         }
-        if (response.status === 200) {
+        if (response.status !== 202) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `CAPTCHA solved successfully!\n\nToken: ${data.token}\nType: ${data.type}\nSolved in: ${data.solvedIn}\nStatus: ${data.status}`,
+                        text: `Error: ${data.message || data.error || "Unknown error"} (status: ${response.status})`,
                     },
                 ],
+                isError: true,
             };
         }
+        // Poll for result (max 60 seconds)
+        const solveId = data.id;
+        const pollUrl = `${GATESOLVE_API}/api/solve?id=${solveId}`;
+        const maxAttempts = 20;
+        for (let i = 0; i < maxAttempts; i++) {
+            await new Promise((r) => setTimeout(r, 3000));
+            const pollResp = await fetch(pollUrl);
+            const pollData = await pollResp.json();
+            if (pollData.status === "solved") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `CAPTCHA solved successfully!\n\nToken: ${pollData.token}\nType: ${pollData.type}\nSolved in: ${pollData.solvedIn}\nSolve ID: ${solveId}`,
+                        },
+                    ],
+                };
+            }
+            if (pollData.status === "failed") {
+                let failText = `CAPTCHA solve failed.\n\nSolve ID: ${solveId}\nType: ${type}`;
+                if (pollData.failure) {
+                    failText += `\nReason: ${pollData.failure.reason}`;
+                    failText += `\nSuggestion: ${pollData.failure.suggestion}`;
+                }
+                if (pollData.hint)
+                    failText += `\nHint: ${pollData.hint}`;
+                return {
+                    content: [{ type: "text", text: failText }],
+                    isError: true,
+                };
+            }
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: `Error: ${data.message || "Unknown error"} (status: ${response.status})`,
+                    text: `Solve timed out after 60 seconds. You can continue polling manually:\nGET ${pollUrl}`,
                 },
             ],
             isError: true,
@@ -74,6 +131,125 @@ server.tool("solve_captcha", "Solve a CAPTCHA using GateSolve. Supports Cloudfla
         };
     }
 });
+// Tool: detect_block
+server.tool("detect_block", "Check what kind of access block a URL has before attempting to solve. Returns classification (public-ok, js-challenge, captcha, auth-wall, blocked-silent, rate-limited, error), solvability, and recommendations. No API key required.", {
+    url: z.string().url().describe("The URL to check for access blocks"),
+}, async ({ url }) => {
+    try {
+        const response = await fetch(`${GATESOLVE_API}/api/detect?url=${encodeURIComponent(url)}`);
+        const data = await response.json();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Block Detection for ${url}:\n\nClassification: ${data.classification}\nHTTP Status: ${data.httpStatus}\nSolvable: ${data.solvable ? "Yes" : "No"}${data.captchaType ? `\nCAPTCHA Type: ${data.captchaType}` : ""}${data.confidence !== undefined ? `\nConfidence: ${(data.confidence * 100).toFixed(0)}%` : ""}${data.recommendation ? `\n\nRecommendation: ${data.recommendation}` : ""}${data.recovery ? `\nMax Retries: ${data.recovery.maxRetries}, Backoff: ${data.recovery.backoffSeconds}s` : ""}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to detect block: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: check_usage
+server.tool("check_usage", "Check your API key quota — how many solves used, remaining, and limit. Requires GATESOLVE_API_KEY environment variable.", {}, async () => {
+    const apiKey = process.env.GATESOLVE_API_KEY;
+    if (!apiKey) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "GATESOLVE_API_KEY environment variable not set. Set it to your gs_xxx API key to check usage.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        const response = await fetch(`${GATESOLVE_API}/api/v1/usage`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        const data = await response.json();
+        if (response.status === 401) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid API key. ${data.message || ""}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `GateSolve Usage:\n\nUsed: ${data.used}/${data.limit} solves\nRemaining: ${data.remaining}\nPercent Used: ${data.percentUsed}\nPlan: ${data.plan}${data.upgradeInfo ? `\n\n⚠️ ${data.upgradeInfo}` : ""}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to check usage: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: dry_run_solve
+server.tool("dry_run_solve", "Validate a CAPTCHA solve request without consuming credits or creating a job. Returns whether the request is valid, estimated time and cost, and type-specific warnings. No API key required.", {
+    type: z
+        .enum(["cloudflare-turnstile", "recaptcha-v2", "recaptcha-v3", "hcaptcha"])
+        .describe("The type of CAPTCHA to solve"),
+    siteKey: z.string().describe("The site key for the CAPTCHA"),
+    pageUrl: z.string().url().describe("The URL of the page containing the CAPTCHA"),
+}, async ({ type, siteKey, pageUrl }) => {
+    try {
+        const response = await fetch(`${GATESOLVE_API}/api/v1/solve/dry-run`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ type, siteKey, pageUrl }),
+        });
+        const data = await response.json();
+        let text = `Dry Run Result: ${data.valid ? "✅ Valid" : "❌ Invalid"}\n`;
+        if (data.issues?.length)
+            text += `\nIssues:\n${data.issues.map((i) => `- ${i}`).join("\n")}`;
+        if (data.warnings?.length)
+            text += `\nWarnings:\n${data.warnings.map((w) => `- ${w}`).join("\n")}`;
+        if (data.estimate)
+            text += `\n\nEstimate:\n- Solve time: ${data.estimate.solveTimeSeconds}s\n- Price: $${data.estimate.priceUsd} USDC\n- Method: ${data.estimate.method}`;
+        if (data.nextStep)
+            text += `\n\n${data.nextStep}`;
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to dry run: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 // Tool: list_captcha_types
 server.tool("list_captcha_types", "List all supported CAPTCHA types with pricing, accuracy, and required fields.", {}, async () => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatesolve/mcp-server",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "mcpName": "io.github.arsonx-dev/gatesolve-mcp",
   "description": "MCP server for GateSolve CAPTCHA solving via x402 micropayments",
   "type": "module",
@@ -29,5 +29,14 @@
   "devDependencies": {
     "typescript": "^5.0.0",
     "@types/node": "^20.0.0"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arsonx-dev/gatesolve-mcp"
+  },
+  "homepage": "https://gatesolve.dev",
+  "bugs": {
+    "url": "https://github.com/arsonx-dev/gatesolve-mcp/issues"
+  },
+  "author": "GateSolve <arson@agentmail.to> (https://gatesolve.dev)"
 }

package/src/index.ts

@@ -8,40 +8,53 @@ const GATESOLVE_API = process.env.GATESOLVE_API_URL || "https://gatesolve.dev";
 
 const server = new McpServer({
   name: "gatesolve",
-  version: "0.1.0",
+  version: "0.2.0",
 });
 
 // Tool: solve_captcha
 server.tool(
   "solve_captcha",
-  "Solve a CAPTCHA using GateSolve. Supports Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha. Payment is handled via x402 micropayments (USDC on Base network).",
+  "Solve a CAPTCHA using GateSolve. Supports Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha. Uses async submit-poll flow. Requires GATESOLVE_API_KEY env var (free tier: 100 solves) or paymentToken for MPP.",
   {
     type: z
       .enum(["cloudflare-turnstile", "recaptcha-v2", "recaptcha-v3", "hcaptcha"])
       .describe("The type of CAPTCHA to solve"),
     siteKey: z.string().describe("The site key / widget key for the CAPTCHA"),
     pageUrl: z.string().url().describe("The URL of the page containing the CAPTCHA"),
+    callbackUrl: z
+      .string()
+      .url()
+      .optional()
+      .describe("Optional webhook URL to receive result instead of polling"),
     paymentToken: z
       .string()
       .optional()
       .describe(
-        "x402 payment token (USDC on Base). If omitted, returns payment requirements."
+        "x402 payment token (USDC on Base). If omitted, uses API key free tier."
       ),
   },
-  async ({ type, siteKey, pageUrl, paymentToken }) => {
+  async ({ type, siteKey, pageUrl, callbackUrl, paymentToken }) => {
     try {
+      const apiKey = process.env.GATESOLVE_API_KEY;
       const headers: Record<string, string> = {
         "Content-Type": "application/json",
       };
 
+      if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+      }
       if (paymentToken) {
         headers["X-402-Pay"] = paymentToken;
       }
 
-      const response = await fetch(`${GATESOLVE_API}/api/v1/solve`, {
+      // Submit solve request
+      const body: Record<string, string> = { type, siteKey, pageUrl };
+      if (callbackUrl) body.callbackUrl = callbackUrl;
+
+      const response = await fetch(`${GATESOLVE_API}/api/solve`, {
         method: "POST",
         headers,
-        body: JSON.stringify({ type, siteKey, pageUrl }),
+        body: JSON.stringify(body),
       });
 
       const data = await response.json();
@@ -51,28 +64,76 @@ server.tool(
           content: [
             {
               type: "text" as const,
-              text: `Payment required to solve this CAPTCHA.\n\nPayment details:\n- Network: ${data.accepts?.network || "base"}\n- Token: ${data.accepts?.token || "USDC"}\n- Amount: ${data.accepts?.amount || "0.02"} USDC\n- Receiver: ${data.accepts?.receiver}\n- Protocol: x402 v${data.x402Version || "1.0"}\n\nProvide the payment token in the 'paymentToken' parameter to complete the solve.`,
+              text: `Authentication required.\n\nSet GATESOLVE_API_KEY env var to your gs_xxx key (get one free at POST ${GATESOLVE_API}/api/waitlist).\n\nOr use MPP payment: ${data.mpp?.endpoint || `${GATESOLVE_API}/api/mpp/solve`}`,
+            },
+          ],
+        };
+      }
+
+      if (response.status === 401) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Invalid API key. Get a free one: POST ${GATESOLVE_API}/api/waitlist with {"email": "your@email.com"}`,
             },
           ],
+          isError: true,
         };
       }
 
-      if (response.status === 200) {
+      if (response.status !== 202) {
         return {
           content: [
             {
               type: "text" as const,
-              text: `CAPTCHA solved successfully!\n\nToken: ${data.token}\nType: ${data.type}\nSolved in: ${data.solvedIn}\nStatus: ${data.status}`,
+              text: `Error: ${data.message || data.error || "Unknown error"} (status: ${response.status})`,
             },
           ],
+          isError: true,
         };
       }
 
+      // Poll for result (max 60 seconds)
+      const solveId = data.id;
+      const pollUrl = `${GATESOLVE_API}/api/solve?id=${solveId}`;
+      const maxAttempts = 20;
+
+      for (let i = 0; i < maxAttempts; i++) {
+        await new Promise((r) => setTimeout(r, 3000));
+        const pollResp = await fetch(pollUrl);
+        const pollData = await pollResp.json();
+
+        if (pollData.status === "solved") {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `CAPTCHA solved successfully!\n\nToken: ${pollData.token}\nType: ${pollData.type}\nSolved in: ${pollData.solvedIn}\nSolve ID: ${solveId}`,
+              },
+            ],
+          };
+        }
+
+        if (pollData.status === "failed") {
+          let failText = `CAPTCHA solve failed.\n\nSolve ID: ${solveId}\nType: ${type}`;
+          if (pollData.failure) {
+            failText += `\nReason: ${pollData.failure.reason}`;
+            failText += `\nSuggestion: ${pollData.failure.suggestion}`;
+          }
+          if (pollData.hint) failText += `\nHint: ${pollData.hint}`;
+          return {
+            content: [{ type: "text" as const, text: failText }],
+            isError: true,
+          };
+        }
+      }
+
       return {
         content: [
           {
             type: "text" as const,
-            text: `Error: ${data.message || "Unknown error"} (status: ${response.status})`,
+            text: `Solve timed out after 60 seconds. You can continue polling manually:\nGET ${pollUrl}`,
           },
         ],
         isError: true,
@@ -91,6 +152,144 @@ server.tool(
   }
 );
 
+// Tool: detect_block
+server.tool(
+  "detect_block",
+  "Check what kind of access block a URL has before attempting to solve. Returns classification (public-ok, js-challenge, captcha, auth-wall, blocked-silent, rate-limited, error), solvability, and recommendations. No API key required.",
+  {
+    url: z.string().url().describe("The URL to check for access blocks"),
+  },
+  async ({ url }) => {
+    try {
+      const response = await fetch(
+        `${GATESOLVE_API}/api/detect?url=${encodeURIComponent(url)}`
+      );
+      const data = await response.json();
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Block Detection for ${url}:\n\nClassification: ${data.classification}\nHTTP Status: ${data.httpStatus}\nSolvable: ${data.solvable ? "Yes" : "No"}${data.captchaType ? `\nCAPTCHA Type: ${data.captchaType}` : ""}${data.confidence !== undefined ? `\nConfidence: ${(data.confidence * 100).toFixed(0)}%` : ""}${data.recommendation ? `\n\nRecommendation: ${data.recommendation}` : ""}${data.recovery ? `\nMax Retries: ${data.recovery.maxRetries}, Backoff: ${data.recovery.backoffSeconds}s` : ""}`,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Failed to detect block: ${error instanceof Error ? error.message : "Unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool: check_usage
+server.tool(
+  "check_usage",
+  "Check your API key quota — how many solves used, remaining, and limit. Requires GATESOLVE_API_KEY environment variable.",
+  {},
+  async () => {
+    const apiKey = process.env.GATESOLVE_API_KEY;
+    if (!apiKey) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "GATESOLVE_API_KEY environment variable not set. Set it to your gs_xxx API key to check usage.",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const response = await fetch(`${GATESOLVE_API}/api/v1/usage`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      const data = await response.json();
+
+      if (response.status === 401) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Invalid API key. ${data.message || ""}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `GateSolve Usage:\n\nUsed: ${data.used}/${data.limit} solves\nRemaining: ${data.remaining}\nPercent Used: ${data.percentUsed}\nPlan: ${data.plan}${data.upgradeInfo ? `\n\n⚠️ ${data.upgradeInfo}` : ""}`,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Failed to check usage: ${error instanceof Error ? error.message : "Unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool: dry_run_solve
+server.tool(
+  "dry_run_solve",
+  "Validate a CAPTCHA solve request without consuming credits or creating a job. Returns whether the request is valid, estimated time and cost, and type-specific warnings. No API key required.",
+  {
+    type: z
+      .enum(["cloudflare-turnstile", "recaptcha-v2", "recaptcha-v3", "hcaptcha"])
+      .describe("The type of CAPTCHA to solve"),
+    siteKey: z.string().describe("The site key for the CAPTCHA"),
+    pageUrl: z.string().url().describe("The URL of the page containing the CAPTCHA"),
+  },
+  async ({ type, siteKey, pageUrl }) => {
+    try {
+      const response = await fetch(`${GATESOLVE_API}/api/v1/solve/dry-run`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type, siteKey, pageUrl }),
+      });
+      const data = await response.json();
+
+      let text = `Dry Run Result: ${data.valid ? "✅ Valid" : "❌ Invalid"}\n`;
+      if (data.issues?.length) text += `\nIssues:\n${data.issues.map((i: string) => `- ${i}`).join("\n")}`;
+      if (data.warnings?.length) text += `\nWarnings:\n${data.warnings.map((w: string) => `- ${w}`).join("\n")}`;
+      if (data.estimate) text += `\n\nEstimate:\n- Solve time: ${data.estimate.solveTimeSeconds}s\n- Price: $${data.estimate.priceUsd} USDC\n- Method: ${data.estimate.method}`;
+      if (data.nextStep) text += `\n\n${data.nextStep}`;
+
+      return {
+        content: [{ type: "text" as const, text }],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Failed to dry run: ${error instanceof Error ? error.message : "Unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
 // Tool: list_captcha_types
 server.tool(
   "list_captcha_types",