@machines-cash/agent-skill 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const MCP_URL = process.env.MACHINES_MCP_URL?.trim() || "https://mcp.machines.cash";
+const MCP_SERVER_URL = `${MCP_URL.replace(/\/$/, "")}/mcp`;
+const MCP_CONNECT_CLIENT_ID = process.env.MACHINES_MCP_CONNECT_CLIENT_ID?.trim() || "cli_native";
+const SKILL_NAME = "machines-user-ops";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillSourceDir = path.resolve(__dirname, "..", "skill");
+
+function printHelp() {
+  console.log(`machines-agent-skill
+
+Usage:
+  machines-agent-skill install --host codex|claude|both
+  machines-agent-skill auth login [--manual-key]
+  machines-agent-skill doctor
+`);
+}
+
+function parseFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index < 0) return null;
+  return args[index + 1] ?? null;
+}
+
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function copyDir(sourceDir, targetDir) {
+  await ensureDir(targetDir);
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(sourcePath, targetPath);
+      continue;
+    }
+    await fs.copyFile(sourcePath, targetPath);
+  }
+}
+
+function upsertCodexMcpSection(configToml) {
+  const sectionName = "[mcp_servers.machines]";
+  const sectionBody = `${sectionName}\nurl = \"${MCP_SERVER_URL}\"\n`;
+  const sectionRegex = /^\[mcp_servers\.machines\][\s\S]*?(?=^\[[^\]]+\]|\Z)/m;
+
+  if (sectionRegex.test(configToml)) {
+    return configToml.replace(sectionRegex, sectionBody);
+  }
+
+  const suffix = configToml.endsWith("\n") ? "" : "\n";
+  return `${configToml}${suffix}\n${sectionBody}`;
+}
+
+async function installCodex() {
+  const home = os.homedir();
+  const codexSkillDir = path.join(home, ".codex", "skills", SKILL_NAME);
+  const codexConfigPath = path.join(home, ".codex", "config.toml");
+
+  await copyDir(skillSourceDir, codexSkillDir);
+
+  let configToml = "";
+  if (await pathExists(codexConfigPath)) {
+    configToml = await fs.readFile(codexConfigPath, "utf8");
+  }
+  const nextConfigToml = upsertCodexMcpSection(configToml);
+  await ensureDir(path.dirname(codexConfigPath));
+  await fs.writeFile(codexConfigPath, nextConfigToml, "utf8");
+
+  console.log(`codex configured: ${codexConfigPath}`);
+  console.log(`codex skill installed: ${codexSkillDir}`);
+}
+
+async function installClaude() {
+  const home = os.homedir();
+  const claudeSkillDir = path.join(home, ".claude", "skills", SKILL_NAME);
+  const claudeSettingsPath = path.join(home, ".claude", "settings.json");
+
+  await copyDir(skillSourceDir, claudeSkillDir);
+
+  let settings = {};
+  if (await pathExists(claudeSettingsPath)) {
+    try {
+      settings = JSON.parse(await fs.readFile(claudeSettingsPath, "utf8"));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    settings = {};
+  }
+
+  const root = settings;
+  if (!root.mcpServers || typeof root.mcpServers !== "object" || Array.isArray(root.mcpServers)) {
+    root.mcpServers = {};
+  }
+
+  root.mcpServers.machines = {
+    transport: "http",
+    url: MCP_SERVER_URL,
+  };
+
+  await ensureDir(path.dirname(claudeSettingsPath));
+  await fs.writeFile(claudeSettingsPath, `${JSON.stringify(root, null, 2)}\n`, "utf8");
+
+  console.log(`claude configured: ${claudeSettingsPath}`);
+  console.log(`claude skill installed: ${claudeSkillDir}`);
+}
+
+async function installCommand(args) {
+  const host = (parseFlag(args, "--host") || "both").toLowerCase();
+  if (!["codex", "claude", "both"].includes(host)) {
+    throw new Error("--host must be codex, claude, or both");
+  }
+
+  if (host === "codex" || host === "both") {
+    await installCodex();
+  }
+  if (host === "claude" || host === "both") {
+    await installClaude();
+  }
+}
+
+function createPkceVerifier() {
+  return randomBytes(48).toString("base64url");
+}
+
+function createPkceChallenge(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+function createState() {
+  return randomBytes(24).toString("hex");
+}
+
+function openBrowser(url) {
+  const openArgsByPlatform = {
+    darwin: ["open", [url]],
+    win32: ["cmd", ["/c", "start", "", url]],
+    linux: ["xdg-open", [url]],
+  };
+
+  const [command, args] = openArgsByPlatform[process.platform] || openArgsByPlatform.linux;
+  const child = spawn(command, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+function buildCallbackPageHtml(message) {
+  return `<!doctype html><html><head><meta charset=\"utf-8\"/><title>Machines Auth</title><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"/></head><body style=\"font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#0b0b0b;color:#f5f5f5;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;\"><div style=\"max-width:420px;padding:16px;border:1px solid #2a2a2a;border-radius:12px;background:#111\">${message}<div style=\"margin-top:8px;color:#9ca3af;font-size:13px\">You can close this window.</div></div></body></html>`;
+}
+
+async function exchangeOAuthCode(options) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: options.clientId,
+    code: options.code,
+    redirect_uri: options.redirectUri,
+    code_verifier: options.codeVerifier,
+  });
+
+  const response = await fetch(`${MCP_URL.replace(/\/$/, "")}/oauth/token`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+    },
+    body: body.toString(),
+  });
+
+  const text = await response.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    payload = { raw: text };
+  }
+
+  if (!response.ok) {
+    const errorDescription =
+      typeof payload?.error_description === "string"
+        ? payload.error_description
+        : typeof payload?.error === "string"
+          ? payload.error
+          : "token exchange failed";
+    throw new Error(errorDescription);
+  }
+
+  if (!payload || typeof payload !== "object" || typeof payload.access_token !== "string") {
+    throw new Error("invalid token response");
+  }
+
+  return payload;
+}
+
+async function saveAuth(payload) {
+  const authDir = path.join(os.homedir(), ".machines", "agent-skill");
+  const authPath = path.join(authDir, "auth.json");
+  await ensureDir(authDir);
+
+  const out = {
+    mcpBaseUrl: MCP_URL,
+    mcpServerUrl: MCP_SERVER_URL,
+    clientId: MCP_CONNECT_CLIENT_ID,
+    accessToken: payload.access_token,
+    refreshToken: typeof payload.refresh_token === "string" ? payload.refresh_token : null,
+    expiresIn: typeof payload.expires_in === "number" ? payload.expires_in : null,
+    scope: typeof payload.scope === "string" ? payload.scope : "*",
+    tokenType: typeof payload.token_type === "string" ? payload.token_type : "Bearer",
+    obtainedAt: new Date().toISOString(),
+  };
+
+  await fs.writeFile(authPath, `${JSON.stringify(out, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return authPath;
+}
+
+async function loginCommand(args) {
+  const manualKey = hasFlag(args, "--manual-key");
+  const state = createState();
+  const codeVerifier = createPkceVerifier();
+  const codeChallenge = createPkceChallenge(codeVerifier);
+  const authResult = await new Promise((resolve, reject) => {
+    const timeoutMs = 5 * 60 * 1000;
+    let settled = false;
+    let timeout;
+    let redirectUri = "";
+
+    const closeServer = (server) =>
+      new Promise((closeResolve) => server.close(() => closeResolve()));
+
+    const server = createServer(async (req, res) => {
+      const requestUrl = new URL(req.url || "/", "http://127.0.0.1");
+      if (requestUrl.pathname !== "/callback") {
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end("not found");
+        return;
+      }
+
+      const incomingState = requestUrl.searchParams.get("state");
+      if (!incomingState || incomingState !== state) {
+        res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+        res.end(buildCallbackPageHtml("Invalid OAuth state."));
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          await closeServer(server);
+          reject(new Error("state mismatch during OAuth callback"));
+        }
+        return;
+      }
+
+      const error = requestUrl.searchParams.get("error");
+      const errorDescription = requestUrl.searchParams.get("error_description");
+      const code = requestUrl.searchParams.get("code");
+
+      if (error) {
+        res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+        res.end(buildCallbackPageHtml(`Authorization failed: ${errorDescription || error}`));
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          await closeServer(server);
+          reject(new Error(errorDescription || error));
+        }
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+        res.end(buildCallbackPageHtml("Missing authorization code."));
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          await closeServer(server);
+          reject(new Error("authorization code missing"));
+        }
+        return;
+      }
+
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(buildCallbackPageHtml("Authorization complete."));
+      if (!settled) {
+        settled = true;
+        clearTimeout(timeout);
+        await closeServer(server);
+        resolve({ code, redirectUri });
+      }
+    });
+
+    server.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      if (!port) {
+        reject(new Error("failed to bind local callback server"));
+        return;
+      }
+
+      redirectUri = `http://127.0.0.1:${port}/callback`;
+      const authorizeUrl = new URL(`${MCP_URL.replace(/\/$/, "")}/oauth/authorize`);
+      authorizeUrl.searchParams.set("response_type", "code");
+      authorizeUrl.searchParams.set("client_id", MCP_CONNECT_CLIENT_ID);
+      authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+      authorizeUrl.searchParams.set("state", state);
+      authorizeUrl.searchParams.set("scope", "*");
+      authorizeUrl.searchParams.set("code_challenge", codeChallenge);
+      authorizeUrl.searchParams.set("code_challenge_method", "S256");
+      if (manualKey) {
+        authorizeUrl.searchParams.set("auth_mode", "consumer_key");
+      }
+
+      console.log(`opening browser for Machines login...`);
+      console.log(`if browser does not open, visit: ${authorizeUrl.toString()}`);
+      try {
+        openBrowser(authorizeUrl.toString());
+      } catch {
+        // User can open URL manually.
+      }
+
+      timeout = setTimeout(async () => {
+        if (settled) return;
+        settled = true;
+        await closeServer(server);
+        reject(new Error("oauth login timed out"));
+      }, timeoutMs);
+    });
+  });
+
+  const tokenPayload = await exchangeOAuthCode({
+    clientId: MCP_CONNECT_CLIENT_ID,
+    code: authResult.code,
+    redirectUri: authResult.redirectUri,
+    codeVerifier,
+  });
+
+  const authPath = await saveAuth(tokenPayload);
+  console.log(`login complete. token file: ${authPath}`);
+}
+
+async function doctorCommand() {
+  const home = os.homedir();
+  const checks = [
+    {
+      label: "codex config",
+      path: path.join(home, ".codex", "config.toml"),
+    },
+    {
+      label: "codex skill",
+      path: path.join(home, ".codex", "skills", SKILL_NAME, "SKILL.md"),
+    },
+    {
+      label: "claude settings",
+      path: path.join(home, ".claude", "settings.json"),
+    },
+    {
+      label: "claude skill",
+      path: path.join(home, ".claude", "skills", SKILL_NAME, "SKILL.md"),
+    },
+    {
+      label: "local auth cache",
+      path: path.join(home, ".machines", "agent-skill", "auth.json"),
+    },
+  ];
+
+  for (const check of checks) {
+    const exists = await pathExists(check.path);
+    console.log(`${exists ? "ok" : "missing"}  ${check.label}: ${check.path}`);
+  }
+
+  try {
+    const response = await fetch(`${MCP_URL.replace(/\/$/, "")}/.well-known/oauth-authorization-server`);
+    console.log(`${response.ok ? "ok" : "warn"}  oauth metadata: ${response.status}`);
+  } catch (error) {
+    console.log(`warn  oauth metadata: ${(error && error.message) || "unreachable"}`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  const command = args[0];
+  if (command === "install") {
+    await installCommand(args.slice(1));
+    return;
+  }
+
+  if (command === "auth") {
+    const sub = args[1];
+    if (sub !== "login") {
+      throw new Error("auth subcommand must be: login");
+    }
+    await loginCommand(args.slice(2));
+    return;
+  }
+
+  if (command === "doctor") {
+    await doctorCommand();
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`machines-agent-skill error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@machines-cash/agent-skill",
+  "version": "0.1.0",
+  "description": "Installable Machines MCP user skill and auth helper for Codex and Claude",
+  "type": "module",
+  "bin": {
+    "machines-agent-skill": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skill"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "echo 'no build step'",
+    "test": "echo 'no tests'"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: machines-user-ops
+description: Use Machines MCP user operations for cards, balances, deposits, withdrawals, and safe card-detail reveal. Trigger when users ask to manage their Machines account or spend flows.
+---
+
+# Machines User Ops
+
+Use the Machines MCP server at `https://mcp.machines.cash/mcp`.
+
+## Defaults
+- Prefer concise, end-user responses.
+- For card lists, prefer `machines.user.cards.list`.
+- For reads, prefer `machines.consumer.read` with end-user presentation.
+- Never ask users for internal IDs when the tool can resolve them.
+
+## Sensitive data
+- Never print API keys, bearer tokens, or encrypted blobs.
+- For full card details, use `machines.consumer.card_secrets.reveal` or `reveal_card_details`.
+- Do not manually stitch secrets flows unless debugging.
+
+## Common tasks
+- Create card: `machines.consumer.write` (`group="cards"`, `method="POST"`, `path=""`).
+- Update card limits/status: `machines.consumer.write` (`group="cards"`, `method="PATCH"`, `path="{cardId}"`).
+- Balance: `machines.consumer.read` (`group="balances"`).
+- Transactions: `machines.consumer.read` (`group="transactions"`).
+- Scoped session mint (if needed): `machines.consumer.sessions.create`.
+
+## Financial writes
+- Include `idempotencyKey` for financial write groups.
+- Surface short actionable errors; avoid internal route details.

package/skill/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Machines User Ops
+short_description: Manage Machines cards, balances, and payments via MCP
+default_prompt: Help the user manage their Machines account with concise, safe user operations.