@toolgrain/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keshav Katwe
+
+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,92 @@
-# Temporary Holding Version
+# @toolgrain/node
 
-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.
+Node.js stdio and HTTP transports for Toolgrain MCP servers. Tools and server
+composition live in
+[@toolgrain/mcp](https://github.com/keshavkatwe/toolgrain/tree/main/packages/mcp#readme).
+
+## Installation
+
+Install the same `0.1.0` version across Toolgrain libraries.
+
+```sh
+npm install @toolgrain/node@0.1.0 @toolgrain/mcp@0.1.0 zod
+npm install --save-dev typescript @types/node
+```
+
+Node-facing declarations use Node types, so TypeScript applications need
+`@types/node` in their development dependencies.
+
+## Own an HTTP listener
+
+```ts
+import { createServer, tool } from "@toolgrain/mcp";
+import { http } from "@toolgrain/node";
+import { z } from "zod";
+
+const server = createServer({
+  name: "hello-http",
+  version: "1.0.0",
+  tools: {
+    greet: tool({
+      input: z.object({ name: z.string().min(1) }),
+      execute: ({ name }) => `Hello, ${name}!`,
+    }),
+  },
+});
+
+const transport = http({ port: 3000 });
+await server.listen(transport);
+console.error(`MCP port: ${transport.address()?.port}`);
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.once(signal, () => {
+    void server.close();
+  });
+}
+```
+
+Save as `server.mts`, compile with TypeScript using
+`--strict --module NodeNext --target ES2022`, and run `node server.mjs`.
+The endpoint defaults to `http://127.0.0.1:3000/mcp`. `server.close()` closes the
+owned listener. Toolgrain installs no process signal handlers; the example adds
+its own shutdown handling.
+
+## Stdio and existing listeners
+
+To use the same unprotected tool definitions over stdio, import `stdio` from
+`@toolgrain/node` and attach `stdio()` to a fresh server instead of `http()`.
+`stdio({ input?, output?, maxMessageBytes? })` defaults to process stdin/stdout
+and a 1 MiB incoming-message limit. EOF closes the transport. Application logs
+must go to stderr. Closing detaches listeners and pauses input without ending
+supplied streams or exiting the process. See the complete
+[stdio example](https://github.com/keshavkatwe/toolgrain/tree/main/apps/stdio-example).
+
+Use `createNodeHttpHandler(server, options?)` with an existing Node HTTP listener
+or Express. Mount the combined handler at the root before body parsing; it owns
+MCP and optional auth-metadata routing, while your application owns shutdown.
+See the [Express example](https://github.com/keshavkatwe/toolgrain/tree/main/apps/express-example#readme).
+
+Both HTTP entry points support `path`, `allowedHosts`, `allowedOrigins`, and
+`maxMessageBytes`. `http()` additionally accepts `port` and `hostname`; use port
+0 for an available port and `address()` to read a copied bound address. It
+restricts default loopback hosts to the actual port; externally mounted handlers
+default to loopback on any port. Set production hosts explicitly. Applications
+own CORS, TLS, and trusted proxy normalization. Forwarded headers are ignored.
+
+Auth-configured servers require HTTP. See the
+[authorization guide](https://github.com/keshavkatwe/toolgrain/blob/main/docs/authorization.md).
+
+## Requirements and protocol support
+
+ESM only. Node.js `^24.20.0` or Bun `>=1.4.4 <2`; Zod `^4.6.6` through MCP;
+TypeScript 5.5.4 or later with `strict` enabled. Both MCP `2026-07-28` and
+`2025-06-18` are supported over stdio and independent HTTP POSTs with JSON
+responses. See the
+[support policy](https://github.com/keshavkatwe/toolgrain/blob/main/docs/support-policy.md)
+and [client compatibility notes](https://github.com/keshavkatwe/toolgrain/blob/main/docs/compatibility.md).
+
+## License
+
+MIT License, copyright 2026 Keshav Katwe. See the
+[license text](https://github.com/keshavkatwe/toolgrain/blob/main/packages/node/LICENSE).
+Third-party dependencies retain their own licenses.

package/dist/framing.d.ts

@@ -0,0 +1,8 @@
+import type { TransportCallbacks } from "@toolgrain/mcp";
+type DecoderCallbacks = Pick<TransportCallbacks, "onMessage" | "onParseError">;
+/** Collects byte fragments until a newline, then decodes one UTF-8 JSON message. */
+export declare function createMessageDecoder(callbacks: DecoderCallbacks, maxMessageBytes: number): {
+    write(chunk: Buffer): void;
+    end(): void;
+};
+export {};

package/dist/framing.js

@@ -0,0 +1,59 @@
+/** Collects byte fragments until a newline, then decodes one UTF-8 JSON message. */
+export function createMessageDecoder(callbacks, maxMessageBytes) {
+    let fragments = [];
+    let bufferedBytes = 0;
+    const utf8 = new TextDecoder("utf-8", { fatal: true });
+    function append(fragment) {
+        bufferedBytes += fragment.length;
+        if (bufferedBytes > maxMessageBytes)
+            throw new Error(`MCP message exceeds ${maxMessageBytes} bytes`);
+        if (fragment.length)
+            fragments.push(fragment);
+    }
+    function resetBuffer() {
+        fragments = [];
+        bufferedBytes = 0;
+    }
+    function decodeMessage() {
+        const bytes = Buffer.concat(fragments, bufferedBytes);
+        resetBuffer();
+        if (isBlank(bytes))
+            return;
+        let value;
+        try {
+            value = JSON.parse(utf8.decode(bytes));
+        }
+        catch (error) {
+            callbacks.onParseError(error);
+            return;
+        }
+        callbacks.onMessage(value);
+    }
+    return {
+        write(chunk) {
+            let start = 0;
+            for (;;) {
+                const newline = chunk.indexOf(10, start);
+                if (newline < 0) {
+                    append(chunk.subarray(start));
+                    return;
+                }
+                append(chunk.subarray(start, newline));
+                decodeMessage();
+                start = newline + 1;
+            }
+        },
+        end() {
+            if (!isBlank(Buffer.concat(fragments, bufferedBytes)))
+                callbacks.onParseError(new SyntaxError("Unterminated MCP message at end of input"));
+            resetBuffer();
+        },
+    };
+}
+/** Lines containing only JSON whitespace carry no message and are skipped. */
+function isBlank(bytes) {
+    for (const byte of bytes)
+        if (byte !== 0x20 && byte !== 0x09 && byte !== 0x0d)
+            return false;
+    return true;
+}

package/dist/http-body.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from "node:http";
+/** Cancelling body consumption must not destroy the socket before an error response is sent. */
+export declare function requestBody(input: IncomingMessage): ReadableStream<Uint8Array>;

package/dist/http-body.js

@@ -0,0 +1,38 @@
+/** Cancelling body consumption must not destroy the socket before an error response is sent. */
+export function requestBody(input) {
+    let detach;
+    return new ReadableStream({
+        start(controller) {
+            const data = (chunk) => {
+                controller.enqueue(chunk);
+                input.pause();
+            };
+            const end = () => {
+                detach();
+                controller.close();
+            };
+            const error = (failure) => {
+                detach();
+                controller.error(failure);
+            };
+            const aborted = () => error(new Error("Request aborted"));
+            detach = () => {
+                input.off("data", data);
+                input.off("end", end);
+                input.off("error", error);
+                input.off("aborted", aborted);
+                input.pause();
+            };
+            input.on("data", data);
+            input.once("end", end);
+            input.once("error", error);
+            input.once("aborted", aborted);
+        },
+        pull() {
+            input.resume();
+        },
+        cancel() {
+            detach();
+        },
+    }, { highWaterMark: 0 });
+}

package/dist/http-connection.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** One HTTP invocation owns its abort signal and listener cleanup. */
+export declare function watchHttpConnection(input: IncomingMessage, output: ServerResponse): {
+    signal: AbortSignal;
+    dispose(): void;
+};

package/dist/http-connection.js

@@ -0,0 +1,22 @@
+/** One HTTP invocation owns its abort signal and listener cleanup. */
+export function watchHttpConnection(input, output) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const disconnected = () => {
+        if (!output.writableFinished)
+            abort();
+    };
+    input.once("aborted", abort);
+    input.once("error", abort);
+    output.once("error", abort);
+    output.once("close", disconnected);
+    return {
+        signal: controller.signal,
+        dispose() {
+            input.off("aborted", abort);
+            input.off("error", abort);
+            output.off("error", abort);
+            output.off("close", disconnected);
+        },
+    };
+}

package/dist/http-handler.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function nodeHttpHandler(handle: (request: Request) => Promise<Response>, matches?: (pathname: string) => boolean): (input: IncomingMessage, output: ServerResponse, next?: () => void) => Promise<void>;

package/dist/http-handler.js

@@ -0,0 +1,23 @@
+import { watchHttpConnection } from "./http-connection.js";
+import { handleNodeRequest } from "./http-request.js";
+import { writeHttpFailure, writeHttpResponse } from "./http-response.js";
+import { requestUrl } from "./http-url.js";
+export function nodeHttpHandler(handle, matches) {
+    return async (input, output, next) => {
+        const connection = watchHttpConnection(input, output);
+        try {
+            if (next && matches && !matches(new URL(requestUrl(input)).pathname)) {
+                next();
+                return;
+            }
+            const response = await handleNodeRequest(input, connection.signal, handle);
+            await writeHttpResponse(output, response, connection.signal, input.complete);
+        }
+        catch (error) {
+            await writeHttpFailure(output, connection.signal, error);
+        }
+        finally {
+            connection.dispose();
+        }
+    };
+}

package/dist/http-listener.d.ts

@@ -0,0 +1,15 @@
+import type { AddressInfo } from "node:net";
+import type { HttpOptions } from "@toolgrain/http";
+import type { RequestTransport } from "@toolgrain/mcp";
+export interface HttpTransportOptions extends HttpOptions {
+    /** Defaults to 3000. Use 0 to let the operating system choose a port. */
+    port?: number;
+    /** Bind address; defaults to 127.0.0.1. This is separate from allowedHosts. */
+    hostname?: string;
+}
+export interface HttpTransport extends RequestTransport {
+    /** A copied bound address, or undefined before startup and after closing. */
+    address(): AddressInfo | undefined;
+}
+/** Own a Node HTTP listener with combined MCP routing and local host defaults. */
+export declare function http(options?: HttpTransportOptions): HttpTransport;

package/dist/http-listener.js

@@ -0,0 +1,95 @@
+import { createServer as createHttpServer, } from "node:http";
+import { createNodeHttpHandler } from "./http.js";
+/** Own a Node HTTP listener with combined MCP routing and local host defaults. */
+export function http(options = {}) {
+    const port = options.port ?? 3000;
+    const hostname = options.hostname ?? "127.0.0.1";
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new RangeError("port must be an integer between 0 and 65535");
+    if (!hostname || /[\s/?#@\\]/.test(hostname))
+        throw new TypeError("hostname must be a bind hostname or IP address");
+    const config = {
+        ...options,
+        ...(options.allowedHosts === undefined
+            ? {}
+            : { allowedHosts: [...options.allowedHosts] }),
+        ...(options.allowedOrigins === undefined
+            ? {}
+            : { allowedOrigins: [...options.allowedOrigins] }),
+    };
+    let listener;
+    let started = false;
+    let closed = false;
+    let closePromise;
+    const binding = new AbortController();
+    let onClose;
+    const notifyClose = () => {
+        const notify = onClose;
+        onClose = undefined;
+        notify?.();
+    };
+    return {
+        mode: "request",
+        address() {
+            const address = listener?.address();
+            return address && typeof address !== "string"
+                ? { ...address }
+                : undefined;
+        },
+        async start(server, callbacks) {
+            if (started || closed)
+                throw new Error("HTTP transport cannot restart");
+            started = true;
+            const node = createHttpServer();
+            listener = node;
+            onClose = callbacks.onClose;
+            node.once("close", notifyClose);
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    node.off("error", failed);
+                    node.off("close", stopped);
+                    node.off("listening", ready);
+                };
+                const failed = (error) => {
+                    cleanup();
+                    reject(error);
+                };
+                const stopped = () => failed(new Error("HTTP transport closed during startup"));
+                const ready = () => {
+                    cleanup();
+                    resolve();
+                };
+                node.once("error", failed);
+                node.once("close", stopped);
+                node.once("listening", ready);
+                node.listen({ host: hostname, port, signal: binding.signal });
+            });
+            const address = node.address();
+            const localHosts = ["localhost", "127.0.0.1", "[::1]"].map((host) => `${host}:${address.port}`);
+            const handle = createNodeHttpHandler(server, {
+                ...config,
+                allowedHosts: config.allowedHosts ?? localHosts,
+            });
+            node.on("error", callbacks.onError);
+            node.on("request", (request, response) => {
+                void handle(request, response);
+            });
+        },
+        close() {
+            if (closePromise)
+                return closePromise;
+            closed = true;
+            closePromise = Promise.resolve().then(() => new Promise((resolve) => {
+                if (!listener) {
+                    resolve();
+                    return;
+                }
+                listener.close(() => resolve());
+                binding.abort();
+                listener.closeAllConnections();
+            }));
+            notifyClose();
+            return closePromise;
+        },
+    };
+}

package/dist/http-request.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage } from "node:http";
+export declare class ConsumedRequestError extends Error {
+    constructor();
+}
+/** Adapt Node input to a Web Request; release body listeners even when validation rejects it. */
+export declare function handleNodeRequest(input: IncomingMessage, signal: AbortSignal, handle: (request: Request) => Promise<Response>): Promise<Response>;

package/dist/http-request.js

@@ -0,0 +1,36 @@
+import { requestBody } from "./http-body.js";
+import { requestUrl } from "./http-url.js";
+export class ConsumedRequestError extends Error {
+    constructor() {
+        super("Request body has already been consumed");
+    }
+}
+function requestHeaders(input) {
+    const headers = new Headers();
+    for (let index = 0; index < input.rawHeaders.length; index += 2) {
+        headers.append(input.rawHeaders[index], input.rawHeaders[index + 1]);
+    }
+    return headers;
+}
+/** Adapt Node input to a Web Request; release body listeners even when validation rejects it. */
+export async function handleNodeRequest(input, signal, handle) {
+    if (input.readableEnded || input.destroyed || input.readableEncoding)
+        throw new ConsumedRequestError();
+    let body;
+    try {
+        const method = input.method ?? "GET";
+        const headers = requestHeaders(input);
+        body =
+            method === "GET" || method === "HEAD" ? undefined : requestBody(input);
+        const init = {
+            method,
+            headers,
+            signal,
+            ...(body ? { body, duplex: "half" } : {}),
+        };
+        return await handle(new Request(requestUrl(input), init));
+    }
+    finally {
+        await body?.cancel().catch(() => { });
+    }
+}

package/dist/http-response.d.ts

@@ -0,0 +1,4 @@
+import type { ServerResponse } from "node:http";
+/** Preserve Node backpressure and close keep-alive when an incoming body was not fully read. */
+export declare function writeHttpResponse(output: ServerResponse, response: Response, signal: AbortSignal, inputComplete: boolean): Promise<void>;
+export declare function writeHttpFailure(output: ServerResponse, signal: AbortSignal, error: unknown): Promise<void>;

package/dist/http-response.js

@@ -0,0 +1,72 @@
+import { once } from "node:events";
+import { ConsumedRequestError } from "./http-request.js";
+import { InvalidRequestUrlError } from "./http-url.js";
+async function writeBody(output, body, signal) {
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || signal.aborted)
+                break;
+            if (!output.write(value))
+                await once(output, "drain", { signal });
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Preserve Node backpressure and close keep-alive when an incoming body was not fully read. */
+export async function writeHttpResponse(output, response, signal, inputComplete) {
+    if (signal.aborted)
+        return;
+    if (!inputComplete)
+        response.headers.set("Connection", "close");
+    output.writeHead(response.status, Object.fromEntries(response.headers));
+    if (response.body)
+        await writeBody(output, response.body, signal);
+    if (signal.aborted)
+        return;
+    await finishResponse(output, signal);
+}
+async function finishResponse(output, signal) {
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            output.off("finish", finish);
+            signal.removeEventListener("abort", abort);
+        };
+        const finish = () => {
+            cleanup();
+            resolve();
+        };
+        const abort = () => {
+            cleanup();
+            reject(signal.reason);
+        };
+        output.once("finish", finish);
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+            output.end();
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+export async function writeHttpFailure(output, signal, error) {
+    if (signal.aborted || output.destroyed)
+        return;
+    if (output.headersSent) {
+        output.destroy();
+        return;
+    }
+    output.writeHead(error instanceof ConsumedRequestError ||
+        error instanceof InvalidRequestUrlError
+        ? 400
+        : 500);
+    await finishResponse(output, signal).catch(() => {
+        output.destroy();
+    });
+}

package/dist/http-url.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage } from "node:http";
+export declare class InvalidRequestUrlError extends Error {
+}
+/** Proxy headers require normalization by trusted application middleware. */
+export declare function requestUrl(input: IncomingMessage): string;

package/dist/http-url.js

@@ -0,0 +1,23 @@
+export class InvalidRequestUrlError extends Error {
+}
+/** Proxy headers require normalization by trusted application middleware. */
+export function requestUrl(input) {
+    const host = input.headers.host;
+    const target = input.url ?? "/";
+    if (!host ||
+        /[\s,/?#@\\]/.test(host) ||
+        !target.startsWith("/") ||
+        target.startsWith("//") ||
+        target.includes("\\"))
+        throw new InvalidRequestUrlError("Invalid HTTP request URL");
+    const secure = "encrypted" in input.socket && input.socket.encrypted === true;
+    try {
+        const url = new URL(target, `${secure ? "https" : "http"}://${host}`);
+        if (url.username || url.password || url.hash)
+            throw new Error("Invalid URL");
+        return url.href;
+    }
+    catch {
+        throw new InvalidRequestUrlError("Invalid HTTP request URL");
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+import { type HttpOptions } from "@toolgrain/http";
+import type { Server } from "@toolgrain/mcp";
+/** Mount at the root before body parsing. Delegates unmatched paths when next is supplied. */
+export declare function createNodeHttpHandler(server: Server, options?: HttpOptions): (input: import("http").IncomingMessage, output: import("http").ServerResponse, next?: () => void) => Promise<void>;
+export declare function createNodeProtectedResourceMetadataHandler(server: Server, options?: Pick<HttpOptions, "allowedHosts">): (input: import("http").IncomingMessage, output: import("http").ServerResponse, next?: () => void) => Promise<void>;

package/dist/http.js

@@ -0,0 +1,10 @@
+import { createHttpHandler, createProtectedResourceMetadataHandler, } from "@toolgrain/http";
+import { nodeHttpHandler } from "./http-handler.js";
+/** Mount at the root before body parsing. Delegates unmatched paths when next is supplied. */
+export function createNodeHttpHandler(server, options) {
+    const handle = createHttpHandler(server, options);
+    return nodeHttpHandler(handle, handle.matches);
+}
+export function createNodeProtectedResourceMetadataHandler(server, options) {
+    return nodeHttpHandler(createProtectedResourceMetadataHandler(server, options));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { HttpOptions } from "@toolgrain/http";
+export { createNodeHttpHandler, createNodeProtectedResourceMetadataHandler, } from "./http.js";
+export type { HttpTransport, HttpTransportOptions } from "./http-listener.js";
+export { http } from "./http-listener.js";
+export type { StdioOptions } from "./stdio.js";
+export { stdio } from "./stdio.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createNodeHttpHandler, createNodeProtectedResourceMetadataHandler, } from "./http.js";
+export { http } from "./http-listener.js";
+export { stdio } from "./stdio.js";

package/dist/stdio.d.ts

@@ -0,0 +1,10 @@
+import type { Readable, Writable } from "node:stream";
+import type { Transport } from "@toolgrain/mcp";
+export interface StdioOptions {
+    input?: Readable;
+    output?: Writable;
+    /** Maximum UTF-8 bytes per incoming message, excluding its newline. Default: 1 MiB. */
+    maxMessageBytes?: number;
+}
+/** A single-use transport; supplied streams remain owned by the caller. */
+export declare function stdio(options?: StdioOptions): Transport;

package/dist/stdio.js

@@ -0,0 +1,118 @@
+import { stdin, stdout } from "node:process";
+import { createMessageDecoder } from "./framing.js";
+import { writeLine } from "./write.js";
+/** A single-use transport; supplied streams remain owned by the caller. */
+export function stdio(options = {}) {
+    return new StdioTransport(options);
+}
+class StdioTransport {
+    input;
+    output;
+    maxMessageBytes;
+    writeCancellation = new AbortController();
+    state = "idle";
+    callbacks;
+    decoder;
+    writes = Promise.resolve();
+    constructor(options) {
+        this.input = options.input ?? stdin;
+        this.output = options.output ?? stdout;
+        this.maxMessageBytes = options.maxMessageBytes ?? 1024 * 1024;
+        if (!Number.isSafeInteger(this.maxMessageBytes) || this.maxMessageBytes < 1)
+            throw new RangeError("maxMessageBytes must be a positive safe integer");
+    }
+    // Arrow methods preserve detached calls supported by the factory's original API.
+    start = async (transportCallbacks) => {
+        if (this.state !== "idle")
+            throw new Error("Stdio transport can only start once");
+        if (this.input.destroyed ||
+            this.input.readableEnded ||
+            this.output.destroyed ||
+            this.output.writableEnded) {
+            this.shutdown();
+            throw new Error("Stdio streams are already closed");
+        }
+        this.state = "open";
+        this.callbacks = transportCallbacks;
+        this.decoder = createMessageDecoder({
+            onMessage: (message) => {
+                if (this.state === "open")
+                    this.callbacks?.onMessage(message);
+            },
+            onParseError: (error) => {
+                if (this.state === "open")
+                    this.callbacks?.onParseError(error);
+            },
+        }, this.maxMessageBytes);
+        this.input.on("end", this.onInputEnd);
+        this.input.on("close", this.onStreamClose);
+        this.input.on("error", this.onStreamError);
+        this.output.on("close", this.onStreamClose);
+        this.output.on("error", this.onStreamError);
+        this.input.on("data", this.onData);
+        this.input.resume();
+    };
+    send = (message) => {
+        const write = this.writes.then(async () => {
+            if (this.state !== "open")
+                throw new Error("Stdio transport is not open");
+            await writeLine(this.output, `${JSON.stringify(message)}\n`, this.writeCancellation.signal);
+        });
+        this.writes = write.catch(() => {
+            /* Keep the write queue usable; the caller receives the rejection. */
+        });
+        return write;
+    };
+    close = async () => {
+        this.shutdown();
+    };
+    shutdown(reason) {
+        if (this.state === "closed")
+            return;
+        this.state = "closed";
+        const notify = this.callbacks;
+        this.callbacks = undefined;
+        this.decoder = undefined;
+        this.writeCancellation.abort(reason && "error" in reason
+            ? reason.error
+            : new Error("Stdio transport is closed"));
+        this.detach();
+        if (reason && "error" in reason)
+            notify?.onError(reason.error);
+        else if (reason)
+            notify?.onClose();
+    }
+    detach() {
+        this.input.off("data", this.onData);
+        this.input.off("end", this.onInputEnd);
+        this.input.off("close", this.onStreamClose);
+        this.input.off("error", this.onStreamError);
+        this.output.off("close", this.onStreamClose);
+        this.output.off("error", this.onStreamError);
+        this.input.pause();
+    }
+    onStreamError = (error) => {
+        this.shutdown({ error });
+    };
+    onStreamClose = () => {
+        this.shutdown({ closed: true });
+    };
+    onInputEnd = () => {
+        try {
+            this.decoder?.end();
+        }
+        catch (error) {
+            this.onStreamError(error);
+            return;
+        }
+        this.onStreamClose();
+    };
+    onData = (chunk) => {
+        try {
+            this.decoder?.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        catch (error) {
+            this.onStreamError(error);
+        }
+    };
+}

package/dist/write.d.ts

@@ -0,0 +1,3 @@
+import type { Writable } from "node:stream";
+/** Resolves after both the write callback and any required drain event. */
+export declare function writeLine(output: Writable, line: string, signal: AbortSignal): Promise<void>;

package/dist/write.js

@@ -0,0 +1,82 @@
+/** Resolves after both the write callback and any required drain event. */
+export function writeLine(output, line, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let writeCallbackComplete = false;
+        let backpressureCleared = false;
+        let settled = false;
+        function cleanup() {
+            output.off("error", onError);
+            output.off("close", onClose);
+            output.off("drain", onDrain);
+            signal.removeEventListener("abort", onAbort);
+        }
+        function rejectWrite(error) {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        }
+        function finish() {
+            if (settled) {
+                if (writeCallbackComplete)
+                    cleanup();
+                return;
+            }
+            if (writeCallbackComplete && backpressureCleared) {
+                settled = true;
+                cleanup();
+                resolve();
+            }
+        }
+        function onError(error) {
+            rejectWrite(error);
+            cleanup();
+        }
+        function onClose() {
+            rejectWrite(new Error("Output stream closed during write"));
+            cleanup();
+        }
+        function onDrain() {
+            backpressureCleared = true;
+            finish();
+        }
+        function onAbort() {
+            rejectWrite(signal.reason);
+            output.off("drain", onDrain);
+            signal.removeEventListener("abort", onAbort);
+            // Closing the transport cannot cancel a caller-owned stream's OS write.
+            // Until its callback completes, retain error/close listeners to consume
+            // a late write failure rather than causing an unhandled stream error.
+            if (writeCallbackComplete)
+                cleanup();
+        }
+        output.once("error", onError);
+        output.once("close", onClose);
+        output.once("drain", onDrain);
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            if (output.destroyed || output.writableEnded)
+                throw new Error("Output stream is not writable");
+            const accepted = output.write(line, "utf8", (error) => {
+                // Writable emits callback errors as events afterward. Keep onError
+                // attached until that event, including when shutdown already rejected.
+                if (error)
+                    return;
+                writeCallbackComplete = true;
+                finish();
+            });
+            if (accepted) {
+                backpressureCleared = true;
+                finish();
+            }
+        }
+        catch (error) {
+            rejectWrite(error);
+            cleanup();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@toolgrain/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Node.js stdio and HTTP transports for Toolgrain MCP servers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keshavkatwe/toolgrain.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/keshavkatwe/toolgrain/tree/main/packages/node#readme",
+  "bugs": {
+    "url": "https://github.com/keshavkatwe/toolgrain/issues"
+  },
+  "keywords": [
+    "toolgrain",
+    "mcp",
+    "model-context-protocol",
+    "nodejs",
+    "stdio",
+    "http"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:package": "node smoke/runtime.mjs && tsc -p smoke/tsconfig.json && toolgrain-repo exports",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test:coverage": "vitest run --coverage",
+    "test:size": "toolgrain-repo size"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vitest": "5.0.4",
+    "@types/node": "24.10.0",
+    "zod": "4.6.7",
+    "@toolgrain/repo-tools": "0.0.0"
+  },
+  "dependencies": {
+    "@toolgrain/mcp": "0.1.0",
+    "@toolgrain/protocol": "0.1.0",
+    "@toolgrain/http": "0.1.0"
+  },
+  "engines": {
+    "node": "^24.20.0",
+    "bun": ">=1.4.4 <2"
+  }
+}