@finchagentic/mcp 4.0.0 → 4.1.0

package/dist/tools/vault.js

@@ -11,7 +11,7 @@ const VAULT_TYPES = ["research", "execution", "workflow", "prompt", "file", "mem
 exports.VAULT_TOOLS = [
     {
         name: "vault_save",
-        description: "Save or update a versioned artifact in Noel-Vault. Same key = update (git-style: prior version snapshotted, patched to v+1). " +
+        description: "Save or update a versioned artifact in Finch Vault. Same key = update (git-style: prior version snapshotted, patched to v+1). " +
             "Types: research | execution | workflow | prompt | file | memory. " +
             "Entries up to 10MB - content over 600KB auto-offloads to blob storage. " +
             "For quick unstructured notes, use memory_add instead.",
@@ -33,7 +33,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_read",
-        description: "Read a Noel-Vault entry by its key. Returns full content, version, tags, and any linked entries.",
+        description: "Read a Finch Vault entry by its key. Returns full content, version, tags, and any linked entries.",
         inputSchema: {
             type: "object",
             properties: {
@@ -44,7 +44,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_list",
-        description: "List Noel-Vault entries. Filter by type, agent, or pinned status. Returns previews, not full content.",
+        description: "List Finch Vault entries. Filter by type, agent, or pinned status. Returns previews, not full content.",
         inputSchema: {
             type: "object",
             properties: {
@@ -58,14 +58,14 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_search",
-        description: "Search Noel-Vault using semantic AI search (powered by Supermemory) when available, " +
-            "with automatic fallback to full-text search. Semantic search understands meaning - " +
-            "'low risk DeFi yield' matches 'conservative staking strategies' without exact keywords. " +
+        description: "Search Finch Vault using full-text (keyword) search over titles, content, and tags. " +
+            "This is lexical matching, not embeddings - exact and near words in your query rank " +
+            "highest, so short specific phrases work better than long abstract descriptions. " +
             "Optionally filter by type. Returns ranked results with previews.",
         inputSchema: {
             type: "object",
             properties: {
-                query: { type: "string", description: "Search query - natural language works best with semantic mode" },
+                query: { type: "string", description: "Search query - specific keywords work better than abstract phrasing (this is full-text search, not semantic)" },
                 type: { type: "string", enum: [...VAULT_TYPES], description: "Narrow search to a specific type" },
                 limit: { type: "number", description: "Max results (default 20)" },
             },
@@ -74,7 +74,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_history",
-        description: "Get the full version history of a Noel-Vault entry - like git log. " +
+        description: "Get the full version history of a Finch Vault entry - like git log. " +
             "Shows each version with its commit message, author agent, size, and timestamp.",
         inputSchema: {
             type: "object",
@@ -86,7 +86,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_diff",
-        description: "Compare two versions of a Noel-Vault entry - like git diff. " +
+        description: "Compare two versions of a Finch Vault entry - like git diff. " +
             "Shows lines added (+) and removed (-) between fromVersion and toVersion.",
         inputSchema: {
             type: "object",
@@ -100,7 +100,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_export",
-        description: "Export your entire Noel-Vault or a specific type as a structured bundle. " +
+        description: "Export your entire Finch Vault or a specific type as a structured bundle. " +
             "Useful for archiving, syncing to GitHub, or passing context to another agent.",
         inputSchema: {
             type: "object",
@@ -139,7 +139,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_pin",
-        description: "Pin or unpin a Noel-Vault entry. Pinned entries always appear first in vault_list and are " +
+        description: "Pin or unpin a Finch Vault entry. Pinned entries always appear first in vault_list and are " +
             "prioritized in memory_context and search results. Use for your most important research, key prompts, or canonical references.",
         inputSchema: {
             type: "object",
@@ -152,7 +152,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_unpublish",
-        description: "Make a previously shared Noel-Vault entry private again, removing it from the public community " +
+        description: "Make a previously shared Finch Vault entry private again, removing it from the public community " +
             "listing. Use this to reverse vault publishing or packet_share. Note that anyone who already " +
             "copied the content while it was public still has it — unpublishing stops future discovery, " +
             "it does not retract what was taken.",
@@ -166,7 +166,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_delete",
-        description: "PERMANENT. Delete a Noel-Vault entry and ALL of its version history — this cannot be undone. " +
+        description: "PERMANENT. Delete a Finch Vault entry and ALL of its version history — this cannot be undone. " +
             "Requires confirm: true. Use vault_list to browse first, and show the user the exact entry " +
             "(key + title) you are about to destroy before confirming.",
         inputSchema: {
@@ -180,7 +180,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_tag",
-        description: "Add or replace tags on an existing Noel-Vault entry without modifying its content. " +
+        description: "Add or replace tags on an existing Finch Vault entry without modifying its content. " +
             "Useful for organizing entries retroactively. Set replace=true to overwrite all existing tags.",
         inputSchema: {
             type: "object",
@@ -194,7 +194,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_link",
-        description: "Create a semantic relationship between two Noel-Vault entries - building a knowledge graph. " +
+        description: "Create a semantic relationship between two Finch Vault entries - building a knowledge graph. " +
             "Relations: references | derived_from | supersedes | related | continues. " +
             "Example: link a synthesis entry as 'derived_from' several research entries, or mark a newer analysis as 'supersedes' an older one. " +
             "Duplicate links are updated in-place.",
@@ -214,7 +214,7 @@ exports.VAULT_TOOLS = [
     },
     {
         name: "vault_related",
-        description: "Traverse the Noel-Vault knowledge graph - get all entries linked to a given entry. " +
+        description: "Traverse the Finch Vault knowledge graph - get all entries linked to a given entry. " +
             "Returns both outbound links (entries this entry references) and inbound links (entries that reference this one). " +
             "Filter by relation type to find only derived entries, superseded versions, continuations, etc.",
         inputSchema: {
@@ -302,7 +302,7 @@ async function handleVaultTool(name, args) {
             if (data.error)
                 return { content: [{ type: "text", text: `Error: ${data.error}` }], isError: true };
             const { key, version, changed } = data;
-            // Mirror to semantic memory (fire-and-forget). Skip when running a local
+            // Mirror to searchable memory (fire-and-forget). Skip when running a local
             // vault WITHOUT local memory - otherwise the mirror would phone home to
             // the hosted proxy (needs auth the local-only user doesn't have, and
             // ships their data off-machine, defeating the whole point). vault_search
@@ -335,7 +335,7 @@ async function handleVaultTool(name, args) {
                 `Key: \`${key}\``,
                 `Version: v${version}`,
                 changed && version > 1 ? `Previous version auto-snapshotted.` : "",
-                mirrorToMemory ? `🧠 Synced to semantic memory` : (localVault ? `💾 Stored locally at ~/.finch/vault` : ""),
+                mirrorToMemory ? `🧠 Synced to searchable memory` : (localVault ? `💾 Stored locally at ~/.finch/vault` : ""),
                 ...linkSummary,
                 ``,
                 `Use \`vault_read\` to retrieve, \`vault_history\` to see all versions.`,
@@ -361,7 +361,7 @@ async function handleVaultTool(name, args) {
                                     `vault_read: entry \`${vaultReadKey}\` not found.`,
                                     ``,
                                     `Try searching for it:`,
-                                    `- \`vault_search query="${searchTerms}"\` — semantic search across all entries`,
+                                    `- \`vault_search query="${searchTerms}"\` — full-text search across all entries`,
                                     `- \`vault_list\` — browse all entries`,
                                     `- \`vault_search query="${vaultReadKey.split("/")[0]}"\` — search by type prefix`,
                                 ].join("\n") }], isError: true };
@@ -435,7 +435,7 @@ async function handleVaultTool(name, args) {
             const entries = data.entries ?? [];
             if (!entries.length)
                 return { content: [{ type: "text", text: `No vault entries found${parsed.data.type ? ` of type '${parsed.data.type}'` : ""}.` }] };
-            const header = `📚 **Noel-Vault** (${entries.length} entries)`;
+            const header = `📚 **Finch Vault** (${entries.length} entries)`;
             const rows = entries.map((e) => `${e.isPinned ? "📌 " : ""}[\`${e.key}\`] ${e.title} - v${e.version} · ${e.type} · ${formatBytes(e.size)} · ${formatDate(e.updatedAt)}`);
             return { content: [{ type: "text", text: [header, "", ...rows].join("\n") }] };
         }
@@ -443,7 +443,9 @@ async function handleVaultTool(name, args) {
             const parsed = SearchSchema.safeParse(args);
             if (!parsed.success)
                 return { content: [{ type: "text", text: `Invalid input: ${parsed.error.issues[0].message}` }], isError: true };
-            // Try semantic search first (proxied through Convex). Large vault
+            // Full-text search, proxied through Convex (searchSupermemory is a
+            // legacy name - it calls Finch's own /memory/search endpoint, not a
+            // third-party semantic service; there is no embedding step here). Large vault
             // entries are indexed as multiple chunks tagged with isVaultChunk +
             // vaultKey - group chunks back to their parent entry so the result
             // list shows one row per entry, not one row per chunk.

package/dist/wallet.js

@@ -36,8 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BASE_CHAIN_ID = exports.MEV_PROTECT_ENABLED = exports.BROADCAST_RPC = exports.BASE_RPC = void 0;
 exports.clearWalletCache = clearWalletCache;
 exports.getMachineKey = getMachineKey;
+exports.warnIfNoPassphrase = warnIfNoPassphrase;
 exports.getOrCreateWallet = getOrCreateWallet;
 exports.signRequest = signRequest;
+exports.waitForReceipt = waitForReceipt;
 exports.signAndBroadcast = signAndBroadcast;
 const ethers_1 = require("ethers");
 const fs = __importStar(require("fs"));
@@ -67,10 +69,30 @@ const WALLET_FILE = path.join(WALLET_DIR, "wallet.json");
 let _cachedWallet = null;
 function clearWalletCache() { _cachedWallet = null; }
 function getMachineKey() {
-    // If a passphrase is set, use it as the primary secret for stronger encryption.
-    // Without it, the key is derived from public machine info only - this is
-    // convenience encryption (prevents casual reads), not security against
-    // an attacker who has read access to both the file and system info.
+    // A passphrase is meant to make the wallet portable (move the encrypted
+    // file + set the same passphrase elsewhere and it still decrypts) - so when
+    // one is set, derive the key from ONLY the passphrase, no machine binding.
+    // Without a passphrase, fall back to machine info as convenience-only
+    // encryption (prevents casual reads, not security against an attacker who
+    // has both the file and the system info).
+    const passphrase = process.env.FINCH_WALLET_PASSPHRASE ?? "";
+    if (passphrase) {
+        return crypto.createHash("sha256").update(passphrase).digest("hex").slice(0, 32);
+    }
+    return crypto
+        .createHash("sha256")
+        .update(os.hostname() + os.platform() + os.arch())
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Pre-fix key derivation: always folded in machine info even when a
+ * passphrase was set, so a wallet encrypted before this fix can only ever be
+ * decrypted on the exact machine that created it - never portable. Kept
+ * solely so those existing wallets still open; getOrCreateWallet migrates
+ * them to the portable scheme in place on first successful decrypt.
+ */
+function getLegacyMachineKey() {
     const passphrase = process.env.FINCH_WALLET_PASSPHRASE ?? "";
     return crypto
         .createHash("sha256")
@@ -101,18 +123,43 @@ async function getOrCreateWallet() {
             _cachedWallet = wallet;
             return wallet;
         }
-        catch (err) {
-            // A wallet file already exists but couldn't be decrypted - this almost
-            // always means FINCH_WALLET_PASSPHRASE (or the machine info the key
-            // is derived from) doesn't match what encrypted it. Silently creating
-            // a fresh wallet here would overwrite the existing encrypted file,
-            // orphaning it and any funds it controls. Refuse instead.
-            throw new Error(`Could not decrypt existing wallet at ${WALLET_FILE}: ${err?.message ?? "unknown error"}\n\n` +
-                `This usually means FINCH_WALLET_PASSPHRASE doesn't match the passphrase ` +
-                `used when this wallet was encrypted (or this is a different machine). ` +
-                `Refusing to auto-create a replacement wallet, since that would silently ` +
-                `orphan the existing one and any funds it holds.\n\n` +
-                `If you're sure this wallet should be abandoned, move or delete ${WALLET_FILE} manually first.`);
+        catch (currentErr) {
+            // Fall back to the pre-fix machine-bound scheme, for wallets encrypted
+            // before passphrases became portable. Only relevant on the ORIGINAL
+            // machine (it still needs that machine's hostname/platform/arch) - it
+            // can't rescue a wallet file copied to a new machine from before this
+            // fix; there was no passphrase-only secret saved anywhere to recover.
+            try {
+                const wallet = await ethers_1.ethers.Wallet.fromEncryptedJson(encrypted, getLegacyMachineKey());
+                _cachedWallet = wallet;
+                // Migrate in place to the portable scheme now that we've proven we
+                // hold the right key, so this only ever needs to happen once.
+                try {
+                    const migrated = await wallet.encrypt(getMachineKey());
+                    fs.writeFileSync(WALLET_FILE, migrated, { mode: 0o600 });
+                    process.stderr.write(`\nMigrated ${WALLET_FILE} to the portable passphrase scheme.\n\n`);
+                }
+                catch {
+                    /* migration is best-effort - the legacy key still works next run either way */
+                }
+                return wallet;
+            }
+            catch {
+                // A wallet file already exists but couldn't be decrypted under either
+                // scheme - this almost always means FINCH_WALLET_PASSPHRASE doesn't
+                // match what encrypted it, or this is a different machine and no
+                // passphrase was ever set. Silently creating a fresh wallet here
+                // would overwrite the existing encrypted file, orphaning it and any
+                // funds it controls. Refuse instead.
+                throw new Error(`Could not decrypt existing wallet at ${WALLET_FILE}: ${currentErr?.message ?? "unknown error"}\n\n` +
+                    `This usually means FINCH_WALLET_PASSPHRASE doesn't match the passphrase ` +
+                    `used when this wallet was encrypted, or this file was copied from a ` +
+                    `different machine and no passphrase was set when it was created (in ` +
+                    `which case the key was machine-bound and cannot be recovered elsewhere). ` +
+                    `Refusing to auto-create a replacement wallet, since that would silently ` +
+                    `orphan the existing one and any funds it holds.\n\n` +
+                    `If you're sure this wallet should be abandoned, move or delete ${WALLET_FILE} manually first.`);
+            }
         }
     }
     const wallet = ethers_1.ethers.Wallet.createRandom();
@@ -161,6 +208,36 @@ async function broadcastTx(signedTx) {
         throw new Error(`broadcast failed: ${data.error.message}`);
     return data.result;
 }
+/**
+ * Poll for the mined receipt and report the ACTUAL on-chain outcome.
+ *
+ * eth_sendRawTransaction only confirms the mempool accepted the tx, not that
+ * it succeeded - a stale quote, slippage beyond the router's own guard, or an
+ * allowance edge case can all revert on-chain while still broadcasting fine.
+ * Callers must gate their success/failure message on this, not on
+ * signAndBroadcast() returning a hash.
+ */
+async function waitForReceipt(txHash, timeoutMs = 60000, pollMs = 2000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const receipt = await rpcPost("eth_getTransactionReceipt", [txHash]);
+            if (receipt) {
+                return {
+                    mined: true,
+                    ok: parseInt(receipt.status, 16) === 1,
+                    blockNumber: parseInt(receipt.blockNumber, 16),
+                    gasUsed: receipt.gasUsed ? BigInt(receipt.gasUsed).toString() : undefined,
+                };
+            }
+        }
+        catch {
+            /* transient RPC error - keep polling until timeout */
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    return { mined: false };
+}
 async function signAndBroadcast(wallet, txData) {
     let data = txData.data || "0x";
     if (txData.permit2?.eip712) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@finchagentic/mcp",
-  "version": "4.0.0",
-  "description": "The runtime layer for Agentic AI. 121 MCP tools: persistent memory, autonomous agents, vault storage, scheduled workflows, DeFi on Base (base_mcp_*), Robinhood Chain tokenized stocks and arbitrary crypto with V3/V4 smart routing (rh_*), live market data, deep research, and Finch Terminal. Runs fully local \u2014 self-hosted vault + memory on your own disk, no account, your LLM does the thinking. Works in Claude Code, Cursor, Windsurf, and any MCP client.",
+  "version": "4.1.0",
+  "description": "The runtime layer for Agentic AI. Persistent memory, autonomous agents, and workflows that survive every session.",
   "main": "dist/index.js",
   "bin": {
     "finch": "dist/cli.js",
@@ -23,35 +23,23 @@
   },
   "keywords": [
     "mcp",
-    "mcp-server",
     "model-context-protocol",
     "ai-agent",
-    "autonomous-agents",
+    "agentic",
     "persistent-memory",
-    "memory-layer",
+    "autonomous-agents",
+    "workflows",
     "vault",
-    "agentic",
-    "workflow-automation",
-    "claude-code",
-    "cursor",
-    "windsurf",
     "finch",
     "finchagentic",
-    "research",
-    "automation",
-    "defi",
-    "base-chain",
-    "tool-calling",
-    "finch-terminal",
-    "ai-terminal",
-    "knowledge-graph",
-    "semantic-search"
+    "claude-code",
+    "cursor"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/finchagentic/mcp.git"
   },
-  "homepage": "https://github.com/finchagentic/mcp#readme",
+  "homepage": "https://docs.finch.com",
   "bugs": {
     "url": "https://github.com/finchagentic/mcp/issues"
   },