@toolgrain/node 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @toolgrain/node
+
+## 0.1.2
+
+### Patch Changes
+
+- da94c47: Document the public API with JSDoc for exported types, members, options, and functions. Preserve field documentation in auth accessor return types and protocol constant hovers.
+- f199707: Point package homepages and README documentation links to the live Toolgrain documentation site.
+- d0c10ac: Use matching stable Toolgrain packages in installation instructions instead of
+  embedding outdated release pins.
+- Updated dependencies [da94c47]
+- Updated dependencies [f199707]
+- Updated dependencies [d0c10ac]
+  - @toolgrain/http@0.1.2
+  - @toolgrain/mcp@0.1.2
+  - @toolgrain/protocol@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- 16752a8: Refresh package READMEs with Toolgrain branding, clearer package roles, and direct
+  links to the tool, transport, and authorization guides. Clarify the supported Zod
+  version in installation commands and explicitly load Node types when compiling
+  the Node examples with current TypeScript.
+- Updated dependencies [16752a8]
+  - @toolgrain/mcp@0.1.1
+  - @toolgrain/http@0.1.1
+  - @toolgrain/protocol@0.1.1
+
+## 0.1.0
+
+Initial stable release. See the [0.1.0 release notes](https://github.com/keshavkatwe/toolgrain/releases/tag/v0.1.0) for installation instructions and known limitations.

package/README.md

@@ -1,15 +1,29 @@
+<a href="https://github.com/keshavkatwe/toolgrain#readme">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/keshavkatwe/toolgrain/main/brand/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/keshavkatwe/toolgrain/main/brand/logo-light.svg">
+    <img src="https://raw.githubusercontent.com/keshavkatwe/toolgrain/main/brand/logo-light.svg" alt="Toolgrain" width="200" height="48">
+  </picture>
+</a>
+
 # @toolgrain/node
 
-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).
+**Choose stdio or HTTP. Keep your tools.**
+
+Node.js transports for Toolgrain: process stdio, a managed HTTP listener, and
+handlers for an existing Node application.
+
+[Documentation](https://toolgrain.mintlify.site/transports/overview) ·
+[Examples](https://toolgrain.mintlify.site/examples) ·
+[npm](https://www.npmjs.com/package/@toolgrain/node)
 
 ## Installation
 
-Install the same `0.1.0` version across Toolgrain libraries.
+Install matching stable versions across Toolgrain libraries. These commands
+resolve npm's `latest` tag.
 
 ```sh
-npm install @toolgrain/node@0.1.0 @toolgrain/mcp@0.1.0 zod
+npm install @toolgrain/node @toolgrain/mcp zod@^4.6.6
 npm install --save-dev typescript @types/node
 ```
 
@@ -46,7 +60,7 @@ for (const signal of ["SIGINT", "SIGTERM"] as const) {
 ```
 
 Save as `server.mts`, compile with TypeScript using
-`--strict --module NodeNext --target ES2022`, and run `node server.mjs`.
+`--strict --module NodeNext --target ES2022 --types node`, 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.
@@ -74,7 +88,7 @@ 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).
+[authorization guide](https://toolgrain.mintlify.site/guides/authorization).
 
 ## Requirements and protocol support
 
@@ -82,8 +96,8 @@ 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).
+[support policy](https://toolgrain.mintlify.site/project/support-policy)
+and [client compatibility notes](https://toolgrain.mintlify.site/compatibility/protocol).
 
 ## License
 

package/dist/http-listener.d.ts

@@ -1,15 +1,27 @@
 import type { AddressInfo } from "node:net";
 import type { HttpOptions } from "@toolgrain/http";
 import type { RequestTransport } from "@toolgrain/mcp";
+/** Managed listener settings plus the shared HTTP endpoint and validation options. */
 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;
 }
+/** Single-use Node HTTP listener owned by the MCP server to which it is attached. */
 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. */
+/**
+ * Create a managed Node HTTP transport for independent MCP POSTs with JSON responses.
+ * `server.listen()` starts its listener and public auth metadata routes when configured.
+ * Default accepted hosts are loopback authorities on the actual listening port;
+ * `hostname` controls binding separately from the `allowedHosts` request policy.
+ *
+ * @param options - Listener settings, exact endpoint path, allowlists, and body limit.
+ * @returns A single-use request transport with a copied bound-address accessor.
+ * Closing through the server aborts active requests and closes listener connections.
+ * @throws For an invalid port or bind hostname; listener startup errors reject `listen()`.
+ */
 export declare function http(options?: HttpTransportOptions): HttpTransport;

package/dist/http-listener.js

@@ -1,6 +1,16 @@
 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. */
+/**
+ * Create a managed Node HTTP transport for independent MCP POSTs with JSON responses.
+ * `server.listen()` starts its listener and public auth metadata routes when configured.
+ * Default accepted hosts are loopback authorities on the actual listening port;
+ * `hostname` controls binding separately from the `allowedHosts` request policy.
+ *
+ * @param options - Listener settings, exact endpoint path, allowlists, and body limit.
+ * @returns A single-use request transport with a copied bound-address accessor.
+ * Closing through the server aborts active requests and closes listener connections.
+ * @throws For an invalid port or bind hostname; listener startup errors reject `listen()`.
+ */
 export function http(options = {}) {
     const port = options.port ?? 3000;
     const hostname = options.hostname ?? "127.0.0.1";

package/dist/http.d.ts

@@ -1,5 +1,26 @@
 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. */
+/**
+ * Create a Node handler combining MCP and public protected-resource metadata routes.
+ * Mount it at the application root before body parsing. Owned routes validate hosts
+ * before authentication or body work; forwarded headers are ignored.
+ *
+ * @param server - Server that authorizes and dispatches each independent request.
+ * @param options - Endpoint, host/origin allowlists, and request-body limit.
+ * @returns An async `(input, output, next?)` handler for Node requests/responses.
+ * Unmatched paths call `next()` when supplied; otherwise they return 404.
+ * The application owns its listener, TLS, CORS, and trusted proxy normalization.
+ * @throws For invalid HTTP configuration when constructing the handler.
+ */
 export declare function createNodeHttpHandler(server: Server, options?: HttpOptions): (input: import("http").IncomingMessage, output: import("http").ServerResponse, next?: () => void) => Promise<void>;
+/**
+ * Create a public GET/HEAD handler for an auth-configured server's well-known metadata route.
+ * Register it separately when a framework requires explicit route registration.
+ * Hosts are checked before metadata work; unmatched metadata paths return 404.
+ *
+ * @param server - Auth-configured MCP server whose public resource metadata is advertised.
+ * @param options - Host allowlist; defaults to loopback hosts on any port.
+ * @returns An async handler accepting a Node request and response; it does not own a listener.
+ * @throws If authorization is not configured or the host allowlist is invalid.
+ */
 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

@@ -1,10 +1,31 @@
 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. */
+/**
+ * Create a Node handler combining MCP and public protected-resource metadata routes.
+ * Mount it at the application root before body parsing. Owned routes validate hosts
+ * before authentication or body work; forwarded headers are ignored.
+ *
+ * @param server - Server that authorizes and dispatches each independent request.
+ * @param options - Endpoint, host/origin allowlists, and request-body limit.
+ * @returns An async `(input, output, next?)` handler for Node requests/responses.
+ * Unmatched paths call `next()` when supplied; otherwise they return 404.
+ * The application owns its listener, TLS, CORS, and trusted proxy normalization.
+ * @throws For invalid HTTP configuration when constructing the handler.
+ */
 export function createNodeHttpHandler(server, options) {
     const handle = createHttpHandler(server, options);
     return nodeHttpHandler(handle, handle.matches);
 }
+/**
+ * Create a public GET/HEAD handler for an auth-configured server's well-known metadata route.
+ * Register it separately when a framework requires explicit route registration.
+ * Hosts are checked before metadata work; unmatched metadata paths return 404.
+ *
+ * @param server - Auth-configured MCP server whose public resource metadata is advertised.
+ * @param options - Host allowlist; defaults to loopback hosts on any port.
+ * @returns An async handler accepting a Node request and response; it does not own a listener.
+ * @throws If authorization is not configured or the host allowlist is invalid.
+ */
 export function createNodeProtectedResourceMetadataHandler(server, options) {
     return nodeHttpHandler(createProtectedResourceMetadataHandler(server, options));
 }

package/dist/stdio.d.ts

@@ -1,10 +1,21 @@
 import type { Readable, Writable } from "node:stream";
 import type { Transport } from "@toolgrain/mcp";
+/** Streams and framing limit for a single-use, newline-delimited JSON transport. */
 export interface StdioOptions {
+    /** Incoming UTF-8 JSON stream; defaults to process stdin and remains application-owned. */
     input?: Readable;
+    /** Outgoing MCP response stream; defaults to process stdout and must not contain application logs. */
     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. */
+/**
+ * Create a single-use stdio transport with newline framing and write backpressure.
+ * Attach it through `server.listen()`. Closing detaches listeners and pauses input;
+ * supplied streams remain application-owned and are not ended or destroyed.
+ *
+ * @param options - Input/output streams and a positive incoming-message byte limit.
+ * @returns A transport that can be attached once and cannot restart after closing.
+ * @throws `RangeError` if `maxMessageBytes` is not a positive safe integer.
+ */
 export declare function stdio(options?: StdioOptions): Transport;

package/dist/stdio.js

@@ -1,7 +1,15 @@
 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. */
+/**
+ * Create a single-use stdio transport with newline framing and write backpressure.
+ * Attach it through `server.listen()`. Closing detaches listeners and pauses input;
+ * supplied streams remain application-owned and are not ended or destroyed.
+ *
+ * @param options - Input/output streams and a positive incoming-message byte limit.
+ * @returns A transport that can be attached once and cannot restart after closing.
+ * @throws `RangeError` if `maxMessageBytes` is not a positive safe integer.
+ */
 export function stdio(options = {}) {
     return new StdioTransport(options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/node",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Node.js stdio and HTTP transports for Toolgrain MCP servers.",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "git+https://github.com/keshavkatwe/toolgrain.git",
     "directory": "packages/node"
   },
-  "homepage": "https://github.com/keshavkatwe/toolgrain/tree/main/packages/node#readme",
+  "homepage": "https://toolgrain.mintlify.site/reference/node",
   "bugs": {
     "url": "https://github.com/keshavkatwe/toolgrain/issues"
   },
@@ -33,6 +33,7 @@
     }
   },
   "files": [
+    "CHANGELOG.md",
     "dist"
   ],
   "scripts": {
@@ -52,9 +53,9 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/mcp": "0.1.0",
-    "@toolgrain/protocol": "0.1.0",
-    "@toolgrain/http": "0.1.0"
+    "@toolgrain/mcp": "0.1.2",
+    "@toolgrain/protocol": "0.1.2",
+    "@toolgrain/http": "0.1.2"
   },
   "engines": {
     "node": "^24.20.0",