tinyfish-mcp-lite 0.0.0-stage → 0.1.0

package/dist/core/session.js

@@ -0,0 +1,89 @@
+/**
+ * Session bridging state.
+ *
+ * The proxy relays session headers verbatim: the client re-sends upstream's
+ * own Mcp-Session-Id, so localKey is normally the upstream-issued id itself
+ * and the map's main job is abort tracking for in-flight upstream fetches.
+ * The upstreamSessionId / protocolVersion fields cost nothing and keep the
+ * door open for a future stdio transport that needs real id bridging.
+ *
+ * Close is local-only cleanup: the hosted server has no DELETE endpoint, so
+ * teardown just aborts in-flight fetches and drops the entry.
+ *
+ * Growth characteristic (deliberate): entries are created on first use and
+ * removed only by close()/closeAll(). The HTTP surface has no client-driven
+ * teardown signal (clients cannot DELETE), so a long-running proxy
+ * accumulates one small entry per distinct session key until process shutdown
+ * runs closeAll() via the shutdown hook. That is acceptable for a local
+ * single-user proxy — entries are a few strings plus an empty Set. Call
+ * core.close(localKey) wherever a transport does learn of a session's end
+ * (e.g. a future stdio transport's disconnect); an idle TTL can be added
+ * later if a real leak ever materializes.
+ */
+export class SessionStore {
+    sessions = new Map();
+    get size() {
+        return this.sessions.size;
+    }
+    get(localKey) {
+        return this.sessions.get(localKey);
+    }
+    has(localKey) {
+        return this.sessions.has(localKey);
+    }
+    /** Create-on-first-use lookup. */
+    getOrCreate(localKey) {
+        let entry = this.sessions.get(localKey);
+        if (entry === undefined) {
+            entry = { inflight: new Set() };
+            this.sessions.set(localKey, entry);
+        }
+        return entry;
+    }
+    /**
+     * Map an additional key to an existing entry. Used by initialize() to make
+     * the upstream-issued Mcp-Session-Id resolve to the same session as the
+     * initialize-time local key: the client re-sends upstream's id, so later
+     * calls arrive keyed by that id.
+     */
+    alias(aliasKey, entry) {
+        this.sessions.set(aliasKey, entry);
+    }
+    /**
+     * Register a new in-flight upstream request for the session, creating the
+     * session on first use. Pair with endRequest once the request settles.
+     */
+    beginRequest(localKey) {
+        const controller = new AbortController();
+        this.getOrCreate(localKey).inflight.add(controller);
+        return controller;
+    }
+    /** Forget a settled request's controller (no-op if the session was closed). */
+    endRequest(localKey, controller) {
+        this.sessions.get(localKey)?.inflight.delete(controller);
+    }
+    /**
+     * Local-only teardown: abort every in-flight upstream fetch for the session
+     * and drop the entry — including every alias key that maps to the same
+     * entry. No upstream DELETE — the hosted server has no DELETE endpoint.
+     */
+    close(localKey) {
+        const entry = this.sessions.get(localKey);
+        if (entry === undefined)
+            return;
+        for (const [key, value] of this.sessions) {
+            if (value === entry)
+                this.sessions.delete(key);
+        }
+        for (const controller of entry.inflight) {
+            controller.abort();
+        }
+        entry.inflight.clear();
+    }
+    /** Close every session (shutdown path). */
+    closeAll() {
+        for (const localKey of [...this.sessions.keys()]) {
+            this.close(localKey);
+        }
+    }
+}

package/dist/core/sse.d.ts

@@ -0,0 +1,20 @@
+export interface SseEvent {
+    /** The data payload parsed as JSON (every upstream frame is one JSON-RPC message). */
+    message: unknown;
+    /**
+     * The exact data payload string: field values of every `data:` line in the
+     * block, joined with "\n". Relay this verbatim (re-split on "\n" into
+     * `data:` lines when re-framing) to preserve upstream's bytes.
+     */
+    rawData: string;
+    /** `event:` field value, if the block carried one (unused upstream). */
+    event?: string;
+    /** `id:` field value, if the block carried one (unused upstream). */
+    id?: string;
+}
+/**
+ * Parse an SSE byte stream into events. Throws UpstreamProtocolError when a
+ * data payload is not valid JSON; stream read failures propagate as-is (the
+ * consumer maps them to transport errors).
+ */
+export declare function parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent, void, undefined>;

package/dist/core/sse.js

@@ -0,0 +1,123 @@
+/**
+ * Incremental SSE parser over a ReadableStream<Uint8Array>.
+ *
+ * Handles chunk boundaries
+ * anywhere — mid-line, mid-event, mid-CRLF, even mid-UTF-8-codepoint (the
+ * streaming TextDecoder holds partial sequences) — per the SSE processing
+ * model:
+ *
+ * - Lines end with LF or CRLF (upstream sends LF; CRLF tolerated).
+ * - `data:` field values accumulate; multi-line data is joined with "\n".
+ * - `event:` / `id:` fields are tolerated and surfaced (currently unused
+ *   upstream — every real frame is a bare `data:` line).
+ * - `:` comment lines are consumed, never forwarded.
+ * - `retry:` and unknown fields are ignored.
+ * - A blank line dispatches the pending event; blocks without any `data:`
+ *   field dispatch nothing (spec behavior — comments/ids alone are dropped).
+ * - A stream that ends without a trailing blank line still dispatches its
+ *   pending event.
+ *
+ * Each yielded event carries BOTH the parsed JSON and the raw joined data
+ * payload string, so a relaying transport can pipe upstream's original bytes
+ * through untouched instead of re-serializing.
+ *
+ * Teardown: breaking out of (or throwing from) a for-await over this
+ * generator runs its return path, which ends the inner for-await over the
+ * stream and cancels the ReadableStream — no orphaned upstream reads.
+ */
+import { UpstreamProtocolError } from "./errors.js";
+/**
+ * Parse an SSE byte stream into events. Throws UpstreamProtocolError when a
+ * data payload is not valid JSON; stream read failures propagate as-is (the
+ * consumer maps them to transport errors).
+ */
+export async function* parseSseStream(stream) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let dataLines = null;
+    let eventField;
+    let idField;
+    /** Fold one complete line into the pending event; return it when dispatched. */
+    const processLine = (line) => {
+        if (line === "") {
+            // Blank line: dispatch the pending event, if it carried any data.
+            const pending = dataLines;
+            const event = eventField;
+            const id = idField;
+            dataLines = null;
+            eventField = undefined;
+            idField = undefined;
+            if (pending === null)
+                return undefined;
+            const rawData = pending.join("\n");
+            return { message: parseJsonPayload(rawData), rawData, event, id };
+        }
+        if (line.startsWith(":"))
+            return undefined; // comment — consumed
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1); // spec: strip one leading space
+        switch (field) {
+            case "data":
+                (dataLines ??= []).push(value);
+                break;
+            case "event":
+                eventField = value;
+                break;
+            case "id":
+                idField = value;
+                break;
+            default:
+                // retry: and unknown fields — ignored.
+                break;
+        }
+        return undefined;
+    };
+    for await (const chunk of stream) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let newline;
+        while ((newline = buffer.indexOf("\n")) !== -1) {
+            let line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            // CRLF: the CR waits in the buffer until its LF arrives, so a CRLF pair
+            // split across chunks needs no special casing — just strip it here.
+            if (line.endsWith("\r"))
+                line = line.slice(0, -1);
+            const event = processLine(line);
+            if (event !== undefined)
+                yield event;
+        }
+    }
+    // Stream ended: flush the decoder's partial UTF-8 state and any final line
+    // without a trailing newline, then dispatch a pending event (tolerate a
+    // stream that ends without the final blank line).
+    buffer += decoder.decode();
+    if (buffer.length > 0) {
+        let line = buffer;
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        const event = processLine(line);
+        if (event !== undefined)
+            yield event;
+    }
+    const flushed = processLine("");
+    if (flushed !== undefined)
+        yield flushed;
+}
+/**
+ * Every upstream frame must be a JSON-RPC message. An empty `data:` payload is
+ * therefore a protocol violation too (JSON.parse("") throws): it surfaces as
+ * UpstreamProtocolError, same as any other non-JSON payload.
+ */
+function parseJsonPayload(rawData) {
+    try {
+        return JSON.parse(rawData);
+    }
+    catch (err) {
+        throw new UpstreamProtocolError("Upstream SSE frame is not valid JSON", undefined, {
+            cause: err,
+        });
+    }
+}

package/dist/core/tool-filter.d.ts

@@ -0,0 +1,48 @@
+import { type ProxyCore } from "./proxy-core.js";
+/** The two tools the hosted server serves for free. */
+export declare const DEFAULT_ALLOWED_TOOLS: readonly string[];
+/** Env var: comma-separated tool allowlist, or "*" to disable filtering. */
+export declare const TOOLS_ENV_VAR = "TINYFISH_TOOLS";
+/**
+ * `allow` exposes only the listed tools (insertion-ordered for the startup
+ * log); `passthrough` disables the filter entirely (upstream verbatim).
+ */
+export type ToolPolicy = {
+    mode: "allow";
+    allowed: ReadonlySet<string>;
+} | {
+    mode: "passthrough";
+};
+/**
+ * Parse TINYFISH_TOOLS. Undefined → the free-tool default; "*" → passthrough;
+ * otherwise a strict comma-separated list (each entry trimmed, deduped,
+ * order-preserving). Throws ConfigError with an actionable message on
+ * malformed input — same contract as parseConfig in config.ts.
+ */
+export declare function parseToolPolicy(raw: string | undefined): ToolPolicy;
+/**
+ * Wrap a ProxyCore with the policy. Passthrough returns the core itself
+ * (identity — zero overhead, zero behavior change). Otherwise every
+ * tools/list response has non-allowed tools stripped (result key order and
+ * nextCursor preserved; error or unexpected shapes relayed untouched), and
+ * every tools/call naming a hidden tool is answered LOCALLY with the same
+ * JSON-RPC error the hosted server itself produces for an unknown tool —
+ * the request never reaches upstream, so it can never bill.
+ *
+ * Not intercepted, by design:
+ * - initialize/resources/* — delegated verbatim (fork policy is about tools
+ *   only; anything else would diverge from upstream for no token win).
+ *
+ * Also closed (defense in depth — the no-paid-call guarantee must not
+ * depend on upstream behavior):
+ * - tools/call shaped as a NOTIFICATION (no id): the adapter routes
+ *   notifications through notify(), which would otherwise forward verbatim;
+ *   hidden-tool ones are swallowed locally (notifications have no response
+ *   channel, so a silent drop is indistinguishable from upstream's 204).
+ * - JSON-RPC batch ARRAYS carrying a hidden tools/call: MCP forbids
+ *   batching and the hosted server rejects batches as InvalidRequest, but
+ *   JSON-RPC 2.0 permits them — a batch-capable upstream change must not
+ *   silently widen the filter. Batches containing hidden-tool calls are
+ *   rejected locally with the exact shape upstream produces today.
+ */
+export declare function withToolFilter(core: ProxyCore, policy: ToolPolicy): ProxyCore;

package/dist/core/tool-filter.js

@@ -0,0 +1,213 @@
+/**
+ * FORK ADDITION (tinyfish-mcp-lite) — this module does not exist upstream.
+ *
+ * Free-tool allowlist for the fork: the hosted TinyFish server exposes 28
+ * tools, but only `search` and `fetch_content` are free — every other tool
+ * costs credits the account may not have, while its schema still lands in
+ * the client's context and burns tokens on each session (filtering to the
+ * two free tools cuts the tools/list payload by ~72%). This module hides
+ * everything else from the client AND blocks calls to hidden tools locally,
+ * so a hallucinated tool name can never reach the paid upstream path.
+ *
+ * Design constraints (see FORK.md):
+ * - Upstream files stay untouched except the two-line wiring in index.ts —
+ *   all fork logic lives in this fork-owned module, so `git merge
+ *   upstream/main` stays conflict-free by construction.
+ * - Implemented as a ProxyCore decorator, not an adapter change: the adapter
+ *   routes every tools/call through forwardStream and every tools/list
+ *   through forward, so decorating those two methods covers both directions
+ *   (advertise and invoke) without touching request parsing or SSE relay.
+ * - TINYFISH_TOOLS="*" restores byte-identical upstream passthrough.
+ */
+import { ConfigError } from "../config.js";
+import { log } from "../log.js";
+import { requestIdOf } from "./proxy-core.js";
+/** The two tools the hosted server serves for free. */
+export const DEFAULT_ALLOWED_TOOLS = ["search", "fetch_content"];
+/** Env var: comma-separated tool allowlist, or "*" to disable filtering. */
+export const TOOLS_ENV_VAR = "TINYFISH_TOOLS";
+/** Tool names MCP permits: letters, digits, `_`, `-`, `.` (defensive superset). */
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+/**
+ * Parse TINYFISH_TOOLS. Undefined → the free-tool default; "*" → passthrough;
+ * otherwise a strict comma-separated list (each entry trimmed, deduped,
+ * order-preserving). Throws ConfigError with an actionable message on
+ * malformed input — same contract as parseConfig in config.ts.
+ */
+export function parseToolPolicy(raw) {
+    if (raw === undefined) {
+        return { mode: "allow", allowed: new Set(DEFAULT_ALLOWED_TOOLS) };
+    }
+    const value = raw.trim();
+    if (value === "*") {
+        return { mode: "passthrough" };
+    }
+    if (value === "") {
+        throw new ConfigError(`Invalid ${TOOLS_ENV_VAR} "${raw}" — list at least one tool name (comma-separated) or "*" for all upstream tools`);
+    }
+    const seen = new Set();
+    for (const entry of value.split(",")) {
+        const name = entry.trim();
+        if (!TOOL_NAME_PATTERN.test(name)) {
+            throw new ConfigError(`Invalid ${TOOLS_ENV_VAR} entry "${entry}" — tool names may contain only letters, digits, "_", "-", "."`);
+        }
+        seen.add(name);
+    }
+    return { mode: "allow", allowed: seen };
+}
+/**
+ * Wrap a ProxyCore with the policy. Passthrough returns the core itself
+ * (identity — zero overhead, zero behavior change). Otherwise every
+ * tools/list response has non-allowed tools stripped (result key order and
+ * nextCursor preserved; error or unexpected shapes relayed untouched), and
+ * every tools/call naming a hidden tool is answered LOCALLY with the same
+ * JSON-RPC error the hosted server itself produces for an unknown tool —
+ * the request never reaches upstream, so it can never bill.
+ *
+ * Not intercepted, by design:
+ * - initialize/resources/* — delegated verbatim (fork policy is about tools
+ *   only; anything else would diverge from upstream for no token win).
+ *
+ * Also closed (defense in depth — the no-paid-call guarantee must not
+ * depend on upstream behavior):
+ * - tools/call shaped as a NOTIFICATION (no id): the adapter routes
+ *   notifications through notify(), which would otherwise forward verbatim;
+ *   hidden-tool ones are swallowed locally (notifications have no response
+ *   channel, so a silent drop is indistinguishable from upstream's 204).
+ * - JSON-RPC batch ARRAYS carrying a hidden tools/call: MCP forbids
+ *   batching and the hosted server rejects batches as InvalidRequest, but
+ *   JSON-RPC 2.0 permits them — a batch-capable upstream change must not
+ *   silently widen the filter. Batches containing hidden-tool calls are
+ *   rejected locally with the exact shape upstream produces today.
+ */
+export function withToolFilter(core, policy) {
+    if (policy.mode === "passthrough") {
+        return core;
+    }
+    const allowed = policy.allowed;
+    function filterToolsListBody(body) {
+        if (typeof body !== "object" || body === null)
+            return body;
+        const result = body.result;
+        if (typeof result !== "object" || result === null)
+            return body;
+        const tools = result.tools;
+        if (!Array.isArray(tools))
+            return body;
+        const kept = tools.filter((tool) => typeof tool === "object" &&
+            tool !== null &&
+            typeof tool.name === "string" &&
+            allowed.has(tool.name));
+        if (kept.length === tools.length)
+            return body;
+        // Spread re-assignment keeps every original key in place (including
+        // `tools` at its original position and any `nextCursor`), so the
+        // re-serialized response stays byte-stable apart from removed entries.
+        return {
+            ...body,
+            result: { ...result, tools: kept },
+        };
+    }
+    return {
+        // Delegated methods are copied by reference — the decorator overrides
+        // only the routing methods below. No `this` anywhere (the underlying
+        // core is a plain object literal, like the decorator).
+        ...core,
+        async forward(localKey, request, clientProtocolVersion) {
+            if (containsHiddenToolCall(request, allowed)) {
+                // Batch array with a hidden tools/call inside: answer locally with
+                // the same rejection the hosted server produces for batches today
+                // (HTTP 400 / -32600), so client behavior is unchanged while the
+                // fork — not upstream — owns the no-paid-call property.
+                return invalidBatchResponse();
+            }
+            const response = await core.forward(localKey, request, clientProtocolVersion);
+            if (requestMethodOf(request) !== "tools/list")
+                return response;
+            return { ...response, body: filterToolsListBody(response.body) };
+        },
+        async forwardStream(localKey, request, onEvent, clientProtocolVersion, signal) {
+            const name = calledToolNameOf(request);
+            if (name !== undefined && !allowed.has(name)) {
+                return blockedToolResponse(request, name);
+            }
+            return core.forwardStream(localKey, request, onEvent, clientProtocolVersion, signal);
+        },
+        async notify(localKey, notification, clientProtocolVersion) {
+            // A tools/call without an id is protocol-invalid but the adapter
+            // forwards ANY notification verbatim — close that path: hidden-tool
+            // calls are dropped locally (the adapter still answers the client
+            // 204, exactly like upstream's notification path).
+            const name = calledToolNameOf(notification);
+            if (name !== undefined && !allowed.has(name)) {
+                log.warn(`dropped tools/call notification for hidden tool "${name}" — notifications have no response channel`);
+                return;
+            }
+            return core.notify(localKey, notification, clientProtocolVersion);
+        },
+    };
+}
+/** The hosted server's batch rejection, mirrored byte-for-byte. */
+function invalidBatchResponse() {
+    return {
+        status: 400,
+        body: {
+            jsonrpc: "2.0",
+            error: { code: -32600, message: "Invalid JSON-RPC 2.0 request format" },
+            id: -1,
+        },
+        sessionId: null,
+        contentType: "application/json",
+    };
+}
+/** True only for ARRAY requests (MCP-forbidden batches) hiding a blocked call. */
+function containsHiddenToolCall(request, allowed) {
+    if (!Array.isArray(request))
+        return false;
+    return request.some((element) => {
+        const name = calledToolNameOf(element);
+        return name !== undefined && !allowed.has(name);
+    });
+}
+/**
+ * The local answer for a hidden tool. Mirrors the hosted server's own
+ * unknown-tool error — JSON-RPC -32602 "Unknown tool: <name>", client-error
+ * code mapped to HTTP 400 — so a client cannot tell the block apart from
+ * calling a genuinely nonexistent tool upstream, and no paid request is
+ * ever sent. Upstream echoes no session id on locally synthesized answers.
+ */
+function blockedToolResponse(request, name) {
+    return {
+        status: 400,
+        body: {
+            jsonrpc: "2.0",
+            error: { code: -32602, message: `Unknown tool: ${name}` },
+            id: requestIdOf(request),
+        },
+        sessionId: null,
+        contentType: "application/json",
+    };
+}
+/** The JSON-RPC method of a request message, if it is a string. */
+function requestMethodOf(request) {
+    if (typeof request !== "object" || request === null)
+        return undefined;
+    const method = request.method;
+    return typeof method === "string" ? method : undefined;
+}
+/**
+ * The tool name of a tools/call request. Undefined when the request is not
+ * a tools/call or carries no string name — those forward upstream and let
+ * the hosted server produce its own (authoritative) error.
+ */
+function calledToolNameOf(request) {
+    if (requestMethodOf(request) !== "tools/call")
+        return undefined;
+    if (typeof request !== "object" || request === null)
+        return undefined;
+    const params = request.params;
+    if (typeof params !== "object" || params === null)
+        return undefined;
+    const name = params.name;
+    return typeof name === "string" && name !== "" ? name : undefined;
+}

package/dist/core/upstream.d.ts

@@ -0,0 +1,58 @@
+import { UpstreamAbortedError, UpstreamUnreachableError } from "./errors.js";
+export type FetchLike = typeof globalThis.fetch;
+export interface UpstreamClientOptions {
+    /** Full upstream MCP URL, e.g. https://agent.tinyfish.ai/mcp */
+    url: string;
+    /** Sent as X-API-Key. Never logged. */
+    apiKey: string;
+    /** Sent as X-TF-Client-Version; defaults to the package version. */
+    clientVersion?: string;
+    /** Injectable fetch for tests; defaults to globalThis.fetch. */
+    fetchFn?: FetchLike;
+}
+export interface UpstreamCallOptions {
+    /** Replayed as Mcp-Session-Id when known. */
+    sessionId?: string;
+    /** Client's MCP-Protocol-Version, passed through when the client sent one. */
+    protocolVersion?: string;
+    /** Aborts the request and any in-progress body read. */
+    signal?: AbortSignal;
+}
+/**
+ * Response classification. Transport failures are not a variant — they are
+ * thrown as typed errors (UpstreamUnreachableError / UpstreamAbortedError).
+ */
+export type UpstreamResponse = {
+    kind: "json";
+    status: number;
+    /** Mcp-Session-Id echoed by upstream (JSON responses only). */
+    sessionId: string | null;
+    /** The parsed JSON-RPC response, verbatim — success or error object. */
+    body: unknown;
+    /** Upstream's Content-Type header, verbatim (null if absent). */
+    contentType: string | null;
+} | {
+    kind: "sse";
+    status: number;
+    /** Raw upstream byte stream. Upstream SSE responses carry no session header. */
+    stream: ReadableStream<Uint8Array>;
+} | {
+    /** 204/empty body — upstream's answer to notifications. */
+    kind: "empty";
+    status: number;
+};
+export declare class UpstreamClient {
+    private readonly url;
+    private readonly apiKey;
+    private readonly clientVersion;
+    private readonly fetchFn;
+    constructor(options: UpstreamClientOptions);
+    /** POST one JSON-RPC message upstream and classify the response. */
+    post(message: unknown, options?: UpstreamCallOptions): Promise<UpstreamResponse>;
+}
+/**
+ * Map a fetch/stream failure to a typed transport error. Never includes the
+ * key. When `url` is given (the fetch call site knows it), the upstream host
+ * is attached so the error shaping can name it in the client-facing message.
+ */
+export declare function toTransportError(err: unknown, url?: string): UpstreamAbortedError | UpstreamUnreachableError;