@oneshot-agent/mcp-server 0.15.0 → 0.17.0

package/README.md

@@ -20,6 +20,11 @@ The server supports two auth methods: **CDP Wallet** (recommended, no private ke
 | `CDP_API_KEY_SECRET` | Option A | Coinbase CDP API key secret |
 | `CDP_WALLET_SECRET` | Option A | Coinbase CDP wallet secret |
 | `ONESHOT_WALLET_PRIVATE_KEY` | Option B | Raw private key for signing payments |
+| `ONESHOT_BUDGET_DAILY` | No | Max USDC the agent may spend per UTC day (spend budget, enforced server-side) |
+| `ONESHOT_BUDGET_PER_TRANSACTION` | No | Max USDC for any single call |
+| `ONESHOT_BUDGET_ALERT_AT` | No | Fraction of the daily budget that triggers a warning (default 0.8) |
+| `ONESHOT_BUDGET_PAUSE_AT` | No | Fraction at which paid calls stop (default 1.0) |
+| `ONESHOT_BUDGET_ALERT_EMAIL` | No | Email for budget alerts |
 
 ### Claude Desktop
 
@@ -83,6 +88,10 @@ Add to `~/.claude/settings.json`:
 
 Get CDP credentials at [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/welcome). Or use `ONESHOT_WALLET_PRIVATE_KEY` instead of CDP env vars for raw key auth.
 
+### Read authentication
+
+Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return private, per-agent data. The server wraps the OneShot TypeScript SDK, which automatically signs a short-lived **EIP-712 read proof** (`x-agent-proof`) on each read so the API can verify you control the `X-Agent-ID` wallet. No configuration needed — this ships via `@oneshot-agent/sdk >= 0.25.0` (the bundled dependency). Read-proof verification is rolling out in log-only mode server-side, so older callers keep working until enforcement is enabled.
+
 ## Available Tools
 
 ### Communication
@@ -181,6 +190,7 @@ Get CDP credentials at [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/a
 | `oneshot_notifications` | List agent notifications |
 | `oneshot_mark_notification_read` | Mark notification as read |
 | `oneshot_get_balance` | Get USDC wallet balance |
+| `oneshot_budget_status` | Today's spend vs the configured budget (read-only) |
 
 All paid tools are priced in USDC via the x402 protocol. See [Pricing](https://docs.oneshotagent.com/pricing) for current rates.
 

package/dist/budget-env.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Spend budget from ONESHOT_BUDGET_* env vars. Set at the process level by the
+ * developer, never by the model: the only budget tool exposed to the agent
+ * (oneshot_budget_status) is read-only — a guardrail the agent can raise
+ * itself isn't a guardrail. Unset → undefined → the SDK leaves whatever is
+ * stored server-side untouched.
+ */
+export declare function budgetConfigFromEnv(env?: NodeJS.ProcessEnv): {
+    budgets?: {
+        daily?: number;
+        perTransaction?: number;
+        alertAt?: number;
+        pauseAt?: number;
+    };
+    alerts?: {
+        email?: string;
+    };
+};

package/dist/budget-env.js

@@ -0,0 +1,47 @@
+/**
+ * Spend budget from ONESHOT_BUDGET_* env vars. Set at the process level by the
+ * developer, never by the model: the only budget tool exposed to the agent
+ * (oneshot_budget_status) is read-only — a guardrail the agent can raise
+ * itself isn't a guardrail. Unset → undefined → the SDK leaves whatever is
+ * stored server-side untouched.
+ */
+export function budgetConfigFromEnv(env = process.env) {
+    const problems = [];
+    // A set-but-invalid value must fail startup, not silently become "no cap":
+    // the SDK would reject it server-side and the agent would run unguarded.
+    const read = (name, check, rule) => {
+        const raw = env[name];
+        if (raw === undefined)
+            return undefined;
+        // Blank = unset, deliberately: `${VAR}` templating in compose/CI yields ""
+        // for an unset variable, and failing startup there would break every
+        // deployment that templates optional vars. Warn so it's never silent.
+        if (raw.trim() === "") {
+            console.error(`Warning: ${name} is set but blank — treating as unset (no cap from this variable)`);
+            return undefined;
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n) || !check(n)) {
+            problems.push(`${name}=${JSON.stringify(raw)} (${rule})`);
+            return undefined;
+        }
+        return n;
+    };
+    const budgets = {
+        daily: read("ONESHOT_BUDGET_DAILY", (n) => n > 0, "must be a positive number"),
+        perTransaction: read("ONESHOT_BUDGET_PER_TRANSACTION", (n) => n > 0, "must be a positive number"),
+        alertAt: read("ONESHOT_BUDGET_ALERT_AT", (n) => n > 0 && n <= 1, "must be a fraction in (0, 1]"),
+        pauseAt: read("ONESHOT_BUDGET_PAUSE_AT", (n) => n > 0 && n <= 1, "must be a fraction in (0, 1]"),
+    };
+    const email = env.ONESHOT_BUDGET_ALERT_EMAIL?.trim();
+    if (email && !email.includes("@"))
+        problems.push(`ONESHOT_BUDGET_ALERT_EMAIL=${JSON.stringify(email)} (must be an email address)`);
+    if (problems.length) {
+        throw new Error(`Invalid spend budget configuration:\n  ${problems.join("\n  ")}`);
+    }
+    const hasBudget = Object.values(budgets).some((v) => v !== undefined);
+    return {
+        ...(hasBudget ? { budgets } : {}),
+        ...(email ? { alerts: { email } } : {}),
+    };
+}

package/dist/index.js

@@ -4,17 +4,29 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { OneShot } from "@oneshot-agent/sdk";
 import { tools, handleToolCall } from "./tools/index.js";
+import { budgetConfigFromEnv } from "./budget-env.js";
 const CDP_KEY_ID = process.env.CDP_API_KEY_ID;
 const PRIVATE_KEY = process.env.ONESHOT_WALLET_PRIVATE_KEY;
 async function initAgent() {
+    let budget;
+    try {
+        budget = budgetConfigFromEnv();
+    }
+    catch (err) {
+        // Fail visibly: a mis-set ONESHOT_BUDGET_* must not start an unguarded agent.
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+    if (budget.budgets)
+        console.error(`Spend budget: ${JSON.stringify(budget.budgets)}`);
     if (CDP_KEY_ID) {
         // Preferred: Coinbase CDP Server Wallet (no private key exposure)
         console.error("Using Coinbase CDP wallet");
-        return OneShot.create({ cdp: true });
+        return OneShot.create({ cdp: true, ...budget });
     }
     if (PRIVATE_KEY) {
         // Fallback: raw private key
-        return new OneShot({ privateKey: PRIVATE_KEY });
+        return new OneShot({ privateKey: PRIVATE_KEY, ...budget });
     }
     console.error("Error: Set CDP_API_KEY_ID + CDP_API_KEY_SECRET + CDP_WALLET_SECRET (recommended)\n" +
         "       or ONESHOT_WALLET_PRIVATE_KEY");
@@ -26,7 +38,7 @@ async function main() {
     // Create MCP server
     const server = new Server({
         name: "oneshot-mcp",
-        version: "0.15.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.17.0", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/domains.js

@@ -1,6 +1,6 @@
 export const listDomainsTool = {
     name: "oneshot_list_domains",
-    description: "List the agent's sending domains. Each has default_from (canonical default sender, e.g. agent@domain — billed like any address on its first send), addresses[] (mailboxes already provisioned — {address, status, warmup_state}; empty means none yet), pool_status (rotation eligibility: active|paused|removed), warmup_state (reputation health: warming|warmed|degraded), pause_reason (warming|low_reputation|manual|null), warmup_score, and daily send limits. A domain can be paused AND warming — reputation pauses auto-recover once warmed; manual pauses need a resume. Free.",
+    description: "List the agent's sending domains. Each has default_from (canonical default sender, e.g. agent@domain — billed like any address on its first send), mailbox_mode (relay|mailbox), addresses[] (mailboxes already provisioned — {address, status, warmup_state}; empty means none yet), pool_status (rotation eligibility: active|paused|removed), warmup_state (reputation health: warming|warmed|degraded), pause_reason (warming|low_reputation|manual|null), warmup_score, and daily send limits. mailbox_mode is a property of the domain, fixed when it was set up: on a 'mailbox' domain EVERY address not already active in addresses[] bills the one-time mailbox_provisioning_fee on its first send, the canonical default_from included — omitting mailbox_mode when you quote does not make the send relay. 'relay' domains never charge it. A domain can be paused AND warming — reputation pauses auto-recover once warmed; manual pauses need a resume. Free.",
     inputSchema: { type: "object", properties: {} },
 };
 export const pauseDomainTool = {

package/dist/tools/email.js

@@ -35,7 +35,7 @@ export const emailTool = {
             mailbox_mode: {
                 type: "string",
                 enum: ["relay", "mailbox"],
-                description: "How this domain sends (optional, defaults to 'relay'). 'relay' = header send, no per-address mailbox, no mailbox fee. 'mailbox' = a real dedicated mailbox per address (better deliverability + per-address warmup); each new address adds a one-time mailbox_provisioning_fee to the quote. Only applies when a domain is first set up — use it on a new from_domain; an existing domain keeps the mode it was created with.",
+                description: "How this domain sends (optional). 'relay' = header send, no per-address mailbox, no mailbox fee. 'mailbox' = a real dedicated mailbox per address (better deliverability + per-address warmup); each new address adds a one-time mailbox_provisioning_fee to the quote. Only honored while a domain is unprovisioned (brand new, or owned with provisioning_status 'unprovisioned') — an already-provisioned domain keeps the mode it was created with, which means OMITTING this does not make a send relay and does not avoid the fee. On a domain already in mailbox mode every address that isn't active yet bills the fee on its first send, the default agent@ included; from_mailbox does not change that. Use oneshot_list_domains to see each domain's mailbox_mode before quoting.",
             },
             attachments: {
                 type: "array",

package/dist/tools/index.js

@@ -8,7 +8,7 @@ import { enrichProfileTool, findEmailTool, verifyEmailTool, handleEnrichProfile,
 import { inboxListTool, inboxGetTool, handleInboxList, handleInboxGet } from "./inbox.js";
 import { smsInboxListTool, smsInboxGetTool, handleSmsInboxList, handleSmsInboxGet } from "./sms-inbox.js";
 import { notificationsTool, markReadTool, handleNotifications, handleMarkRead } from "./notifications.js";
-import { getBalanceTool, handleGetBalance } from "./wallet.js";
+import { getBalanceTool, budgetStatusTool, handleGetBalance, handleBudgetStatus } from "./wallet.js";
 import { buildTool, updateBuildTool, handleBuild, handleUpdateBuild } from "./build.js";
 import { browserTool, browserCreateProfileTool, browserListProfilesTool, browserDeleteProfileTool, handleBrowser, handleBrowserCreateProfile, handleBrowserListProfiles, handleBrowserDeleteProfile } from "./browser.js";
 import { webSearchTool, handleWebSearch } from "./search.js";
@@ -77,6 +77,7 @@ export const tools = [
     notificationsTool,
     markReadTool,
     getBalanceTool,
+    budgetStatusTool,
 ];
 // Tool handlers map
 const handlers = {
@@ -137,6 +138,7 @@ const handlers = {
     "oneshot_notifications": handleNotifications,
     "oneshot_mark_notification_read": handleMarkRead,
     "oneshot_get_balance": handleGetBalance,
+    "oneshot_budget_status": handleBudgetStatus,
 };
 export async function handleToolCall(agent, toolName, args) {
     const handler = handlers[toolName];

package/dist/tools/wallet.d.ts

@@ -2,3 +2,5 @@ import { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { OneShot } from "@oneshot-agent/sdk";
 export declare const getBalanceTool: Tool;
 export declare function handleGetBalance(agent: OneShot, _args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").UnifiedBalance>;
+export declare const budgetStatusTool: Tool;
+export declare function handleBudgetStatus(agent: OneShot, _args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").AgentBudgetStatus>;

package/dist/tools/wallet.js

@@ -10,3 +10,17 @@ export async function handleGetBalance(agent, _args) {
     const balance = await agent.getUnifiedBalance();
     return balance;
 }
+export const budgetStatusTool = {
+    name: "oneshot_budget_status",
+    description: "Read-only: today's spend versus the agent's configured spend budget — daily cap, per-call cap, " +
+        "spent_today_usdc, remaining_usdc, pct_used and resets_at (next UTC midnight). Use it to plan " +
+        "remaining work; paid calls are rejected with budget_exceeded once the cap is reached. The budget " +
+        "itself is set by the operator via ONESHOT_BUDGET_* env vars and cannot be changed from here. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+export async function handleBudgetStatus(agent, _args) {
+    return agent.budgets();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneshot-agent/mcp-server",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "MCP server for OneShot - commercial actions for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
   "dependencies": {
     "@coinbase/cdp-sdk": "1.45.0",
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@oneshot-agent/sdk": "^0.23.0",
+    "@oneshot-agent/sdk": "^0.27.0",
     "zod": "3.25.76"
   },
   "devDependencies": {