tinyfish-mcp-lite 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { ConfigError, parseConfig } from "./config.js";
+import { createProxyCore } from "./core/proxy-core.js";
+// FORK(lite): free-tool allowlist — see src/core/tool-filter.ts and FORK.md.
+import { parseToolPolicy, withToolFilter } from "./core/tool-filter.js";
+import { createMcpAdapter } from "./http/adapter.js";
+import { createAppHandler, startHttpServer } from "./http/index.js";
+import { log } from "./log.js";
+import { shutdownHooks } from "./shutdown.js";
+import { VERSION } from "./version.js";
+function isErrnoException(err) {
+    return err instanceof Error && "code" in err;
+}
+async function main() {
+    let config;
+    let toolPolicy; // FORK(lite)
+    try {
+        config = parseConfig(process.env);
+        // FORK(lite): TINYFISH_TOOLS allowlist (default: the free search +
+        // fetch_content; "*" restores unfiltered upstream passthrough).
+        toolPolicy = parseToolPolicy(process.env.TINYFISH_TOOLS);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // The real MCP handler: origin/routing shell → adapter → proxy core.
+    // createProxyCore registers session teardown into shutdownHooks itself.
+    // FORK(lite): the decorator hides non-allowed tools from tools/list and
+    // 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 {
+        server = await startHttpServer(config.port, handler);
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === "EADDRINUSE") {
+            log.error(`Port ${config.port} is already in use — stop the other process or set PORT to a free port`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // The one startup line. Never include config.apiKey here or in any other log call.
+    log.info(`listening on http://127.0.0.1:${config.port} — upstream ${config.upstreamUrl} — v${VERSION}`);
+    // FORK(lite): state the active tool policy so a "missing tool" is never a
+    // mystery. Tool names only — never the API key.
+    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");
+    }
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        server.close();
+        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);
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+}
+main().catch((err) => {
+    log.error(`startup failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/log.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal leveled logger. Writes to stderr only — stdout stays clean for a
+ * future stdio transport. Callers must never pass the API key into a message.
+ */
+export type LogLevel = "info" | "warn" | "error";
+export declare const log: {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+};

package/dist/log.js

@@ -0,0 +1,18 @@
+/**
+ * Minimal leveled logger. Writes to stderr only — stdout stays clean for a
+ * future stdio transport. Callers must never pass the API key into a message.
+ */
+function write(level, message) {
+    process.stderr.write(`tinyfish-mcp [${level}] ${message}\n`);
+}
+export const log = {
+    info(message) {
+        write("info", message);
+    },
+    warn(message) {
+        write("warn", message);
+    },
+    error(message) {
+        write("error", message);
+    },
+};

package/dist/shutdown.d.ts

@@ -0,0 +1,2 @@
+/** Cleanup hooks (e.g. session teardown) run on SIGINT/SIGTERM before exit. */
+export declare const shutdownHooks: Array<() => void | Promise<void>>;

package/dist/shutdown.js

@@ -0,0 +1,2 @@
+/** Cleanup hooks (e.g. session teardown) run on SIGINT/SIGTERM before exit. */
+export const shutdownHooks = [];

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/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Package version, read once at startup. Feeds X-TF-Client-Version upstream. */
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+// Resolves to the package root's package.json from both src/ (dev) and dist/ (published).
+const pkg = require("../package.json");
+/** Package version, read once at startup. Feeds X-TF-Client-Version upstream. */
+export const VERSION = pkg.version;

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "tinyfish-mcp-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "url": "git+https://github.com/ByronFinn/tinyfish-mcp-lite.git"
+  },
+  "homepage": "https://github.com/ByronFinn/tinyfish-mcp-lite#readme",
+  "bugs": {
+    "url": "https://github.com/ByronFinn/tinyfish-mcp-lite/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tinyfish",
+    "web-automation",
+    "browser-automation",
+    "proxy"
+  ],
+  "author": "ByronFinn (fork of TinyFish's tinyfish-mcp-server, MIT)",
+  "type": "module",
+  "license": "MIT",
+  "allowScripts": {
+    "tinyfish-mcp-lite": true,
+    "esbuild": true,
+    "fsevents": true
+  },
+  "bin": {
+    "tinyfish-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:integration": "vitest --run --config vitest.integration.config.ts",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "type-check": "tsc --noEmit --project tsconfig.all.json",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "overrides": {
+    "@vitest/mocker": "^4.1.11",
+    "fast-uri": "^3.1.8",
+    "nanoid": "^3.3.19",
+    "qs": "^6.16.0"
+  }
+}