@agentkv/cli 0.1.0

package/dist/mcp-MINXA6WX.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+import {
+  VERSION,
+  clientFromConfig,
+  forbiddenEnvKey,
+  getOnrampProvider,
+  peekStoredAccount,
+  readConfigFile,
+  readEnvSecret,
+  readFileSecret,
+  resolveConfig,
+  runWithSecret,
+  scrubSensitiveEnv,
+  writeSecretFile
+} from "./chunk-34AG6FLC.js";
+
+// src/mcp.ts
+import { existsSync } from "fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var toolError = (error, code) => ({
+  isError: true,
+  content: [{ type: "text", text: JSON.stringify({ error, code }) }]
+});
+function buildMcpServer(client, onramp, accountMode = false) {
+  const server = new McpServer({ name: "agentkv", version: VERSION });
+  server.tool(
+    "agentkv_set",
+    "Store an encrypted value under a key (costs $0.005 USD per write, or 5 credits \u2248 $0.0005 via prepay). NOTE: the value passes through this agent's model context \u2014 do NOT use for secrets; use agentkv_set_from_env or agentkv_set_from_file instead.",
+    {
+      key: z.string().describe("The key to store the value under"),
+      // .refine(v !== undefined) marks `value` REQUIRED in the advertised JSON schema. A bare
+      // z.unknown() is optional (isOptional() === true), so the schema omitted `value` from
+      // `required` and the SDK accepted {key} — then client.set(key, undefined) threw a
+      // confusing runtime invalid_value instead of a protocol-level InvalidParams rejection.
+      value: z.unknown().refine((v) => v !== void 0, { message: "value is required" }).describe("The value to encrypt and store"),
+      ttl_days: z.number().optional().describe("Time-to-live in days"),
+      strict_ttl: z.boolean().optional().describe("If true, reads do not slide the expiry"),
+      idempotency_key: z.string().optional().describe(
+        "Stable key making a retried write exactly-once \u2014 reuse the same value across retries so the server dedupes instead of double-charging"
+      )
+    },
+    {
+      title: "Set value",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await client.set(args.key, args.value, {
+              ttlDays: args.ttl_days,
+              strictTtl: args.strict_ttl,
+              idempotencyKey: args.idempotency_key
+            })
+          )
+        }
+      ]
+    })
+  );
+  server.tool(
+    "agentkv_get",
+    "Read and decrypt a value by key (costs $0.003 USD per read, or 3 credits \u2248 $0.0003 via prepay); returns null if absent. NOTE: the decrypted value is returned into this agent's model context \u2014 do NOT use for secrets; use agentkv_get_to_file or agentkv_run_with_secret instead.",
+    {
+      key: z.string().describe("The key to retrieve"),
+      idempotency_key: z.string().optional().describe(
+        "Stable key making a retried read exactly-once \u2014 reuse the same value across retries so the server dedupes instead of double-charging"
+      )
+    },
+    { title: "Get value", readOnlyHint: true, openWorldHint: true },
+    async (args) => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await client.get(
+              args.key,
+              args.idempotency_key ? { idempotencyKey: args.idempotency_key } : {}
+            )
+          )
+        }
+      ]
+    })
+  );
+  server.tool(
+    "agentkv_delete",
+    "Delete a key (free operation)",
+    { key: z.string().describe("The key to delete") },
+    {
+      title: "Delete key",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    async (args) => ({
+      content: [{ type: "text", text: JSON.stringify(await client.delete(args.key)) }]
+    })
+  );
+  server.tool(
+    "agentkv_deposit",
+    "Buy credits with USDC (any amount \u2265 $1; credits are 1/10 the pay-per-op price). Real payment \u2014 $amount_usd is charged from the wallet.",
+    { amount_usd: z.number().describe("Amount in USD to deposit as credits") },
+    {
+      title: "Deposit credits",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => {
+      if (accountMode) {
+        return toolError(
+          `Account-key mode has no signing wallet to pay from. Account credits are added by depositing USDC to ${client.endpoint}/account/deposit from a wallet that can sign (e.g. awal), not via this tool.`,
+          "account_mode"
+        );
+      }
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(await client.deposit(args.amount_usd)) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "agentkv_balance",
+    "Read the current credit balance (free)",
+    {},
+    { title: "Read balance", readOnlyHint: true, openWorldHint: true },
+    async () => ({
+      content: [
+        { type: "text", text: JSON.stringify({ balance: await client.balance() }) }
+      ]
+    })
+  );
+  server.tool(
+    "agentkv_wallet_address",
+    "Return this agent's wallet address (its namespace in AgentKV)",
+    {},
+    { title: "Wallet address", readOnlyHint: true, openWorldHint: false },
+    async () => ({
+      content: [
+        {
+          type: "text",
+          // Account-key mode has no wallet; client.address is the zero-address sentinel, so
+          // returning it verbatim would misrepresent identity. Report account-key mode instead.
+          text: JSON.stringify(
+            accountMode ? {
+              mode: "account-key",
+              address: null,
+              note: "account-key mode has no wallet address; the account is identified by its bearer key"
+            } : { address: client.address }
+          )
+        }
+      ]
+    })
+  );
+  server.tool(
+    "agentkv_fund",
+    "Return a card\u2192USDC onramp URL that delivers USDC to this agent's wallet (its namespace). Read-only \u2014 builds a URL, no payment is made. Open the URL to buy USDC and have it sent to the wallet on Base; then use agentkv_deposit to convert USDC to credits.",
+    {
+      amount_usd: z.number().optional().describe("Optional preset fiat (USD) amount to pre-fill in the onramp")
+    },
+    { title: "Fund via onramp", readOnlyHint: true, openWorldHint: true },
+    async (args) => {
+      if (accountMode) {
+        return toolError(
+          `Account-key mode has no single wallet to onramp into. Account credits are funded by depositing USDC to ${client.endpoint}/account/deposit from a wallet that can sign (e.g. awal). An onramp can fund such a signing wallet: fund a wallet first (e.g. send USDC to it, \`awal address\`, or set AGENTKV_PRIVATE_KEY and re-run the funding flow), then deposit to the account.`,
+          "account_mode"
+        );
+      }
+      if (!onramp) {
+        return toolError(
+          "onramp is not configured for this server (no provider/config available)",
+          "onramp_unavailable"
+        );
+      }
+      let provider;
+      try {
+        provider = getOnrampProvider(onramp.provider);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e), "unknown_provider");
+      }
+      let url;
+      try {
+        url = provider.buildUrl({
+          address: client.address,
+          network: onramp.network,
+          amountUsd: args.amount_usd,
+          config: onramp.config
+        });
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e), "onramp_config");
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ provider: provider.id, url, address: client.address })
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "agentkv_list_keys",
+    "List this wallet's stored keys \u2014 the real key NAMES, decrypted locally. The server only ever sees opaque per-wallet digests + ciphertext, never plaintext key names. Free (identity-signed). Paginated: pass the returned cursor to fetch the next page.",
+    {
+      cursor: z.string().optional().describe("Opaque pagination cursor from a previous call"),
+      limit: z.number().optional().describe("Max keys per page")
+    },
+    { title: "List keys", readOnlyHint: true, openWorldHint: true },
+    async (args) => {
+      const res = await client.listKeys({ cursor: args.cursor ?? null, limit: args.limit });
+      return { content: [{ type: "text", text: JSON.stringify(res) }] };
+    }
+  );
+  server.tool(
+    "agentkv_set_from_env",
+    "Store a secret read from a LOCAL environment variable, without the value entering this agent's model context. Pass the env var NAME (not its value); the server reads it locally, encrypts, and stores it. Use this (not agentkv_set) for credentials.",
+    {
+      key: z.string().describe("The key to store under"),
+      env_var: z.string().describe(
+        "Name of the local environment variable whose value to store (never sent to the model)"
+      ),
+      ttl_days: z.number().optional().describe("Time-to-live in days"),
+      strict_ttl: z.boolean().optional().describe("If true, reads do not slide the expiry"),
+      idempotency_key: z.string().optional().describe("Stable key for exactly-once retried writes")
+    },
+    {
+      title: "Set from env var",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => {
+      const r = readEnvSecret(args.env_var);
+      if (!r.ok) return toolError(r.error, r.code);
+      const res = await client.set(args.key, r.value, {
+        ttlDays: args.ttl_days,
+        strictTtl: args.strict_ttl,
+        idempotencyKey: args.idempotency_key
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res) }] };
+    }
+  );
+  server.tool(
+    "agentkv_set_from_file",
+    "Store a secret read from a LOCAL file, without the contents entering this agent's model context. Pass the file PATH; the server reads it locally (as UTF-8 text, trimming one trailing newline unless trim:false \u2014 not for binary key material), encrypts, and stores it. Use this (not agentkv_set) for credentials.",
+    {
+      key: z.string().describe("The key to store under"),
+      path: z.string().describe("Local file path to read (contents never sent to the model)"),
+      trim: z.boolean().optional().describe("Trim a single trailing newline (default true)"),
+      ttl_days: z.number().optional().describe("Time-to-live in days"),
+      strict_ttl: z.boolean().optional().describe("If true, reads do not slide the expiry"),
+      idempotency_key: z.string().optional().describe("Stable key for exactly-once retried writes")
+    },
+    {
+      title: "Set from file",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => {
+      const r = readFileSecret(args.path, { trim: args.trim });
+      if (!r.ok) return toolError(r.error, r.code);
+      const res = await client.set(args.key, r.value, {
+        ttlDays: args.ttl_days,
+        strictTtl: args.strict_ttl,
+        idempotencyKey: args.idempotency_key
+      });
+      return { content: [{ type: "text", text: JSON.stringify(res) }] };
+    }
+  );
+  server.tool(
+    "agentkv_get_to_file",
+    "Read a secret and write the decrypted value to a LOCAL FILE, without the value entering this agent's model context. Returns { found, path, bytes } \u2014 the file path and byte count, never the value. Performs a paid read each call. The destination must NOT already exist (a fresh path is created \u2014 this prevents overwriting or symlink redirection); omit `path` for a private temp file. Use this (not agentkv_get) for credentials, then delete the file when done.",
+    {
+      key: z.string().describe("The key to read"),
+      path: z.string().optional().describe("Destination file path; if omitted, a private temp file is created"),
+      idempotency_key: z.string().optional().describe("Stable key for exactly-once retried reads")
+    },
+    {
+      title: "Get to file",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => {
+      if (args.path && existsSync(args.path)) {
+        return toolError(
+          "destination already exists; choose a fresh path that does not already exist",
+          "dest_exists"
+        );
+      }
+      const v = await client.get(
+        args.key,
+        args.idempotency_key ? { idempotencyKey: args.idempotency_key } : {}
+      );
+      if (v === null || v === void 0) {
+        return { content: [{ type: "text", text: JSON.stringify({ found: false }) }] };
+      }
+      const text = typeof v === "string" ? v : JSON.stringify(v);
+      let written;
+      try {
+        written = writeSecretFile(text, args.path);
+      } catch (e) {
+        const code = e?.code;
+        if (code === "EEXIST")
+          return toolError("destination already exists; choose a fresh path", "dest_exists");
+        if (code === "ENOENT")
+          return toolError("destination parent directory does not exist", "dest_parent_missing");
+        if (code === "EACCES" || code === "EPERM")
+          return toolError("destination is not writable", "dest_unwritable");
+        return toolError("could not write file", "write_failed");
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ found: true, path: written.path, bytes: written.bytes })
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "agentkv_run_with_secret",
+    "Run a command with a stored secret injected into the child process's environment ONLY, without the value entering this agent's model context. Pass the env var NAME + command + args; the server decrypts the secret, sets it in the child env, runs the command, and returns its exit code + output (not the secret). Performs a paid read each call. The command must not echo the secret. Use this to USE a credential without the model ever seeing it.",
+    {
+      key: z.string().describe("The key holding the secret"),
+      env_var: z.string().describe("Env var name to expose the secret as in the child process"),
+      command: z.string().describe("Executable to run (no shell; pass a real executable)"),
+      args: z.array(z.string()).optional().describe("Arguments passed as argv (no shell expansion)"),
+      cwd: z.string().optional().describe("Working directory"),
+      timeout_ms: z.number().optional().describe(
+        "Kill the command after this many ms (default 120000; values \u22640 use the default)"
+      ),
+      extra_env: z.record(z.string()).optional().describe("Additional NON-secret env vars to set for the child process"),
+      idempotency_key: z.string().optional().describe("Stable key for exactly-once retried reads")
+    },
+    {
+      title: "Run with secret",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    async (args) => {
+      const badEnv = forbiddenEnvKey([args.env_var, ...Object.keys(args.extra_env ?? {})]);
+      if (badEnv) return toolError(`refusing process-hijack env var: ${badEnv}`, "forbidden_env");
+      const v = await client.get(
+        args.key,
+        args.idempotency_key ? { idempotencyKey: args.idempotency_key } : {}
+      );
+      if (v === null || v === void 0) return toolError(`key ${args.key} not found`, "not_found");
+      const secret = typeof v === "string" ? v : JSON.stringify(v);
+      let result;
+      try {
+        result = await runWithSecret({
+          secret,
+          envVar: args.env_var,
+          command: args.command,
+          args: args.args,
+          cwd: args.cwd,
+          timeoutMs: args.timeout_ms,
+          extraEnv: args.extra_env
+        });
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e), "spawn_failed");
+      }
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+  );
+  return server;
+}
+async function startMcp(deps = {}) {
+  const env = deps.env ?? process.env;
+  const cfg = resolveConfig({}, env, () => readConfigFile(env));
+  const client = deps.client ?? clientFromConfig(cfg, {
+    env,
+    // CRITICAL: notice to stderr only — stdout is the MCP JSON-RPC channel.
+    notify: (m) => process.stderr.write(`agentkv: ${m}
+`)
+  });
+  const accountMode = cfg.accountKey != null || cfg.privateKey == null && peekStoredAccount(env) != null;
+  scrubSensitiveEnv(env);
+  const server = buildMcpServer(
+    client,
+    {
+      provider: cfg.onrampProvider ?? "coinbase",
+      network: cfg.network,
+      config: cfg.onrampConfig ?? {}
+    },
+    accountMode
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  await new Promise((resolve) => {
+    server.server.onclose = resolve;
+    process.stdin.once("close", resolve);
+    process.stdin.once("end", resolve);
+  });
+}
+export {
+  buildMcpServer,
+  startMcp
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agentkv/cli",
+  "version": "0.1.0",
+  "description": "AgentKV CLI and MCP server: read/write encrypted, x402-paid key-value data from the terminal or any MCP client",
+  "license": "MIT",
+  "author": "The AgentKV Authors <contact@agentx402.ai>",
+  "homepage": "https://github.com/agentx402-ai/agentkv#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentx402-ai/agentkv.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/agentx402-ai/agentkv/issues"
+  },
+  "keywords": [
+    "agentkv",
+    "x402",
+    "cli",
+    "mcp",
+    "key-value",
+    "encrypted",
+    "zero-knowledge",
+    "usdc",
+    "agent",
+    "wallet"
+  ],
+  "type": "module",
+  "bin": {
+    "agentkv": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "tsc --noEmit && vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentkv/client": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.21.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}