chekk-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Chekk MCP Server
+ *
+ * Makes every project deployed on chekk.dev available as agent-callable
+ * tools via the Model Context Protocol.
+ *
+ * Usage (Claude Desktop / Cursor / any MCP client):
+ *   npx @chekk/mcp-server
+ *
+ * Tools exposed:
+ *   - chekk_search_tools   Search Chekk's project index by keyword, framework, etc.
+ *   - chekk_get_manifest    Get the full agent manifest for a specific project.
+ *   - chekk_call            Call an action on a Chekk-deployed project (proxied).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+/**
+ * Chekk MCP Server
+ *
+ * Makes every project deployed on chekk.dev available as agent-callable
+ * tools via the Model Context Protocol.
+ *
+ * Usage (Claude Desktop / Cursor / any MCP client):
+ *   npx @chekk/mcp-server
+ *
+ * Tools exposed:
+ *   - chekk_search_tools   Search Chekk's project index by keyword, framework, etc.
+ *   - chekk_get_manifest    Get the full agent manifest for a specific project.
+ *   - chekk_call            Call an action on a Chekk-deployed project (proxied).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const CHEKK_API = process.env.CHEKK_API_URL || "https://chekk.dev/api/v1";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function chekkFetch(path, init) {
+    const url = path.startsWith("http") ? path : `${CHEKK_API}${path}`;
+    const res = await fetch(url, {
+        ...init,
+        headers: {
+            "User-Agent": "chekk-mcp-server/0.1.0",
+            "Accept": "application/json",
+            ...(init?.headers || {}),
+        },
+    });
+    return res;
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "chekk",
+    version: "0.1.0",
+});
+// ---------------------------------------------------------------------------
+// Tool 1: chekk_search_tools
+// ---------------------------------------------------------------------------
+server.registerTool("chekk_search_tools", {
+    title: "Search Chekk Tools",
+    description: "Search Chekk's index of deployed projects that agents can call. " +
+        "Returns projects with their available actions, payment requirements, " +
+        "and entry points. Use this to discover what tools are available on Chekk.",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Keyword search across project names and descriptions"),
+        framework: z
+            .string()
+            .optional()
+            .describe("Filter by framework: nextjs, react, fastapi, express, flask, django, etc."),
+        has_payment: z
+            .boolean()
+            .optional()
+            .describe("Filter to projects that accept USDC payments"),
+        has_auth: z
+            .boolean()
+            .optional()
+            .describe("Filter to projects that require authentication"),
+        min_actions: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Minimum number of callable actions"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Max results to return (default 20)"),
+    },
+}, async (args) => {
+    const params = new URLSearchParams();
+    if (args.query)
+        params.set("q", args.query);
+    if (args.framework)
+        params.set("framework", args.framework);
+    if (args.has_payment !== undefined)
+        params.set("has_payment", String(args.has_payment));
+    if (args.has_auth !== undefined)
+        params.set("has_auth", String(args.has_auth));
+    if (args.min_actions !== undefined)
+        params.set("min_actions", String(args.min_actions));
+    params.set("limit", String(args.limit || 20));
+    const res = await chekkFetch(`/agents/search?${params}`);
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error searching Chekk: HTTP ${res.status} — ${await res.text()}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await res.json();
+    const items = (data.items || []).map((item) => ({
+        project: item.slug,
+        title: item.title || item.repo,
+        description: item.description,
+        framework: item.framework,
+        actions_count: item.actions_count,
+        requires_auth: item.requires?.auth || false,
+        requires_payment: item.requires?.payment || false,
+        manifest_url: item.well_known,
+        chat_url: item.chat,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    total: data.count,
+                    results: items,
+                    hint: "Use chekk_get_manifest with a project slug to see all available actions, " +
+                        "or chekk_call to invoke an action directly.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool 2: chekk_get_manifest
+// ---------------------------------------------------------------------------
+server.registerTool("chekk_get_manifest", {
+    title: "Get Project Manifest",
+    description: "Get the full agent manifest for a Chekk-deployed project. " +
+        "Returns all callable actions with their HTTP methods, paths, " +
+        "required inputs, payment prices, and auth requirements. " +
+        "Use this to understand what a specific project can do before calling it.",
+    inputSchema: {
+        project: z
+            .string()
+            .describe('Project slug in "owner/repo" format, e.g. "greatdaveo/DavShop-Api"'),
+    },
+}, async (args) => {
+    const [owner, repo] = args.project.split("/");
+    if (!owner || !repo) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: 'Invalid project slug. Use "owner/repo" format.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const res = await chekkFetch(`/agent/${owner}/${repo}/manifest`);
+    if (!res.ok) {
+        if (res.status === 404) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Project "${args.project}" not found or has no agent manifest. ` +
+                            `Try chekk_search_tools to find available projects.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching manifest: HTTP ${res.status}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const manifest = await res.json();
+    // Summarize for the agent
+    const actions = (manifest.actions || []).map((a) => ({
+        id: a.id,
+        method: a.method,
+        path: a.path,
+        description: a.description,
+        side_effect: a.side_effect,
+        inputs: a.inputs,
+    }));
+    const summary = {
+        project: manifest.slug,
+        description: manifest.description,
+        framework: manifest.framework,
+        deployed_url: manifest.deployed_url,
+        actions_count: actions.length,
+        actions,
+        requires_auth: manifest.requires?.auth || false,
+        requires_payment: manifest.requires?.payment || false,
+        payment_info: manifest.payment || null,
+        session: manifest.session || null,
+        hint: "Use chekk_call with the project slug, method, path, and body to invoke an action.",
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(summary, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool 3: chekk_call
+// ---------------------------------------------------------------------------
+server.registerTool("chekk_call", {
+    title: "Call a Chekk Tool",
+    description: "Execute an action on a Chekk-deployed project. " +
+        "Proxies your request through Chekk's agent gateway, which handles " +
+        "rate limiting, payment enforcement (402 challenges), and routing. " +
+        "If the action requires payment, you'll receive a 402 response with " +
+        "instructions to pay USDC on Base.",
+    inputSchema: {
+        project: z
+            .string()
+            .describe('Project slug in "owner/repo" format, e.g. "greatdaveo/DavShop-Api"'),
+        method: z
+            .enum(["GET", "POST", "PUT", "PATCH", "DELETE"])
+            .default("POST")
+            .describe("HTTP method for the action"),
+        path: z
+            .string()
+            .describe('API path to call, e.g. "/api/orders"'),
+        body: z
+            .record(z.unknown())
+            .optional()
+            .describe("Request body (JSON object) for POST/PUT/PATCH"),
+        query: z
+            .record(z.string())
+            .optional()
+            .describe("Query parameters as key-value pairs"),
+        payment_receipt: z
+            .string()
+            .optional()
+            .describe("Payment receipt ID from a previous 402 challenge (after paying USDC)"),
+    },
+}, async (args) => {
+    const [owner, repo] = args.project.split("/");
+    if (!owner || !repo) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: 'Invalid project slug. Use "owner/repo" format.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (args.payment_receipt) {
+        headers["X-Payment-Receipt"] = args.payment_receipt;
+    }
+    const callBody = {
+        method: args.method,
+        path: args.path,
+    };
+    if (args.body)
+        callBody.body = args.body;
+    if (args.query)
+        callBody.query = args.query;
+    const res = await chekkFetch(`/agent/${owner}/${repo}/call`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(callBody),
+    });
+    const data = await res.json();
+    if (res.status === 402) {
+        // Payment required — return the challenge
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "payment_required",
+                        message: data.message,
+                        receipt_id: data.receipt_id,
+                        challenge: data.challenge,
+                        hint: data.hint,
+                        next_step: "Pay the USDC amount to the specified address on Base, " +
+                            "then call chekk_call again with payment_receipt set to the receipt_id.",
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    if (res.status === 429) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "rate_limited",
+                        message: data.message,
+                        retry_after_seconds: data.retry_after_seconds,
+                        scope: data.scope,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "error",
+                        http_status: res.status,
+                        error: data,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Success
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    status: "success",
+                    upstream_status: data.upstream_status,
+                    result: data.upstream_body,
+                    paid: data.paid || false,
+                    receipt_id: data.receipt_id || null,
+                    response_time_ms: data.upstream_seconds
+                        ? Math.round(data.upstream_seconds * 1000)
+                        : null,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Chekk MCP server failed to start:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "chekk-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that exposes every Chekk-deployed project as agent-callable tools",
+  "type": "module",
+  "bin": {
+    "chekk-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "files": ["dist"],
+  "keywords": ["mcp", "chekk", "agent", "tools", "llm"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}