@finchagentic/mcp 4.2.0 → 4.4.1

package/README.md

@@ -29,13 +29,13 @@ Always pin the version. Never use `@latest`.
 
 ```bash
 # One-command installer (detects common MCP clients)
-npx -y -p @finchagentic/mcp@4.2.0 finch install
+npx -y -p @finchagentic/mcp@4.4.1 finch install
 ```
 
 ### Claude Code
 
 ```bash
-claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
+claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.4.1 finch-mcp
 ```
 
 ### Cursor / Windsurf / Claude Desktop
@@ -45,7 +45,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
   "mcpServers": {
     "finch": {
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
     }
   }
 }
@@ -59,7 +59,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
     "finch": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "finch-mcp"]
+      "args": ["-y", "-p", "@finchagentic/mcp@4.4.1", "finch-mcp"]
     }
   }
 }
@@ -79,7 +79,7 @@ claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
 
 </details>
 
-No LLM API key is required to start — 108 of 113 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
+No LLM API key is required to start — 111 of 116 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
 
 ## Quick start
 
@@ -99,15 +99,19 @@ save this thesis to vault
 
 ## What you get
 
-**113 tools** across four pillars:
+**116 tools** across four pillars:
 
 | Pillar | What it does |
 |--------|----------------|
 | **Memory** | Full-text searchable memory + versioned vault + chronicle |
-| **Agents** | Spawn, recall, update named agents |
-| **Workflows** | Automations, monitors, packets, deep research |
+| **Agents** | Spawn, recall, update named agents — `agent_recall` also pulls related memory/vault context matching the agent's goal, not just its own logged updates |
+| **Workflows** | Automations, monitors, packets, deep research (auto-saves reports + auto-links related past research) |
 | **Execution** | Base DeFi, Robinhood Chain, market data, web, GitHub |
 
+Coding and research sessions persist the same way: `deep_research` auto-saves its report to vault and links it to related past reports; `code_session_save` does the same for coding/debugging sessions (`vault_save type=code`, versioned per project, auto-linked). Both exist so the next session — yours or another agent's — starts with real context instead of cold.
+
+`vault_save` and `agent_spawn` also take an optional `workspaceProject` - the same named Projects a user organizes their Agents/vault content into on the webapp's Agents page. Pass a name and it's matched case-insensitively or created automatically (`list_projects` to browse what exists first). Hosted vault only - local-vault mode has no project concept.
+
 Default palette is `core` (lighter context). Full set:
 
 ```json
@@ -119,7 +123,7 @@ Default palette is `core` (lighter context). Full set:
 Finch is the runtime. **Your LLM is the brain. Your data stays yours.**
 
 ```bash
-npx -y -p @finchagentic/mcp@4.2.0 finch setup
+npx -y -p @finchagentic/mcp@4.4.1 finch setup
 # enable local vault (and optional local memory)
 ```
 
@@ -146,12 +150,12 @@ Scheduled/cloud features still need an account. Core memory, vault, and public-d
 | `GITHUB_TOKEN` | For `github_search_code` |
 | `ALCHEMY_API_KEY` | Faster Base RPC (optional) |
 
-**Cost model:** almost everything is free to run — the other 108 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
+**Cost model:** almost everything is free to run — the other 110 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
 
 Guided setup:
 
 ```bash
-npx -y -p @finchagentic/mcp@4.2.0 finch setup
+npx -y -p @finchagentic/mcp@4.4.1 finch setup
 ```
 
 ## Security
@@ -160,7 +164,7 @@ npx -y -p @finchagentic/mcp@4.2.0 finch setup
 |:-:|----------|------|
 | 1 | Prompt injection | External content is data only — never instructions |
 | 2 | Mainnet confirm | Estimate → preview → confirm → execute |
-| 3 | Pinned install | Always `@finchagentic/mcp@4.2.0`, never `@latest` |
+| 3 | Pinned install | Always `@finchagentic/mcp@4.4.1`, never `@latest` |
 | 4 | Credential vault | Never paste secrets into prompts or third-party tools |
 | 5 | Data disclosure | Know what leaves the machine (LLM, Firecrawl, GitHub, chain RPCs) |
 | 6 | Server monitors | Scheduled jobs need explicit confirmation |

package/dist/annotations.js

@@ -26,7 +26,7 @@ const WRITE_IDEMPOTENT = new Set([
 const WRITE = new Set([
     "agent_spawn",
     "chronicle_add",
-    "create_automation",
+    "code_session_save",
     "memory_add",
     "memory_extract",
     "memory_consolidate",
@@ -65,6 +65,13 @@ const DESTRUCTIVE = new Set([
     "rh_mcp_swap",
     "rh_dca_create", // arms recurring real buys
     "rh_bracket_create", // arms real TP/SL sells
+    // a swap/send automation arms unattended, REPEATING real fund movement
+    // (the backend's 1-minute cron evaluator fires it) - same risk class as
+    // rh_dca_create/rh_bracket_create above, not a plain additive write. An
+    // alert-only automation doesn't move funds, but the tool can't tell which
+    // kind it's about to create until AFTER the backend parses rawInput, so
+    // it's classified by its worst case, same reasoning as rh_orders_tick.
+    "create_automation",
     "rh_orders_tick", // preview by default, but can execute:true and move funds
     // executors that run other (possibly fund-moving) tools
     "run_automation",
@@ -73,6 +80,7 @@ const DESTRUCTIVE = new Set([
     // for a fixed period; unstake moves it (plus rewards) back
     "stake_finch",
     "unstake_finch",
+    "claim_vested_rewards", // treasury -> custodial wallet USDG transfer
 ]);
 function annotationsFor(name) {
     if (DESTRUCTIVE.has(name)) {

package/dist/index.js

@@ -66,14 +66,17 @@ const C = {
     reset: "\x1b[0m",
     bold: "\x1b[1m",
 };
+// Was still spelling out the pre-rebrand "NOELCLAW" wordmark in ASCII art -
+// leftover from before the Finch rebrand, never caught because nothing
+// visually diffs a banner string.
 const BANNER = `
 ${C.cyan}
-  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗
-  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║
-  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║
-  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║
-  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
-  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
+  ███████╗██╗███╗   ██╗ ██████╗██╗  ██╗
+  ██╔════╝██║████╗  ██║██╔════╝██║  ██║
+  █████╗  ██║██╔██╗ ██║██║     ███████║
+  ██╔══╝  ██║██║╚██╗██║██║     ██╔══██║
+  ██║     ██║██║ ╚████║╚██████╗██║  ██║
+  ╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝
 ${C.reset}`;
 function line(label, value, color = C.cyan) {
     const pad = " ".repeat(Math.max(0, 12 - label.length));
@@ -114,9 +117,9 @@ async function main() {
         { label: "Base MCP", match: n => n.startsWith("base_mcp_") },
         { label: "RH MCP", match: n => n.startsWith("rh_") },
         { label: "Automation", match: n => /^(create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation)$/.test(n) },
-        { label: "Vault", match: n => n.startsWith("vault_") },
+        { label: "Vault", match: n => n.startsWith("vault_") || n === "code_session_save" || n === "list_projects" },
         { label: "Wallet", match: n => /^(get_wallet_address|get_wallet_balance|wallet_sign_message)$/.test(n) },
-        { label: "Staking", match: n => /^(stake_finch|unstake_finch|stake_finch_status|stake_auto_restake)$/.test(n) },
+        { label: "Staking", match: n => /^(stake_finch|unstake_finch|stake_finch_status|stake_auto_restake|claim_vested_rewards)$/.test(n) },
         { label: "MiroShark", match: n => n.startsWith("miroshark_") },
         { label: "Scanner", match: n => /^(scan_market|score_token|check_token)$/.test(n) },
         { label: "Agents", match: n => n.startsWith("agent_") },

package/dist/project.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalVaultActive = isLocalVaultActive;
+exports.resolveProjectId = resolveProjectId;
+const convex_js_1 = require("./convex.js");
+const local_vault_js_1 = require("./local-vault.js");
+// MCP has no persistent "active project" UI state the way the webapp Sidebar
+// switcher does - a caller (vault_save, agent_spawn) names the project it
+// wants by string on each call instead. Resolution + auto-create both happen
+// server-side (POST /projects/resolve, see convex/http.ts +
+// convex/projects.ts's resolveOrCreateProjectForUser) so the match/dedup
+// logic exists in exactly one place, shared with the webapp's own project
+// picker.
+//
+// Local-vault mode (vaultBackend: "local") has no project concept at all -
+// it's a flat, unauthenticated file store on the user's own machine with no
+// server to resolve a name against. Callers should check
+// isLocalVaultActive() first and skip resolution entirely rather than call
+// this and get a confusing network-style failure.
+function isLocalVaultActive() {
+    return !!(0, local_vault_js_1.getLocalVaultConfig)();
+}
+async function resolveProjectId(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return await (0, convex_js_1.callConvex)("/projects/resolve", "POST", { name: trimmed }, "vault_save");
+    }
+    catch {
+        // Resolution is best-effort - a save should never fail just because the
+        // project lookup did. Falls back to unassigned, same as the webapp's
+        // agent_spawn membership check when a stale/bad id doesn't match.
+        return null;
+    }
+}

package/dist/server.js

@@ -115,7 +115,7 @@ exports.ALL_TOOLS = [
     // SWARM_TOOLS removed v3.19 - multi-agent research is now built into
     // deep_research (depth=standard|deep). Handler fully removed v3.21.
     // FRAMEWORK_TOOLS removed - list_playbooks/run_playbook/get_finch_ledger backend routes never existed, see tools/ import comment above.
-    ...vault_js_1.VAULT_TOOLS, // 15 - save, read, list, search, history, diff, export, pin, unpublish, tag, delete, link, related, store_credential, get_credential
+    ...vault_js_1.VAULT_TOOLS, // 17 - save, code_session_save, read, list, search, history, diff, export, pin, unpublish, tag, delete, link, related, store_credential, get_credential, list_projects
     ...wallet_js_1.WALLET_TOOLS, // 3 - get_wallet_address, get_wallet_balance, wallet_sign_message
     ...miroshark_js_1.MIROSHARK_TOOLS, // 3 - simulate, status, stop
     ...agents_js_1.AGENT_TOOLS, // 4 - agent_spawn, agent_recall, agent_update, agent_ledger (vault-backed, all working). list_agents/hire_agent and the autonomous-schedule tools (agent_identity/agent_schedule/agent_unschedule/agent_pause/agent_resume/agent_runs) removed - their backend routes were never implemented, see tools/agents.ts
@@ -139,14 +139,22 @@ exports.ALL_TOOLS = [
     ...github_js_1.GITHUB_TOOLS, // 8 - list_repos, list_prs, get_pr, list_issues, get_issue, get_file, get_commits, search_code
     ...chronicle_js_1.CHRONICLE_TOOLS, // 4 - chronicle_add, chronicle_list, chronicle_search, chronicle_stats
     ...packets_js_1.PACKET_TOOLS, // 4 - packet_create, packet_run, packet_list, packet_share
-    ...stake_js_1.STAKE_TOOLS, // 4 - stake_finch_status, stake_finch, unstake_finch, stake_auto_restake (custodial wallet; requires `finch login`)
-    // total: 113 tools as measured by ALL_TOOLS.length - do not hand-maintain a
+    ...stake_js_1.STAKE_TOOLS, // 5 - stake_finch_status, stake_finch, unstake_finch, claim_vested_rewards, stake_auto_restake (custodial wallet; requires `finch login`)
+    // total: 116 tools as measured by ALL_TOOLS.length - do not hand-maintain a
     // count in this comment (drifted stale multiple times already: before
     // staking was added, after the P1 audit removed 9 dead framework/agent-
     // schedule tools, after memory_publish was removed for promising a
-    // marketplace that doesn't exist, and after stake_auto_restake was added;
-    // ALL_TOOLS.length is the only number that can't lie). Per-category counts
-    // above are best-effort documentation, not load-bearing anywhere.
+    // marketplace that doesn't exist, after stake_auto_restake was added,
+    // after claim_vested_rewards was added to close the gap where the
+    // stake-lifecycle notification told users to "run claimVestedRewards" but
+    // no MCP tool by that name existed, after code_session_save was added so
+    // coding sessions persist the same way deep_research already auto-saves
+    // research, and after list_projects was added alongside `workspaceProject`
+    // support on vault_save/agent_spawn - MCP tools can now file into the same
+    // Projects the webapp Agents page organizes by, resolved/auto-created
+    // server-side via POST /projects/resolve; ALL_TOOLS.length is the only
+    // number that can't lie). Per-category counts above are best-effort
+    // documentation, not load-bearing anywhere.
 ];
 exports.HANDLER_MAP = new Map([
     ...market_js_1.MARKET_TOOLS.map(t => [t.name, market_js_1.handleMarketTool]),

package/dist/tool-filter.js

@@ -27,11 +27,11 @@ exports.filterTools = filterTools;
 // through that same preset). New tools MUST match a preset or the test fails
 // the build, instead of quietly vanishing like these did.
 const PRESETS = {
-    core: /^(memory_|vault_|agent_|ask_finch|finch_status|finch_diagnostics|finch_shell_chat|get_wallet_address|get_wallet_balance|wallet_sign_message|chronicle_|packet_)/,
-    defi: /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history|get_base_token_data|stock_fundamentals|stock_insider|stock_events|market_thesis|trade_plan|base_mcp_|rh_|base_|get_defi_yields|score_token|check_token|scan_market|get_wallet_balance|wallet_sign_message|create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation|miroshark_|stake_|unstake_finch)/,
-    research: /^(memory_|vault_|deep_research|research_compare|research_chain|web_search|web_scrape|schedule_research|list_monitors|cancel_monitor|ask_finch|stock_fundamentals|stock_insider|stock_events)/,
-    memory: /^(memory_|vault_|agent_|chronicle_)/,
-    coder: /^(audit_contract|github_)/,
+    core: /^(memory_|vault_|code_session_save|list_projects|agent_|ask_finch|finch_status|finch_diagnostics|finch_shell_chat|get_wallet_address|get_wallet_balance|wallet_sign_message|chronicle_|packet_)/,
+    defi: /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history|get_base_token_data|stock_fundamentals|stock_insider|stock_events|market_thesis|trade_plan|base_mcp_|rh_|base_|get_defi_yields|score_token|check_token|scan_market|get_wallet_balance|wallet_sign_message|create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation|miroshark_|stake_|unstake_finch|claim_vested_rewards)/,
+    research: /^(memory_|vault_|code_session_save|list_projects|deep_research|research_compare|research_chain|web_search|web_scrape|schedule_research|list_monitors|cancel_monitor|ask_finch|stock_fundamentals|stock_insider|stock_events)/,
+    memory: /^(memory_|vault_|code_session_save|list_projects|agent_|chronicle_)/,
+    coder: /^(audit_contract|github_|code_session_save)/,
 };
 function filterTools(allTools) {
     // Default is "core" - keeps LLM context cost low while everything

package/dist/tools/agents.js

@@ -7,6 +7,8 @@ const zod_1 = require("zod");
 const convex_js_1 = require("../convex.js");
 const llm_js_1 = require("../llm.js");
 const local_vault_js_1 = require("../local-vault.js");
+const memory_js_1 = require("./memory.js");
+const project_js_1 = require("../project.js");
 // ─── Agent Learning Memory (v3.25) ──────────────────────────────────────────
 // After every agent_update, an LLM reviews the new progress in context of the
 // agent's goal + prior learnings to extract a single repeatable insight. The
@@ -133,6 +135,12 @@ exports.AGENT_TOOLS = [
                 name: { type: "string", description: "Unique agent name (e.g. 'market-researcher', 'onboarding-helper')" },
                 goal: { type: "string", description: "What this agent is trying to accomplish" },
                 context: { type: "string", description: "Optional starting context, data, or notes for the agent" },
+                workspaceProject: {
+                    type: "string",
+                    description: "Optional: file this agent into a named Finch workspace project (visible on the Agents page's " +
+                        "project switcher). Matched case-insensitively by name; created automatically if it doesn't exist " +
+                        "yet. Hosted vault only (no effect in local-vault mode).",
+                },
             },
             required: ["name", "goal"],
         },
@@ -140,6 +148,8 @@ exports.AGENT_TOOLS = [
     {
         name: "agent_recall",
         description: "Recall a persistent agent by name - loads its goal, current progress, findings, full history, and accumulated learnings (patterns the agent extracted from past runs). " +
+            "Also pulls related context from memory/vault (code_session_save entries, deep_research reports, notes) matching the agent's goal, " +
+            "so recall reflects everything relevant to the goal - not just what agent_update explicitly logged. " +
             "Use this to resume a long-running task, check what an agent last did, or hand context to a fresh LLM session. " +
             "Learnings compound over time - the more an agent runs, the smarter recall becomes.",
         inputSchema: {
@@ -192,6 +202,7 @@ const SpawnAgentSchema = zod_1.z.object({
     name: zod_1.z.string().min(1).max(60).regex(/^[a-z0-9-]+$/, "name must be lowercase alphanumeric with hyphens"),
     goal: zod_1.z.string().min(1),
     context: zod_1.z.string().optional(),
+    workspaceProject: zod_1.z.string().optional(),
 });
 const RecallAgentSchema = zod_1.z.object({ name: zod_1.z.string().min(1) });
 const UpdateAgentSchema = zod_1.z.object({
@@ -217,8 +228,8 @@ async function handleAgentTool(name, args) {
     if (name === "agent_spawn") {
         const parsed = SpawnAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
-        const { name: agentName, goal, context } = parsed.data;
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+        const { name: agentName, goal, context, workspaceProject } = parsed.data;
         const content = JSON.stringify({
             goal,
             status: "active",
@@ -237,19 +248,30 @@ async function handleAgentTool(name, args) {
             commitMsg: "spawned",
         };
         const localVault = (0, local_vault_js_1.getLocalVaultConfig)();
+        // Resolve the project name -> id server-side (auto-creates on first use).
+        // No-op in local-vault mode - there is no project concept there.
+        let resolvedProjectName = null;
+        if (workspaceProject && !localVault) {
+            const resolved = await (0, project_js_1.resolveProjectId)(workspaceProject);
+            if (resolved) {
+                savePayload.projectId = resolved.projectId;
+                resolvedProjectName = resolved.name;
+            }
+        }
         const data = localVault
             ? (0, local_vault_js_1.localVaultSave)(localVault, savePayload)
             : await (0, convex_js_1.callConvex)("/vault/save", "POST", savePayload, "vault_save");
         if (data.error)
             return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
+        const projectLine = resolvedProjectName ? `\n**Project:** ${resolvedProjectName}` : "";
         return {
-            content: [{ type: "text", text: `🤖 Agent **${agentName}** spawned${localVault ? " locally" : ""}.\n\n**Goal:** ${goal}\n\nRecall with \`agent_recall\` · Update progress with \`agent_update\`` }],
+            content: [{ type: "text", text: `🤖 Agent **${agentName}** spawned${localVault ? " locally" : ""}.\n\n**Goal:** ${goal}${projectLine}\n\nRecall with \`agent_recall\` · Update progress with \`agent_update\`` }],
         };
     }
     if (name === "agent_recall") {
         const parsed = RecallAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const localVault = (0, local_vault_js_1.getLocalVaultConfig)();
         let data;
         try {
@@ -291,12 +313,30 @@ async function handleAgentTool(name, args) {
             lines.push(`\n**Recent updates:**\n${updates.join("\n")}`);
         if (state.nextStep)
             lines.push(`\n**Next step:** ${state.nextStep}`);
+        // Related context - best-effort pull of relevant memory/vault knowledge
+        // (code_session_save entries, deep_research reports, manual notes) so the
+        // agent isn't blind to work done on its goal outside its own update log.
+        // This is what makes recall "continuously have context" rather than only
+        // ever knowing what agent_update explicitly logged.
+        if (state.goal) {
+            try {
+                const related = await (0, memory_js_1.hybridMemorySearch)(state.goal, 4);
+                if (related.length) {
+                    lines.push(`\n**📎 Related context (${related.length}):**`);
+                    related.forEach((r) => {
+                        const title = r.metadata?.title ?? r.content.slice(0, 70).replace(/\n/g, " ");
+                        lines.push(`  • ${title}`);
+                    });
+                }
+            }
+            catch { /* best-effort - recall must never fail because of this */ }
+        }
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     if (name === "agent_update") {
         const parsed = UpdateAgentSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const { name: agentName, progress, findings, status = "active", nextStep } = parsed.data;
         return withAgentLock(agentName, async () => {
             const localVault = (0, local_vault_js_1.getLocalVaultConfig)();

package/dist/tools/automation.js

@@ -44,10 +44,17 @@ function categorizeError(err) {
 exports.AUTOMATION_TOOLS = [
     {
         name: "create_automation",
-        description: "Create an automation in plain English. Supports DCA, price alerts, conditional buys/sells, and recurring market updates.",
+        description: "Create an automation in plain English. Supports DCA, price alerts, conditional buys/sells, and recurring market updates. " +
+            "A swap/send automation arms UNATTENDED, REPEATING real fund movement (a backend cron fires it going forward, not just once) - " +
+            "requires two calls. First call WITHOUT confirm: returns a preview of the parsed trigger/action, nothing is created yet. " +
+            "Show that preview to the user in plain language and get explicit confirmation. Only then call again with the SAME rawInput " +
+            "and confirm: true to actually create it. Never pass confirm: true on the first call.",
         inputSchema: {
             type: "object",
-            properties: { rawInput: { type: "string", description: "Plain English description of the automation" } },
+            properties: {
+                rawInput: { type: "string", description: "Plain English description of the automation" },
+                confirm: { type: "boolean", description: "Must be true to actually create. Omit or false to get a preview only - nothing is created." },
+            },
             required: ["rawInput"],
         },
     },
@@ -108,7 +115,7 @@ exports.AUTOMATION_TOOLS = [
         },
     },
 ];
-const CreateAutomationSchema = zod_1.z.object({ rawInput: zod_1.z.string().min(1) });
+const CreateAutomationSchema = zod_1.z.object({ rawInput: zod_1.z.string().min(1), confirm: zod_1.z.boolean().optional() });
 const AutomationIdSchema = zod_1.z.object({ automationId: zod_1.z.string().min(1) });
 const RunAutomationSchema = zod_1.z.object({ automationId: zod_1.z.string().min(1), dryRun: zod_1.z.boolean().optional() });
 const RunsSchema = zod_1.z.object({ automationId: zod_1.z.string().min(1), limit: zod_1.z.number().int().min(1).max(100).optional() });
@@ -148,15 +155,44 @@ async function handleAutomationTool(name, args) {
             const parsed = CreateAutomationSchema.safeParse(args);
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: rawInput ${parsed.error.issues[0].message}` }], isError: true };
-            const data = await (0, convex_js_1.callConvex)("/automations/create", "POST", { rawInput: parsed.data.rawInput }, "create_automation");
-            if (!data.success)
-                return { content: [{ type: "text", text: `Failed: ${data.error}` }], isError: true };
             const triggerLabel = {
                 schedule: "⏰ Schedule", price_drop_pct: "📉 Price Drop %", price_rise_pct: "📈 Price Rise %",
                 price_below: "⬇️ Price Below", price_above: "⬆️ Price Above",
                 dominance_below: "📊 Dominance Below", dominance_above: "📊 Dominance Above",
             };
             const actionLabel = { swap: "💱 Swap", send: "📤 Send", alert: "🔔 Alert" };
+            // Not confirmed yet - dry-run only (backend validates/parses but does
+            // NOT create anything - see http.ts's /automations/create dryRun
+            // branch). A swap/send automation arms unattended, repeating real
+            // fund movement, so it needs a real preview + explicit confirm, same
+            // shape as base_mcp_swap/send - not created blind on the first call.
+            if (parsed.data.confirm !== true) {
+                const preview = await (0, convex_js_1.callConvex)("/automations/create", "POST", { rawInput: parsed.data.rawInput, dryRun: true }, "create_automation");
+                if (!preview.success)
+                    return { content: [{ type: "text", text: `Could not parse this automation: ${preview.error}` }], isError: true };
+                const moneyMoving = preview.actionType === "swap" || preview.actionType === "send";
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `**Preview - nothing created yet**`, ``,
+                                `**Trigger:** ${triggerLabel[preview.triggerType] ?? preview.triggerType}`,
+                                `**Action:** ${actionLabel[preview.actionType] ?? preview.actionType}`,
+                                preview.fromToken && preview.toToken ? `**Swap:** ${preview.amountUsd ? `$${preview.amountUsd}` : `${preview.amountPct}%`} ${preview.fromToken} → ${preview.toToken}` : ``,
+                                preview.toAddress ? `**Send:** ${preview.amountUsd ? `$${preview.amountUsd}` : ""} ${preview.fromToken ?? ""} to \`${preview.toAddress}\`` : ``,
+                                preview.priceToken ? `**Price condition:** ${preview.priceToken} ${preview.triggerType?.includes("above") ? "above" : "below"} ${preview.priceThreshold}` : ``,
+                                preview.priceBaselineUsd ? `**Baseline price:** $${Number(preview.priceBaselineUsd).toLocaleString()}` : ``,
+                                moneyMoving
+                                    ? `\n⚠️ This will move real funds, repeatedly, unattended, until paused or deleted. Show this preview to the user and get explicit confirmation.`
+                                    : `\nThis is alert-only - it will not move funds.`,
+                                `\nIf this is correct, call create_automation again with the same rawInput and confirm: true.`,
+                            ].filter(Boolean).join("\n"),
+                        }],
+                };
+            }
+            const data = await (0, convex_js_1.callConvex)("/automations/create", "POST", { rawInput: parsed.data.rawInput }, "create_automation");
+            if (!data.success)
+                return { content: [{ type: "text", text: `Failed: ${data.error}` }], isError: true };
             return {
                 content: [{
                         type: "text",

package/dist/tools/coder.js

@@ -52,7 +52,7 @@ async function handleCoderTool(name, args) {
         return null;
     const p = AuditSchema.safeParse(args);
     if (!p.success)
-        return err(`Invalid input: ${p.error.message}`);
+        return err(p.error.issues[0].message);
     const { code, focus = [] } = p.data;
     // The pattern scan grounds the review. Without it an audit is pure model
     // opinion — someone might trust "looks safe" with nothing behind it.

package/dist/tools/deep-research.js

@@ -915,7 +915,7 @@ async function handleDeepResearch(name, args, onProgress) {
         return null;
     const parsed = InputSchema.safeParse(args);
     if (!parsed.success) {
-        return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
     }
     const { query, focus, continueFrom } = parsed.data;
     const clientQueries = parsed.data.queries ?? [];

package/dist/tools/defi.js

@@ -99,7 +99,7 @@ async function handleDefiTool(name, args) {
         case "estimate_swap": {
             const parsed = SwapSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${String(parsed.error.issues[0].path[0])} ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
             const { fromToken, toToken, amount, maxSlippagePct, maxPriceImpactPct } = parsed.data;
             const slippageLimit = maxSlippagePct ?? DEFAULT_MAX_SLIPPAGE_PCT;
             const impactLimit = maxPriceImpactPct ?? DEFAULT_MAX_PRICE_IMPACT_PCT;
@@ -137,7 +137,7 @@ async function handleDefiTool(name, args) {
         case "swap_tokens": {
             const parsed = SwapSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${String(parsed.error.issues[0].path[0])} ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
             const { fromToken, toToken, amount, maxSlippagePct, maxPriceImpactPct } = parsed.data;
             const slippageLimit = maxSlippagePct ?? DEFAULT_MAX_SLIPPAGE_PCT;
             const impactLimit = maxPriceImpactPct ?? DEFAULT_MAX_PRICE_IMPACT_PCT;
@@ -190,7 +190,7 @@ async function handleDefiTool(name, args) {
         case "send_token": {
             const parsed = SendSchema.safeParse(args);
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${String(parsed.error.issues[0].path[0])} ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
             const { token, toAddress, amount } = parsed.data;
             const wallet = await (0, wallet_js_1.getOrCreateWallet)();
             const result = await (0, convex_js_1.callConvex)("/mcp/defi/send", "POST", parsed.data, "send_token");
@@ -225,7 +225,7 @@ async function handleDefiTool(name, args) {
         case "get_defi_yields": {
             const parsed = DefiYieldsSchema.safeParse(args ?? {});
             if (!parsed.success)
-                return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
             const { token, minApy = 1, limit = 20 } = parsed.data;
             let pools;
             try {

package/dist/tools/equity.js

@@ -183,7 +183,7 @@ async function handleEquityTool(name, args) {
         return null;
     const parsed = Schema.safeParse(args);
     if (!parsed.success) {
-        return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
     }
     const ticker = parsed.data.ticker.trim().toUpperCase();
     const periods = parsed.data.periods ?? 6;

package/dist/tools/events.js

@@ -97,7 +97,7 @@ async function handleEventTool(name, args) {
         return null;
     const parsed = Schema.safeParse(args);
     if (!parsed.success) {
-        return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
     }
     const ticker = parsed.data.ticker.trim().toUpperCase();
     const limit = parsed.data.limit ?? 15;

package/dist/tools/github.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GITHUB_TOOLS = void 0;
 exports.buildRepoList = buildRepoList;
@@ -9,13 +42,30 @@ exports.buildIssueDetail = buildIssueDetail;
 exports.buildCommitList = buildCommitList;
 exports.buildCodeSearch = buildCodeSearch;
 exports.handleGithubTool = handleGithubTool;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const GH_BASE = "https://api.github.com";
+// Was hardcoded "finch-mcp/3.28.0" - stale the moment package.json's version
+// moved on (already 4.4.0 locally as of this fix), unlike server.ts/cli.ts/
+// index.ts which all read it from package.json at runtime per this repo's
+// own stated policy (see CLAUDE.md's mcp-server note). __dirname here is
+// dist/tools/ once built, so two levels up reaches the package root - one
+// level deeper than server.ts's own copy of this pattern (dist/).
+const PKG_VERSION = (() => {
+    try {
+        const raw = fs.readFileSync(path.join(__dirname, "..", "..", "package.json"), "utf8");
+        return JSON.parse(raw).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 function ghHeaders() {
     const token = process.env.GITHUB_TOKEN;
     const h = {
         Accept: "application/vnd.github.v3+json",
         "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "finch-mcp/3.28.0",
+        "User-Agent": `finch-mcp/${PKG_VERSION}`,
     };
     if (token)
         h.Authorization = `Bearer ${token}`;

package/dist/tools/insider.js

@@ -116,7 +116,7 @@ async function handleInsiderTool(name, args) {
         return null;
     const parsed = Schema.safeParse(args);
     if (!parsed.success) {
-        return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
     }
     const ticker = parsed.data.ticker.trim().toUpperCase();
     const limit = parsed.data.limit ?? 15;

package/dist/tools/insight.js

@@ -451,7 +451,7 @@ async function handleInsightTool(name, args) {
     if (name === "market_thesis") {
         const parsed = MarketThesisSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const { token, context } = parsed.data;
         const priceData = await fetchVerifiedPrice(token);
         // Hard guard: without a verified live price, refuse to generate. Better
@@ -519,7 +519,7 @@ async function handleInsightTool(name, args) {
     if (name === "trade_plan") {
         const parsed = TradePlanSchema.safeParse(args);
         if (!parsed.success)
-            return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
         const { token, side = "long", portfolioSize, riskTolerance = "moderate", timeframe } = parsed.data;
         const priceData = await fetchVerifiedPrice(token);
         // Hard guard: trade plans without verified live price = entry/SL/TP