clawdeals-mcp 0.1.3

package/README.md

@@ -0,0 +1,44 @@
+# clawdeals-mcp
+
+Minimal **MCP stdio server** exposing the Clawdeals v0 tool catalog and forwarding each tool call 1:1 to the Clawdeals REST API.
+
+If `npx clawdeals-mcp ...` returns npm `E404`, the package is not yet published in the registry you are using.
+Use the repo-local commands instead:
+
+```bash
+npm run mcp:stdio
+npm run mcp:install
+```
+
+## Run
+
+```bash
+export CLAWDEALS_API_KEY="cd_live_..."
+export CLAWDEALS_API_BASE="https://app.clawdeals.com/api"
+
+npx clawdeals-mcp
+```
+
+## Install into your IDE (recommended)
+
+This updates supported MCP config files on your machine (Cursor and Claude Desktop).
+
+```bash
+export CLAWDEALS_API_KEY="cd_live_..."
+export CLAWDEALS_API_BASE="https://app.clawdeals.com/api"
+
+npx clawdeals-mcp install
+```
+
+Target a specific config file:
+
+```bash
+npx clawdeals-mcp install -- --file "/path/to/mcp.json"
+```
+
+## Env
+
+- `CLAWDEALS_API_KEY` (required)
+- `CLAWDEALS_API_BASE` (required, example: `https://app.clawdeals.com/api`)
+- `CLAWDEALS_ORIGIN` (optional, default: `mcp`)
+- `CLAWDEALS_TIMEOUT_MS` (optional, default: `15000`)

package/bin/clawdeals-mcp.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgRoot = path.resolve(__dirname, "..");
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+function printHelp() {
+  process.stdout.write(`clawdeals-mcp (stdio MCP server)\n\nUsage:\n  clawdeals-mcp                Run the MCP stdio server\n  clawdeals-mcp install [args]  Install/update MCP client config (Cursor/Claude Desktop)\n\nEnv:\n  CLAWDEALS_API_KEY      Required\n  CLAWDEALS_API_BASE     Required (example: https://app.clawdeals.com/api)\n  CLAWDEALS_ORIGIN       Optional (default: mcp)\n  CLAWDEALS_TIMEOUT_MS   Optional (default: 15000)\n\nExamples:\n  npx clawdeals-mcp\n  npx clawdeals-mcp install\n  npx clawdeals-mcp install -- --file /path/to/mcp.json\n`);
+}
+
+function printVersion() {
+  // Keep in sync with package.json; used primarily for debugging.
+  process.stdout.write("0.1.3\n");
+}
+
+if (cmd === "-h" || cmd === "--help") {
+  printHelp();
+  process.exit(0);
+}
+
+if (cmd === "-v" || cmd === "--version") {
+  printVersion();
+  process.exit(0);
+}
+
+function runNode(scriptRelPath, args) {
+  const scriptAbsPath = path.resolve(pkgRoot, scriptRelPath);
+  const result = spawnSync(process.execPath, [scriptAbsPath, ...args], {
+    stdio: "inherit",
+    env: process.env
+  });
+
+  if (result.error) {
+    process.stderr.write(`${String(result.error?.stack || result.error)}\n`);
+    process.exit(1);
+  }
+
+  process.exit(typeof result.status === "number" ? result.status : 1);
+}
+
+if (cmd === "install") {
+  // Forward remaining args to the installer.
+  // Note: allow "--" passthrough from npm/npx callers.
+  const passthrough = argv.slice(1).filter((a) => a !== "--");
+  runNode("mcp/install.mjs", passthrough);
+}
+
+if (cmd && cmd !== "stdio") {
+  process.stderr.write(`Unknown command: ${cmd}\n\n`);
+  printHelp();
+  process.exit(1);
+}
+
+// Default: run the stdio server.
+runNode("mcp-server.mjs", cmd === "stdio" ? argv.slice(1) : argv);

package/mcp/clawdeals-api.mjs

@@ -0,0 +1,200 @@
+import crypto from "node:crypto";
+const DEFAULT_ORIGIN = "mcp";
+const DEFAULT_TIMEOUT_MS = 15000;
+
+function buildStableError({ code, message, details = {}, requestId, retryAfterSeconds = null }) {
+  return {
+    ok: false,
+    error: {
+      code: code || "ERROR",
+      message: message || "Request failed",
+      details: details && typeof details === "object" ? details : {}
+    },
+    meta: {
+      request_id: requestId || crypto.randomUUID(),
+      ...(typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) ? { retry_after_seconds: retryAfterSeconds } : {})
+    }
+  };
+}
+
+function codeFromStatus(status) {
+  if (status === 401) return "UNAUTHORIZED";
+  if (status === 403) return "FORBIDDEN";
+  if (status === 404) return "NOT_FOUND";
+  if (status === 409) return "CONFLICT";
+  if (status === 429) return "RATE_LIMITED";
+  return "ERROR";
+}
+
+function parseRetryAfterSeconds(value) {
+  if (!value) return null;
+  const n = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return n;
+}
+
+function normalizeBaseUrl(baseUrl) {
+  const raw = typeof baseUrl === "string" ? baseUrl.trim() : "";
+  if (!raw) return "";
+  return raw.replace(/\/+$/, "");
+}
+
+function normalizeTimeoutMs(value) {
+  const parsed = Number.parseInt(String(value || ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return DEFAULT_TIMEOUT_MS;
+}
+
+function isWriteMethod(method) {
+  const normalized = String(method || "GET").toUpperCase();
+  return normalized !== "GET" && normalized !== "HEAD" && normalized !== "OPTIONS";
+}
+
+function safeJsonParse(text) {
+  if (!text) return { ok: true, value: {} };
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (error) {
+    return { ok: false, value: null };
+  }
+}
+
+function toQueryStringParams(query) {
+  const params = new URLSearchParams();
+  if (!query || typeof query !== "object") return params;
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      // REST handlers in this repo typically expect comma-separated strings, not repeated keys.
+      params.set(key, value.map((v) => String(v)).join(","));
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  return params;
+}
+
+export async function callClawdeals({
+  method,
+  path,
+  query,
+  body,
+  idempotencyKey,
+  requestId,
+  env = process.env,
+  fetchImpl = fetch
+}) {
+  const apiKey = env.CLAWDEALS_API_KEY;
+  if (!apiKey) {
+    return buildStableError({
+      code: "UNAUTHORIZED",
+      message: "CLAWDEALS_API_KEY is required",
+      requestId
+    });
+  }
+
+  const baseUrl = normalizeBaseUrl(env.CLAWDEALS_API_BASE);
+  if (!baseUrl) {
+    return buildStableError({
+      code: "CONFIG_ERROR",
+      message: "CLAWDEALS_API_BASE is required (example: https://app.clawdeals.com/api)",
+      requestId
+    });
+  }
+  const origin = (env.CLAWDEALS_ORIGIN || DEFAULT_ORIGIN).trim() || DEFAULT_ORIGIN;
+  const timeoutMs = normalizeTimeoutMs(env.CLAWDEALS_TIMEOUT_MS);
+  const resolvedRequestId = requestId || crypto.randomUUID();
+
+  const url = new URL(`${baseUrl}${path}`);
+  const params = toQueryStringParams(query);
+  params.forEach((value, key) => url.searchParams.set(key, value));
+
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${apiKey}`,
+    "x-clawdeals-origin": origin,
+    "x-request-id": resolvedRequestId
+  };
+
+  if (idempotencyKey) {
+    headers["Idempotency-Key"] = String(idempotencyKey);
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  // Prevent this timer from keeping the process alive.
+  timeout.unref?.();
+
+  const isWrite = isWriteMethod(method);
+  const shouldSendBody = isWrite && body !== undefined;
+
+  try {
+    const response = await fetchImpl(url.toString(), {
+      method,
+      headers: {
+        ...headers,
+        ...(shouldSendBody ? { "content-type": "application/json; charset=utf-8" } : {})
+      },
+      body: shouldSendBody ? JSON.stringify(body ?? {}) : undefined,
+      signal: controller.signal
+    });
+
+    clearTimeout(timeout);
+
+    const retryAfterSeconds = parseRetryAfterSeconds(response.headers.get("retry-after"));
+    const text = await response.text();
+    const parsed = safeJsonParse(text);
+
+    if (!parsed.ok) {
+      return buildStableError({
+        code: response.status >= 400 ? codeFromStatus(response.status) : "ERROR",
+        message: "Non-JSON response from server",
+        requestId: resolvedRequestId,
+        retryAfterSeconds
+      });
+    }
+
+    const value = parsed.value;
+
+    if (response.status < 400) {
+      return {
+        ok: true,
+        data: value,
+        meta: {
+          request_id: resolvedRequestId
+        }
+      };
+    }
+
+    const serverError = value && typeof value === "object" ? value.error : null;
+    if (serverError && typeof serverError === "object") {
+      return {
+        ok: false,
+        error: {
+          code: serverError.code || codeFromStatus(response.status),
+          message: serverError.message || "Request failed",
+          details: serverError.details && typeof serverError.details === "object" ? serverError.details : {}
+        },
+        meta: {
+          request_id: resolvedRequestId,
+          ...(typeof retryAfterSeconds === "number" && Number.isFinite(retryAfterSeconds) ? { retry_after_seconds: retryAfterSeconds } : {})
+        }
+      };
+    }
+
+    return buildStableError({
+      code: codeFromStatus(response.status),
+      message: response.statusText || "Request failed",
+      requestId: resolvedRequestId,
+      retryAfterSeconds
+    });
+  } catch (error) {
+    clearTimeout(timeout);
+    const isAbort = error && typeof error === "object" && error.name === "AbortError";
+    return buildStableError({
+      code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+      message: isAbort ? "Request timed out" : "Network error",
+      requestId: resolvedRequestId
+    });
+  }
+}

package/mcp/install-lib.mjs

@@ -0,0 +1,136 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function stripJsonc(input) {
+  const s = String(input || "");
+  let out = "";
+  let inString = false;
+  let quote = '"';
+  let escape = false;
+
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const next = i + 1 < s.length ? s[i + 1] : "";
+
+    if (inString) {
+      out += ch;
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === quote) {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      out += ch;
+      continue;
+    }
+
+    // Line comment: //
+    if (ch === "/" && next === "/") {
+      i++;
+      while (i + 1 < s.length && s[i + 1] !== "\n") i++;
+      continue;
+    }
+
+    // Block comment: /* ... */
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < s.length) {
+        if (s[i] === "*" && i + 1 < s.length && s[i + 1] === "/") {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+
+    out += ch;
+  }
+
+  return out;
+}
+
+function removeTrailingCommas(input) {
+  let s = String(input || "");
+  // Repeatedly remove ", }" and ", ]" occurrences until stable.
+  for (let i = 0; i < 10; i++) {
+    const next = s.replace(/,\s*([}\]])/g, "$1");
+    if (next === s) break;
+    s = next;
+  }
+  return s;
+}
+
+export function parseJsonLike(input) {
+  const raw = String(input || "");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Best-effort JSONC parsing for configs with comments / trailing commas.
+    const cleaned = removeTrailingCommas(stripJsonc(raw));
+    return JSON.parse(cleaned);
+  }
+}
+
+export function formatJson(obj) {
+  return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+export function ensureObject(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  return {};
+}
+
+export function buildClawdealsServerConfig({ serverPath, apiKey, apiBase, origin, timeoutMs }) {
+  return {
+    type: "stdio",
+    command: "node",
+    args: [serverPath],
+    env: {
+      CLAWDEALS_API_KEY: apiKey,
+      CLAWDEALS_API_BASE: apiBase,
+      CLAWDEALS_ORIGIN: origin,
+      CLAWDEALS_TIMEOUT_MS: timeoutMs
+    }
+  };
+}
+
+export function buildClawdealsNpxServerConfig({ packageName = "clawdeals-mcp", apiKey, apiBase, origin, timeoutMs }) {
+  return {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", packageName],
+    env: {
+      CLAWDEALS_API_KEY: apiKey,
+      CLAWDEALS_API_BASE: apiBase,
+      CLAWDEALS_ORIGIN: origin,
+      CLAWDEALS_TIMEOUT_MS: timeoutMs
+    }
+  };
+}
+
+export function upsertServer({ config, keyName, serverName, serverConfig }) {
+  const root = ensureObject(config);
+  const container = ensureObject(root[keyName]);
+  container[serverName] = serverConfig;
+  root[keyName] = container;
+  return root;
+}
+
+export function resolveRepoServerPath({ installScriptUrl }) {
+  // <pkg>/mcp/install.mjs -> <pkg>/mcp-server.mjs
+  const installFilePath = fileURLToPath(installScriptUrl);
+  const installDir = path.dirname(installFilePath);
+  return path.resolve(installDir, "..", "mcp-server.mjs");
+}

package/mcp/install.mjs

@@ -0,0 +1,258 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildClawdealsServerConfig,
+  buildClawdealsNpxServerConfig,
+  ensureObject,
+  formatJson,
+  parseJsonLike,
+  upsertServer
+} from "./install-lib.mjs";
+
+function fail(message) {
+  console.error(`mcp:install: ${message}`);
+  process.exit(1);
+}
+
+function existsFile(p) {
+  try {
+    const st = fs.statSync(p);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function existsDir(p) {
+  try {
+    const st = fs.statSync(p);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function mkdirp(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function nowStamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}${pad(d.getHours())}${pad(d.getMinutes())}${pad(
+    d.getSeconds()
+  )}`;
+}
+
+function readUtf8(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function writeUtf8(p, content) {
+  fs.writeFileSync(p, content, "utf8");
+}
+
+function backupIfExists(filePath) {
+  if (!existsFile(filePath)) return null;
+  const backupPath = `${filePath}.bak-${nowStamp()}`;
+  fs.copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+function detectCursorConfigPath() {
+  const home = os.homedir();
+  const cursorDir = path.join(home, ".cursor");
+  if (!existsDir(cursorDir)) return null;
+
+  const json = path.join(cursorDir, "mcp.json");
+  const jsonc = path.join(cursorDir, "mcp.jsonc");
+  if (existsFile(json)) return { filePath: json, defaultKey: "servers" };
+  if (existsFile(jsonc)) return { filePath: jsonc, defaultKey: "servers" };
+
+  // Cursor directory exists but config doesn't; create mcp.json.
+  return { filePath: json, defaultKey: "servers" };
+}
+
+function detectClaudeDesktopConfigPath() {
+  const platform = process.platform;
+  const home = os.homedir();
+
+  if (platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (!appData) return null;
+    return path.join(appData, "Claude", "claude_desktop_config.json");
+  }
+
+  // Linux / others
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return path.join(xdg, "Claude", "claude_desktop_config.json");
+}
+
+function chooseKeyName(parsed, defaultKey) {
+  const root = ensureObject(parsed);
+  if (root.mcpServers && typeof root.mcpServers === "object") return "mcpServers";
+  if (root.servers && typeof root.servers === "object") return "servers";
+  return defaultKey;
+}
+
+function loadOrInitConfig(filePath, defaultKey) {
+  if (!existsFile(filePath)) return { [defaultKey]: {} };
+
+  const raw = readUtf8(filePath);
+  // Treat an existing-but-empty file as "no config yet" so onboarding works.
+  // parseJsonLike("") throws, which would otherwise cause a misleading "skip".
+  const cleaned = String(raw || "").replace(/^\uFEFF/, "");
+  if (!cleaned.trim()) return { [defaultKey]: {} };
+
+  const parsed = parseJsonLike(cleaned);
+  if (!parsed || typeof parsed !== "object") return { [defaultKey]: {} };
+  return parsed;
+}
+
+function installIntoFile({ filePath, defaultKey, serverName, serverConfig, dryRun }) {
+  let parsed;
+  try {
+    parsed = loadOrInitConfig(filePath, defaultKey);
+  } catch (err) {
+    console.error(`mcp:install: Skipping (unparseable JSON/JSONC): ${filePath}`);
+    console.error(`mcp:install: ${String(err?.message || err)}`);
+    return { ok: false, skipped: true, filePath, reason: "unparseable" };
+  }
+
+  const keyName = chooseKeyName(parsed, defaultKey);
+  const next = upsertServer({ config: parsed, keyName, serverName, serverConfig });
+
+  if (dryRun) {
+    console.log(`mcp:install: (dry-run) would write ${filePath}`);
+    return { ok: true, filePath, keyName, backupPath: null, wrote: false };
+  }
+
+  const dir = path.dirname(filePath);
+  if (!existsDir(dir)) mkdirp(dir);
+
+  const backupPath = backupIfExists(filePath);
+  writeUtf8(filePath, formatJson(next));
+  return { ok: true, filePath, keyName, backupPath, wrote: true };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const dryRun = argv.includes("--dry-run");
+  const local = argv.includes("--local") || argv.includes("--repo");
+  const fileArgIdx = argv.findIndex((a) => a === "--file" || a === "--path");
+  const explicitFile = fileArgIdx >= 0 ? argv[fileArgIdx + 1] : null;
+  if (fileArgIdx >= 0 && !explicitFile) {
+    fail("Missing value for --file (expected a path to a config file)");
+  }
+
+  const serverPathIdx = argv.findIndex((a) => a === "--server-path");
+  const explicitServerPath = serverPathIdx >= 0 ? argv[serverPathIdx + 1] : null;
+  if (serverPathIdx >= 0 && !explicitServerPath) {
+    fail("Missing value for --server-path (expected an absolute path to a local mcp-server.mjs)");
+  }
+
+  const packageIdx = argv.findIndex((a) => a === "--package");
+  const packageName = packageIdx >= 0 ? argv[packageIdx + 1] : "clawdeals-mcp";
+  if (packageIdx >= 0 && !packageName) {
+    fail("Missing value for --package (expected an npm package name)");
+  }
+
+  const apiKey = String(process.env.CLAWDEALS_API_KEY || "").trim();
+  if (!apiKey) fail("CLAWDEALS_API_KEY is required");
+
+  const apiBase = String(process.env.CLAWDEALS_API_BASE || "").trim();
+  if (!apiBase) fail("CLAWDEALS_API_BASE is required (example: https://app.clawdeals.com/api)");
+  const origin = String(process.env.CLAWDEALS_ORIGIN || "mcp").trim();
+  const timeoutMs = String(process.env.CLAWDEALS_TIMEOUT_MS || "15000").trim();
+
+  const serverConfig = local
+    ? (() => {
+        const raw = String(explicitServerPath || process.env.CLAWDEALS_MCP_SERVER_PATH || "").trim();
+        if (!raw) {
+          fail("Missing --server-path (or env CLAWDEALS_MCP_SERVER_PATH) for --local installs");
+        }
+        const serverPath = path.resolve(raw);
+        if (!existsFile(serverPath)) fail(`Missing server script: ${serverPath}`);
+        return buildClawdealsServerConfig({ serverPath, apiKey, apiBase, origin, timeoutMs });
+      })()
+    : buildClawdealsNpxServerConfig({ packageName, apiKey, apiBase, origin, timeoutMs });
+
+  const targets = [];
+
+  if (explicitFile) {
+    targets.push({ kind: "explicit", filePath: path.resolve(explicitFile), defaultKey: "servers" });
+  } else {
+    const cursor = detectCursorConfigPath();
+    if (cursor) targets.push({ kind: "cursor", ...cursor });
+
+    const claudePath = detectClaudeDesktopConfigPath();
+    if (claudePath && existsFile(claudePath)) {
+      targets.push({ kind: "claude-desktop", filePath: claudePath, defaultKey: "mcpServers" });
+    }
+  }
+
+  if (!targets.length) {
+    console.log("mcp:install: No supported MCP config file found.");
+    console.log("mcp:install: Supported: Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json).");
+    console.log("");
+    console.log("Manual config (Cursor-style):");
+    console.log(
+      formatJson({
+        servers: {
+          clawdeals: serverConfig
+        }
+      }).trimEnd()
+    );
+    process.exit(2);
+  }
+
+  const results = targets.map((t) =>
+    installIntoFile({
+      filePath: t.filePath,
+      defaultKey: t.defaultKey,
+      serverName: "clawdeals",
+      serverConfig,
+      dryRun
+    })
+  );
+
+  const ok = results.filter((r) => r.ok);
+  const wrote = results.filter((r) => r.ok && r.wrote);
+  const skipped = results.filter((r) => !r.ok && r.skipped);
+
+  for (const r of wrote) {
+    console.log(`mcp:install: Updated ${r.filePath} (${r.keyName}.clawdeals)`);
+    if (r.backupPath) console.log(`mcp:install: Backup ${r.backupPath}`);
+  }
+  for (const r of skipped) {
+    console.log(`mcp:install: Skipped ${r.filePath} (${r.reason})`);
+  }
+
+  if (!ok.length) {
+    console.error("mcp:install: No files were updated. All targets were skipped.");
+    process.exit(1);
+  }
+  if (!dryRun && wrote.length === 0) {
+    console.error("mcp:install: No files were updated.");
+    process.exit(1);
+  }
+
+  console.log("");
+  if (skipped.length) {
+    console.log(`mcp:install: Warning: ${skipped.length} target file(s) were skipped (see above).`);
+    console.log("");
+  }
+
+  if (dryRun ? ok.length : wrote.length) {
+    console.log(dryRun ? "mcp:install: Next steps (after running without --dry-run):" : "mcp:install: Next steps:");
+    console.log("mcp:install: 1) Restart your IDE so it reloads MCP servers.");
+    console.log('mcp:install: 2) In your IDE, call "clawdeals.deals.list" with { "limit": 1 }.');
+  }
+}
+
+main().catch((err) => fail(String(err?.stack || err?.message || err)));