@finchagentic/mcp 4.6.2 → 4.6.3

package/dist/tools/research.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESEARCH_TOOLS = void 0;
+exports.handleResearchTool = handleResearchTool;
+const zod_1 = require("zod");
+const convex_js_1 = require("../convex.js");
+const public_url_js_1 = require("../public-url.js");
+const FC_BASE = "https://api.firecrawl.dev/v1";
+exports.RESEARCH_TOOLS = [
+    {
+        name: "web_scrape",
+        description: "Fetch and extract clean readable content from any URL - returns markdown. " +
+            "Use when an agent needs to read an article, docs page, GitHub repo, or any web page. " +
+            "Set FIRECRAWL_API_KEY for best quality (firecrawl.dev). Falls back to basic fetch if not set.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch" },
+                focus: { type: "string", description: "Optional: specific topic or section to extract from the page" },
+            },
+            required: ["url"],
+        },
+    },
+    {
+        name: "web_search",
+        description: "Search the web and return raw results: titles, URLs, and snippets. No synthesis or analysis — " +
+            "use this for quick lookups, finding sources, or fetching recent news. " +
+            "For multi-source research with LLM synthesis, use deep_research instead. " +
+            "Requires FIRECRAWL_API_KEY (firecrawl.dev).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                limit: { type: "number", description: "Max results (default 5, max 10)" },
+            },
+            required: ["query"],
+        },
+    },
+];
+const ScrapeSchema = zod_1.z.object({
+    url: zod_1.z.string().url(),
+    focus: zod_1.z.string().optional(),
+});
+const SearchSchema = zod_1.z.object({
+    query: zod_1.z.string().min(1),
+    limit: zod_1.z.number().int().min(1).max(10).optional(),
+});
+async function firecrawlScrape(url) {
+    // Priority 1: user's own FIRECRAWL_API_KEY (BYOK fast-path, zero network detour).
+    const key = process.env.FIRECRAWL_API_KEY;
+    if (key) {
+        try {
+            const res = await fetch(`${FC_BASE}/scrape`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "Authorization": `Bearer ${key}` },
+                body: JSON.stringify({ url, formats: ["markdown"], onlyMainContent: true }),
+                signal: AbortSignal.timeout(20000),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                return data.data?.markdown ?? null;
+            }
+        }
+        catch { /* fall through to backend proxy */ }
+    }
+    // Priority 2: route through Finch backend (session-token authed, backend
+    // pays for the Firecrawl call). The backend returns 503 if it doesn't have
+    // FIRECRAWL_API_KEY set either, in which case web_scrape silently falls
+    // through to basicFetch below.
+    try {
+        const data = await (0, convex_js_1.callConvex)("/research/firecrawl-scrape", "POST", { url }, "web_scrape", 25000);
+        if (data?.markdown)
+            return data.markdown;
+    }
+    catch { /* fall through */ }
+    return null;
+}
+async function basicFetch(url) {
+    try {
+        const res = await fetch(url, {
+            headers: { "User-Agent": "Mozilla/5.0 (compatible; FinchBot/1.0)" },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!res.ok)
+            return null;
+        const html = await res.text();
+        return html
+            .replace(/<script[\s\S]*?<\/script>/gi, "")
+            .replace(/<style[\s\S]*?<\/style>/gi, "")
+            .replace(/<[^>]+>/g, " ")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 4000);
+    }
+    catch {
+        return null;
+    }
+}
+async function handleResearchTool(name, args) {
+    if (name === "web_scrape") {
+        const parsed = ScrapeSchema.safeParse(args);
+        if (!parsed.success)
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+        const { url, focus } = parsed.data;
+        const unsafe = await (0, public_url_js_1.assertPublicUrl)(url);
+        if (unsafe) {
+            return { content: [{ type: "text", text: (0, public_url_js_1.refuseUrlText)(url, unsafe) }], isError: true };
+        }
+        let content = await firecrawlScrape(url);
+        const source = content ? "Firecrawl" : "basic fetch";
+        if (!content)
+            content = await basicFetch(url);
+        if (!content) {
+            return { content: [{ type: "text", text: `Could not fetch ${url} - page may require JavaScript or block crawlers.` }], isError: true };
+        }
+        const focusNote = focus ? `\n\n_Focus: ${focus}_\n\n` : "\n\n";
+        const body = content.length > 6000 ? content.slice(0, 6000) + "\n\n…(truncated)" : content;
+        return { content: [{ type: "text", text: `**${url}**${focusNote}${body}\n\n_Source: ${source}_` }] };
+    }
+    if (name === "web_search") {
+        const parsed = SearchSchema.safeParse(args);
+        if (!parsed.success)
+            return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+        const { query, limit = 5 } = parsed.data;
+        // Priority 1: user BYOK direct path. Priority 2: Finch proxy.
+        // Same data shape so the formatting code below is identical for both.
+        const key = process.env.FIRECRAWL_API_KEY;
+        let results = null;
+        let lastErr = null;
+        if (key) {
+            try {
+                const res = await fetch(`${FC_BASE}/search`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${key}` },
+                    body: JSON.stringify({ query, limit }),
+                    signal: AbortSignal.timeout(15000),
+                });
+                if (res.ok) {
+                    const data = await res.json();
+                    results = data.data ?? [];
+                }
+                else {
+                    lastErr = `${res.status}: ${(await res.text()).slice(0, 200)}`;
+                }
+            }
+            catch (err) {
+                lastErr = err?.message ?? "BYOK search failed";
+            }
+        }
+        if (!results) {
+            try {
+                const data = await (0, convex_js_1.callConvex)("/research/firecrawl-search", "POST", { query, limit }, "web_search", 30000);
+                results = data?.results ?? [];
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `web_search failed.`,
+                                ``,
+                                `Tried backend proxy: ${msg.slice(0, 200)}`,
+                                lastErr ? `Direct call also failed: ${lastErr}` : "",
+                                ``,
+                                `Fix: either run \`/login\` so the Finch backend can pay, or set FIRECRAWL_API_KEY in your MCP env block.`,
+                            ].filter(Boolean).join("\n"),
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        const safeResults = results ?? [];
+        if (!safeResults.length) {
+            return { content: [{ type: "text", text: `No results found for: "${query}"` }] };
+        }
+        const lines = [`🔍 **Web Search: "${query}"** - ${safeResults.length} results\n`];
+        for (const r of safeResults) {
+            lines.push(`**${r.title ?? r.url}**`);
+            lines.push(r.url);
+            if (r.description)
+                lines.push(r.description.slice(0, 200));
+            lines.push("");
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    return null;
+}

package/dist/tools/rh-bridge.js

@@ -0,0 +1,148 @@
+"use strict";
+// Tokenized stock ↔ real equity comparison on Robinhood Chain.
+//
+// Robinhood Chain exists to trade equities 24/7 on-chain, but the two prices
+// drift: the token trades continuously against a shallow pool while the real
+// share only prices during market hours. That gap is the whole point of the
+// bridge — and it matters to both sides. An equity trader wants to know whether
+// after-hours exposure is fairly priced; an on-chain trader wants to know when
+// the token has detached from the asset it represents.
+//
+// The gap alone is not an opportunity: a 20% premium on a $100k pool you cannot
+// exit is a trap, so pool depth is reported next to every quote.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRIDGE_TOOLS = void 0;
+exports.handleBridgeTool = handleBridgeTool;
+const zod_1 = require("zod");
+const rh_mcp_js_1 = require("./rh-mcp.js");
+exports.BRIDGE_TOOLS = [
+    {
+        name: "rh_stock_bridge",
+        description: "Compare a tokenized stock on Robinhood Chain (4663) against the real US equity: " +
+            "on-chain price vs live share price, the premium/discount between them, pool depth, " +
+            "and whether the US market is currently open. Covers the 22 tokenized tickers " +
+            "(NVDA, TSLA, AAPL, COIN…). Omit `ticker` to scan all of them at once. " +
+            "No API key needed. Reports the gap and the depth — it does not tell you to trade it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ticker: {
+                    type: "string",
+                    description: "Tokenized stock symbol, e.g. 'NVDA'. Omit to scan every tokenized stock.",
+                },
+                minGapPct: {
+                    type: "number",
+                    description: "When scanning, only show names whose gap exceeds this (default 0 = show all)",
+                },
+            },
+            required: [],
+        },
+    },
+];
+const Schema = zod_1.z.object({
+    ticker: zod_1.z.string().min(1).max(10).optional(),
+    minGapPct: zod_1.z.number().min(0).max(100).optional(),
+});
+async function realQuote(symbol) {
+    try {
+        const res = await fetch(`https://query1.finance.yahoo.com/v8/finance/chart/${encodeURIComponent(symbol)}?interval=1d&range=1d`, { headers: { "User-Agent": "Mozilla/5.0" }, signal: AbortSignal.timeout(12000) });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        const m = j?.chart?.result?.[0]?.meta;
+        if (!m?.regularMarketPrice)
+            return null;
+        // The chart endpoint carries no `marketState`, so derive it: during the
+        // regular session `regularMarketTime` keeps advancing, and once the bell
+        // rings it freezes at the close. A recent timestamp means live pricing.
+        const ts = Number(m.regularMarketTime) * 1000;
+        const ageMin = isFinite(ts) ? (Date.now() - ts) / 60000 : Infinity;
+        return { price: m.regularMarketPrice, state: ageMin <= 20 ? "REGULAR" : "CLOSED" };
+    }
+    catch {
+        return null;
+    }
+}
+async function buildRow(s) {
+    const [dex, rq] = await Promise.all([(0, rh_mcp_js_1.dexTokenBest)(s.address), realQuote(s.symbol)]);
+    const onchain = dex?.priceUsd != null ? Number(dex.priceUsd) : null;
+    const real = rq?.price ?? null;
+    const gapPct = onchain != null && real != null && real > 0 ? ((onchain - real) / real) * 100 : null;
+    return {
+        symbol: s.symbol,
+        name: s.name,
+        address: s.address,
+        onchain: onchain != null && isFinite(onchain) ? onchain : null,
+        real,
+        gapPct,
+        liquidityUsd: dex?.liquidity?.usd ?? 0,
+        marketState: rq?.state,
+    };
+}
+function gapTag(gap, liq) {
+    const a = Math.abs(gap);
+    if (a < 1)
+        return "🟢 tracking";
+    if (a < 3)
+        return "🟡 minor drift";
+    if (liq < 50000)
+        return "🟠 wide — but the pool is thin";
+    return "🔴 wide";
+}
+async function handleBridgeTool(name, args) {
+    if (name !== "rh_stock_bridge")
+        return null;
+    const parsed = Schema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
+    }
+    const wanted = parsed.data.ticker?.trim().toUpperCase();
+    const minGap = parsed.data.minGapPct ?? 0;
+    const targets = wanted ? rh_mcp_js_1.RH_STOCKS.filter((s) => s.symbol === wanted) : rh_mcp_js_1.RH_STOCKS;
+    if (wanted && targets.length === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `**${wanted}** is not a tokenized stock on Robinhood Chain.\n\n` +
+                        `Available: ${rh_mcp_js_1.RH_STOCKS.map((s) => s.symbol).join(", ")}`,
+                }],
+            isError: true,
+        };
+    }
+    const rows = await Promise.all(targets.map(buildRow));
+    const usable = rows.filter((r) => r.gapPct != null);
+    const marketState = usable.find((r) => r.marketState)?.marketState ?? "UNKNOWN";
+    const marketOpen = marketState === "REGULAR";
+    const lines = [
+        `# Tokenized stock ↔ real equity — Robinhood Chain (4663)`,
+        ``,
+        `**US market: ${marketOpen ? "🟢 OPEN" : "🔴 CLOSED"}**` +
+            (marketOpen
+                ? ` — both sides are pricing live, so a gap is a genuine dislocation.`
+                : ` — the share price is frozen at the last close while the token keeps trading. ` +
+                    `A gap here is largely expected and is NOT by itself a mispricing.`),
+        ``,
+    ];
+    // Single-ticker detail view.
+    if (wanted && usable.length === 1) {
+        const r = usable[0];
+        lines.push(`## ${r.symbol} — ${r.name}`, ``, `| | |`, `|---|---|`, `| On-chain (token) | **$${r.onchain.toFixed(4)}** |`, `| Real share | **$${r.real.toFixed(2)}** |`, `| Gap | **${r.gapPct >= 0 ? "+" : ""}${r.gapPct.toFixed(2)}%** ${gapTag(r.gapPct, r.liquidityUsd)} |`, `| Pool depth | $${Math.round(r.liquidityUsd).toLocaleString()} |`, `| Token | \`${r.address}\` |`, ``, `${rh_mcp_js_1.RH_EXPLORER}/token/${r.address}`, ``);
+    }
+    else {
+        const shown = usable
+            .filter((r) => Math.abs(r.gapPct) >= minGap)
+            .sort((a, b) => Math.abs(b.gapPct) - Math.abs(a.gapPct));
+        lines.push(`| Ticker | On-chain | Real | Gap | Pool depth |`, `|---|---|---|---|---|`, ...shown.map((r) => `| **${r.symbol}** | $${r.onchain.toFixed(2)} | $${r.real.toFixed(2)} | ` +
+            `${r.gapPct >= 0 ? "+" : ""}${r.gapPct.toFixed(2)}% ${gapTag(r.gapPct, r.liquidityUsd)} | ` +
+            `$${Math.round(r.liquidityUsd).toLocaleString()} |`), ``);
+        const missing = rows.filter((r) => r.gapPct == null);
+        if (missing.length) {
+            lines.push(`_No usable quote for: ${missing.map((m) => m.symbol).join(", ")}._`, ``);
+        }
+    }
+    lines.push(`---`, ``, `**Reading this**`, ``, `- A gap is only tradeable to the depth of the pool. A 20% premium on a $100k pool is not ` +
+        `a 20% opportunity — size it against the depth column, then check the real fill with \`rh_mcp_estimate\`.`, `- While the US market is closed the token is the only live price. Drift is expected, and it ` +
+        `often reflects overnight news the share price has not opened to yet.`, `- Buying the token is exposure to the token, not ownership of the share. Redemption terms, ` +
+        `custody and counterparty are Robinhood's, not this tool's — and are not verified here.`, ``, `_Prices: on-chain via DexScreener, share via Yahoo Finance. Not investment advice._`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}