@toolgrain/node 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @toolgrain/node
 
+## 0.1.3
+
+### Patch Changes
+
+- @toolgrain/http@0.1.3
+  - @toolgrain/mcp@0.1.3
+  - @toolgrain/protocol@0.1.3
+
+## 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

package/README.md

@@ -13,16 +13,17 @@
 Node.js transports for Toolgrain: process stdio, a managed HTTP listener, and
 handlers for an existing Node application.
 
-[Documentation](https://github.com/keshavkatwe/toolgrain/blob/main/docs/transports.md) ·
-[Examples](https://github.com/keshavkatwe/toolgrain/blob/main/apps/README.md) ·
+[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@^4.6.6
+npm install @toolgrain/node @toolgrain/mcp zod@^4.6.6
 npm install --save-dev typescript @types/node
 ```
 
@@ -87,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
 
@@ -95,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.1",
+  "version": "0.1.3",
   "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"
   },
@@ -53,9 +53,9 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/mcp": "0.1.1",
-    "@toolgrain/protocol": "0.1.1",
-    "@toolgrain/http": "0.1.1"
+    "@toolgrain/mcp": "0.1.3",
+    "@toolgrain/protocol": "0.1.3",
+    "@toolgrain/http": "0.1.3"
   },
   "engines": {
     "node": "^24.20.0",