@oneshot-agent/mcp-server 0.32.0 → 0.33.0

package/README.md

@@ -102,7 +102,7 @@ Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return p
 ## 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
+server and must not hold a wallet key. For them, OneShot hosts the same 78 tools over
 Streamable HTTP at **`https://win.oneshotagent.com/mcp`**, authenticated with an
 **agent access token** and billed to the agent's credit balance:
 
@@ -125,6 +125,18 @@ instead of the wallet variables for a credits-only session on your own machine.
 
 ## Available Tools
 
+### Soul Hunt
+
+| Tool | Description |
+|------|-------------|
+| `oneshot_hunt_list` | List active or collected Soul Hunts. Free. |
+| `oneshot_hunt_status` | Detailed status, rounds and timeline for a specific hunt. Free. |
+| `oneshot_hunt_predict` | Submit a prediction for a hunt. Debits a stake from your balance. Paid, and requires a wallet session — Soul Hunt enforces a wallet-signed write proof that an access-token/OAuth session cannot produce. |
+| `oneshot_hunt_collection` | View the souls you have captured. Free. |
+| `oneshot_hunt_leaderboard` | Public predictor leaderboard. Free. |
+
+Soul Hunt is a separate service (`api.soulhunt.ai`) from the main OneShot API; the wallet session's `X-Agent-ID`/`x-agent-proof` carry over, but the OneShot bearer token never does.
+
 ### Communication
 
 | Tool | Description |

package/dist/index.js

@@ -50,7 +50,7 @@ async function main() {
     const agent = await initAgent();
     const server = new Server({
         name: "oneshot-mcp",
-        version: "0.32.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.33.0", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/analytics.js

@@ -25,7 +25,7 @@ export const receiptsListTool = {
         type: "object",
         properties: {
             period: { type: "number", description: "Lookback window in days" },
-            category: { type: "string", description: "Filter by tool category" },
+            category: { type: "string", enum: ["data", "verification", "communication", "commerce", "infrastructure", "agent_to_agent"], description: "Filter by receipt category" },
             limit: { type: "number", description: "Max receipts to return (1-100, default 50)" },
             offset: { type: "number", description: "Pagination offset" },
             since: { type: "string", description: "Lower bound on created_at (ISO 8601). Page back to older receipts." },
@@ -72,6 +72,10 @@ export async function handleRocs(agent, args) {
     return agent.rocs({ period: args.period });
 }
 export async function handleReceiptsList(agent, args) {
+    // Pass `category` through as received — an unrecognized value must still
+    // reach the API and get its 400 invalid_category response (#1078), not be
+    // silently dropped here into an unfiltered list. The cast only satisfies
+    // the SDK's compile-time enum narrowing; the API validates at runtime.
     return agent.receiptsList({
         period: args.period,
         category: args.category,

package/dist/tools/annotations.js

@@ -6,6 +6,11 @@ const OPEN = true;
 const OWN = false;
 const DESTRUCTIVE = true;
 export const TOOL_ANNOTATIONS = {
+    oneshot_hunt_list: read("List Soul Hunts", OPEN),
+    oneshot_hunt_status: read("Get Soul Hunt Status", OPEN),
+    oneshot_hunt_predict: write("Predict Soul Hunt", OPEN),
+    oneshot_hunt_collection: read("List Collected Souls", OWN),
+    oneshot_hunt_leaderboard: read("Soul Hunt Leaderboard", OPEN),
     oneshot_email: write("Send email", OPEN),
     oneshot_voice: write("Place a phone call", OPEN),
     oneshot_sms: write("Send a text message", OPEN),

package/dist/tools/hunt.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { OneShot } from "@oneshot-agent/sdk";
+export declare const huntListTool: Tool;
+export declare const huntStatusTool: Tool;
+export declare const huntPredictTool: Tool;
+export declare const huntCollectionTool: Tool;
+export declare const huntLeaderboardTool: Tool;
+export declare function handleHuntList(agent: OneShot, args: Record<string, unknown>): Promise<any>;
+export declare function handleHuntStatus(agent: OneShot, args: Record<string, unknown>): Promise<any>;
+export declare function handleHuntPredict(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").HuntQuote>;
+export declare function handleHuntCollection(agent: OneShot, args: Record<string, unknown>): Promise<any[]>;
+export declare function handleHuntLeaderboard(agent: OneShot, args: Record<string, unknown>): Promise<any>;

package/dist/tools/hunt.js

@@ -0,0 +1,76 @@
+export const huntListTool = {
+    name: "oneshot_hunt_list",
+    description: "List active or collected Soul Hunts. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string", description: "Hunt status ('active', 'captured', 'expired', etc.)", default: "active" },
+            limit: { type: "number", default: 20 },
+            offset: { type: "number", default: 0 },
+        },
+    },
+};
+export const huntStatusTool = {
+    name: "oneshot_hunt_status",
+    description: "Get detailed status, rounds, and timeline for a specific Soul Hunt. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            hunt_id: { type: "string", description: "Hunt ID or Soul Slug" },
+        },
+        required: ["hunt_id"],
+    },
+};
+export const huntPredictTool = {
+    name: "oneshot_hunt_predict",
+    description: "Submit a prediction for a Soul Hunt. Debits a stake (USDC) from your balance based on the round tier. Paid.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            hunt_id: { type: "string", description: "Hunt ID or Soul Slug" },
+            predicted_tool: { type: "string", description: "The exact tool the soul will use next (e.g., 'research', 'email_send')" },
+            predicted_action: { type: "string", description: "What the soul will do with the tool (max 500 chars)" },
+            predicted_motivation: { type: "string", description: "Why the soul will do this, based on its objective (max 500 chars)" },
+        },
+        required: ["hunt_id", "predicted_tool", "predicted_action", "predicted_motivation"],
+    },
+};
+export const huntCollectionTool = {
+    name: "oneshot_hunt_collection",
+    description: "View the souls you have successfully captured. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+export const huntLeaderboardTool = {
+    name: "oneshot_hunt_leaderboard",
+    description: "Get the public predictor leaderboard. Free.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            period: { type: "string", description: "Time period ('all', 'month', 'week')", default: "all" },
+            sort: { type: "string", description: "Sort column ('captures', 'score', 'earned')", default: "captures" },
+            limit: { type: "number", default: 25 },
+            offset: { type: "number", default: 0 },
+        },
+    },
+};
+// MCP clients may send explicit nulls for optional fields; map null to
+// undefined so the SDK's defaults apply instead of serializing "null".
+const opt = (v) => (v === null ? undefined : v);
+export async function handleHuntList(agent, args) {
+    return agent.hunts.list(opt(args.status), opt(args.limit), opt(args.offset));
+}
+export async function handleHuntStatus(agent, args) {
+    return agent.hunts.status(args.hunt_id);
+}
+export async function handleHuntPredict(agent, args) {
+    return agent.hunts.predict(args.hunt_id, args.predicted_tool, args.predicted_action, args.predicted_motivation);
+}
+export async function handleHuntCollection(agent, args) {
+    return agent.hunts.collection();
+}
+export async function handleHuntLeaderboard(agent, args) {
+    return agent.hunts.leaderboard(opt(args.period), opt(args.sort), opt(args.limit), opt(args.offset));
+}

package/dist/tools/index.js

@@ -22,6 +22,7 @@ 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 { huntListTool, huntStatusTool, huntPredictTool, huntCollectionTool, huntLeaderboardTool, handleHuntList, handleHuntStatus, handleHuntPredict, handleHuntCollection, handleHuntLeaderboard } from "./hunt.js";
 import { TOOL_ANNOTATIONS } from "./annotations.js";
 import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue } from "./analytics.js";
 const toolDefinitions = [
@@ -83,6 +84,11 @@ const toolDefinitions = [
     listDomainsTool,
     pauseDomainTool,
     resumeDomainTool,
+    huntListTool,
+    huntStatusTool,
+    huntPredictTool,
+    huntCollectionTool,
+    huntLeaderboardTool,
     spendBreakdownTool,
     rocsTool,
     rocsByGoalTool,
@@ -166,6 +172,11 @@ const handlers = {
     "oneshot_list_domains": handleListDomains,
     "oneshot_pause_domain": handlePauseDomain,
     "oneshot_resume_domain": handleResumeDomain,
+    "oneshot_hunt_list": handleHuntList,
+    "oneshot_hunt_status": handleHuntStatus,
+    "oneshot_hunt_predict": handleHuntPredict,
+    "oneshot_hunt_collection": handleHuntCollection,
+    "oneshot_hunt_leaderboard": handleHuntLeaderboard,
     "oneshot_spend_breakdown": handleSpendBreakdown,
     "oneshot_return_on_spend": handleRocs,
     "oneshot_return_on_spend_by_goal": handleRocsByGoal,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oneshot-agent/mcp-server",
-  "version": "0.32.0",
-  "description": "MCP server for OneShot - 73 tools for AI agents",
+  "version": "0.33.0",
+  "description": "MCP server for OneShot - 78 tools for AI agents",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
   "dependencies": {
     "@coinbase/cdp-sdk": "1.45.0",
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@oneshot-agent/sdk": "^0.46.0",
+    "@oneshot-agent/sdk": "^0.47.0",
     "zod": "3.25.76"
   },
   "devDependencies": {