@andrhamm/web-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-10-31)
+
+- Six tools in three tiers: `web_lookup` and `web_read` (basic), `web_research` and `web_page` (standard), `web_investigate` and `web_search` (advanced).
+- Research runs as one headless Claude Haiku session with WebSearch and WebFetch, with an optional Brave Search head start.
+- Replies are compact markdown sized to `max_tokens`, enforced by per-request schema length limits and a trimming safety net, with an optional `format: "json"`.
+- Flat-file cache for answers and fetched pages; Brave results are held in memory only.
+- stdio and Streamable HTTP transports.
+- Bounded wait queue (`WEB_MCP_QUEUE`, error `busy`); each call's time budget includes waiting.
+- Cancelling a call, or closing its connection, stops its Claude run (error `cancelled`).
+- Brave queries are cut to Brave's 75-word limit; a rejected query no longer switches Brave off.
+- A timeout while a page body downloads reports `timeout`; other body read failures report `fetch_failed`.
+- Pages are decoded with the charset from the Content-Type header or a `<meta>` tag, falling back to UTF-8.
+- A stopped Claude run that ignores SIGTERM is killed after 3 seconds.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Hammond
+
+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

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# web-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local MCP server that answers web research questions for agents and returns the smallest useful reply: a direct answer, short verbatim quotes, numbered sources and what it could not find, never longer than the token cap the caller sets.
+
+It exists so that small local models (and agents in a network sandbox) can use the web without spending their context on search result pages. A Claude Haiku session does the searching, reading and filtering on your own Claude subscription, through the Claude Code command line you are already signed in to. No API keys are needed. A Brave Search API key is optional and gives each research run a head start.
+
+## Requirements
+
+- Node.js 22 or newer.
+- [Claude Code](https://code.claude.com/docs) installed and signed in with a Claude subscription. The server runs the unmodified `claude` command; it never reads or stores your credentials.
+- Optional: a [Brave Search API](https://brave.com/search/api/) key, in `BRAVE_API_KEY` or in a file named by `BRAVE_API_KEY_FILE`.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio web -- npx -y @andrhamm/web-mcp
+```
+
+pi coding agent:
+
+```bash
+pi mcp add web -- npx -y @andrhamm/web-mcp
+```
+
+LM Studio and other clients that use an `mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "web": { "command": "npx", "args": ["-y", "@andrhamm/web-mcp"], "env": { "BRAVE_API_KEY": "<your key>" } }
+  }
+}
+```
+
+The server reads `BRAVE_API_KEY` from the environment its client starts it with. A desktop app started outside a shell may not see variables your shell sets, so put the key in the client's `env` block or point `BRAVE_API_KEY_FILE` at a file that holds it.
+
+### Sandboxed agents (HTTP)
+
+An agent in a sandbox has no Claude sign-in, so run the server on the host and let the sandbox reach it over HTTP:
+
+```bash
+npx -y @andrhamm/web-mcp --http 127.0.0.1:7343
+claude mcp add --transport http web http://127.0.0.1:7343/mcp
+```
+
+On loopback without a token, the server accepts only localhost `Host` and `Origin` headers. To listen on any other address you must set `WEB_MCP_HTTP_TOKEN`; clients then send `Authorization: Bearer <token>`. One HTTP process also shares one concurrency limit across all its callers.
+
+## Tools
+
+Tools come in three tiers, so each agent role can be given only the tools it can use well. Allow-list them by name in your client, or start the server with `--tiers basic` (or `basic,standard`) to hide the rest.
+
+| Tier | Tool | Inputs | Use |
+|---|---|---|---|
+| basic | `web_lookup` | `question`, `max_tokens` (optional, default 300) | Answer a question from the web. |
+| basic | `web_read` | `url`, `question` (optional), `max_tokens` (optional, default 300) | Say briefly what one page says. |
+| standard | `web_research` | `question`, `goal`, `max_tokens` (default 400), `format` | Research for a stated goal; full reply with findings and quotes. |
+| standard | `web_page` | `url`, `goal`, `max_tokens`, `format` | Read one known page for a goal; quotes checked against the page. |
+| advanced | `web_investigate` | `web_research` inputs plus `depth`, `recency`, `domains`, `cache` | Research with control over effort, freshness and sources. |
+| advanced | `web_search` | `query`, `count`, `recency`, `domains` | Raw Brave results: titles, URLs, snippets, dates. Listed only when a Brave key is set. |
+
+`goal` is what the caller will do with the answer. The server keeps only what serves it, so a good goal makes a short reply. It is sent to Claude and to the web, so never put secrets in it.
+
+`max_tokens` (50 to 4000) is a ceiling, not a target. Haiku is asked for the shortest reply that serves the goal. If it still runs over, the server drops the least important findings first, then quotes, then gaps, then trailing sentences, and marks the reply `trimmed yes`. Tokens are estimated with an o200k count times 1.3, which tracks Claude's tokenizer on prose and runs low on code.
+
+`depth` sets the effort: `quick` allows 2 searches and 3 page reads, `standard` 4 and 6, `deep` 8 and 12. Each call has a time budget (90, 180 or 300 seconds; 90 for page tools) counted from when it arrives, so time spent waiting for a free slot uses it up too.
+
+## Replies
+
+Replies are compact markdown, because for this kind of content it costs fewer tokens than JSON and every model reads it well:
+
+```
+Answer: Send the key in the `X-Subscription-Token` header [1].
+Confidence: high
+
+Findings
+- Every request must include the API key in this header. [1] "All requests to the Brave Search API must include an API key in the X-Subscription-Token HTTP header."
+
+Sources
+[1] Authentication. https://api-dashboard.search.brave.com/documentation/guides/authentication
+
+Gaps
+- Rate limits for the free credit were not checked.
+
+meta: claude-haiku-5-5, searches 0, pages 0, brave, verified 1/1, cached no, trimmed no, 7.5 s
+```
+
+The basic tools return only the answer, the sources and a `Not found:` line. Standard and advanced tools accept `format: "json"` for code that wants to parse the reply; the object matches `src/contract.ts`, with `findings[].source` as a 0-based index into `sources` and `findings[].verified: true` on quotes the server checked. The server does not send MCP structured content, because some clients show that to the model instead of the text.
+
+`verified n/m` means n of the m quotes in the reply were checked word for word against page text the server holds: the page itself for `web_read` and `web_page`, and the Brave snippets for research runs. A quote that fails the check is removed and its claim kept, so the other m minus n quotes were not checked: they come from pages Haiku read through WebFetch, whose text the server never sees.
+
+Errors come back as tool errors with a code first: `claude_not_signed_in`, `no_backend`, `rate_limited`, `busy`, `timeout`, `cancelled`, `fetch_failed`, `blocked_url`, `bad_output`.
+
+## How it works
+
+Each research call is one headless `claude -p` run on Haiku with only the WebSearch and WebFetch tools. Haiku splits the question into the parts the goal needs, searches, reads the most promising pages, checks after each read whether every part is backed by a quote, and stops when it is, or when the depth caps are reached. It then fills a JSON structure whose schema carries length limits sized to `max_tokens` (answer length, number of findings, quote and gap length). Claude Code rejects output that breaks them and Haiku rewrites it, which keeps most replies inside the cap without trimming. The server then renders, verifies, trims if still needed, and caches.
+
+With a Brave key, the server first runs one Brave web search and gives Haiku the results and snippets as a head start, so simple questions often need no further searching. Each uncached research call spends one Brave request, and each `web_search` call spends one. Page tools spend none. Brave accepts at most 75 words per query, so long questions are cut to fit. If Brave rejects a query, only that call loses its head start; only a key or plan error switches Brave off until restart.
+
+Page tools fetch the page directly (public addresses only, 2 MB, 20 seconds), extract the main text with Mozilla Readability, convert it to compact markdown, keep the passages that match the goal, and give those to Haiku with no tools.
+
+The Claude run is isolated from your own Claude Code setup: no user or project settings, hooks, plugins, MCP servers or slash commands, an empty working directory, and no saved session. `ANTHROPIC_API_KEY` is removed from its environment so it always uses the subscription and never bills the API.
+
+## Cancellation
+
+When a caller cancels a call, or drops its connection, the server removes it from the wait queue or stops its Claude run at once, so no subscription usage is spent on an answer nobody will read. Over stdio this works for any client. Over HTTP it works when the client closes the request's connection, as clients on the 2026-07-28 protocol do. Clients on the older 2025 protocol cancel with a separate message that a stateless HTTP server cannot match to the call, so their abandoned runs stop at the time budget instead.
+
+## Cache
+
+Answers and fetched pages are cached as small JSON files in `WEB_MCP_CACHE_DIR`, or the platform cache directory under `web-mcp` (`~/Library/Caches` on macOS, `XDG_CACHE_HOME` or `~/.cache` on Linux, `LOCALAPPDATA` on Windows).
+
+| Entry | Lifetime |
+|---|---|
+| Research answer, recency `day` | 1 hour |
+| `week` | 6 hours |
+| `month` | 1 day |
+| `year` | 3 days |
+| `any` | 7 days |
+| Page text and page answers | 1 day |
+| Brave results | 10 minutes, in memory only |
+
+Brave's API terms allow only transient storage of search results, so they are never written to disk. `cache: "refresh"` on `web_investigate` ignores cached answers and pages.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `BRAVE_API_KEY`, `BRAVE_API_KEY_FILE` | unset | Brave key, or a file holding it. Enables the head start and `web_search`. |
+| `CLAUDE_BIN` | `claude` | Path to the Claude Code command. |
+| `WEB_MCP_MODEL` | `haiku` | Model alias or id passed to `claude --model`. |
+| `WEB_MCP_CONCURRENCY` | 2 | Claude runs at once; the rest wait in order. |
+| `WEB_MCP_QUEUE` | 8 | Calls allowed to wait for a slot; beyond that a call fails at once with `busy`. |
+| `WEB_MCP_CACHE_DIR` | platform cache dir | Where cached answers and pages live. |
+| `WEB_MCP_HTTP_TOKEN` | unset | Bearer token for `--http`; required off loopback. |
+
+Logs go to stderr only.
+
+## Use of your Claude subscription
+
+Every uncached call runs Claude Code under your own sign-in and counts toward your plan's usage limits. Run this server for your own agents. Do not offer it to other people as a shared Claude backend: Anthropic's terms allow ordinary individual use of Claude Code with your own subscription, not reselling access to it.
+
+## Limits
+
+- Pages that render their content with JavaScript come back thin; there is no headless browser.
+- Page tools do not consult `robots.txt`.
+- `recency` is exact for the Brave head start and best effort for Claude's own searches.
+- The token estimate is approximate; set `max_tokens` with some margin if a hard limit matters.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run lint
+```
+
+Tests run against a fake `claude` command and need no network or sign-in. To try a local build in Claude Code: `claude mcp add --transport stdio web -- node <clone>/dist/src/index.js`.
+
+Releasing: bump `version` in `package.json`, add the changes to `CHANGELOG.md`, commit, then push a matching tag (`git tag v0.2.0 && git push origin v0.2.0`). The publish workflow tests, builds and publishes to npm with provenance.
+
+## License
+
+MIT

package/dist/src/brave.js

@@ -0,0 +1,100 @@
+// Brave Search web results: the head start for research runs and the raw `web_search` tool.
+// Brave's API terms allow only transient storage of results, so they are cached in memory for minutes and never on disk.
+import { readFileSync } from "node:fs";
+import { MemoryCache } from "./cache.js";
+import { ToolError } from "./contract.js";
+export function braveKey(env = process.env) {
+    if (env.BRAVE_API_KEY?.trim())
+        return env.BRAVE_API_KEY.trim();
+    if (env.BRAVE_API_KEY_FILE) {
+        try {
+            return readFileSync(env.BRAVE_API_KEY_FILE, "utf8").trim() || undefined;
+        }
+        catch {
+            console.error("[web-mcp] BRAVE_API_KEY_FILE is set but could not be read; Brave is off");
+        }
+    }
+    return undefined;
+}
+const FRESHNESS = { day: "pd", week: "pw", month: "pm", year: "py" };
+const memo = new MemoryCache(10 * 60_000);
+let disabledReason;
+export const braveAvailable = () => !disabledReason && !!braveKey();
+// Brave answers 422 VALIDATION above 75 words ("Search query must be at most 75 words", checked 2026-10-23).
+const MAX_WORDS = 75;
+/** The question plus site filters, with the question cut so the whole query stays within Brave's word limit. */
+export function braveQuery(query, domains) {
+    const inc = domains?.include ?? [];
+    const exc = domains?.exclude ?? [];
+    const filters = [];
+    if (inc.length)
+        filters.push(inc.length === 1 ? `site:${inc[0]}` : `(${inc.map((d) => `site:${d}`).join(" OR ")})`);
+    for (const d of exc)
+        filters.push(`-site:${d}`);
+    const filterWords = filters.join(" ").split(/\s+/).filter(Boolean).length;
+    const words = query
+        .trim()
+        .split(/\s+/)
+        .slice(0, Math.max(1, MAX_WORDS - filterWords));
+    return [words.join(" "), ...filters].join(" ");
+}
+const clean = (s) => s
+    .replace(/<[^>]+>/g, "")
+    .replace(/&#x27;|&#39;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .trim();
+export async function braveSearch(query, opts) {
+    const key = braveKey();
+    if (!key || disabledReason)
+        throw new ToolError("no_backend", disabledReason ?? "No Brave API key is configured", "Set BRAVE_API_KEY or BRAVE_API_KEY_FILE");
+    const params = new URLSearchParams({ q: braveQuery(query, opts.domains), count: String(opts.count), extra_snippets: "true" });
+    const fresh = opts.recency && FRESHNESS[opts.recency];
+    if (fresh)
+        params.set("freshness", fresh);
+    const url = `https://api.search.brave.com/res/v1/web/search?${params}`;
+    const hit = memo.get(url);
+    if (hit)
+        return hit;
+    const res = await fetch(url, {
+        headers: { accept: "application/json", "x-subscription-token": key },
+        signal: AbortSignal.timeout(15_000),
+    }).catch((e) => {
+        throw new ToolError("fetch_failed", `Brave search failed: ${e.message}`);
+    });
+    if (res.status === 401 || res.status === 403 || res.status === 422) {
+        const err = (await res.json().catch(() => ({})));
+        const code = err.error?.code ?? String(res.status);
+        // Only a key or subscription problem turns Brave off; a 422 is also how Brave rejects a bad query (code VALIDATION).
+        if (res.status !== 422 || /TOKEN|SUBSCRIPTION|AUTH/i.test(code)) {
+            disabledReason = `Brave rejected the API key (${code})`;
+            console.error(`[web-mcp] ${disabledReason}; Brave is off until restart`);
+            throw new ToolError("no_backend", disabledReason, "Check the Brave plan and key");
+        }
+        const why = err.error?.meta?.errors?.[0]?.msg ?? err.error?.detail ?? code;
+        throw new ToolError("fetch_failed", `Brave rejected the query: ${why}`, "Shorten the query or use fewer domain filters");
+    }
+    if (res.status === 429)
+        throw new ToolError("rate_limited", "Brave rate limit or credit exhausted", "Wait a moment, or check the Brave plan's credit");
+    if (!res.ok)
+        throw new ToolError("fetch_failed", `Brave answered HTTP ${res.status}`);
+    const body = (await res.json());
+    const hits = (body?.web?.results ?? []).map((r) => ({
+        url: String(r.url),
+        title: clean(String(r.title ?? r.url)),
+        snippets: [r.description, ...(r.extra_snippets ?? [])].filter((s) => typeof s === "string" && s !== "").map(clean),
+        ...(typeof r.page_age === "string" ? { published: r.page_age.slice(0, 10) } : {}),
+    }));
+    memo.set(url, hits);
+    return hits;
+}
+export function renderHits(hits, maxSnippets = 3) {
+    return hits
+        .map((h, i) => [
+        `[${i + 1}] ${h.title}. ${h.url}${h.published ? ` (${h.published})` : ""}`,
+        ...h.snippets.slice(0, maxSnippets).map((s) => `  ${s}`),
+    ].join("\n"))
+        .join("\n");
+}

package/dist/src/budget.js

@@ -0,0 +1,95 @@
+import { countTokens } from "gpt-tokenizer";
+import { renderBody } from "./render.js";
+// shortcut: o200k count times 1.3 approximates Claude's tokenizer on English prose; low on code-heavy text. Recalibrate if callers report overruns.
+const CLAUDE_FACTOR = 1.3;
+export const estimateTokens = (text) => Math.ceil(countTokens(text) * CLAUDE_FACTOR);
+/** Words to ask the model for, leaving room for markup. */
+// Measured 2026-10-22: Haiku lands 15 to 40 percent over the words it is given, and labels plus sources take about 60 tokens.
+export const wordTarget = (maxTokens) => Math.max(20, Math.floor(maxTokens * 0.42));
+/** Findings that fit beside the answer: about one per 150 tokens of cap. */
+export const findingsTarget = (maxTokens) => Math.min(8, Math.floor(maxTokens / 150));
+/** Hard limits for the schema: an answer of about 1.35 characters per token of cap, and the findings target. */
+export const limits = (maxTokens) => ({
+    answerChars: Math.max(160, Math.round(maxTokens * 1.35)),
+    findings: findingsTarget(maxTokens),
+});
+export const capLine = (maxTokens) => `Output cap: max_tokens ${maxTokens}: about ${wordTarget(maxTokens)} words in total at most, counting answer, findings, quotes and source titles. ` +
+    `The answer must fit in ${limits(maxTokens).answerChars} characters. ` +
+    `At most ${findingsTarget(maxTokens)} findings${findingsTarget(maxTokens) === 0 ? " (put the facts in the answer)" : ""}; none that repeat the answer without adding a quote.`;
+/** Drop a trailing site name ("Title | Site", "Title - Site") and cap the length: titles repeat on every reply. */
+export function shortTitle(t) {
+    const cut = t.replace(/\s+[|\u2013\u2014-]\s+[^|\u2013\u2014-]{1,40}$/, "").trim();
+    const s = cut.length >= 8 ? cut : t.trim();
+    return s.length > 80 ? `${s.slice(0, 77).trimEnd()}...` : s;
+}
+/** Dedupe sources by URL, drop unreferenced ones, renumber findings and [n] markers. */
+export function compact(r) {
+    const byUrl = new Map(); // url -> new 1-based number
+    const sources = [];
+    const oldToNew = new Map();
+    const used = new Set(r.findings.map((f) => f.source));
+    for (const m of r.answer.matchAll(/\[(\d+)\]/g))
+        used.add(Number(m[1]));
+    r.sources.forEach((s, i) => {
+        if (!used.has(i + 1))
+            return;
+        const key = s.url.replace(/\/$/, "");
+        let n = byUrl.get(key);
+        if (n === undefined) {
+            sources.push({ ...s, title: shortTitle(s.title) });
+            n = sources.length;
+            byUrl.set(key, n);
+        }
+        oldToNew.set(i + 1, n);
+    });
+    const findings = r.findings.filter((f) => oldToNew.has(f.source)).map((f) => ({ ...f, source: oldToNew.get(f.source) ?? f.source }));
+    const answer = r.answer.replace(/\[(\d+)\]/g, (_all, d) => (oldToNew.has(Number(d)) ? `[${oldToNew.get(Number(d))}]` : ""));
+    return { ...r, answer, findings, sources };
+}
+/**
+ * Safety net after the model: drop the least important findings whole (the rest keep their quotes),
+ * then the last quote, then gaps, then cut the answer at sentence ends, until the body fits.
+ */
+export function trim(r, maxTokens, format) {
+    const fits = (x) => estimateTokens(renderBody(x, format)) <= maxTokens;
+    if (fits(r))
+        return r;
+    let x = { ...r, findings: [...r.findings], meta: { ...r.meta, trimmed: true } };
+    while (x.findings.length > 1 && !fits(x))
+        x = compact({ ...x, findings: x.findings.slice(0, -1) });
+    if (!fits(x) && x.findings[0]?.quote)
+        x = { ...x, findings: [{ ...x.findings[0], quote: undefined }] };
+    if (!fits(x))
+        x = compact({ ...x, findings: [] });
+    if (!fits(x))
+        x = { ...x, gaps: [] };
+    while (!fits(x)) {
+        const sentences = x.answer.match(/[^.!?]+[.!?]+\s*/g) ?? [];
+        const answer = sentences.length > 1 ? sentences.slice(0, -1).join("").trim() : `${x.answer.slice(0, Math.floor(x.answer.length * 0.8)).trim()}...`;
+        if (answer.length < 10)
+            break;
+        x = compact({ ...x, answer });
+    }
+    return x;
+}
+// Letters and digits only: quotes survive markdown, smart quotes and spacing differences between the page and the model.
+const norm = (s) => s
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+/**
+ * Check quotes against text the server holds, keyed by URL. Quotes from sources not in `held` are left alone.
+ * A quote found there marks its finding `verified`; one not found is dropped and its claim kept.
+ */
+export function verifyQuotes(r, held) {
+    const normHeld = new Map([...held].map(([u, t]) => [u.replace(/\/$/, ""), norm(t)]));
+    const findings = r.findings.map((f) => {
+        if (!f.quote)
+            return f;
+        const text = normHeld.get(r.sources[f.source - 1]?.url.replace(/\/$/, "") ?? "");
+        if (text === undefined)
+            return f;
+        return text.includes(norm(f.quote)) ? { ...f, verified: true } : { ...f, quote: undefined };
+    });
+    return { ...r, findings };
+}

package/dist/src/cache.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function cacheDir(env = process.env, platform = process.platform) {
+    if (env.WEB_MCP_CACHE_DIR)
+        return env.WEB_MCP_CACHE_DIR;
+    const base = platform === "darwin"
+        ? join(homedir(), "Library", "Caches")
+        : platform === "win32"
+            ? (env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"))
+            : (env.XDG_CACHE_HOME ?? join(homedir(), ".cache"));
+    return join(base, "web-mcp");
+}
+export const HOUR = 3_600_000;
+/**
+ * Flat-file TTL cache: one `sha256(key).json` per entry holding `{expires, body}`.
+ * shortcut: expired files are ignored, never swept; add a sweep if the directory grows past a few thousand files.
+ */
+export class FileCache {
+    dir;
+    constructor(dir = cacheDir()) {
+        this.dir = dir;
+    }
+    path(key) {
+        return join(this.dir, `${createHash("sha256").update(key).digest("hex")}.json`);
+    }
+    async get(key, now = Date.now()) {
+        try {
+            const { expires, body } = JSON.parse(await readFile(this.path(key), "utf8"));
+            return expires > now ? body : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async set(key, body, ttlMs, now = Date.now()) {
+        try {
+            await mkdir(this.dir, { recursive: true });
+            const p = this.path(key);
+            const tmp = `${p}.${process.pid}.tmp`;
+            await writeFile(tmp, JSON.stringify({ expires: now + ttlMs, body }));
+            await rename(tmp, p);
+        }
+        catch (e) {
+            console.error(`[web-mcp] cache write failed: ${e.message}`);
+        }
+    }
+}
+/** In-memory TTL map for data that must not touch disk (Brave results: its terms allow transient storage only). */
+export class MemoryCache {
+    ttlMs;
+    m = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    get(key, now = Date.now()) {
+        const e = this.m.get(key);
+        if (e && e.expires > now)
+            return e.value;
+        this.m.delete(key);
+        return undefined;
+    }
+    set(key, value, now = Date.now()) {
+        if (this.m.size > 500)
+            this.m.clear(); // bounded; entries live minutes anyway
+        this.m.set(key, { expires: now + this.ttlMs, value });
+    }
+}
+export const normKey = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();