tinyfish-mcp-lite 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
-# @tiny-fish/mcp
+# tinyfish-mcp-lite
 
-[![npm version](https://img.shields.io/npm/v/@tiny-fish/mcp)](https://www.npmjs.com/package/@tiny-fish/mcp)
+[![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,
@@ -51,31 +51,59 @@ this fork too — with exactly these differences:
 
 ### Install (this fork)
 
-The npm package name below belongs to **upstream** — installing it gets the
-unfiltered server. To use this fork, install it from GitHub (requires
-Node.js >= 22):
+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
-# one-liner (the fork's prepare script builds dist/ during install)
-npm install -g github:ByronFinn/tinyfish-mcp-lite
-TINYFISH_API_KEY=tf_... tinyfish-mcp
+# 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
+TINYFISH_API_KEY=tf_... node dist/index.js             # HTTP
+# TINYFISH_API_KEY=tf_... node dist/index.js --stdio   # stdio
 ```
 
-> **npm ≥ 11.17 with the install-script policy enabled** (an `allow-scripts`
-> entry in your `~/.npmrc`): git-based installs (`npx github:…`,
-> `npm install -g github:…`) fail with `EALLOWSCRIPTS` — a known npm quirk
-> where the policy reaches the inner git-dep build via the environment. Use
-> the clone route instead, then `npm install -g .` from the clone if you
-> want the `tinyfish-mcp` command on your PATH.
+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.
 
-Then point your MCP client at `http://127.0.0.1:3711/mcp` exactly as
-described in [Client configuration](#client-configuration) below.
+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

package/dist/config.js

@@ -6,9 +6,7 @@ export const API_KEY_GUIDANCE = "Set TINYFISH_API_KEY — get a key at https://a
 export class ConfigError extends Error {
 }
 const envSchema = z.object({
-    TINYFISH_API_KEY: z
-        .string({ error: API_KEY_GUIDANCE })
-        .min(1, { error: API_KEY_GUIDANCE }),
+    TINYFISH_API_KEY: z.string({ error: API_KEY_GUIDANCE }).min(1, { error: API_KEY_GUIDANCE }),
     PORT: z
         .string()
         .optional()

package/dist/http/adapter.js

@@ -24,7 +24,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { JsonRpcErrorCodes, LocalWriteError, ProxyCoreError, toJsonRpcError, toStreamErrorFrame, } from "../core/errors.js";
-import { requestIdOf } from "../core/proxy-core.js";
+import { requestIdOf, } from "../core/proxy-core.js";
 import { log } from "../log.js";
 export function createMcpAdapter(core) {
     return async (req, res) => {

package/dist/index.js

@@ -11,14 +11,30 @@ import { VERSION } from "./version.js";
 function isErrnoException(err) {
     return err instanceof Error && "code" in err;
 }
+// FORK(lite): stdio shutdown hook runner — mirrors the HTTP branch's shutdown
+// path (core.closeAll aborts in-flight upstream fetches).
+async function runShutdownHooks() {
+    for (const hook of shutdownHooks) {
+        try {
+            await hook();
+        }
+        catch (err) {
+            log.error(`shutdown hook failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
 async function main() {
+    // FORK(lite): stdio owns no port — drop PORT from the environment the
+    // config parses, so a stray PORT (e.g. copied from another server's client
+    // config block) cannot abort a transport that never listens.
+    const env = process.argv.includes("--stdio") ? { ...process.env, PORT: undefined } : process.env;
     let config;
     let toolPolicy; // FORK(lite)
     try {
-        config = parseConfig(process.env);
+        config = parseConfig(env);
         // FORK(lite): TINYFISH_TOOLS allowlist (default: the free search +
         // fetch_content; "*" restores unfiltered upstream passthrough).
-        toolPolicy = parseToolPolicy(process.env.TINYFISH_TOOLS);
+        toolPolicy = parseToolPolicy(env.TINYFISH_TOOLS);
     }
     catch (err) {
         if (err instanceof ConfigError) {
@@ -33,6 +49,32 @@ async function main() {
     // answers tools/call for them locally — paid tools are never advertised
     // and never invoked upstream.
     const core = withToolFilter(createProxyCore({ upstreamUrl: config.upstreamUrl, apiKey: config.apiKey }), toolPolicy);
+    // FORK(lite): stdio transport — spawn-and-forget mode for clients that
+    // launch their MCP servers as commands (`tinyfish-mcp --stdio`, or
+    // `npx -y tinyfish-mcp-lite --stdio`). Same core, same filter; the client
+    // owns the lifecycle (stdin closed ⇒ exit), so no PORT and no long-running
+    // server. See src/stdio/adapter.ts and FORK.md.
+    if (process.argv.includes("--stdio")) {
+        const { runStdioTransport } = await import("./stdio/adapter.js");
+        log.info(`stdio transport — upstream ${config.upstreamUrl} — v${VERSION}`);
+        if (toolPolicy.mode === "allow") {
+            log.info(`tool filter: exposing [${[...toolPolicy.allowed].join(", ")}] — set TINYFISH_TOOLS=* to expose every upstream tool`);
+        }
+        else {
+            log.info("tool filter: off (TINYFISH_TOOLS=*) — exposing every upstream tool");
+        }
+        // The client normally shuts us down by closing stdin; a signal (client
+        // killed, terminal gone) must still run the hooks — closeAll aborts
+        // in-flight upstream fetches — instead of the default hard exit.
+        const onSignal = () => {
+            void runShutdownHooks().then(() => process.exit(0));
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        await runStdioTransport(core);
+        await runShutdownHooks();
+        process.exit(0);
+    }
     const handler = createAppHandler(createMcpAdapter(core));
     let server;
     try {

package/dist/stdio/adapter.d.ts

@@ -0,0 +1,13 @@
+import type { Readable, Writable } from "node:stream";
+import { type ProxyCore } from "../core/proxy-core.js";
+export interface StdioStreams {
+    input: Readable;
+    output: Writable;
+}
+/**
+ * Run the transport until `streams.input` ends or errors (the client closed
+ * or lost its pipe — MCP stdio shutdown) or `streams.output` errors/closes
+ * (EPIPE: the client died without closing stdin). Resolves void; the caller
+ * runs shutdown hooks and exits.
+ */
+export declare function runStdioTransport(core: ProxyCore, streams?: StdioStreams): Promise<void>;

package/dist/stdio/adapter.js

@@ -0,0 +1,267 @@
+/**
+ * FORK ADDITION (tinyfish-mcp-lite) — this module does not exist upstream.
+ *
+ * stdio transport: spawn-and-forget mode for MCP clients that launch their
+ * servers as commands. The client owns the process lifecycle (stdin closed ⇒
+ * shutdown), no port to manage, no server to start by hand. Newline-delimited
+ * JSON-RPC on stdin/stdout per the MCP stdio spec; every log goes to stderr
+ * (log.ts) so stdout stays protocol-pure — log.ts documents exactly this
+ * contract ("stdout stays clean for a future stdio transport").
+ *
+ * Routing mirrors the HTTP adapter's route() one-to-one (notifications →
+ * notify BEFORE any tools/call check; initialize → initialize; tools/call →
+ * forwardStream; everything else, including forbidden batch arrays and
+ * shapeless bodies, → forward), so the withToolFilter decorator covers both
+ * transports identically: tools/list filtered, hidden tools/call answered
+ * locally, notification-shaped calls dropped, batches rejected — see
+ * tests/stdio.test.ts and tests/tool-filter.test.ts.
+ *
+ * Differences from the HTTP hop that are intrinsic to stdio:
+ * - No status codes, no headers: upstream's JSON-RPC body is the message;
+ *   a JSON-RPC error body relays verbatim, and failures upstream never
+ *   answered as JSON-RPC are shaped through toJsonRpcError (same as HTTP).
+ *   A notification whose upstream hop fails writes NOTHING — JSON-RPC forbids
+ *   replying to notifications, and an id-null error line would be protocol
+ *   garbage to an id-dispatching client; the failure is logged to stderr.
+ * - One client, one session: the localKey is the empty string — the same
+ *   session-less shape the HTTP hop uses — so before initialize bridges the
+ *   real upstream session id, upstream.post omits Mcp-Session-Id entirely and
+ *   no adapter-invented id can reach the wire. While an initialize round-trip
+ *   is outstanding, further lines are queued (JSON-RPC pipelining is legal,
+ *   and the MCP lifecycle even allows pings in this window) and dispatched in
+ *   arrival order once it settles, so they ride the bridged upstream session.
+ * - A parse error answers with id null (JSON-RPC rule for unparseable input)
+ *   rather than the HTTP hop's -1: there is no upstream shape to stay
+ *   byte-compatible with on this transport.
+ * - Progress notifications from a streamed tools/call relay to stdout as
+ *   ordinary JSON-RPC notification lines (MCP stdio allows server → client
+ *   notifications any time). onEvent returns the write promise so the core's
+ *   frame loop awaits each relayed frame — stdout backpressure propagates to
+ *   the upstream stream (the OnEvent contract) and a dead stdout surfaces as
+ *   LocalWriteError instead of being silently swallowed.
+ *
+ * Writes are queued (requests dispatch concurrently — a slow search must not
+ * stall pings — so responses may become ready out of order, which JSON-RPC
+ * ids disambiguate; the queue serializes the write() calls, so lines can
+ * never interleave mid-line) and each write respects pipe backpressure.
+ * Shutdown (stdin close, stdin error, stdout error or close) aborts in-flight
+ * upstream fetches via core.close, waits for the outstanding handlers so
+ * their final (often error) responses still reach a client that is draining
+ * stdout, then drains the write queue before resolving — the caller's exit
+ * never truncates a half-written line.
+ */
+import { createInterface } from "node:readline";
+import { ProxyCoreError, toJsonRpcError } from "../core/errors.js";
+import { requestIdOf } from "../core/proxy-core.js";
+import { log } from "../log.js";
+/** stdio serves exactly one client; "" matches the HTTP hop's session-less shape. */
+const SESSION_KEY = "";
+/**
+ * Run the transport until `streams.input` ends or errors (the client closed
+ * or lost its pipe — MCP stdio shutdown) or `streams.output` errors/closes
+ * (EPIPE: the client died without closing stdin). Resolves void; the caller
+ * runs shutdown hooks and exits.
+ */
+export function runStdioTransport(core, streams = { input: process.stdin, output: process.stdout }) {
+    let resolveRun;
+    const run = new Promise((resolve) => {
+        resolveRun = resolve;
+    });
+    let writeChain = Promise.resolve();
+    let finished = false;
+    let inflight = 0;
+    let inflightSettled = null;
+    let initGate = null;
+    const gatedLines = [];
+    /**
+     * Chain a write onto the queue and hand the promise back — onEvent returns
+     * it so upstream SSE frames are relayed one awaited write at a time.
+     */
+    const enqueue = (message) => {
+        const write = writeChain.then(() => writeLine(streams.output, message));
+        // Keep the queue alive after a failed write (dying client); `write`
+        // itself still rejects, preserving the LocalWriteError contract.
+        writeChain = write.then(() => undefined, () => undefined);
+        return write;
+    };
+    /** Fire-and-forget enqueue for responses; a failed stdout write is logged. */
+    const emit = (message) => {
+        void enqueue(message).catch((err) => {
+            log.warn(`writing to stdout failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        input.close();
+        void (async () => {
+            // Abort in-flight upstream fetches for this session so the handlers
+            // below settle promptly (idempotent — the caller's shutdown hooks run
+            // core.closeAll() on top, covering the rest of the session store).
+            core.close(SESSION_KEY);
+            // Let the outstanding handlers land their final responses before the
+            // drain below captures the queue, so a client still draining stdout
+            // receives them instead of a truncated stream.
+            if (inflight > 0) {
+                await new Promise((resolve) => {
+                    inflightSettled = resolve;
+                });
+            }
+            await writeChain;
+            resolveRun();
+        })();
+    };
+    const settleInflight = () => {
+        inflight -= 1;
+        if (inflight === 0 && inflightSettled !== null) {
+            const settle = inflightSettled;
+            inflightSettled = null;
+            settle();
+        }
+    };
+    // Relayed SSE progress frames (free tools never stream today, but the
+    // relay must exist so the stdio path can never orphan upstream progress).
+    const onEvent = (event) => enqueue(event);
+    async function routeMessage(message) {
+        try {
+            if (isNotification(message)) {
+                await core.notify(SESSION_KEY, message);
+                return;
+            }
+            const method = methodOf(message);
+            if (method === "initialize") {
+                const response = await core.initialize(SESSION_KEY, message, protocolVersionOf(message));
+                emit(response.body);
+                return;
+            }
+            if (method === "tools/call") {
+                const response = await core.forwardStream(SESSION_KEY, message, onEvent);
+                emit(response.body);
+                return;
+            }
+            // Everything else — ping, tools/list, resources/*, client responses to
+            // (never-initiated) server requests, unknown methods, and batch arrays —
+            // forwards generically, byte-for-byte the HTTP adapter's fallthrough.
+            const response = await core.forward(SESSION_KEY, message);
+            emit(response.body);
+        }
+        catch (err) {
+            // Same classification as the HTTP adapter: classified core errors log
+            // their message; anything else is a proxy bug (full stack, generic
+            // InternalError to the client).
+            if (err instanceof ProxyCoreError) {
+                log.warn(err.message);
+            }
+            else {
+                log.error(`proxy bug (client got a generic InternalError): ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            }
+            // A notification has no response channel — JSON-RPC forbids replying
+            // to one, so its upstream failure only logs (see module comment).
+            if (!isNotification(message)) {
+                emit(toJsonRpcError(err, requestIdOf(message)).body);
+            }
+        }
+    }
+    async function dispatchMessage(message) {
+        inflight += 1;
+        try {
+            await routeMessage(message);
+        }
+        finally {
+            settleInflight();
+        }
+    }
+    function handleLine(line) {
+        if (finished)
+            return;
+        const trimmed = line.trim();
+        if (trimmed === "")
+            return;
+        if (initGate !== null) {
+            // Pipelined behind an in-flight initialize: queued, dispatched in
+            // arrival order once it settles (see module comment).
+            gatedLines.push(trimmed);
+            return;
+        }
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            // Unparseable input: the one message answered without forwarding.
+            emit({
+                jsonrpc: "2.0",
+                error: { code: -32700, message: "Parse error: Invalid JSON" },
+                id: null,
+            });
+            return;
+        }
+        if (!isNotification(message) && methodOf(message) === "initialize") {
+            // Install the gate before any await so lines arriving during the
+            // round-trip hit the queue above, then flush it in order.
+            const gate = dispatchMessage(message);
+            initGate = gate;
+            void gate.finally(() => {
+                initGate = null;
+                if (!finished) {
+                    for (const queued of gatedLines.splice(0))
+                        handleLine(queued);
+                }
+            });
+            return;
+        }
+        void dispatchMessage(message);
+    }
+    const input = createInterface({ input: streams.input });
+    input.on("line", (line) => {
+        handleLine(line);
+    });
+    // readline re-emits an input-stream error here; without this listener the
+    // 'error' event is unhandled (crash, hooks never run) and 'close' never
+    // fires afterwards — hence the explicit finish().
+    input.on("error", (err) => {
+        log.warn(`stdin error: ${err instanceof Error ? err.message : String(err)}`);
+        finish();
+    });
+    input.on("close", finish);
+    streams.output.on("error", (err) => {
+        log.warn(`stdout error (client went away?): ${err instanceof Error ? err.message : String(err)}`);
+        finish();
+    });
+    // stdout destroyed without an error event (silent destroy): still shut down.
+    streams.output.on("close", finish);
+    return run;
+}
+/** One JSON-RPC message per line; resolves on kernel-buffer flush or drain. */
+function writeLine(output, message) {
+    return new Promise((resolve, reject) => {
+        const ok = output.write(`${JSON.stringify(message)}\n`, (err) => err ? reject(err) : resolve());
+        if (!ok)
+            output.once("drain", () => resolve());
+    });
+}
+/** JSON-RPC notification: an object with a method and no id key (upstream's rule). */
+function isNotification(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        !Array.isArray(message) &&
+        typeof message.method === "string" &&
+        !("id" in message));
+}
+function methodOf(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const method = message.method;
+    return typeof method === "string" ? method : undefined;
+}
+/** `initialize.params.protocolVersion`, when the client sent one. */
+function protocolVersionOf(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const params = message.params;
+    if (typeof params !== "object" || params === null)
+        return undefined;
+    const version = params.protocolVersion;
+    return typeof version === "string" ? version : undefined;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tinyfish-mcp-lite",
-  "version": "0.1.0",
-  "description": "Fork of @tiny-fish/mcp exposing only the free TinyFish tools (search, fetch_content) \u2014 local reverse proxy to agent.tinyfish.ai/mcp",
+  "version": "0.2.1",
+  "description": "Fork of @tiny-fish/mcp exposing only the free TinyFish tools (search, fetch_content) — local reverse proxy to agent.tinyfish.ai/mcp",
   "mcpName": "io.github.ByronFinn/tinyfish-mcp-lite",
   "repository": {
     "type": "git",