tinyfish-mcp-lite 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TinyFish
+
+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,355 @@
-# Temporary Holding Version
+# tinyfish-mcp-lite
 
-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.
+[![npm version](https://img.shields.io/npm/v/tinyfish-mcp-lite)](https://www.npmjs.com/package/tinyfish-mcp-lite)
+
+> **⚠️ You are on `tinyfish-mcp-lite`** — a fork that exposes **only the two
+> free hosted tools** (`search`, `fetch_content`) and hides the 26 paid ones,
+> so they neither burn client context tokens (~72% smaller `tools/list`) nor
+> can ever be invoked through this proxy. **Start here:
+> [Using this fork](#using-this-fork-tinyfish-mcp-lite)** · fork guide:
+> [FORK.md](FORK.md). Everything below this section is inherited from
+> upstream and describes the unfiltered behavior unless noted.
+
+TinyFish MCP server: web search, page fetching and extraction, browser
+automation and page monitoring for Claude, Cursor, VS Code and any MCP
+client. Search and Fetch are free.
+
+> **Using Claude or ChatGPT in the browser or desktop app?** Skip the setup and add the official
+> TinyFish plugin for **[Claude](https://claude.ai/directory/tinyfish)** or **[ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_695325bae7348191b58ae9349a963d22)** in one click. It bundles
+> these tools with ready-made skills and safety rules.
+
+This package is a transparent reverse proxy that exposes a local
+Streamable-HTTP MCP endpoint at `http://127.0.0.1:3711/mcp` and forwards every
+request to the hosted TinyFish MCP server at `https://agent.tinyfish.ai/mcp`.
+
+The proxy defines no tools and no schemas of its own. `tools/list`,
+`tools/call`, `resources/*`, errors, and the `run_web_automation` SSE progress
+stream all come from the hosted server: streaming (SSE) responses are relayed
+byte-verbatim, and non-streaming JSON responses are relayed content-identical
+(parsed and re-serialized, deep-equal to upstream). What the hosted server
+says is what your client sees.
+
+## Using this fork (tinyfish-mcp-lite)
+
+Everything below about install, API key, and client configuration applies to
+this fork too — with exactly these differences:
+
+- **Only the free tools are exposed.** `tools/list` returns exactly
+  `search` and `fetch_content` (their schemas verbatim from upstream). All
+  other tools are hidden.
+- **Paid tools cannot be invoked.** A `tools/call` naming a hidden tool is
+  answered locally with the same error the hosted server itself produces for
+  an unknown tool (HTTP 400, JSON-RPC `-32602 "Unknown tool: <name>"`) — the
+  request never leaves your machine, so it can never bill. Notification-
+  shaped calls and JSON-RPC batches carrying hidden tools are blocked the
+  same way.
+- **One extra env var, `TINYFISH_TOOLS`** (default `search,fetch_content`):
+  a comma-separated allowlist. Set `TINYFISH_TOOLS=*` to restore the full
+  upstream catalog (28 tools, unfiltered). Invalid values abort startup.
+- **A second startup log line** states the active filter, e.g.
+  `tinyfish-mcp [info] tool filter: exposing [search, fetch_content] — set TINYFISH_TOOLS=* to expose every upstream tool`.
+
+### Install (this fork)
+
+The fork ships on npm as **`tinyfish-mcp-lite`** (requires Node.js >= 22).
+Two transports are available:
+
+**stdio — one command, the client manages the process.** Most clients that
+launch MCP servers as commands (Claude Code with a `command` entry, Cursor,
+Zed, many launcher UIs) want this:
+
+```sh
+# the client spawns it; add TINYFISH_API_KEY to the command's environment
+npx -y tinyfish-mcp-lite --stdio
+
+# or with the global install (`npm i -g tinyfish-mcp-lite`):
+tinyfish-mcp --stdio
+```
+
+In a client config that takes a command + env vars, that is:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "tinyfish-mcp-lite", "--stdio"],
+  "env": { "TINYFISH_API_KEY": "tf_..." }
+}
+```
+
+**HTTP — one shared server for several clients.** Start it once (terminal,
+systemd, pm2) and point every client at the same URL:
+
+```sh
+TINYFISH_API_KEY=tf_... npx tinyfish-mcp-lite          # no --stdio flag
+```
+
+```sh
+# or from a clone
+git clone https://github.com/ByronFinn/tinyfish-mcp-lite.git
+cd tinyfish-mcp-lite
+npm ci && npm run build
+TINYFISH_API_KEY=tf_... node dist/index.js             # HTTP
+# TINYFISH_API_KEY=tf_... node dist/index.js --stdio   # stdio
+```
+
+Both transports expose the same filtered proxy; stdio just has no port and
+no manual startup — closing the client's pipe shuts the process down.
+
+> **Note on git-based installs** (`npm i -g github:ByronFinn/tinyfish-mcp-lite`):
+> npm ≥ 11.17 with the install-script policy enabled (an `allow-scripts`
+> entry in your `~/.npmrc`) rejects them with `EALLOWSCRIPTS` — the policy
+> leaks into the inner git-dep build via the environment. Use the npm or
+> clone routes instead; registry installs (`npx tinyfish-mcp-lite`) are
+> unaffected.
+
+For the HTTP transport, point your MCP client at `http://127.0.0.1:3711/mcp`
+as described in [Client configuration](#client-configuration) below.
+
+Why a fork at all: the hosted server's paid tools (automation, browsers,
+monitors…) are unusable without wallet funds, but their schemas still land
+in every client session. If you only ever use the free search/fetch, this
+fork keeps the client context lean and makes accidental paid calls
+impossible. Fork maintenance and upstream-sync details: [FORK.md](FORK.md).
+
+## Tools
+
+The hosted server exposes 28 tools. You can use them to search the web, fetch and
+extract pages, automate browsers, run remote Chrome sessions (CDP), keep
+signed-in Browser Context Profiles and schedule page and topic Monitors.
+(In this fork only the `Search & Fetch` row is advertised — see
+[Using this fork](#using-this-fork-tinyfish-mcp-lite).)
+
+| Category | Tools |
+|---|---|
+| Search & Fetch | `search`, `fetch_content` |
+| Web automation | `run_web_automation`, `run_web_automation_async`, `get_run`, `list_runs`, `cancel_run`, `batch_status`, `batch_cancel` |
+| Browser sessions | `create_browser_session`, `list_browser_sessions`, `close_browser_session` |
+| Browser Context Profiles | `create_profile`, `list_profiles`, `start_profile_setup_session`, `save_profile_setup_session`, `cancel_profile_setup_session` |
+| Monitors | `create_monitor`, `get_monitor`, `list_monitors`, `run_monitor`, `pause_monitor`, `resume_monitor`, `cancel_monitor` |
+| Account & usage | `get_wallet`, `get_search_usage`, `list_fetch_usage`, `guide_next_step` |
+
+- [Tool reference](https://github.com/tinyfish-io/tinyfish-mcp-server/blob/main/docs/tools.md): every tool, verbatim, with parameters
+- [Examples](https://github.com/tinyfish-io/tinyfish-mcp-server/blob/main/docs/examples.md): common workflows and prompts
+- [MCP Integration guide](https://docs.tinyfish.ai/mcp-integration): client setup, auth, rates, troubleshooting
+- Full documentation: [docs.tinyfish.ai](https://docs.tinyfish.ai)
+
+## Use the hosted server first
+
+If your MCP client supports remote Streamable-HTTP servers (Claude Code,
+Claude Desktop connectors, Cursor, VS Code, and most modern clients do),
+connect it **directly** to the hosted server — no install, no local process:
+
+```text
+https://agent.tinyfish.ai/mcp
+```
+
+Use this package instead when:
+
+- your client only talks to local MCP servers, or
+- you want to authenticate with a **TinyFish API key** from your environment
+  instead of the hosted server's OAuth flow (CI, headless machines, scripts).
+
+## Install
+
+```sh
+npm install -g @tiny-fish/mcp
+```
+
+Or run it without installing:
+
+```sh
+npx @tiny-fish/mcp
+```
+
+Requires **Node.js >= 22**. (This is a deliberate deviation from the TinyFish
+CLI's `>=24` requirement — nothing here needs Node 24.)
+
+## API key
+
+The server reads `TINYFISH_API_KEY` from its environment at startup and sends
+it upstream as `X-API-Key` on every call. Get a key at
+[https://agent.tinyfish.ai](https://agent.tinyfish.ai).
+
+```sh
+export TINYFISH_API_KEY=tf_...
+tinyfish-mcp
+```
+
+On success it prints one line to stderr:
+
+```text
+tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0
+```
+
+The key is never logged and never echoed back to clients.
+
+## Client configuration
+
+Start `tinyfish-mcp` (e.g. in a terminal, or under your process manager of
+choice), then point your client at `http://127.0.0.1:3711/mcp`.
+
+### Claude Code
+
+```sh
+claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp
+```
+
+### Claude Desktop
+
+Settings → Connectors → Add custom connector, with URL
+`http://127.0.0.1:3711/mcp`. On versions whose
+`claude_desktop_config.json` supports URL-based servers:
+
+```json
+{
+  "mcpServers": {
+    "tinyfish": {
+      "url": "http://127.0.0.1:3711/mcp"
+    }
+  }
+}
+```
+
+Note: Claude Desktop can also use the hosted `https://agent.tinyfish.ai/mcp`
+directly as a custom connector — prefer that unless you need API-key auth.
+
+### Cursor
+
+`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "tinyfish": {
+      "url": "http://127.0.0.1:3711/mcp"
+    }
+  }
+}
+```
+
+### VS Code
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "tinyfish": {
+      "type": "http",
+      "url": "http://127.0.0.1:3711/mcp"
+    }
+  }
+}
+```
+
+### Any other client
+
+Configure a Streamable-HTTP (remote/URL) MCP server with:
+
+```json
+{ "url": "http://127.0.0.1:3711/mcp" }
+```
+
+The endpoint accepts `POST /mcp` only (matching the hosted server, which has
+no GET SSE channel and no DELETE session teardown). `GET /healthz` returns
+`200 ok` for debugging.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `TINYFISH_API_KEY` | (required) | TinyFish API key, sent upstream as `X-API-Key`. The server refuses to start without it. |
+| `PORT` | `3711` | Local listen port (integer 1-65535). No auto-increment: if the port is busy the server exits with an error. |
+| `TINYFISH_UPSTREAM_URL` | `https://agent.tinyfish.ai/mcp` | Upstream MCP URL. Must be `https:`; `http:` is allowed only for `127.0.0.1`/`localhost` (local testing). |
+| `TINYFISH_TOOLS` | `search,fetch_content` | **Fork only:** comma-separated allowlist of upstream tools to expose; `*` disables filtering and exposes the full upstream catalog. Invalid values abort startup. |
+
+The proxy also sends attribution headers on every upstream call:
+`X-TF-Request-Origin: tinyfish-mcp`, `X-TF-Client-Name: tinyfish-mcp`, and
+`X-TF-Client-Version: <package version>`.
+
+## Security & trust model
+
+This is a loopback-only server with a deliberate, documented trust boundary:
+
+- **Loopback bind, always.** The server binds the `127.0.0.1` literal and this
+  is not configurable — it can never listen on `0.0.0.0` or a LAN interface.
+- **Origin validation.** Requests carrying an `Origin` header are rejected
+  with `403` unless the origin is `http(s)://127.0.0.1` or
+  `http(s)://localhost` (any port). This blocks the DNS-rebinding attack the
+  MCP spec calls out for local HTTP servers. Requests without an `Origin`
+  header (curl, MCP SDKs, inspectors) are allowed.
+- **Server-holds-key.** The process reads `TINYFISH_API_KEY` from its env;
+  clients send no credential on the local hop. This is the simplest model,
+  but it means **any local process that can reach `127.0.0.1:<port>` can use
+  your key and drive automations** (which can spend TinyFish credits). The
+  loopback bind and Origin check are the mitigations; treat the port as a
+  local trust boundary on a machine you trust.
+
+## Troubleshooting
+
+**"Port 3711 is already in use"** — another process holds the port. Stop it,
+or set `PORT` to a free port and update your client config to match.
+
+**HTTP 502 with JSON-RPC error `-32001`** ("Upstream rejected the request …
+check that TINYFISH_API_KEY is set to a valid TinyFish API key") — the hosted
+server rejected your key. Verify `TINYFISH_API_KEY` is set in the environment
+of the `tinyfish-mcp` process (not just your shell) and that the key is valid
+at [https://agent.tinyfish.ai](https://agent.tinyfish.ai). The error's `data`
+carries the upstream status and (truncated) body for diagnosis.
+
+**HTTP 502 with JSON-RPC error `-32000`** ("cannot reach …") — the upstream
+server is unreachable: check your network/proxy/VPN; the hosted server may
+also be temporarily down. If you overrode `TINYFISH_UPSTREAM_URL`, check it.
+If a streamed `run_web_automation` call fails mid-stream you get the same
+`-32000` as the final SSE frame, with a "the run may still be executing"
+warning and the `runId` when known — check the run's status instead of
+retrying blindly.
+
+**Batch requests don't work** — MCP forbids JSON-RPC batching and the hosted
+server does not support batch arrays. The proxy forwards a batch as-is and
+the upstream answers its own error; send one JSON-RPC message per request.
+
+**Claude/other client can't connect** — make sure `tinyfish-mcp` is actually
+running (it's a standalone server; clients do not launch it) and that
+`GET http://127.0.0.1:3711/healthz` answers `ok`.
+
+## Development
+
+```sh
+npm ci
+npm run build        # tsc → dist/, marks dist/index.js executable
+npm test             # unit tests (offline, mock upstream)
+npm run test:watch   # unit tests in watch mode
+npm run lint         # eslint over src/ tests/
+npm run format       # prettier
+npm run type-check   # tsc --noEmit over the whole tree
+```
+
+Layout: `src/core/` is the transport-agnostic proxy core (upstream client,
+session bridge, SSE relay, error shaping); `src/http/` is the thin HTTP
+adapter (routing, Origin check); `tests/` holds the unit suites plus
+`tests/helpers/mock-upstream.ts`, a mock of the hosted endpoint that the unit
+tests run against entirely offline.
+
+Integration tests hit the **real** hosted upstream and are gated: without
+`TINYFISH_API_KEY` they skip with a printed notice.
+
+```sh
+TINYFISH_API_KEY=... npm run test:integration
+```
+
+Set `TINYFISH_UPSTREAM_URL` to point them at a sandbox deployment instead of
+production. Note the `run_web_automation` integration test executes a real
+automation and spends credits.
+
+## Maintenance
+
+Maintained by [@Zechereh](https://github.com/Zechereh). Bugs and feature
+requests: [GitHub issues](https://github.com/tinyfish-io/tinyfish-mcp-server/issues).
+This fork is maintained at
+[ByronFinn/tinyfish-mcp-lite](https://github.com/ByronFinn/tinyfish-mcp-lite);
+fork-specific questions live in [FORK.md](FORK.md).
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_PORT = 3711;
+export declare const DEFAULT_UPSTREAM_URL = "https://agent.tinyfish.ai/mcp";
+export declare const API_KEY_GUIDANCE = "Set TINYFISH_API_KEY \u2014 get a key at https://agent.tinyfish.ai";
+export interface Config {
+    /** Never log this field. */
+    apiKey: string;
+    port: number;
+    upstreamUrl: string;
+}
+/** Thrown by parseConfig; `message` is the actionable stderr line(s) for the user. */
+export declare class ConfigError extends Error {
+}
+/**
+ * Pure env → Config parser. Throws ConfigError with an actionable message on
+ * invalid input; performs no I/O and never touches process state.
+ */
+export declare function parseConfig(env: Record<string, string | undefined>): Config;

package/dist/config.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export const DEFAULT_PORT = 3711;
+export const DEFAULT_UPSTREAM_URL = "https://agent.tinyfish.ai/mcp";
+export const API_KEY_GUIDANCE = "Set TINYFISH_API_KEY — get a key at https://agent.tinyfish.ai";
+/** Thrown by parseConfig; `message` is the actionable stderr line(s) for the user. */
+export class ConfigError extends Error {
+}
+const envSchema = z.object({
+    TINYFISH_API_KEY: z.string({ error: API_KEY_GUIDANCE }).min(1, { error: API_KEY_GUIDANCE }),
+    PORT: z
+        .string()
+        .optional()
+        .transform((value, ctx) => {
+        if (value === undefined)
+            return DEFAULT_PORT;
+        const port = /^\d+$/.test(value) ? Number(value) : NaN;
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Invalid PORT "${value}" — must be an integer between 1 and 65535`,
+            });
+            return z.NEVER;
+        }
+        return port;
+    }),
+    TINYFISH_UPSTREAM_URL: z
+        .string()
+        .optional()
+        .transform((value, ctx) => {
+        const raw = value ?? DEFAULT_UPSTREAM_URL;
+        let url;
+        // Error messages never echo the raw value: it may embed credentials or
+        // query-string secrets, and these messages go to stderr.
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            ctx.addIssue({
+                code: "custom",
+                message: "Invalid TINYFISH_UPSTREAM_URL — must be an absolute URL",
+            });
+            return z.NEVER;
+        }
+        if (url.username !== "" || url.password !== "") {
+            ctx.addIssue({
+                code: "custom",
+                message: "Invalid TINYFISH_UPSTREAM_URL — URL credentials are not allowed",
+            });
+            return z.NEVER;
+        }
+        const isLoopback = url.hostname === "127.0.0.1" || url.hostname === "localhost";
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+            ctx.addIssue({
+                code: "custom",
+                message: "Invalid TINYFISH_UPSTREAM_URL — scheme must be https " +
+                    "(http is allowed only for 127.0.0.1/localhost)",
+            });
+            return z.NEVER;
+        }
+        return raw;
+    }),
+});
+/**
+ * Pure env → Config parser. Throws ConfigError with an actionable message on
+ * invalid input; performs no I/O and never touches process state.
+ */
+export function parseConfig(env) {
+    const parsed = envSchema.safeParse(env);
+    if (!parsed.success) {
+        throw new ConfigError(parsed.error.issues.map((issue) => issue.message).join("\n"));
+    }
+    return {
+        apiKey: parsed.data.TINYFISH_API_KEY,
+        port: parsed.data.PORT,
+        upstreamUrl: parsed.data.TINYFISH_UPSTREAM_URL,
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Typed transport-level errors thrown by the proxy core, plus the only
+ * client-facing shaping functions: `toJsonRpcError` for pre-stream failures
+ * and `toStreamErrorFrame` for failures after an SSE relay started. Every
+ * adapter catch path routes through these two functions — no ad-hoc error
+ * bodies anywhere else, with exactly two deliberate exceptions: the adapter's
+ * ParseError reply (http/adapter.ts — built where the unparseable body is
+ * caught, since there is nothing to route), and the last-resort -32603
+ * backstop in http/index.ts's invokeSafely. Messages must never contain the
+ * API key (they describe network/protocol conditions only).
+ *
+ * HTTP status decision for locally shaped errors: the hosted server maps
+ * client-error JSON-RPC codes to HTTP 400 and everything else to 500. The
+ * proxy mirrors the 400 for client errors (-32700 ParseError) and picks
+ * **502 Bad Gateway** for the upstream-leg failures it shapes itself (-32000
+ * unreachable/stream-failed, -32001 auth rejection): the proxy is healthy,
+ * the upstream hop failed — distinguishing these from a genuine local proxy
+ * bug, which stays **500** with -32603 InternalError. Upstream-originated
+ * JSON-RPC errors are never shaped at all: they forward verbatim under
+ * upstream's own HTTP status.
+ */
+/** JSON-RPC error codes used by locally shaped errors. */
+export declare const JsonRpcErrorCodes: {
+    /** Upstream unreachable / upstream stream failed (server-side, HTTP 502). */
+    readonly UpstreamUnavailable: -32000;
+    /** Upstream rejected auth — check TINYFISH_API_KEY (HTTP 502). */
+    readonly UpstreamAuth: -32001;
+    /** Local proxy bug (HTTP 500). */
+    readonly InternalError: -32603;
+    /** Malformed client JSON (HTTP 400, id -1 — mirrors upstream). */
+    readonly ParseError: -32700;
+};
+/** Base class for all proxy-core errors (transport level, not JSON-RPC). */
+export declare class ProxyCoreError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The upstream server could not be reached (DNS, TLS, refused, reset). */
+export declare class UpstreamUnreachableError extends ProxyCoreError {
+    /** Upstream "host[:port]" when known — used in the client-facing message. */
+    host?: string;
+}
+/**
+ * Upstream answered 401/403 with a body that is NOT a JSON-RPC message (a
+ * JSON-RPC error body, whatever its HTTP status, forwards verbatim instead).
+ * Carries the upstream status and body text so the shaped
+ * client error can include them as diagnostics. The body text is truncated to
+ * ~2KB at construction; the Error message itself never includes it.
+ */
+export declare class UpstreamAuthError extends ProxyCoreError {
+    readonly status: number;
+    /** Upstream response body text, truncated to AUTH_BODY_LIMIT chars. */
+    readonly bodyText: string;
+    constructor(status: number, bodyText: string, options?: ErrorOptions);
+}
+/**
+ * ~2KB cap on the upstream auth-failure body relayed in error data.
+ *
+ * Measured in UTF-16 code units (String.prototype.slice), not bytes: for
+ * multi-byte scripts the UTF-8 wire size can reach ~3× (≤ ~6KB) — bounded
+ * either way, which is all the "~2KB" contract promises. A slice boundary can
+ * split a surrogate pair; harmless, since Node's well-formed JSON.stringify
+ * escapes the lone surrogate and the response stays valid JSON.
+ */
+export declare const AUTH_BODY_LIMIT = 2048;
+/**
+ * Delivering a relayed SSE frame to the LOCAL client failed (the transport's
+ * onEvent callback rejected — e.g. the client socket died mid-write). This is
+ * a client-side condition, never an upstream one: it must not be logged or
+ * classified as "Upstream unreachable".
+ */
+export declare class LocalWriteError extends ProxyCoreError {
+}
+/** An in-flight upstream request was aborted locally (session close / shutdown). */
+export declare class UpstreamAbortedError extends ProxyCoreError {
+}
+/**
+ * Upstream answered with something the core cannot interpret (non-JSON body,
+ * SSE stream that ends without a final response frame, unexpected empty body).
+ */
+export declare class UpstreamProtocolError extends ProxyCoreError {
+    /** Upstream HTTP status when one was received before the failure. */
+    readonly status?: number;
+    constructor(message: string, status?: number, options?: ErrorOptions);
+}
+/** True for the AbortError DOMException fetch throws when its signal fires. */
+export declare function isAbortError(err: unknown): boolean;
+export interface JsonRpcErrorBody {
+    jsonrpc: "2.0";
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id: unknown;
+}
+/** A shaped failure: the HTTP status to answer with plus the JSON-RPC body. */
+export interface ShapedJsonRpcError {
+    httpStatus: number;
+    body: JsonRpcErrorBody;
+}
+/**
+ * Map a failure the upstream never answered (or answered unusably) to the
+ * client-facing JSON-RPC error + local HTTP status.
+ * Only failures upstream never saw as JSON-RPC get shaped here —
+ * upstream JSON-RPC errors forward verbatim and never reach this function.
+ * Never includes the API key: transport-error messages describe network and
+ * protocol conditions only, and unexpected local errors get a generic message
+ * (their stack goes to stderr at the catch site, not to the client).
+ */
+export declare function toJsonRpcError(failure: unknown, requestId: unknown): ShapedJsonRpcError;
+/**
+ * Build the final SSE-framed JSON-RPC error for a failure AFTER the local SSE
+ * relay started (mid-stream upstream disconnect). A
+ * tools/call may have side effects, so the message warns that the run may
+ * still be executing and is never retried silently; when a run id was already
+ * seen in a progress frame's `_meta.runId` it is included in `data.runId`
+ * (camelCase, matching upstream's `_meta.runId` convention) and named in the
+ * message, else `data` is omitted entirely.
+ *
+ * The -32000 message differentiates the failure kind: a locally aborted
+ * upstream request (session close / shutdown mid-stream) reads differently
+ * from an upstream that died or broke protocol — but both keep the "run may
+ * still be executing" guidance, because in either case a live run could be
+ * left behind upstream.
+ */
+export declare function toStreamErrorFrame(failure: unknown, requestId: unknown, runId?: string): JsonRpcErrorBody;