@oneshot-agent/mcp-server 0.27.0 → 0.29.0

package/README.md

@@ -1,6 +1,12 @@
 # @oneshot-agent/mcp-server
 
-MCP (Model Context Protocol) server for [OneShot](https://oneshotagent.com) - enabling AI agents to execute commercial actions.
+MCP (Model Context Protocol) server for [OneShot](https://oneshotagent.com). It gives any MCP client (Claude Desktop, Cursor, Claude Code) OneShot's tools: email, calls, SMS, research, enrichment, commerce, website builds. Paid calls are charged one at a time and show up in your receipts. An optional daily budget caps the spend.
+
+Quick start:
+
+1. Install the server (below).
+2. Add it to your client's MCP config with CDP credentials ([Configuration](#configuration)).
+3. Send USDC on Base to the agent's wallet ([Funding Your Agent](#funding-your-agent)).
 
 ## Installation
 
@@ -10,7 +16,7 @@ npm install -g @oneshot-agent/mcp-server
 
 ## Configuration
 
-The server supports three auth methods: **CDP Wallet** (recommended, no private keys in config), a raw private key, or an **access token** (credits-only session, no key at all — see Remote below).
+Pick one of three auth methods: **CDP Wallet** (recommended, no private keys in config), a raw private key, or an **access token** (credits-only session with no key; see Remote below).
 
 ### Environment Variables
 
@@ -87,16 +93,16 @@ 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.
+Get CDP credentials at [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/welcome), or use `ONESHOT_WALLET_PRIVATE_KEY` instead of the 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.
+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)
 
-Clients that run in someone else's cloud — Grok Bot, hosted runners — cannot spawn this
-server and must not hold a wallet key. For them OneShot hosts the same 73 tools over
+Clients that run in someone else's cloud (Grok Bot, hosted runners) cannot spawn this
+server and must not hold a wallet key. For them, OneShot hosts the same 73 tools over
 Streamable HTTP at **`https://win.oneshotagent.com/mcp`**, authenticated with an
 **agent access token** and billed to the agent's credit balance:
 
@@ -178,7 +184,7 @@ instead of the wallet variables for a credits-only session on your own machine.
 |------|-------------|
 | `oneshot_web_search` | Search the web |
 | `oneshot_web_read` | Read any URL as markdown + screenshot |
-| `oneshot_browser` | Autonomous browser — navigate, click, extract |
+| `oneshot_browser` | Autonomous browser: navigate, click, extract |
 
 ### Commerce
 
@@ -198,12 +204,12 @@ instead of the wallet variables for a credits-only session on your own machine.
 
 | Tool | Description |
 |------|-------------|
-| `oneshot_compute` | Create an autonomous goal — objective + budget, the orchestrator plans and executes |
+| `oneshot_compute` | Create an autonomous goal (objective + budget); the orchestrator plans and executes |
 | `oneshot_compute_status` | Get a compute goal's status and budget |
 | `oneshot_compute_tasks` | List tasks planned/executed under a goal |
 | `oneshot_compute_cancel` | Cancel a goal and refund remaining budget |
 | `oneshot_compute_respond` | Respond to a human-in-the-loop task |
-| `oneshot_compute_pause` | Pause a recurring goal — plan and progress are kept |
+| `oneshot_compute_pause` | Pause a recurring goal; plan and progress are kept |
 | `oneshot_compute_resume` | Resume a paused recurring goal |
 | `oneshot_compute_fund` | Top up a recurring goal's USDC budget |
 
@@ -233,7 +239,7 @@ instead of the wallet variables for a credits-only session on your own machine.
 | `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.
+Paid tools are priced in USDC via the x402 protocol. Current rates are on the [Pricing](https://docs.oneshotagent.com/pricing) page.
 
 ## Tool Examples
 
@@ -328,7 +334,16 @@ Use oneshot_inbox_list:
 
 ## Funding Your Agent
 
-Send USDC to your agent's wallet address on Base. The server operates on Base Mainnet (chain 8453).
+Send USDC to your agent's wallet address on Base. The server runs on Base Mainnet (chain 8453).
+
+## LinkedIn connection recovery
+
+If the active account list is empty or an account is `deleted_upstream` or
+`revoked`, ask the human to use `oneshot_linkedin_connect` and authorize fresh
+grants. An existing account with `reconnect_required` must be reconnected through
+the owning application. Reconnect and revoke are deliberately not agent tools.
+Do not create a new connection automatically after authentication failures or
+timeouts.
 
 ## Links
 
@@ -338,12 +353,3 @@ Send USDC to your agent's wallet address on Base. The server operates on Base Ma
 - [Python SDK (LangChain)](https://pypi.org/project/langchain-oneshot/)
 - [Python SDK (Core)](https://pypi.org/project/oneshot-python/)
 - [GitHub](https://github.com/oneshot-agent/sdk)
-
-### LinkedIn connection recovery
-
-If the active account list is empty or an account is `deleted_upstream` or
-`revoked`, ask the human to use `oneshot_linkedin_connect` and authorize fresh
-grants. An existing account with `reconnect_required` needs reconnect through
-the owning application. Reconnect and revoke are intentionally not agent tools.
-Do not automatically create a new connection in response to authentication
-failures or timeouts.

package/dist/index.js

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

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: read("Sync LinkedIn messages", OPEN),
+    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_rocs: read("Show return on spend", OWN),
+    oneshot_rocs_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 { TOOL_ANNOTATIONS } from "./annotations.js";
 import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue } from "./analytics.js";
-// All available tools
-export const tools = [
+// 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

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.27.0",
+  "version": "0.29.0",
   "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.41.0",
+    "@oneshot-agent/sdk": "^0.43.0",
     "zod": "3.25.76"
   },
   "devDependencies": {