@houndmcp/hound-mcp-pi 10.3.0

package/README.md

@@ -0,0 +1,35 @@
+# hound-mcp-pi
+
+Hound web research for the Pi agent. Six native tools, all routed through a single long-lived Hound MCP subprocess:
+
+- **web_fetch** - anti-bot fetch + clean extraction + Internet Archive dead-link recovery
+- **web_search** - keyless web search across 10 backends, neural-reranked
+- **web_crawl** - deep site crawl, sitemap one-fetch map
+- **web_screenshot** - anti-bot screenshot for multimodal agents
+- **cache_clear** - clear fetch cache
+- **hound_version** - version + update status
+
+## Install
+
+```bash
+# 1. Install Hound (the MCP server / engine)
+pip install hound-mcp[all]
+
+# 2. Install this Pi extension
+pi install git:github.com/dondai1234/master-fetch@v10.3.0
+```
+
+That's it. The extension auto-discovers `hound` on your PATH, spawns it as a singleton subprocess, and prewarms it at session start. No API key, no account, no config file.
+
+## How it works
+
+The extension spawns `hound` (the MCP server) as a stdio subprocess and speaks MCP JSON-RPC to it. The subprocess is a singleton — it stays alive for the whole Pi session, so Hound's startup prewarm (stealthy browser, search engines, neural reranker) runs once and persists. Zero re-launch cost per call.
+
+## Requirements
+
+- [Pi coding agent](https://github.com/earendil-works/pi-coding-agent)
+- Python 3.11+ with `hound-mcp[all]` installed (`pip install hound-mcp[all]`)
+
+## License
+
+MIT. Same as Hound itself.

package/extensions/hound.ts

@@ -0,0 +1,569 @@
+/**
+ * Hound MCP extension for Pi agent.
+ *
+ * Six native tools, all routed through a single long-lived Hound MCP stdio
+ * subprocess (singleton - Hound's startup prewarm persists for the whole
+ * session, zero re-launch cost per call):
+ *   - web_fetch      -> mcp_smart_fetch   (auto anti-bot, PDF, archive fallback)
+ *   - web_search     -> mcp_smart_search  (10 keyless backends, consensus rank)
+ *   - web_crawl      -> mcp_smart_crawl   (best-first + sitemap-one-fetch map)
+ *   - web_screenshot -> mcp_screenshot    (image capture for multimodal agents)
+ *   - cache_clear    -> cache_clear        (clear fetch cache)
+ *   - hound_version  -> version            (hound version + update status)
+ *
+ * Hound is fully keyless ($0, no API key, no account). The subprocess is
+ * resolved from PATH so it tracks the installed Hound version automatically.
+ *
+ * Install: pip install hound-mcp[all]
+ * Then:    pi install git:github.com/dondai1234/master-fetch@v10.3.0
+ */
+
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as fs from "node:fs";
+
+// -- Hound executable resolution --
+
+function resolveHoundExe(): string | null {
+  try {
+    const cmd = process.platform === "win32" ? "where hound.exe" : "which hound";
+    const out = execSync(cmd, {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+      windowsHide: true,
+    }).toString().trim();
+    const first = out.split(/\r?\n/)[0];
+    if (first && fs.existsSync(first)) return first;
+  } catch {}
+  const fallback = path.join(
+    os.homedir(),
+    "AppData", "Local", "Programs", "Python", "Python311", "Scripts", "hound.exe",
+  );
+  return fs.existsSync(fallback) ? fallback : null;
+}
+
+const HOUND_EXE = resolveHoundExe();
+const INIT_TIMEOUT_MS = 15_000;
+const CALL_TIMEOUT_MS = 90_000;
+const CRAWL_TIMEOUT_MS = 150_000;
+const INIT_ATTEMPTS = 3;
+const INIT_BACKOFF_MS = 400;
+
+// -- MCP Stdio Client (singleton subprocess + JSON-RPC) --
+//
+// Hound is spawned once per Pi session and kept alive. Its startup prewarm
+// (stealthy browser + search-engine sessions + neural reranker ONNX load)
+// runs in the background during session_start, so by the time the agent
+// makes its first web_fetch/search call, Hound is already warm. A dead
+// subprocess (crash, OS kill) triggers a transparent re-init on the next
+// call - callers never see a raw spawn error, just a slightly slower call.
+//
+// The MCP initialize handshake has a hard timeout. Hound occasionally spawns
+// dead: its synchronous import playwright (via _get_scrapling) runs on the
+// single-threaded asyncio loop and freezes it so server.run can never write
+// the reply. The process is alive but mute - no stderr, no exit - so a longer
+// timeout cannot help. A fresh re-spawn reliably responds in ~2-3s, so we
+// kill the dead one and retry up to INIT_ATTEMPTS times.
+
+interface Pending {
+  resolve: (v: any) => void;
+  reject: (e: Error) => void;
+  timer: NodeJS.Timeout;
+}
+
+class HoundClient {
+  private proc: ChildProcess | null = null;
+  private ready: Promise<boolean> | null = null;
+  private initInFlight: Promise<boolean> | null = null;
+  private nextId = 0;
+  private pending = new Map<number, Pending>();
+  private stdoutBuf = "";
+  private lastStderr = "";
+
+  async ensureReady(): Promise<boolean> {
+    if (this.ready) return this.ready;
+    if (!HOUND_EXE) return false;
+    if (this.initInFlight) return this.initInFlight;
+    const p = this._initWithRetry();
+    this.initInFlight = p;
+    p.then((ok) => {
+      this.initInFlight = null;
+      if (ok) this.ready = p;
+      else this.ready = null;
+    });
+    return p;
+  }
+
+  private async _initWithRetry(): Promise<boolean> {
+    for (let attempt = 1; attempt <= INIT_ATTEMPTS; attempt++) {
+      if (await this._initOnce()) return true;
+      if (attempt < INIT_ATTEMPTS) await new Promise((r) => setTimeout(r, INIT_BACKOFF_MS));
+    }
+    return false;
+  }
+
+  private _initOnce(): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      let settled = false;
+      let initTimer: NodeJS.Timeout | undefined;
+      let stderrBuf = "";
+      const done = (ok: boolean) => {
+        if (settled) return;
+        settled = true;
+        if (initTimer) clearTimeout(initTimer);
+        if (!ok) this.kill();
+        resolve(ok);
+      };
+      try {
+        this.proc = spawn(HOUND_EXE!, [], {
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true,
+          env: { ...process.env },
+        });
+      } catch (e: any) {
+        this.lastStderr = `spawn threw: ${e?.message ?? e}`;
+        done(false);
+        return;
+      }
+      this.proc.on("error", (e: any) => {
+        this.lastStderr = `spawn error: ${e?.message ?? e}`;
+        done(false);
+      });
+      this.proc.on("close", (code, signal) => {
+        for (const [, { reject, timer }] of this.pending) {
+          clearTimeout(timer);
+          reject(new Error("Hound closed"));
+        }
+        this.pending.clear();
+        if (!settled) this.lastStderr = `exited before init (code=${code} signal=${signal})`;
+        this.ready = null;
+        done(false);
+      });
+      this.proc.stderr?.on("data", (chunk: Buffer) => {
+        stderrBuf += chunk.toString("utf-8");
+        if (stderrBuf.length > 4000) stderrBuf = stderrBuf.slice(-4000);
+      });
+      this.proc.stdout?.on("data", (chunk: Buffer) => {
+        this.stdoutBuf += chunk.toString("utf-8");
+        this._drain();
+      });
+      initTimer = setTimeout(() => {
+        this.lastStderr = `initialize timed out after ${INIT_TIMEOUT_MS}ms (dead spawn)`;
+        done(false);
+      }, INIT_TIMEOUT_MS);
+      const id = ++this.nextId;
+      this.pending.set(id, {
+        resolve: () => {
+          this._notify("notifications/initialized", {});
+          this.lastStderr = "";
+          done(true);
+        },
+        reject: (e: Error) => {
+          this.lastStderr = `initialize rejected: ${e.message}`;
+          done(false);
+        },
+        timer: initTimer,
+      });
+      try {
+        this.proc.stdin!.write(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            method: "initialize",
+            params: {
+              protocolVersion: "2025-03-26",
+              capabilities: {},
+              clientInfo: { name: "pi-hound", version: "10.3.0" },
+            },
+            id,
+          }) + "\n",
+        );
+      } catch (e: any) {
+        this.pending.delete(id);
+        this.lastStderr = `stdin write failed: ${e?.message ?? e}`;
+        done(false);
+      }
+    });
+  }
+
+  private _drain() {
+    let idx: number;
+    while ((idx = this.stdoutBuf.indexOf("\n")) !== -1) {
+      const line = this.stdoutBuf.slice(0, idx).trim();
+      this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id != null && this.pending.has(msg.id)) {
+          const { resolve, reject, timer } = this.pending.get(msg.id)!;
+          this.pending.delete(msg.id);
+          clearTimeout(timer);
+          if (msg.error) reject(new Error(msg.error?.message ?? JSON.stringify(msg.error)));
+          else resolve(msg.result);
+        }
+      } catch {}
+    }
+  }
+
+  private _notify(method: string, params: any) {
+    if (!this.proc || this.proc.killed) return;
+    try {
+      this.proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    } catch {}
+  }
+
+  async call(name: string, args: Record<string, any>, timeoutMs = CALL_TIMEOUT_MS): Promise<any> {
+    const ready = await this.ensureReady();
+    if (!ready) {
+      const hint = HOUND_EXE
+        ? `Hound failed to start after ${INIT_ATTEMPTS} attempts. ${this.lastStderr || "Silent dead hang."} Run: hound --doctor`
+        : "Hound not found. Install: pip install hound-mcp[all]";
+      throw new Error(hint);
+    }
+    return new Promise((resolve, reject) => {
+      if (!this.proc || this.proc.killed) {
+        reject(new Error("Hound not running"));
+        return;
+      }
+      const id = ++this.nextId;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Hound timeout: ${name}`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.proc.stdin!.write(
+          JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name, arguments: args }, id }) + "\n",
+        );
+      } catch (e) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(e as Error);
+      }
+    });
+  }
+
+  kill() {
+    if (this.proc && !this.proc.killed) {
+      try { this.proc.stdin?.end(); } catch {}
+      try { this.proc.kill(); } catch {}
+    }
+    this.proc = null;
+    this.ready = null;
+    this.initInFlight = null;
+    for (const [, { timer }] of this.pending) clearTimeout(timer);
+    this.pending.clear();
+  }
+}
+
+const hound = new HoundClient();
+
+// -- Helpers --
+
+function getText(result: any): string {
+  const content = result?.content ?? [];
+  return content.filter((c: any) => c?.type === "text").map((c: any) => c.text).join("\n") || "(no output)";
+}
+
+function getImages(result: any): any[] {
+  const content = result?.content ?? [];
+  return content.filter((c: any) => c?.type === "image");
+}
+
+function tryJson(text: string): any {
+  try { return JSON.parse(text); } catch { return {}; }
+}
+
+function pick(params: Record<string, any>, keys: string[]): Record<string, any> {
+  const out: Record<string, any> = {};
+  for (const k of keys) {
+    if (params[k] !== undefined) out[k] = params[k];
+  }
+  return out;
+}
+
+// -- Extension --
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", () => { hound.ensureReady().catch(() => {}); });
+  pi.on("session_shutdown", () => { hound.kill(); });
+
+  // -- web_fetch --
+  pi.registerTool({
+    name: "web_fetch",
+    label: "Web Fetch",
+    description: "Fetch a URL (or urls=[...] for parallel bulk). Auto HTTP -> stealthy escalation. Returns extracted text + metadata + signals: content_ok, next_action, summary, page_type, content_age_days/is_stale, source_type/is_official, source/archived_at. Hard-block (404/bot/auth) -> auto-recover from Internet Archive (source=archive.org, archived_at=snapshot date; archive_fallback=false in options to opt out). PDFs -> structured markdown + ToC + page ranges + auto-OCR. Long pages: paginate with offset/next_offset or focus='query' for only relevant blocks. actions=[...] for click/form/scroll. include_links/include_media via options.",
+    promptSnippet: "web_fetch(url|urls, extraction_type, css_selector, focus, actions, include_links, pages, offset) - anti-bot fetch + clean extraction; paginates with next_offset; dead-link recovery from Internet Archive.",
+    parameters: Type.Object({
+      url: Type.Optional(Type.String({ description: "URL to fetch" })),
+      urls: Type.Optional(Type.Array(Type.String(), { description: "Multiple URLs (parallel; returns per-URL results)" })),
+      extraction_type: Type.Optional(Type.String({ description: "Content format (default markdown). html = raw HTML." })),
+      css_selector: Type.Optional(Type.String({ description: "CSS selector to narrow extracted content (e.g. 'article', '.main'). Token saver." })),
+      max_content_chars: Type.Optional(Type.Integer({ description: "Max chars of extracted content (default 40000, min 500). Lower = less context; rest paginated via offset/next_offset." })),
+      timeout: Type.Optional(Type.Integer({ description: "Max request time in ms (default 30000)." })),
+      cache_ttl: Type.Optional(Type.Integer({ description: "Cache seconds (default 3600). 0 = force fresh." })),
+      force_fetcher: Type.Optional(Type.String({ description: "Pin to one tier, skip auto-escalation. 'http' = fast HTTP-only (fails on JS/bot walls). 'stealthy' = anti-detect browser. Default = auto." })),
+      offset: Type.Optional(Type.Integer({ description: "Char offset into extracted text to resume a truncated page. Use next_offset from previous response." })),
+      pages: Type.Optional(Type.String({ description: "PDF only: page spec like '1-5' or '1,3,5-7'. Use table_of_contents page/end_page ranges to pick. None = all pages." })),
+      password: Type.Optional(Type.String({ description: "PDF only: password for an encrypted PDF." })),
+      focus: Type.Optional(Type.String({ description: "Query-focused extraction: only BM25-relevant blocks returned. Context saver on long pages. Post-cache (no re-fetch). Re-pass same focus when paginating." })),
+      actions: Type.Optional(Type.Array(Type.Object({}, { additionalProperties: true }), { description: "Page interactions on stealthy browser AFTER load, BEFORE extraction. Forces stealthy + bypasses cache. Each item: {click:'css'}, {fill:{selector:'css',text:'x'}}, {press:'Enter'}, {wait:500}, {scroll:3}, {wait_selector:'css'}." })),
+      options: Type.Optional(Type.Object({}, { additionalProperties: true, description: "include_links (bool,false: response.links=citations/navigation/external+primary_source), include_media (bool,false: up to 20 page image URLs), archive_fallback (bool,true: recover from Internet Archive on hard-block; false=raw failure), proxy, cookies, extra_headers, useragent, wait, network_idle, headless, respect_robots, real_chrome/solve_cloudflare/block_webrtc/hide_canvas/main_content_only/use_trafilatura (anti-detect tuning, good defaults, rarely needed)." })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      try {
+        const args = pick(params, ["url", "urls", "extraction_type", "css_selector", "max_content_chars", "timeout", "cache_ttl", "force_fetcher", "offset", "pages", "password", "focus", "actions", "options"]);
+        const result = await hound.call("mcp_smart_fetch", args, CALL_TIMEOUT_MS);
+        const text = getText(result);
+        const parsed = tryJson(text);
+        if (Array.isArray(parsed.results)) {
+          const ok = parsed.successful ?? 0;
+          const total = parsed.total ?? parsed.results.length;
+          const joined = parsed.results.map((r: any) => `# ${r.url}\n${(r.content ?? []).join("\n")}`).join("\n\n---\n\n");
+          return { content: [{ type: "text", text: joined + `\n\n[${ok}/${total} OK]` }], details: { bulk: true, ok, total } };
+        }
+        const content = Array.isArray(parsed.content) ? parsed.content.join("\n") : text;
+        const foot: string[] = [];
+        if (parsed.summary) foot.push(parsed.summary);
+        if (parsed.next_action) foot.push(`Next: ${parsed.next_action}`);
+        if (parsed.content_ok === false) foot.push("WARNING: content_ok=false - content may be a JS shell/login wall/error page");
+        const trunc = parsed.is_truncated ? ` | next_offset=${parsed.next_offset}` : "";
+        const fetcher = parsed.fetcher_used ?? "";
+        const src = parsed.source === "archive.org" ? ` | ARCHIVE ${parsed.archived_at ?? ""}` : "";
+        return {
+          content: [{ type: "text", text: content + (foot.length ? `\n\n${foot.join("\n")}` : "") + `\n[${fetcher}${trunc}${src}]` }],
+          details: { url: args.url, chars: content.length, content_ok: parsed.content_ok, truncated: !!parsed.is_truncated, source: parsed.source ?? "live" },
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `web_fetch error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(args, theme) {
+      const urlStr = (args.url ?? args.urls?.[0] ?? "").toString();
+      const trunc = urlStr.length > 60 ? urlStr.slice(0, 57) + "..." : urlStr;
+      return new Text(theme.fg("toolTitle", theme.bold("Web Fetch: ")) + theme.fg("accent", trunc), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("dim", "fetching..."), 0, 0);
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      if (d?.bulk) return new Text(theme.fg("accent", `${d.ok}/${d.total} URLs`), 0, 0);
+      const kb = ((d?.chars ?? 0) / 1024).toFixed(1);
+      const src = d?.source === "archive.org" ? " (archive)" : "";
+      const warn = d?.content_ok === false ? " !" : "";
+      return new Text(theme.fg("accent", `${kb}KB${src}${warn}`), 0, 0);
+    },
+  });
+
+  // -- web_search --
+  pi.registerTool({
+    name: "web_search",
+    label: "Web Search",
+    description: "Keyless web search (no API key). 10 backends in parallel (ddg,brave,mojeek,yahoo,yandex,startpage,google,qwant + opt-in wikipedia,grokipedia), neural-reranked + cross-backend consensus. Returns URLs + ranking, NOT content -> web_fetch the ones that match. Each result: relevance_score + fetch_relevance (high/med/low) + engines_consensus. related_queries from result titles+snippets. Blocked backends circuit-broken 60s. NEVER answer from snippets alone. Filters in options: site, exclude_sites, location, language, region, page, freshness.",
+    promptSnippet: "web_search(query) - keyless web search across 10 backends; returns ranked URLs (not content), related_queries, consensus. web_fetch the results that match.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+      options: Type.Optional(Type.Object({}, { additionalProperties: true, description: "max_results (1-50,6), cache_ttl (300), mode (auto|neural|find_similar), engines (list), site, exclude_sites, location, language, region, page, freshness, url (for find_similar)" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      try {
+        const args: Record<string, any> = { query: params.query };
+        if (params.options && Object.keys(params.options).length) args.options = params.options;
+        const result = await hound.call("mcp_smart_search", args, 60_000);
+        const text = getText(result);
+        const parsed = tryJson(text);
+        const results: any[] = parsed.results ?? [];
+        const body = results.length === 0
+          ? `No results for "${params.query}".`
+          : results.map((r: any, i: number) => {
+              const cons = r.engines_consensus ? ` [consensus ${r.engines_consensus}]` : "";
+              const tier = r.fetch_relevance ? ` (${r.fetch_relevance})` : "";
+              return `[${i + 1}]${tier} ${r.title || "(untitled)"}${cons}\n  ${r.url || ""}\n  ${r.snippet || ""}`;
+            }).join("\n\n");
+        const foot: string[] = [];
+        if (Array.isArray(parsed.related_queries) && parsed.related_queries.length)
+          foot.push(`Related: ${parsed.related_queries.slice(0, 6).map((q: string) => `"${q}"`).join(", ")}`);
+        if (Array.isArray(parsed.engine_blocked) && parsed.engine_blocked.length)
+          foot.push(`Blocked: ${parsed.engine_blocked.join(", ")}`);
+        if (parsed.next_action) foot.push(`Next: ${parsed.next_action}`);
+        return {
+          content: [{ type: "text", text: body + (foot.length ? `\n\n${foot.join("\n")}` : "") }],
+          details: { query: params.query, count: results.length, related: parsed.related_queries ?? [], blocked: parsed.engine_blocked ?? [] },
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `web_search error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(args, theme) {
+      const q = (args.query ?? "").toString();
+      const trunc = q.length > 50 ? q.slice(0, 47) + "..." : q;
+      return new Text(theme.fg("toolTitle", theme.bold("Web Search: ")) + theme.fg("accent", `"${trunc}"`), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("dim", "searching..."), 0, 0);
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      if (!d?.count) return new Text(theme.fg("dim", "no results"), 0, 0);
+      const rel = d.related?.length ? ` + ${d.related.length} related` : "";
+      return new Text(theme.fg("accent", `${d.count} results${rel}`), 0, 0);
+    },
+  });
+
+  // -- web_crawl --
+  pi.registerTool({
+    name: "web_crawl",
+    label: "Web Crawl",
+    description: "Deep-crawl a site: best-first same-domain walk, each page as markdown + content_ok + page_type. List pages -> structured link list. sitemap=true (in options) maps whole site from sitemap.xml in one fetch; sitemap='auto' = use if present else BFS. discover_only=true = URL map only. focus='query' prioritizes relevant pages + focus-filters each. crawl_urls=[...] fetches a chosen subset. Caps: max_pages (10), max_depth (2), max_total_chars, deadline_ms. Reuses web_fetch anti-bot + cache.",
+    promptSnippet: "web_crawl(url, focus, options.sitemap, discover_only, crawl_urls, max_pages) - site crawl; sitemap=true maps a whole site in one fetch; crawl_urls fetches a chosen subset.",
+    parameters: Type.Object({
+      url: Type.String({ description: "Start URL (crawl stays on this domain)" }),
+      focus: Type.Optional(Type.String({ description: "Query: prioritize crawling links relevant to this + focus-filter each page. Token saver on doc sites." })),
+      discover_only: Type.Optional(Type.Boolean({ description: "true = return URL map only, no page content. For big sites prefer options sitemap=true." })),
+      crawl_urls: Type.Optional(Type.Array(Type.String(), { description: "Chosen subset of URLs to fetch (second-phase selective crawl, no re-discovery). Use after sitemap=true or discover_only=true." })),
+      options: Type.Optional(Type.Object({}, { additionalProperties: true, description: "sitemap (true|'auto'|false,false: true=map from sitemap.xml in one fetch; 'auto'=use if present else BFS), max_pages (1-100,10), max_depth (0-5,2), path_include (list of path prefixes), path_exclude (list to skip), max_content_chars_per (8000), max_total_chars (token budget), concurrency (1-5,3), cache_ttl (3600;0=fresh), respect_robots (false), force_fetcher ('http'|'stealthy'), timeout (ms,30000), deadline_ms (120000)." })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      try {
+        const args = pick(params, ["url", "focus", "discover_only", "crawl_urls", "options"]);
+        const result = await hound.call("mcp_smart_crawl", args, CRAWL_TIMEOUT_MS);
+        const text = getText(result);
+        const parsed = tryJson(text);
+        const pages: any[] = Array.isArray(parsed.pages) ? parsed.pages : [];
+        let body: string;
+        if (parsed.sitemap_used || (args.discover_only && pages.length)) {
+          body = pages.map((p: any, i: number) => `[${i + 1}] ${p.url}${p.lastmod ? ` (${p.lastmod})` : ""}`).join("\n");
+        } else {
+          body = pages.map((p: any) => {
+            const tag = p.page_type ? `[${p.page_type}]` : "";
+            const ok = p.content_ok ? "" : " WARNING";
+            const c = Array.isArray(p.content) ? p.content.join("\n") : "";
+            return `## ${p.url} ${tag}${ok}\n${c}`;
+          }).join("\n\n---\n\n");
+        }
+        const foot: string[] = [];
+        if (parsed.summary) foot.push(parsed.summary);
+        if (parsed.next_action) foot.push(`Next: ${parsed.next_action}`);
+        return {
+          content: [{ type: "text", text: body + (foot.length ? `\n\n${foot.join("\n")}` : "") }],
+          details: { url: params.url, pages: pages.length, sitemap: !!parsed.sitemap_used },
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `web_crawl error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(args, theme) {
+      const urlStr = (args.url ?? "").toString();
+      const trunc = urlStr.length > 55 ? urlStr.slice(0, 52) + "..." : urlStr;
+      const sm = args.options?.sitemap ? " (sitemap)" : "";
+      return new Text(theme.fg("toolTitle", theme.bold("Web Crawl: ")) + theme.fg("accent", trunc + sm), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("dim", "crawling..."), 0, 0);
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      const sm = d.sitemap ? " (sitemap)" : "";
+      return new Text(theme.fg("accent", `${d.pages} pages${sm}`), 0, 0);
+    },
+  });
+
+  // -- web_screenshot --
+  pi.registerTool({
+    name: "web_screenshot",
+    label: "Web Screenshot",
+    description: "Screenshot a URL as an image. Multimodal agents only (content as images/canvas/visual layout). Text agents: use web_fetch. Stealthy browser auto-managed.",
+    promptSnippet: "web_screenshot(url, full_page, image_type) - anti-bot one-shot screenshot of a URL (stealthy browser). Multimodal agents only.",
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to screenshot" }),
+      options: Type.Optional(Type.Object({}, { additionalProperties: true, description: "full_page (bool,false), image_type (png|jpeg,png), quality (0-100,jpeg), wait (ms), wait_selector (css), network_idle (bool), timeout (ms,30000)." })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      try {
+        const args: Record<string, any> = { url: params.url };
+        if (params.options && Object.keys(params.options).length) args.options = params.options;
+        const result = await hound.call("mcp_screenshot", args, CALL_TIMEOUT_MS);
+        const images = getImages(result);
+        if (images.length) {
+          const out: any[] = [];
+          for (const img of images) out.push({ type: "image", data: img.data, mimeType: img.mimeType || "image/png" });
+          out.push({ type: "text", text: `Screenshot captured for ${params.url}` });
+          return { content: out, details: { url: params.url, images: images.length } };
+        }
+        const parsed = tryJson(getText(result));
+        return {
+          content: [{ type: "text", text: parsed.error ? `Capture failed: ${parsed.error}` : `Screenshot captured for ${params.url} (no image payload)` }],
+          details: { url: params.url, images: 0, error: parsed.error ?? "" },
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `web_screenshot error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(args, theme) {
+      const urlStr = (args.url ?? "").toString();
+      const trunc = urlStr.length > 55 ? urlStr.slice(0, 52) + "..." : urlStr;
+      return new Text(theme.fg("toolTitle", theme.bold("Web Screenshot: ")) + theme.fg("accent", trunc), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("dim", "capturing..."), 0, 0);
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      if (!d?.images) return new Text(theme.fg("dim", "no image"), 0, 0);
+      return new Text(theme.fg("accent", `${d.images} image`), 0, 0);
+    },
+  });
+
+  // -- cache_clear --
+  pi.registerTool({
+    name: "cache_clear",
+    label: "Clear Cache",
+    description: "Clear fetch cache. all=true wipes all (default: expired only). To re-fetch one URL fresh, pass cache_ttl=0 to web_fetch/web_crawl instead. Cache stores extracted text per URL+extraction_type+css_selector+pages (+ per query+filters for search); default TTL 1hr.",
+    promptSnippet: "cache_clear(all) - clear fetch cache. all=true wipes all (default: expired only). For one URL fresh, use cache_ttl=0 on web_fetch instead.",
+    parameters: Type.Object({
+      all: Type.Optional(Type.Boolean({ description: "Wipe all (default: expired only)" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      try {
+        const args = { all: params.all ?? false };
+        const result = await hound.call("cache_clear", args, 10_000);
+        return { content: [{ type: "text", text: getText(result) }], details: { all: args.all } };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `cache_clear error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("Clear Cache")), 0, 0);
+    },
+    renderResult(result, _meta, theme) {
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      return new Text(theme.fg("accent", "cleared"), 0, 0);
+    },
+  });
+
+  // -- hound_version --
+  pi.registerTool({
+    name: "hound_version",
+    label: "Hound Version",
+    description: "Hound version + update status.",
+    promptSnippet: "hound_version() - hound version + update status.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, _ctx) {
+      try {
+        const result = await hound.call("version", {}, 10_000);
+        return { content: [{ type: "text", text: getText(result) }], details: {} };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `hound_version error: ${e.message}` }], details: { error: e.message } };
+      }
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("toolTitle", theme.bold("Hound Version")), 0, 0);
+    },
+    renderResult(result, _meta, theme) {
+      const d = result.details as any;
+      if (d?.error) return new Text(theme.fg("error", `error: ${d.error}`), 0, 0);
+      return new Text(theme.fg("accent", "ok"), 0, 0);
+    },
+  });
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@houndmcp/hound-mcp-pi",
+  "version": "10.3.0",
+  "description": "Hound web research for Pi agent - keyless search, anti-bot fetch, deep crawl, screenshot, Internet Archive dead-link recovery. Free, MIT, no API key.",
+  "publishConfig": {"access": "public"},
+  "keywords": ["pi-package", "mcp", "web", "search", "fetch", "crawl", "ai-agent", "scraping"],
+  "license": "MIT",
+  "author": "dondai1234",
+  "repository": { "type": "git", "url": "https://github.com/dondai1234/master-fetch" },
+  "homepage": "https://github.com/dondai1234/master-fetch",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions/hound.ts"]
+  }
+}