@gatesolve/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# GateSolve MCP Server
+
+Model Context Protocol (MCP) server for [GateSolve](https://gatesolve.dev) — CAPTCHA solving for AI agents via x402 micropayments.
+
+## Tools
+
+### `solve_captcha`
+Solve a CAPTCHA (Turnstile, reCAPTCHA v2/v3, hCaptcha). Returns payment requirements or solution token.
+
+### `list_captcha_types`
+List supported CAPTCHA types with pricing, accuracy, and required fields.
+
+### `check_gatesolve_status`
+Check API health and service status.
+
+## Setup
+
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "gatesolve": {
+      "command": "npx",
+      "args": ["@gatesolve/mcp-server"]
+    }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/arsonx-dev/gatesolve-mcp.git
+cd gatesolve-mcp
+npm install
+npm run build
+npm start
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GATESOLVE_API_URL` | `https://gatesolve.dev` | GateSolve API base URL |
+
+## How It Works
+
+1. Agent calls `solve_captcha` with the CAPTCHA type, site key, and page URL
+2. GateSolve returns a 402 Payment Required with USDC amount
+3. Agent pays via x402 (USDC on Base network)
+4. Agent calls `solve_captcha` again with the payment token
+5. Returns the solved CAPTCHA token
+
+No API keys. No accounts. Just x402.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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",
+});
+// 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).", {
+    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"),
+    paymentToken: z
+        .string()
+        .optional()
+        .describe("x402 payment token (USDC on Base). If omitted, returns payment requirements."),
+}, async ({ type, siteKey, pageUrl, paymentToken }) => {
+    try {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (paymentToken) {
+            headers["X-402-Pay"] = paymentToken;
+        }
+        const response = await fetch(`${GATESOLVE_API}/api/v1/solve`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ type, siteKey, pageUrl }),
+        });
+        const data = await response.json();
+        if (response.status === 402) {
+            return {
+                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.`,
+                    },
+                ],
+            };
+        }
+        if (response.status === 200) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `CAPTCHA solved successfully!\n\nToken: ${data.token}\nType: ${data.type}\nSolved in: ${data.solvedIn}\nStatus: ${data.status}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${data.message || "Unknown error"} (status: ${response.status})`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to connect to GateSolve API: ${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 {
+        const response = await fetch(`${GATESOLVE_API}/api/v1/types`);
+        const data = await response.json();
+        const lines = data.types.map((t) => `**${t.name}** (${t.id})\n  Price: ${t.price} USDC | Avg: ${t.avgSolveTime} | Accuracy: ${t.accuracy}\n  Required: ${t.requiredFields.join(", ")}\n  Optional: ${t.optionalFields.join(", ") || "none"}\n  ${t.description}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `GateSolve Supported CAPTCHA Types:\n\n${lines.join("\n\n")}\n\nPayment: x402 micropayments (USDC on ${data.payment.network})`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to fetch captcha types: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Tool: check_status
+server.tool("check_gatesolve_status", "Check GateSolve API health and service status.", {}, async () => {
+    try {
+        const response = await fetch(`${GATESOLVE_API}/api/health`);
+        const data = await response.json();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `GateSolve Status: ${data.status}\n\nServices:\n- API: ${data.services.api}\n- Database: ${data.services.database}\n- Solver: ${data.services.solver}\n\nMetrics:\n- Total solves: ${data.metrics.totalSolves}\n- Last 24h: ${data.metrics.last24hSolves}\n- Avg solve time: ${data.metrics.avgSolveMs ? `${(data.metrics.avgSolveMs / 1000).toFixed(1)}s` : "N/A"}\n\nLatency: ${data.latencyMs}ms | Version: ${data.version}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `GateSolve API unreachable: ${error instanceof Error ? error.message : "Unknown error"}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@gatesolve/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for GateSolve CAPTCHA solving via x402 micropayments",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "gatesolve-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "captcha",
+    "gatesolve",
+    "x402",
+    "ai-agent",
+    "turnstile",
+    "recaptcha",
+    "hcaptcha"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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",
+});
+
+// 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).",
+  {
+    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"),
+    paymentToken: z
+      .string()
+      .optional()
+      .describe(
+        "x402 payment token (USDC on Base). If omitted, returns payment requirements."
+      ),
+  },
+  async ({ type, siteKey, pageUrl, paymentToken }) => {
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+      };
+
+      if (paymentToken) {
+        headers["X-402-Pay"] = paymentToken;
+      }
+
+      const response = await fetch(`${GATESOLVE_API}/api/v1/solve`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ type, siteKey, pageUrl }),
+      });
+
+      const data = await response.json();
+
+      if (response.status === 402) {
+        return {
+          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.`,
+            },
+          ],
+        };
+      }
+
+      if (response.status === 200) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `CAPTCHA solved successfully!\n\nToken: ${data.token}\nType: ${data.type}\nSolved in: ${data.solvedIn}\nStatus: ${data.status}`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${data.message || "Unknown error"} (status: ${response.status})`,
+          },
+        ],
+        isError: true,
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Failed to connect to GateSolve API: ${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 {
+      const response = await fetch(`${GATESOLVE_API}/api/v1/types`);
+      const data = await response.json();
+
+      const lines = data.types.map(
+        (t: {
+          id: string;
+          name: string;
+          price: string;
+          avgSolveTime: string;
+          accuracy: string;
+          requiredFields: string[];
+          optionalFields: string[];
+          description: string;
+        }) =>
+          `**${t.name}** (${t.id})\n  Price: ${t.price} USDC | Avg: ${t.avgSolveTime} | Accuracy: ${t.accuracy}\n  Required: ${t.requiredFields.join(", ")}\n  Optional: ${t.optionalFields.join(", ") || "none"}\n  ${t.description}`
+      );
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `GateSolve Supported CAPTCHA Types:\n\n${lines.join("\n\n")}\n\nPayment: x402 micropayments (USDC on ${data.payment.network})`,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Failed to fetch captcha types: ${error instanceof Error ? error.message : "Unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool: check_status
+server.tool(
+  "check_gatesolve_status",
+  "Check GateSolve API health and service status.",
+  {},
+  async () => {
+    try {
+      const response = await fetch(`${GATESOLVE_API}/api/health`);
+      const data = await response.json();
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `GateSolve Status: ${data.status}\n\nServices:\n- API: ${data.services.api}\n- Database: ${data.services.database}\n- Solver: ${data.services.solver}\n\nMetrics:\n- Total solves: ${data.metrics.totalSolves}\n- Last 24h: ${data.metrics.last24hSolves}\n- Avg solve time: ${data.metrics.avgSolveMs ? `${(data.metrics.avgSolveMs / 1000).toFixed(1)}s` : "N/A"}\n\nLatency: ${data.latencyMs}ms | Version: ${data.version}`,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `GateSolve API unreachable: ${error instanceof Error ? error.message : "Unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}