tinyfish-mcp-lite 0.1.0 → 0.2.0

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

@@ -33,6 +33,31 @@ 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");
+        }
+        await runStdioTransport(core);
+        for (const hook of shutdownHooks) {
+            try {
+                await hook();
+            }
+            catch (err) {
+                log.error(`shutdown hook failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        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 (the client closed its pipe —
+ * MCP stdio shutdown) or `streams.output` errors (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,177 @@
+/**
+ * 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).
+ * - One client, one session: the localKey is the constant "stdio" — the
+ *   core stores the upstream session id on that entry at initialize and
+ *   replays it on every later call. No Mcp-Session-Id plumbing exists here.
+ * - 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), serialized through the same write queue as
+ *   responses.
+ *
+ * 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), and each write respects pipe backpressure: a full
+ * tools/list line is far larger than PIPE_BUF, so writes must never overlap
+ * mid-line. stdin end drains the queue before the run promise resolves, so
+ * the caller's exit never truncates a half-written response.
+ */
+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, so the local session key is a constant. */
+const SESSION_KEY = "stdio";
+/**
+ * Run the transport until `streams.input` ends (the client closed its pipe —
+ * MCP stdio shutdown) or `streams.output` errors (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;
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        input.close();
+        // Drain pending writes before resolving: the caller exits right after,
+        // and process.exit would truncate an in-flight line.
+        void writeChain.finally(() => resolveRun());
+    };
+    const enqueue = (message) => {
+        writeChain = writeChain
+            .then(() => writeLine(streams.output, message))
+            .catch((err) => {
+            // A failed stdout write means the local client is dying (EPIPE);
+            // the output 'error' handler finishes the transport.
+            log.warn(`writing to stdout failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    // 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 handleLine(line) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            return;
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            // Unparseable input: the one message answered without forwarding.
+            enqueue({
+                jsonrpc: "2.0",
+                error: { code: -32700, message: "Parse error: Invalid JSON" },
+                id: null,
+            });
+            return;
+        }
+        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));
+                enqueue(response.body);
+                return;
+            }
+            if (method === "tools/call") {
+                const response = await core.forwardStream(SESSION_KEY, message, onEvent);
+                enqueue(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);
+            enqueue(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)}`);
+            }
+            enqueue(toJsonRpcError(err, requestIdOf(message)).body);
+        }
+    }
+    const input = createInterface({ input: streams.input });
+    input.on("line", (line) => {
+        void handleLine(line);
+    });
+    input.on("close", finish);
+    streams.output.on("error", (err) => {
+        log.warn(`stdout error (client went away?): ${err instanceof Error ? err.message : String(err)}`);
+        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.0",
+  "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",