@oneshot-agent/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @oneshot-agent/mcp-server
+
+MCP (Model Context Protocol) server for [OneShot](https://oneshotagent.com) - enabling AI agents to execute commercial actions.
+
+## Installation
+
+```bash
+npm install -g @oneshot-agent/mcp-server
+```
+
+## Configuration
+
+### Environment Variables
+
+- `ONESHOT_WALLET_PRIVATE_KEY` (required): Your agent's private key for signing payments
+- `ONESHOT_TEST_MODE`: Set to "false" for production (default: "true" - uses testnet)
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "oneshot": {
+      "command": "npx",
+      "args": ["-y", "@oneshot-agent/mcp-server"],
+      "env": {
+        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+Add to your OpenClaw configuration:
+
+```yaml
+mcp_servers:
+  - name: oneshot
+    command: npx -y @oneshot-agent/mcp-server
+    env:
+      ONESHOT_WALLET_PRIVATE_KEY: "0xYourPrivateKey"
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "oneshot": {
+      "command": "npx",
+      "args": ["-y", "@oneshot-agent/mcp-server"],
+      "env": {
+        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `oneshot_email` | Send emails with attachments | ~$0.01 |
+| `oneshot_voice` | AI-powered phone calls | ~$0.25/min |
+| `oneshot_sms` | Send SMS messages | ~$0.035/segment |
+| `oneshot_research` | Deep web research | $0.50-$2.00 |
+| `oneshot_commerce_search` | Search products | Free |
+| `oneshot_commerce_buy` | Purchase products | Product price + fee |
+| `oneshot_enrich_profile` | Enrich person profiles | ~$0.10 |
+| `oneshot_find_email` | Find email addresses | ~$0.10 |
+| `oneshot_verify_email` | Verify email deliverability | ~$0.01 |
+| `oneshot_notifications` | List agent notifications | Free |
+| `oneshot_mark_notification_read` | Mark notification read | Free |
+
+## Tool Examples
+
+### Send an Email
+
+```
+Use the oneshot_email tool to send an email:
+- to: "user@example.com"
+- subject: "Hello from AI"
+- body: "<h1>Hello!</h1><p>This email was sent by an AI agent.</p>"
+```
+
+### Make a Phone Call
+
+```
+Use the oneshot_voice tool to make a call:
+- target_number: "+14155551234"
+- objective: "Call the restaurant and make a reservation for 2 people at 7pm tonight"
+- caller_persona: "A polite assistant calling on behalf of John"
+```
+
+### Send an SMS
+
+```
+Use the oneshot_sms tool:
+- to_number: "+14155551234"
+- message: "Your order has shipped! Track it at: https://example.com/track/123"
+```
+
+### Research a Topic
+
+```
+Use the oneshot_research tool:
+- topic: "What are the latest developments in quantum computing in 2024?"
+- depth: "deep"
+```
+
+### Find Someone's Email
+
+```
+Use the oneshot_find_email tool:
+- first_name: "John"
+- last_name: "Smith"
+- company_domain: "example.com"
+```
+
+## Funding Your Agent
+
+Fund your agent wallet at [oneshotagent.com](https://oneshotagent.com) with USDC on Base network.
+
+- **Test Mode** (default): Uses Base Sepolia testnet - get test USDC from faucets
+- **Production Mode**: Uses Base Mainnet - requires real USDC
+
+## Links
+
+- [Documentation](https://docs.oneshotagent.com)
+- [Pricing](https://docs.oneshotagent.com/pricing)
+- [SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)

package/bin/oneshot-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+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";
+const PRIVATE_KEY = process.env.ONESHOT_WALLET_PRIVATE_KEY;
+const TEST_MODE = process.env.ONESHOT_TEST_MODE !== "false"; // Default to test mode
+if (!PRIVATE_KEY) {
+    console.error("Error: ONESHOT_WALLET_PRIVATE_KEY environment variable is required");
+    process.exit(1);
+}
+// Initialize OneShot SDK
+const agent = new OneShot({
+    privateKey: PRIVATE_KEY,
+    testMode: TEST_MODE,
+});
+// Create MCP server
+const server = new Server({
+    name: "oneshot-mcp",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    return handleToolCall(agent, name, args || {});
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`OneShot MCP server running (testMode: ${TEST_MODE})`);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/dist/tools/commerce.d.ts

@@ -0,0 +1,6 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const commerceSearchTool: Tool;
+export declare const commerceBuyTool: Tool;
+export declare function handleCommerceSearch(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").CommerceSearchResult>;
+export declare function handleCommerceBuy(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").CommerceBuyResult>;

package/dist/tools/commerce.js

@@ -0,0 +1,82 @@
+export const commerceSearchTool = {
+    name: "oneshot_commerce_search",
+    description: "Search for products to purchase. Free to search, pay only when buying.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Product search query",
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of results (default: 10)",
+            },
+        },
+        required: ["query"],
+    },
+};
+export const commerceBuyTool = {
+    name: "oneshot_commerce_buy",
+    description: "Purchase a product. Requires product URL and shipping address. Price + service fee.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            product_url: {
+                type: "string",
+                description: "Product URL to purchase",
+            },
+            shipping_address: {
+                type: "object",
+                properties: {
+                    first_name: { type: "string" },
+                    last_name: { type: "string" },
+                    street: { type: "string" },
+                    street2: { type: "string" },
+                    city: { type: "string" },
+                    state: { type: "string" },
+                    zip_code: { type: "string" },
+                    country: { type: "string" },
+                    email: { type: "string" },
+                    phone: { type: "string" },
+                },
+                required: ["first_name", "last_name", "street", "city", "state", "zip_code", "phone"],
+            },
+            quantity: {
+                type: "number",
+                description: "Quantity to purchase (default: 1)",
+            },
+            variant_id: {
+                type: "string",
+                description: "Product variant ID (optional)",
+            },
+        },
+        required: ["product_url", "shipping_address"],
+    },
+};
+export async function handleCommerceSearch(agent, args) {
+    return agent.commerceSearch({
+        query: args.query,
+        limit: args.limit,
+    });
+}
+export async function handleCommerceBuy(agent, args) {
+    const shippingAddress = args.shipping_address;
+    return agent.commerceBuy({
+        product_url: args.product_url,
+        shipping_address: {
+            first_name: shippingAddress.first_name,
+            last_name: shippingAddress.last_name,
+            street: shippingAddress.street,
+            street2: shippingAddress.street2,
+            city: shippingAddress.city,
+            state: shippingAddress.state,
+            zip_code: shippingAddress.zip_code,
+            country: shippingAddress.country,
+            email: shippingAddress.email,
+            phone: shippingAddress.phone,
+        },
+        quantity: args.quantity,
+        variant_id: args.variant_id,
+    });
+}

package/dist/tools/email.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const emailTool: Tool;
+export declare function handleEmail(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").EmailResult>;

package/dist/tools/email.js

@@ -0,0 +1,48 @@
+export const emailTool = {
+    name: "oneshot_email",
+    description: "Send an email. Costs ~$0.01 per email. Supports HTML body and attachments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: {
+                type: "string",
+                description: "Recipient email address (or comma-separated list)",
+            },
+            subject: {
+                type: "string",
+                description: "Email subject line",
+            },
+            body: {
+                type: "string",
+                description: "Email body (plain text or HTML)",
+            },
+            from_domain: {
+                type: "string",
+                description: "Custom sender domain (optional, defaults to oneshotagent.com)",
+            },
+            attachments: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        filename: { type: "string" },
+                        content: { type: "string", description: "Base64 encoded content" },
+                        url: { type: "string", description: "URL to fetch attachment from" },
+                        content_type: { type: "string" },
+                    },
+                },
+                description: "File attachments (optional)",
+            },
+        },
+        required: ["to", "subject", "body"],
+    },
+};
+export async function handleEmail(agent, args) {
+    return agent.email({
+        to: args.to,
+        subject: args.subject,
+        body: args.body,
+        from_domain: args.from_domain,
+        attachments: args.attachments,
+    });
+}

package/dist/tools/enrichment.d.ts

@@ -0,0 +1,8 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const enrichProfileTool: Tool;
+export declare const findEmailTool: Tool;
+export declare const verifyEmailTool: Tool;
+export declare function handleEnrichProfile(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").EnrichProfileResult>;
+export declare function handleFindEmail(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").FindEmailResult>;
+export declare function handleVerifyEmail(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").VerifyEmailResult>;

package/dist/tools/enrichment.js

@@ -0,0 +1,86 @@
+export const enrichProfileTool = {
+    name: "oneshot_enrich_profile",
+    description: "Enrich a person's profile from LinkedIn URL, email, or name. Returns job title, company, social links, etc. Costs ~$0.10.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            linkedin_url: {
+                type: "string",
+                description: "LinkedIn profile URL",
+            },
+            email: {
+                type: "string",
+                description: "Email address to enrich",
+            },
+            name: {
+                type: "string",
+                description: "Person's full name",
+            },
+            company_domain: {
+                type: "string",
+                description: "Company domain for additional context",
+            },
+        },
+    },
+};
+export const findEmailTool = {
+    name: "oneshot_find_email",
+    description: "Find email address for a person at a company. Costs ~$0.10.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            full_name: {
+                type: "string",
+                description: "Person's full name",
+            },
+            first_name: {
+                type: "string",
+                description: "Person's first name (use with last_name)",
+            },
+            last_name: {
+                type: "string",
+                description: "Person's last name (use with first_name)",
+            },
+            company_domain: {
+                type: "string",
+                description: "Company domain (e.g., example.com)",
+            },
+        },
+        required: ["company_domain"],
+    },
+};
+export const verifyEmailTool = {
+    name: "oneshot_verify_email",
+    description: "Verify if an email address is valid and deliverable. Costs ~$0.01.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            email: {
+                type: "string",
+                description: "Email address to verify",
+            },
+        },
+        required: ["email"],
+    },
+};
+export async function handleEnrichProfile(agent, args) {
+    return agent.enrichProfile({
+        linkedin_url: args.linkedin_url,
+        email: args.email,
+        name: args.name,
+        company_domain: args.company_domain,
+    });
+}
+export async function handleFindEmail(agent, args) {
+    return agent.findEmail({
+        full_name: args.full_name,
+        first_name: args.first_name,
+        last_name: args.last_name,
+        company_domain: args.company_domain,
+    });
+}
+export async function handleVerifyEmail(agent, args) {
+    return agent.verifyEmail({
+        email: args.email,
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,16 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const tools: Tool[];
+export declare function handleToolCall(agent: OneShot, toolName: string, args: Record<string, unknown>): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/index.js

@@ -0,0 +1,57 @@
+import { emailTool, handleEmail } from "./email.js";
+import { voiceTool, handleVoice } from "./voice.js";
+import { smsTool, handleSms } from "./sms.js";
+import { researchTool, handleResearch } from "./research.js";
+import { commerceSearchTool, commerceBuyTool, handleCommerceSearch, handleCommerceBuy } from "./commerce.js";
+import { enrichProfileTool, findEmailTool, verifyEmailTool, handleEnrichProfile, handleFindEmail, handleVerifyEmail } from "./enrichment.js";
+import { notificationsTool, markReadTool, handleNotifications, handleMarkRead } from "./notifications.js";
+// All available tools
+export const tools = [
+    emailTool,
+    voiceTool,
+    smsTool,
+    researchTool,
+    commerceSearchTool,
+    commerceBuyTool,
+    enrichProfileTool,
+    findEmailTool,
+    verifyEmailTool,
+    notificationsTool,
+    markReadTool,
+];
+// Tool handlers map
+const handlers = {
+    "oneshot_email": handleEmail,
+    "oneshot_voice": handleVoice,
+    "oneshot_sms": handleSms,
+    "oneshot_research": handleResearch,
+    "oneshot_commerce_search": handleCommerceSearch,
+    "oneshot_commerce_buy": handleCommerceBuy,
+    "oneshot_enrich_profile": handleEnrichProfile,
+    "oneshot_find_email": handleFindEmail,
+    "oneshot_verify_email": handleVerifyEmail,
+    "oneshot_notifications": handleNotifications,
+    "oneshot_mark_notification_read": handleMarkRead,
+};
+export async function handleToolCall(agent, toolName, args) {
+    const handler = handlers[toolName];
+    if (!handler) {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await handler(agent, args);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+}

package/dist/tools/notifications.d.ts

@@ -0,0 +1,8 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const notificationsTool: Tool;
+export declare const markReadTool: Tool;
+export declare function handleNotifications(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").NotificationsResult>;
+export declare function handleMarkRead(agent: OneShot, args: Record<string, unknown>): Promise<{
+    success: boolean;
+}>;

package/dist/tools/notifications.js

@@ -0,0 +1,41 @@
+export const notificationsTool = {
+    name: "oneshot_notifications",
+    description: "List notifications for the agent. Free. Shows job completions, failures, and lifecycle warnings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            unread: {
+                type: "boolean",
+                description: "Only return unread notifications (default: false)",
+            },
+            limit: {
+                type: "number",
+                description: "Maximum notifications to return (default: 50, max: 100)",
+            },
+        },
+    },
+};
+export const markReadTool = {
+    name: "oneshot_mark_notification_read",
+    description: "Mark a notification as read. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            notificationId: {
+                type: "string",
+                description: "Notification UUID to mark as read",
+            },
+        },
+        required: ["notificationId"],
+    },
+};
+export async function handleNotifications(agent, args) {
+    return agent.notifications({
+        unread: args.unread,
+        limit: args.limit,
+    });
+}
+export async function handleMarkRead(agent, args) {
+    await agent.markNotificationRead(args.notificationId);
+    return { success: true };
+}

package/dist/tools/research.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const researchTool: Tool;
+export declare function handleResearch(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ResearchResult>;

package/dist/tools/research.js

@@ -0,0 +1,36 @@
+export const researchTool = {
+    name: "oneshot_research",
+    description: "Perform deep web research on a topic. Returns comprehensive report with sources. Costs $0.50-$2.00 depending on depth.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                description: "Research topic or question",
+            },
+            depth: {
+                type: "string",
+                enum: ["quick", "deep"],
+                description: "Research depth (default: deep). Quick: ~30s, Deep: ~2-5min",
+            },
+            max_sources: {
+                type: "number",
+                description: "Maximum number of sources to include (optional)",
+            },
+            output_format: {
+                type: "string",
+                enum: ["report_markdown", "structured_json"],
+                description: "Output format (default: report_markdown)",
+            },
+        },
+        required: ["topic"],
+    },
+};
+export async function handleResearch(agent, args) {
+    return agent.research({
+        topic: args.topic,
+        depth: args.depth,
+        max_sources: args.max_sources,
+        output_format: args.output_format,
+    });
+}

package/dist/tools/sms.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const smsTool: Tool;
+export declare function handleSms(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").SmsSendResult>;

package/dist/tools/sms.js

@@ -0,0 +1,24 @@
+export const smsTool = {
+    name: "oneshot_sms",
+    description: "Send an SMS message. Costs ~$0.035 per segment (160 chars).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to_number: {
+                type: "string",
+                description: "Phone number (E.164 format, e.g., +14155551234)",
+            },
+            message: {
+                type: "string",
+                description: "SMS message content (max 1600 chars, 160 chars per segment)",
+            },
+        },
+        required: ["to_number", "message"],
+    },
+};
+export async function handleSms(agent, args) {
+    return agent.sms({
+        to_number: args.to_number,
+        message: args.message,
+    });
+}

package/dist/tools/voice.d.ts

@@ -0,0 +1,4 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { OneShot } from "@oneshot-agent/sdk";
+export declare const voiceTool: Tool;
+export declare function handleVoice(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").VoiceCallResult>;

package/dist/tools/voice.js

@@ -0,0 +1,39 @@
+export const voiceTool = {
+    name: "oneshot_voice",
+    description: "Make an AI-powered phone call. Costs ~$0.25/minute. The AI will follow the provided objective.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            target_number: {
+                type: "string",
+                description: "Phone number to call (E.164 format, e.g., +14155551234)",
+            },
+            objective: {
+                type: "string",
+                description: "What the AI should accomplish on the call (min 10 characters)",
+            },
+            context: {
+                type: "string",
+                description: "Additional context about the call (optional)",
+            },
+            caller_persona: {
+                type: "string",
+                description: "Persona for the AI caller (optional)",
+            },
+            max_duration_minutes: {
+                type: "number",
+                description: "Maximum call duration in minutes (1-30, optional)",
+            },
+        },
+        required: ["target_number", "objective"],
+    },
+};
+export async function handleVoice(agent, args) {
+    return agent.voice({
+        target_number: args.target_number,
+        objective: args.objective,
+        context: args.context,
+        caller_persona: args.caller_persona,
+        max_duration_minutes: args.max_duration_minutes,
+    });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@oneshot-agent/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for OneShot - commercial actions for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "oneshot-mcp": "./bin/oneshot-mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "oneshot", "ai-agent", "claude", "tools"],
+  "author": "OneShot",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@oneshot-agent/sdk": "^0.5.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["dist", "bin", "README.md"]
+}