@finchagentic/mcp 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 noelclaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+<div align="center">
+
+<!-- Hero Banner SVG (self-contained, no external image) -->
+<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAwIiBoZWlnaHQ9IjMwMCIgdmlld0JveD0iMCAwIDEyMDAgMzAwIj4KICA8ZGVmcz4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0iYmciIHgxPSIwIiB5MT0iMCIgeDI9IjAiIHkyPSIxIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojMGEwYTBhO3N0b3Atb3BhY2l0eToxIi8+CiAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3R5bGU9InN0b3AtY29sb3I6IzFhMWEyNTtzdG9wLW9wYWNpdHk6MSIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDxyYWRpYWxHcmFkaWVudCBpZD0iZ2xvdyIgY3g9IjUwJSIgY3k9IjUwJSIgcj0iNTAlIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojMjU2M0VCO3N0b3Atb3BhY2l0eTowLjMiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxIiBzdHlsZT0ic3RvcC1jb2xvcjojMjU2M0VCO3N0b3Atb3BhY2l0eTowIi8+CiAgICA8L3JhZGlhbEdyYWRpZW50PgogIDwvZGVmcz4KICA8cmVjdCB3aWR0aD0iMTIwMCIgaGVpZ2h0PSIzMDAiIGZpbGw9InVybCgjYmcpIi8+CiAgPGNpcmNsZSBjeD0iNjAwIiBjeT0iMTUwIiByPSIyMDAiIGZpbGw9InVybCgjZ2xvdykiLz4KICA8dGV4dCB4PSI2MDAiIHk9IjEyMCIgZm9udC1mYW1pbHk9InN5c3RlbS11aSwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSI1NiIgZm9udC13ZWlnaHQ9IjgwMCIgZmlsbD0iI2YwZjZmYyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgbGV0dGVyLXNwYWNpbmc9Ii0wLjAzZW0iPk5vZWxDbGF3PC90ZXh0PgogIDx0ZXh0IHg9IjYwMCIgeT0iMTY1IiBmb250LWZhbWlseT0ic3lzdGVtLXVpLCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjIwIiBmb250LXdlaWdodD0iNDAwIiBmaWxsPSIjOTNjNWZkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5UaGUgcnVudGltZSBsYXllciBmb3IgQWdlbnRpYyBBSTwvdGV4dD4KICA8dGV4dCB4PSI2MDAiIHk9IjE5NSIgZm9udC1mYW1pbHk9InN5c3RlbS11aSwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxNCIgZm9udC13ZWlnaHQ9IjQwMCIgZmlsbD0iIzY0NzQ4YiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+MTIxIHRvb2xzIOKAlCBwZXJzaXN0ZW50IG1lbW9yeSDigJQgYWdlbnRzIOKAlCB3b3JrZmxvd3Mg4oCUIERlRmkgb24gQmFzZTwvdGV4dD4KPC9zdmc+" alt="Finch" width="100%">
+
+</div>
+
+---
+
+<div align="center">
+
+# The runtime layer for Agentic AI.
+
+**Your AI remembers, keeps working, and survives every session.**
+
+</div>
+
+---
+
+> Most AI assistants disappear when the conversation ends. Finch gives them persistent state — memory that accumulates, agents that keep running, vaults that version knowledge, and workflows that continue after you close the chat.
+
+## Table of Contents
+
+- [What's New](#whats-new)
+- [Three Pillars](#three-pillars)
+- [Install](#install)
+- [In Practice](#in-practice)
+- [Configuration](#configuration)
+- [Security](#security-boundaries)
+- [Comparison](#why-this-is-different)
+- [Troubleshooting](#troubleshooting)
+- [Links](#links)
+
+---
+
+## What's New
+
+| Feature | Description |
+|---------|-------------|
+| **🔒 Fully local** | Run the whole runtime on your own machine — **vault + memory on your own disk** (versioned, encrypted, no account), wallet keys local, your LLM does the thinking. Nothing phones home. `finch setup` to enable, `finch vault` to inspect. → [Run it fully local](#run-it-fully-local) |
+| **Local Memory** | Run memory tools on a free, self-hosted [supermemory](https://github.com/supermemoryai/supermemory) server on your own machine — zero cost, private, no Finch account needed. `finch setup` to enable. |
+| **OpenAI BYOK** | OpenAI joins Bankr/Anthropic/Grok as a direct LLM provider. `OPENAI_BASE_URL` also lets you point at any self-hosted OpenAI-compatible gateway (LiteLLM, vLLM, Ollama, OpenRouter, your own VPS). |
+| **`finch setup`** | New guided CLI wizard — pick an LLM provider and/or enable local memory in one flow. |
+| **Finch Terminal** | Tool calling from chat — spawn agents, save to vault, search memory, estimate + execute swaps, create automations. All from a single prompt. |
+| **`execute_swap`** | Execute token swaps on Base mainnet from Finch Terminal. Enforces estimate → preview → confirm → execute flow. Routes via 0x Permit2. |
+| **7 Agents** | Noel (AI OS), CoinGecko (market data), Sage (research), Forge (code), Quill (creative), Spectre (trading), Atlas (general) |
+| **Multi-Provider Chat** | Bankr → Anthropic → OpenAI → Grok → Finch proxy fallback |
+| **ConnectMcpModal** | Onboarding flow: auto-generate API key + copy install command from webapp |
+| **Security Hardened** | 8 security boundaries, wallet decrypt-failure protection, 4 other vulnerability fixes (auth, OTP, private key) |
+| **Knowledge Graph** | Vault entries link into a typed graph (`references`, `derived_from`, `supersedes`, `related`, `continues`) — auto-built from `[[wikilinks]]` + `#tags`, with backlinks. Data layer only for now; visual graph is planned. |
+| **Ecosystem** | CI/CD, CodeQL, Dependabot, Husky, Dockerfile, coverage reporting, semantic release, TypeDoc |
+
+---
+
+## Three Pillars
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### Memory
+Semantic, versioned, deduplicated.
+
+Your AI remembers what you told it last week, last month, in a different session — and ranks recent context above stale notes via 90-day half-life decay. Run `finch setup` to switch to a free, self-hosted local backend instead of the Finch-hosted proxy.
+
+```bash
+remember: I prefer conservative DeFi strategies, max 5% APY
+→ ✓ saved to memory
+  auto-loaded in future sessions
+```
+
+</td>
+<td width="33%" valign="top">
+
+### Agents
+Named, persistent, identity-bound.
+
+Spawn an agent with a goal, recall it weeks later, audit every state change. Each agent can hold its own Base wallet address.
+
+```bash
+spawn an agent called market-researcher
+  goal: track Base chain protocols weekly
+→ 🤖 agent spawned
+  recall anytime with agent_recall
+```
+
+</td>
+<td width="33%" valign="top">
+
+### Workflows
+Packets, automations, monitors, deep research.
+
+Anything that runs on a schedule or continues after the chat ends.
+
+```bash
+set up a daily monitor for
+  AI agent infrastructure news
+→ ✓ monitor created
+  runs daily 08:00 UTC
+  findings auto-saved to vault
+```
+
+</td>
+</tr>
+</table>
+
+---
+
+## Install
+
+### One-command auto-install (any MCP client)
+```bash
+npx -y -p @finchagentic/mcp@4.0.0 finch install
+```
+> Detects Claude Desktop, Cursor, Windsurf, VS Code, and Zed, and configures each automatically. **Claude Code** is configured with the dedicated `claude mcp add` command below (its config lives outside the desktop-app path this scan checks).
+
+### Claude Code
+```bash
+claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.0.0 finch-mcp
+```
+
+### Cursor / Windsurf / Claude Desktop
+```json
+{
+  "mcpServers": {
+    "finch": {
+      "command": "npx",
+      "args": ["-y", "-p", "@finchagentic/mcp@4.0.0", "finch-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+`mcp.json` uses the `servers` key (not `mcpServers`), and each entry needs `"type": "stdio"`:
+```json
+{
+  "servers": {
+    "finch": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "@finchagentic/mcp@4.0.0", "finch-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+In `settings.json` under `context_servers` (each entry needs `"source": "custom"`):
+```json
+{
+  "context_servers": {
+    "finch": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "-p", "@finchagentic/mcp@4.0.0", "finch-mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Config file paths</summary>
+
+| Client | Path |
+|--------|------|
+| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Zed | `.config/zed/settings.json` |
+| VS Code | `.vscode/mcp.json` |
+
+</details>
+
+> No LLM API key required — not to start, and not for any tool. Tools load on first use.
+
+> **Always pin the version** (`@finchagentic/mcp@4.0.0`, never `@latest`) — this MCP has wallet, credential, and backend persistence capabilities. See [Security Boundaries](#security-boundaries).
+
+---
+
+## Run it fully local
+
+Finch is the runtime; **your LLM is the brain, and your data stays yours.** You can run the whole thing on your own machine — no Finch account, no cloud, nothing leaving your laptop.
+
+**Turn it on:**
+```bash
+npx -y -p @finchagentic/mcp@4.0.0 finch setup
+# → answer "y" to "Enable local vault" (and, optionally, local memory)
+```
+
+**What runs local:**
+
+| Piece | Where it lives | Notes |
+|-------|----------------|-------|
+| **Vault** | `~/.finch/vault/` | Versioned artifacts + knowledge graph. Credentials AES-256-GCM encrypted. Plain files — copy, `git`, or sync them anywhere. |
+| **Memory** | self-hosted [supermemory](https://github.com/supermemoryai/supermemory) | Semantic recall on your machine. Optional; without it, vault search falls back to local full-text. |
+| **Wallet** | `~/.finch/wallet.json` | Keys never leave your machine. |
+| **The brain** | your MCP client's model | Claude Code, Cursor, etc. **No BYOK LLM key needed** — the model is already yours. |
+| **Public-data tools** | direct API calls | Market, scanner, SEC, GitHub, Robinhood Chain reads — keyless from day one. |
+
+**Your data is a plain folder.** Back it up with `cp`, version it with `git`, sync it however you like — it never syncs anywhere on its own.
+
+```bash
+finch vault     # where it is, what's in it, how to back it up
+finch doctor    # confirm "Local vault: on" and everything else
+```
+
+**What still needs an account** (inherently server-side, can't be local): scheduled/cron agents, cross-device sync, and the community marketplace. Everything else works with zero sign-in.
+
+---
+
+## In Practice
+
+```
+> what have you found so far on AI agent infrastructure?
+  → Pulls from vault: 3 reports across 7 days · summarizes key themes
+
+> give me a bull vs bear thesis on ETH, save it
+  → Full analysis written + auto-saved to vault as v1
+
+> swap 50 USDC to ETH
+  → [estimate_swap] Quote: 0.027 ETH · slippage 0.5% · gas ~$0.03
+  → Confirm swap? (yes/no)
+  → [execute_swap confirmed=true]
+  → ✅ Swap executed · tx 0xabc... · view on Basescan
+
+> spawn an agent to track Base DeFi weekly
+  → 🤖 Agent 'base-tracker' created · runs every Monday 09:00 UTC
+```
+
+---
+
+## 121 Tools Across the Runtime
+
+| Pillar | Categories | Count |
+|--------|-----------|:-----:|
+| Memory | Memory · Vault · Chronicle | 29 |
+| Agents | Agents · Hire | 12 |
+| Workflows | Automation · Monitors · Packets · Deep Research · Research Compare/Chain · OS | 19 |
+| Execution | Base DeFi (base_mcp_*) · Robinhood Chain (rh_*) · Stocks (SEC) · Market · Scanner · Web · GitHub · Code Audit · Wallet | 61 |
+
+> Run `finch doctor` for a 5-second health check showing exactly what's wired and what isn't.
+
+---
+
+## Configuration
+
+<details>
+<summary>Environment Variables (click to expand)</summary>
+
+**No LLM key is required — for any tool.** Tools reach the network, read chains, hold state and execute
+transactions, then hand the result back to *your* client's model to reason over. None of them run inference of
+their own, so none of them can be broken by a missing key.
+
+A key makes Finch a *host* rather than a set of hands. That is only three things:
+
+- `finch run` — the CLI agent loop, which has no client model to borrow
+- **scheduled / cron agents** — they wake with no session attached
+- `deep_research mode:"report"` — opt-in server-written prose; the default `mode:"sources"` is keyless
+
+| Variable | Purpose | When you need it |
+|----------|---------|------------------|
+| `FINCH_SESSION_TOKEN` | Session token from [app.finchagentic.com](https://app.finchagentic.com) | Recommended — vault, memory and agent tools persist against your account |
+| `BANKR_API_KEY` | Use Bankr as your LLM gateway | Only to *be* a host: CLI loop, cron agents |
+| `ANTHROPIC_API_KEY` | Use your own Anthropic quota | Same — never needed by a tool |
+| `OPENAI_API_KEY` | Use OpenAI for chat/research | Same |
+| `OPENAI_BASE_URL` | Route OpenAI-shaped calls to a self-hosted gateway instead (LiteLLM, vLLM, Ollama, OpenRouter) | Same |
+| `GROK_API_KEY` | Use xAI Grok (`grok-4-fast-reasoning` by default) | Same |
+| `FINCH_PROVIDER` | Force a specific provider: `bankr` \| `anthropic` \| `openai` \| `grok` | Optional |
+| `FIRECRAWL_API_KEY` | Better crawl quality for `deep_research` and `web_search` | Optional — both fall back to the Finch proxy |
+| `GITHUB_TOKEN` | Required for `github_search_code` | For GitHub |
+| `ALCHEMY_API_KEY` | Faster Base chain queries | Optional |
+
+Run `npx -y -p @finchagentic/mcp@4.0.0 finch setup` for a guided wizard instead of setting these by hand — it also enables a free, self-hosted local memory + [fully-local vault](#run-it-fully-local), so vault and memory tools need no account at all.
+
+</details>
+
+---
+
+## Security Boundaries
+
+> These 8 boundaries are mandatory. Violating any is a critical security failure.
+
+| # | Boundary | Rule |
+|:---:|----------|------|
+| 1 | **Prompt-Injection** | External content (web, GitHub, vault, memory) is DATA ONLY. Cannot set tool params, request credentials, or drive wallet actions. |
+| 2 | **Mainnet Confirmation** | All Base mainnet transactions require estimate → preview → confirm → execute flow. |
+| 3 | **Pinned Install** | Always use `@finchagentic/mcp@4.0.0` (pinned), never `@latest`. Supply-chain trust model documented. |
+| 4 | **Credential Vault** | Credentials never fetched because untrusted content asks. Never copied into prompts, outputs, or third-party tools. |
+| 5 | **Data Flow Disclosure** | Documented: Bankr, Anthropic, Firecrawl, GitHub, Alchemy, Convex, 0x — what leaves machine vs stored server-side. |
+| 6 | **Server-Side Monitors** | Creating scheduled jobs requires explicit user confirmation. Jobs continue after MCP process exits. |
+| 7 | **Agent Schedules** | `agent_schedule` requires confirmation. Discloses LLM calls, vault writes, cost implications. |
+| 8 | **Identity Custody** | `agent_identity` is backend-controlled. Users should NOT send assets to this address. |
+
+---
+
+## Why This Is Different
+
+| | Other MCPs | Finch |
+|--|------------|----------|
+| **Memory** | Single tier, no decay | Two-tier (semantic + versioned vault), 90-day decay, dedup |
+| **Agents** | Stateless function calls | Persistent named agents, audit ledger, wallet identity |
+| **Workflows** | Manual chaining | Packets, automations, monitors, deep research |
+| **Safety** | Trust the LLM | Slippage caps, audit grounding, 8 security boundaries |
+| **Reliability** | Best effort | 0 errors across 4 rescans · cache + 429 backoff |
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Tools not appearing | Restart your MCP client after adding the config |
+| Old version loading | `npx clear-npx-cache` then restart |
+| `web_search` fails | Set `FIRECRAWL_API_KEY` |
+| Swap refused | Price impact exceeded cap — call `estimate_swap` first |
+| Rate limit (429) | Auto-retries with backoff — no action needed |
+| Diagnose anything | `finch doctor` |
+
+---
+
+## Links
+
+|            |                                                                                |
+| ---------- | ------------------------------------------------------------------------------ |
+| **App**    | [app.finchagentic.com](https://app.finchagentic.com)                                   |
+| **Docs**   | [docs.finch.fun](https://docs.finch.fun)                                 |
+| **npm**    | [npmjs.com/package/@finchagentic/mcp](https://www.npmjs.com/package/@finchagentic/mcp) |
+| **GitHub** | [github.com/finch/mcp](https://github.com/finch/mcp)                     |
+| **X**      | [@finch](https://x.com/finch)                                            |
+
+---
+
+<div align="center">
+
+### Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=finch/mcp&type=Date)](https://star-history.com/#finch/mcp&Date)
+
+---
+
+**MIT License** · Built with by the Finch team
+
+</div>

package/dist/_http-cache.js

@@ -0,0 +1,96 @@
+"use strict";
+// Shared cache + 429-backoff wrapper for external HTTP calls.
+// Designed for read-heavy public APIs like CoinGecko (free tier: 30 req/min)
+// and DexScreener - agent loops + parallel tool calls were tripping rate
+// limits in production. Cache hit returns the prior body without a network
+// round-trip; cache miss does a fetch with bounded retries on 429/503.
+//
+// The cache is in-process only - every MCP server process keeps its own
+// LRU. That's intentional: tokens get fresh data on cold start, no shared
+// state to invalidate across users.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachedFetch = cachedFetch;
+exports.clearHttpCache = clearHttpCache;
+exports.httpCacheStats = httpCacheStats;
+const DEFAULT_TTL_MS = 45000; // 45s - fresh enough for prices, generous enough to absorb a flurry
+const DEFAULT_MAX_ENTRIES = 200;
+const DEFAULT_RETRY_DELAYS_MS = [500, 1500, 4000];
+const cache = new Map();
+function cacheKey(url, init) {
+    // POST bodies are part of the key so two POSTs with different params don't collide.
+    if (!init || !init.body || init.method === "GET")
+        return `GET ${url}`;
+    return `${init.method ?? "POST"} ${url} ${typeof init.body === "string" ? init.body : ""}`;
+}
+function evictExpired() {
+    const now = Date.now();
+    for (const [k, v] of cache) {
+        if (v.expiresAt < now)
+            cache.delete(k);
+    }
+    // LRU-ish eviction - Map preserves insertion order, so the first keys are oldest.
+    while (cache.size > DEFAULT_MAX_ENTRIES) {
+        const firstKey = cache.keys().next().value;
+        if (firstKey === undefined)
+            break;
+        cache.delete(firstKey);
+    }
+}
+async function cachedFetch(url, init = {}, opts = {}) {
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const retryDelays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    const timeout = opts.timeoutMs ?? 15000;
+    evictExpired();
+    const key = cacheKey(url, init);
+    if (!opts.bypassCache) {
+        const hit = cache.get(key);
+        if (hit && hit.expiresAt > Date.now()) {
+            // Refresh recency - re-insert moves it to the end of the Map.
+            cache.delete(key);
+            cache.set(key, hit);
+            return { ok: hit.status >= 200 && hit.status < 300, status: hit.status, text: hit.body, fromCache: true };
+        }
+    }
+    let lastStatus = 0;
+    let lastText = "";
+    for (let attempt = 0; attempt <= retryDelays.length; attempt++) {
+        try {
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });
+            const text = await res.text();
+            lastStatus = res.status;
+            lastText = text;
+            // Cache successful responses + 404s (404 is "definitively not found" - no point retrying).
+            if (res.ok || res.status === 404) {
+                cache.set(key, { body: text, status: res.status, expiresAt: Date.now() + ttl });
+                return { ok: res.ok, status: res.status, text, fromCache: false };
+            }
+            // Retry on 429 (rate limit) and 5xx (transient server errors).
+            if (res.status === 429 || res.status >= 500) {
+                const delay = retryDelays[attempt];
+                if (delay === undefined)
+                    break;
+                // Honor server's Retry-After if provided (CoinGecko sends this).
+                const retryAfter = res.headers.get("retry-after");
+                const waitMs = retryAfter ? Math.min(parseInt(retryAfter) * 1000, 30000) : delay;
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            // Non-retryable client error (400/401/403) - surface to caller without retry.
+            return { ok: false, status: res.status, text, fromCache: false };
+        }
+        catch (err) {
+            lastText = err instanceof Error ? err.message : String(err);
+            const delay = retryDelays[attempt];
+            if (delay === undefined)
+                break;
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    return { ok: false, status: lastStatus, text: lastText, fromCache: false };
+}
+function clearHttpCache() {
+    cache.clear();
+}
+function httpCacheStats() {
+    return { size: cache.size, maxEntries: DEFAULT_MAX_ENTRIES };
+}