chekk 0.5.4 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/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
+ *
+ * Tools exposed:
+ *   - chekk_search       Search Chekk's project index by keyword, framework, etc.
+ *   - chekk_discover      Browse trending, popular, and featured projects.
+ *   - 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,448 @@
+#!/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
+ *
+ * Tools exposed:
+ *   - chekk_search       Search Chekk's project index by keyword, framework, etc.
+ *   - chekk_discover      Browse trending, popular, and featured projects.
+ *   - 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
+// ---------------------------------------------------------------------------
+const AGENT_ID = process.env.CHEKK_AGENT_ID || "chekk-mcp-server/0.2.0";
+async function chekkFetch(path, init) {
+    const url = path.startsWith("http") ? path : `${CHEKK_API}${path}`;
+    return fetch(url, {
+        ...init,
+        headers: {
+            "User-Agent": AGENT_ID,
+            "X-Agent-Id": AGENT_ID,
+            Accept: "application/json",
+            ...(init?.headers || {}),
+        },
+    });
+}
+/** Fire-and-forget call logging — never blocks the tool response. */
+function logCall(data) {
+    chekkFetch("/agents/log", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ ...data, agent_id: AGENT_ID }),
+    }).catch(() => { });
+}
+function formatProject(item) {
+    const requires = item.requires || {};
+    return {
+        project: item.slug || `${item.github_owner}/${item.github_repo}`,
+        title: item.title || item.github_repo || item.repo,
+        description: item.description,
+        framework: item.framework,
+        actions_count: item.actions_count,
+        stars: item.star_count ?? item.stars ?? null,
+        is_healthy: item.is_healthy ?? null,
+        requires_auth: requires.auth || false,
+        requires_payment: requires.payment || false,
+        manifest_url: item.well_known,
+        chat_url: item.chat,
+    };
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "chekk",
+    version: "0.2.0",
+});
+// ---------------------------------------------------------------------------
+// Tool 1: chekk_search
+// ---------------------------------------------------------------------------
+server.registerTool("chekk_search", {
+    title: "Search Chekk Tools",
+    description: "Search Chekk's index of deployed software that agents can call. " +
+        "Returns projects with their available actions, payment requirements, " +
+        "health status, and entry points. Use this when you know what kind " +
+        "of tool you need (e.g. 'markdown to PDF', 'language detection', 'web scraper').",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Keyword search across project names, descriptions, and owners"),
+        framework: z
+            .string()
+            .optional()
+            .describe("Filter by framework: nextjs, react, fastapi, express, flask, django, go, rust, 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 t0 = Date.now();
+    const res = await chekkFetch(`/agents/search?${params}`);
+    logCall({ tool: "search", query: args.query, status_code: res.status, response_time_ms: Date.now() - t0 });
+    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(formatProject);
+    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_discover
+// ---------------------------------------------------------------------------
+server.registerTool("chekk_discover", {
+    title: "Discover Chekk Projects",
+    description: "Browse Chekk's curated project feed. Use this when you want to " +
+        "explore what's available — trending projects, staff picks, most " +
+        "popular tools, or recently deployed software. Good for general " +
+        "discovery when you don't have a specific keyword in mind.",
+    inputSchema: {
+        sort: z
+            .enum(["trending", "popular", "recent", "rising", "staff_picks"])
+            .default("trending")
+            .describe("Sort order: trending (hot this week), popular (all-time stars), " +
+            "recent (newest), rising (breakout last 3 days), staff_picks (curated)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Max results to return (default 20)"),
+    },
+}, async (args) => {
+    const limit = args.limit || 20;
+    const t0 = Date.now();
+    const res = await chekkFetch(`/deployments/recent?limit=${limit}&sort=${args.sort}`);
+    logCall({ tool: "discover", query: args.sort, status_code: res.status, response_time_ms: Date.now() - t0 });
+    if (!res.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching Chekk feed: HTTP ${res.status} — ${await res.text()}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await res.json();
+    const deployments = Array.isArray(data) ? data : data.items || data.deployments || [];
+    const items = deployments.map((d) => ({
+        project: `${d.github_owner}/${d.github_repo}`,
+        title: d.title || d.github_repo,
+        description: d.description,
+        framework: d.framework,
+        stars: d.star_count ?? 0,
+        views: d.view_count ?? 0,
+        is_healthy: d.is_healthy ?? null,
+        is_featured: d.is_featured ?? null,
+        deployed_url: d.deployed_url,
+        manifest_url: `https://chekk.dev/${d.github_owner}/${d.github_repo}/.well-known/agent.json`,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    sort: args.sort,
+                    count: items.length,
+                    results: items,
+                    hint: "Use chekk_search to find specific tools, or chekk_get_manifest to see a project's callable actions.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool 3: 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. "ifihan/nigerian-markets-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 t0 = Date.now();
+    const res = await chekkFetch(`/agent/${owner}/${repo}/manifest`);
+    logCall({ tool: "get_manifest", query: args.project, status_code: res.status, response_time_ms: Date.now() - t0 });
+    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 to find available projects.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching manifest: HTTP ${res.status}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const manifest = await res.json();
+    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 4: 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. "ifihan/nigerian-markets-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/states"'),
+        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 t0 = Date.now();
+    const res = await chekkFetch(`/agent/${owner}/${repo}/call`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(callBody),
+    });
+    const elapsed = Date.now() - t0;
+    const data = await res.json();
+    logCall({ tool: "call", query: args.project, method: args.method, path: args.path, status_code: res.status, response_time_ms: elapsed });
+    if (res.status === 402) {
+        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,
+        };
+    }
+    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

@@ -1,44 +1,28 @@
 {
   "name": "chekk",
-  "version": "0.5.4",
-  "description": "See how you prompt. Chekk analyzes your AI coding workflow, tells you what kind of engineer you are, and shows what your habits actually cost.",
+  "version": "1.0.0",
+  "description": "MCP server that exposes every Chekk-deployed project as agent-callable tools. Use any deployed API as an agent tool.",
+  "type": "module",
   "bin": {
-    "chekk": "./bin/chekk.js"
+    "chekk": "./dist/index.js",
+    "chekk-mcp": "./dist/index.js"
   },
-  "type": "module",
-  "files": [
-    "bin/",
-    "src/"
-  ],
+  "main": "./dist/index.js",
   "scripts": {
-    "start": "node bin/chekk.js"
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
   },
-  "keywords": [
-    "ai",
-    "coding",
-    "claude",
-    "cursor",
-    "copilot",
-    "developer",
-    "analysis",
-    "prompt",
-    "engineering",
-    "vibe-coding",
-    "workflow"
-  ],
-  "author": "Chekk <timi@chekk.dev>",
+  "files": ["dist"],
+  "keywords": ["mcp", "chekk", "agent", "tools", "llm"],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/omarionnn/chekk"
-  },
-  "homepage": "https://chekk.dev",
-  "engines": {
-    "node": ">=18.0.0"
-  },
   "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "ora": "^8.0.1"
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
   }
 }

package/bin/chekk.js

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-
-import { execSync, spawn } from 'child_process';
-import { Command } from 'commander';
-import { run } from '../src/index.js';
-
-const LOCAL_VERSION = '0.5.4';
-
-// ── Auto-update check ──
-// If running from a cached npx install, check if there's a newer version
-// and re-exec with @latest to ensure users always get the freshest build.
-async function checkForUpdate() {
-  try {
-    const latest = execSync('npm view chekk version 2>/dev/null', {
-      encoding: 'utf-8',
-      timeout: 3000,
-    }).trim();
-
-    if (latest && latest !== LOCAL_VERSION && isNewer(latest, LOCAL_VERSION)) {
-      // Re-run with the latest version
-      const args = process.argv.slice(2);
-      const child = spawn('npx', ['--yes', `chekk@${latest}`, ...args], {
-        stdio: 'inherit',
-        shell: true,
-      });
-      child.on('exit', (code) => process.exit(code || 0));
-      return true; // signal that we're handing off
-    }
-  } catch {
-    // Network down or timeout — just run the local version
-  }
-  return false;
-}
-
-function isNewer(remote, local) {
-  const r = remote.split('.').map(Number);
-  const l = local.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((r[i] || 0) > (l[i] || 0)) return true;
-    if ((r[i] || 0) < (l[i] || 0)) return false;
-  }
-  return false;
-}
-
-const handedOff = await checkForUpdate();
-if (!handedOff) {
-  const program = new Command();
-
-  program
-    .name('chekk')
-    .description('The prompt engineering capability score. See how you prompt.')
-    .version(LOCAL_VERSION)
-    .option('--offline', 'Skip AI prose generation, show data-driven output')
-    .option('--verbose', 'Show detailed per-project and per-metric breakdowns')
-    .option('--json', 'Output raw metrics as JSON')
-    .option('--no-upload', 'Skip the claim prompt')
-    .action(async (options) => {
-      await run(options);
-    });
-
-  program.parse();
-}