@oneshot-agent/mcp-server 0.28.0 → 0.29.1

package/README.md

@@ -97,7 +97,7 @@ Get CDP credentials at [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/a
 
 ### Read authentication
 
-Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return private, per-agent data. The server wraps the OneShot TypeScript SDK, which 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. This needs no configuration; it ships in `@oneshot-agent/sdk >= 0.25.0` (the bundled dependency). The server is rolling out read-proof verification in log-only mode, so older callers keep working until enforcement is enabled.
+Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return private, per-agent data. The server wraps the OneShot TypeScript SDK, which 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. This needs no configuration; it ships in `@oneshot-agent/sdk >= 0.25.0` (the bundled dependency). The API enforces this proof by default — a request with no proof (or a mismatched one) and no valid access token is rejected.
 
 ## Remote (hosted)
 
@@ -226,7 +226,7 @@ instead of the wallet variables for a credits-only session on your own machine.
 | Tool | Description |
 |------|-------------|
 | `oneshot_spend_breakdown` | Spend by tool/category over a period |
-| `oneshot_rocs` | Return on Compute Spend analytics |
+| `oneshot_return_on_spend` | Return on spend: cost vs. value produced |
 | `oneshot_receipts_list` | List spend receipts |
 | `oneshot_tag_receipt_value` | Tag a receipt with the value it generated |
 

package/dist/index.js

@@ -52,7 +52,7 @@ async function main() {
     // Create MCP server
     const server = new Server({
         name: "oneshot-mcp",
-        version: "0.28.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.29.1", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/analytics.d.ts

@@ -10,3 +10,8 @@ export declare function handleRocs(agent: OneShot, args: Record<string, unknown>
 export declare function handleReceiptsList(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ReceiptsListResult>;
 export declare function handleRocsByGoal(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").RoCSByGoalResult>;
 export declare function handleTagReceiptValue(agent: OneShot, args: Record<string, unknown>): Promise<void>;
+/**
+ * Old tool names (renamed in 0.29.1 because "rocs" was unclear to users and
+ * to ChatGPT's review scan). Still dispatched, never listed.
+ */
+export declare const LEGACY_TOOL_ALIASES: Record<string, (agent: OneShot, args: Record<string, unknown>) => Promise<unknown>>;

package/dist/tools/analytics.js

@@ -9,8 +9,8 @@ export const spendBreakdownTool = {
     },
 };
 export const rocsTool = {
-    name: "oneshot_rocs",
-    description: "Get Return on Compute Spend (RoCS) analytics for the agent over a period. Free.",
+    name: "oneshot_return_on_spend",
+    description: "Get the agent's return on spend over a period: what its tool calls cost compared with the value they produced (return on compute spend). Free.",
     inputSchema: {
         type: "object",
         properties: {
@@ -54,9 +54,9 @@ export const tagReceiptValueTool = {
     },
 };
 export const rocsByGoalTool = {
-    name: "oneshot_rocs_by_goal",
-    description: "Per-cadence RoCS rollup: spend (receipts) vs. value (outcomes) grouped by goal_id. " +
-        "Answers 'what did this cadence cost vs. earn' in one query. Free.",
+    name: "oneshot_return_on_spend_by_goal",
+    description: "Return on spend per goal: what each goal cost (receipts) compared with the value it produced (tagged outcomes), grouped by goal_id. " +
+        "Answers 'what did this goal cost vs. earn' in one query. Free.",
     inputSchema: {
         type: "object",
         properties: {
@@ -98,3 +98,11 @@ export async function handleTagReceiptValue(agent, args) {
         label: args.label,
     });
 }
+/**
+ * Old tool names (renamed in 0.29.1 because "rocs" was unclear to users and
+ * to ChatGPT's review scan). Still dispatched, never listed.
+ */
+export const LEGACY_TOOL_ALIASES = {
+    oneshot_rocs: handleRocs,
+    oneshot_rocs_by_goal: handleRocsByGoal,
+};

package/dist/tools/annotations.d.ts

@@ -0,0 +1,16 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * MCP tool annotations for every tool (#999). ChatGPT requires all three hints
+ * on every tool, and uses them: a tool that is not read-only asks the user to
+ * confirm before it runs.
+ *
+ *   readOnlyHint     true  = retrieval only (paid lookups included — the only
+ *                            side effect is our own billing)
+ *   destructiveHint  true  = deletes, overwrites or revokes something. Sends are
+ *                            additive writes, so false — like any mail app's send.
+ *   openWorldHint    true  = reaches the public web or third parties;
+ *                    false = only the caller's own OneShot account data.
+ */
+type Hints = Required<Pick<ToolAnnotations, "title" | "readOnlyHint" | "destructiveHint" | "openWorldHint">>;
+export declare const TOOL_ANNOTATIONS: Record<string, Hints>;
+export {};

package/dist/tools/annotations.js

@@ -0,0 +1,96 @@
+/** Retrieval only. */
+const read = (title, openWorld) => ({ title, readOnlyHint: true, destructiveHint: false, openWorldHint: openWorld });
+/** Changes something. `destructive` only for delete / overwrite / revoke. */
+const write = (title, openWorld, destructive = false) => ({ title, readOnlyHint: false, destructiveHint: destructive, openWorldHint: openWorld });
+const OPEN = true;
+const OWN = false;
+const DESTRUCTIVE = true;
+export const TOOL_ANNOTATIONS = {
+    // Communication
+    oneshot_email: write("Send email", OPEN),
+    oneshot_voice: write("Place a phone call", OPEN),
+    oneshot_sms: write("Send a text message", OPEN),
+    // Inbox
+    oneshot_inbox_list: read("List received emails", OWN),
+    oneshot_inbox_get: read("Read a received email", OWN),
+    oneshot_sms_inbox_list: read("List received texts", OWN),
+    oneshot_sms_inbox_get: read("Read a received text", OWN),
+    // Inbound voice
+    oneshot_voice_number_provision: write("Get a phone number", OPEN),
+    oneshot_voice_numbers: read("List phone numbers", OWN),
+    oneshot_voice_inbound_set: write("Set up call answering", OWN, DESTRUCTIVE), // replaces the number's answering settings
+    oneshot_voice_inbound_disable: write("Stop answering calls", OWN),
+    oneshot_voice_inbound_calls: read("List answered calls", OWN),
+    // Research & enrichment
+    oneshot_research: read("Deep research", OPEN),
+    oneshot_people_search: read("Find people", OPEN),
+    oneshot_enrich_profile: read("Look up a person's profile", OPEN),
+    oneshot_find_email: read("Find a work email", OPEN),
+    oneshot_verify_email: read("Verify an email address", OPEN),
+    oneshot_web_search: read("Web search", OPEN),
+    oneshot_deep_research_person: read("Research a person", OPEN),
+    oneshot_social_profiles: read("Find social profiles", OPEN),
+    oneshot_article_search: read("Find articles about a person", OPEN),
+    oneshot_person_newsfeed: read("Get a person's recent posts", OPEN),
+    oneshot_person_interests: read("Summarize a person's interests", OPEN),
+    oneshot_person_interactions: read("Find a person's interactions", OPEN),
+    oneshot_company_search: read("Find companies", OPEN),
+    oneshot_enrich_company: read("Look up a company", OPEN),
+    oneshot_local_search: read("Find local businesses", OPEN),
+    oneshot_local_resolve: read("Look up a local business", OPEN),
+    oneshot_gov_solicitations: read("Find government contracts", OPEN),
+    // Commerce
+    oneshot_commerce_search: read("Search products", OPEN),
+    oneshot_commerce_buy: write("Buy a product", OPEN),
+    // Compute orchestration
+    oneshot_compute: write("Start a goal", OPEN),
+    oneshot_compute_status: read("Check a goal", OWN),
+    oneshot_compute_tasks: read("List a goal's tasks", OWN),
+    oneshot_compute_cancel: write("Cancel a goal", OWN, DESTRUCTIVE),
+    oneshot_compute_respond: write("Answer a goal's question", OWN),
+    oneshot_compute_pause: write("Pause a goal", OWN),
+    oneshot_compute_resume: write("Resume a goal", OWN),
+    oneshot_compute_fund: write("Add budget to a goal", OWN),
+    // Build
+    oneshot_build: write("Build a website", OPEN),
+    oneshot_update_build: write("Update a website", OPEN, DESTRUCTIVE), // overwrites the live site
+    // Browser
+    oneshot_browser: write("Browse and act on a website", OPEN),
+    oneshot_browser_create_profile: write("Create a browser profile", OWN),
+    oneshot_browser_list_profiles: read("List browser profiles", OWN),
+    oneshot_browser_delete_profile: write("Delete a browser profile", OWN, DESTRUCTIVE),
+    // Web read
+    oneshot_web_read: read("Read a web page", OPEN),
+    // LinkedIn
+    oneshot_linkedin_connect: write("Connect LinkedIn", OPEN),
+    oneshot_linkedin_accounts: read("List LinkedIn accounts", OWN),
+    oneshot_linkedin_sync: write("Sync LinkedIn messages", OPEN), // paid; imports history into the account
+    oneshot_linkedin_conversations: read("List LinkedIn conversations", OWN),
+    oneshot_linkedin_messages: read("Read LinkedIn messages", OWN),
+    oneshot_linkedin_reply: write("Send a LinkedIn message", OPEN),
+    oneshot_linkedin_invite: write("Send a LinkedIn invitation", OPEN),
+    oneshot_linkedin_withdraw_invitation: write("Withdraw a LinkedIn invitation", OPEN, DESTRUCTIVE),
+    oneshot_linkedin_view_profile: write("View a LinkedIn profile", OPEN), // notify=true is visible to the person
+    oneshot_linkedin_react: write("React to a LinkedIn post", OPEN),
+    // Domains
+    oneshot_list_domains: read("List sending domains", OWN),
+    oneshot_pause_domain: write("Pause a sending domain", OWN),
+    oneshot_resume_domain: write("Resume a sending domain", OWN),
+    // Analytics
+    oneshot_spend_breakdown: read("Show spending", OWN),
+    oneshot_return_on_spend: read("Show return on spend", OWN),
+    oneshot_return_on_spend_by_goal: read("Show return on spend by goal", OWN),
+    oneshot_receipts_list: read("List receipts", OWN),
+    oneshot_tag_receipt_value: write("Tag a receipt's value", OWN),
+    // Account
+    oneshot_notifications: read("List notifications", OWN),
+    oneshot_mark_notification_read: write("Mark a notification read", OWN),
+    oneshot_get_balance: read("Check balance", OWN),
+    oneshot_budget_status: read("Check budget", OWN),
+    // Approvals
+    oneshot_approval_create: write("Ask a person to approve", OPEN),
+    oneshot_approval_get: read("Check an approval", OWN),
+    oneshot_approval_list: read("List approvals", OWN),
+    oneshot_approval_cancel: write("Cancel an approval", OWN, DESTRUCTIVE),
+    oneshot_action_policy: read("Show approval rules", OWN),
+};

package/dist/tools/index.js

@@ -22,9 +22,10 @@ import { govSolicitationsTool, handleGovSolicitations } from "./gov.js";
 import { linkedinConnectTool, linkedinAccountsTool, linkedinSyncTool, linkedinConversationsTool, linkedinMessagesTool, linkedinReplyTool, linkedinViewProfileTool, linkedinReactTool, linkedinInviteTool, linkedinWithdrawInvitationTool, handleLinkedinConnect, handleLinkedinAccounts, handleLinkedinSync, handleLinkedinConversations, handleLinkedinMessages, handleLinkedinReply, handleLinkedinViewProfile, handleLinkedinReact, handleLinkedinInvite, handleLinkedinWithdrawInvitation, } from "./linkedin.js";
 import { computeTool, computeStatusTool, computeTasksTool, computeCancelTool, computeRespondTool, computePauseTool, computeResumeTool, computeFundTool, handleCompute, handleComputeStatus, handleComputeTasks, handleComputeCancel, handleComputeRespond, handleComputePause, handleComputeResume, handleComputeFund } from "./compute.js";
 import { listDomainsTool, pauseDomainTool, resumeDomainTool, handleListDomains, handlePauseDomain, handleResumeDomain } from "./domains.js";
-import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue } from "./analytics.js";
-// All available tools
-export const tools = [
+import { TOOL_ANNOTATIONS } from "./annotations.js";
+import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue, LEGACY_TOOL_ALIASES } from "./analytics.js";
+// All available tools, before annotations
+const toolDefinitions = [
     // Communication
     emailTool,
     voiceTool,
@@ -112,6 +113,14 @@ export const tools = [
     approvalCancelTool,
     actionPolicyGetTool,
 ];
+// Every tool carries a human title and the three MCP hints clients rely on
+// (ChatGPT confirms any tool that is not read-only). See annotations.ts.
+export const tools = toolDefinitions.map((tool) => {
+    const hints = TOOL_ANNOTATIONS[tool.name];
+    if (!hints)
+        throw new Error(`Tool ${tool.name} has no annotations — add it to tools/annotations.ts`);
+    return { ...tool, title: hints.title, annotations: { ...hints } };
+});
 // Tool handlers map
 const handlers = {
     // Communication
@@ -186,8 +195,10 @@ const handlers = {
     "oneshot_resume_domain": handleResumeDomain,
     // Analytics
     "oneshot_spend_breakdown": handleSpendBreakdown,
-    "oneshot_rocs": handleRocs,
-    "oneshot_rocs_by_goal": handleRocsByGoal,
+    "oneshot_return_on_spend": handleRocs,
+    "oneshot_return_on_spend_by_goal": handleRocsByGoal,
+    // Pre-0.29.1 names: callable, never listed, so existing clients keep working.
+    ...LEGACY_TOOL_ALIASES,
     "oneshot_receipts_list": handleReceiptsList,
     "oneshot_tag_receipt_value": handleTagReceiptValue,
     // Account

package/dist/tools/voice-inbound.js

@@ -2,7 +2,7 @@ export const voiceNumberProvisionTool = {
     name: "oneshot_voice_number_provision",
     description: "Get this agent a phone number without placing a call, so it can answer calls (then use oneshot_voice_inbound_set). " +
         "Returns the existing number for free; otherwise buys one and charges the one-time phone registration fee from prepaid credits. " +
-        "Fails with 402 and buys nothing when credits are too low. Requires a wallet session (not available with an agent access token).",
+        "Fails with 402 and buys nothing when credits are too low. Needs a wallet or OAuth session; a plain agent access token cannot buy numbers.",
     inputSchema: { type: "object", properties: {} },
 };
 export const voiceNumbersTool = {
@@ -15,7 +15,7 @@ export const voiceInboundSetTool = {
     description: "Make one of the agent's numbers answer its own calls. Replaces the whole inbound config. " +
         "During business hours the assistant follows `prompt`; after hours it takes a message, transfers, or declines. " +
         "Calls are paid from prepaid credits per started minute and are declined when credits cannot cover the minimum fee. " +
-        "Requires a wallet session (not available with an agent access token).",
+        "Needs a wallet or OAuth session; a plain agent access token can only read these settings.",
     inputSchema: {
         type: "object",
         properties: {
@@ -56,7 +56,7 @@ export const voiceInboundSetTool = {
 };
 export const voiceInboundDisableTool = {
     name: "oneshot_voice_inbound_disable",
-    description: "Stop answering calls to one of the agent's numbers. The settings are kept, disabled. Free. Requires a wallet session.",
+    description: "Stop answering calls to one of the agent's numbers. The settings are kept, disabled. Free. Needs a wallet or OAuth session.",
     inputSchema: {
         type: "object",
         properties: { phone_number_id: { type: "string", description: "Number id from oneshot_voice_numbers" } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneshot-agent/mcp-server",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "MCP server for OneShot - 73 tools 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.42.0",
+    "@oneshot-agent/sdk": "^0.43.0",
     "zod": "3.25.76"
   },
   "devDependencies": {