@n24q02m/hull 0.0.0-stage → 0.4.0-beta.9

package/build/transport/streamable-http.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Streamable HTTP 2025-11-25 transport wrapper for mcp-core TypeScript.
+ *
+ * Thin convenience wrapper around `@modelcontextprotocol/sdk`'s
+ * `StreamableHTTPServerTransport` that pairs it with an `McpServer`
+ * instance and an optional OAuth Bearer validation middleware.
+ *
+ * The SDK already implements the full 2025-11-25 transport spec
+ * (session management, SSE streaming, stateful / stateless modes),
+ * so this wrapper focuses on the mcp-core ergonomics:
+ *
+ *  - one-call `connect()` that wires server <-> transport
+ *  - `handleRequest(req, res)` that applies the OAuth middleware
+ *    first and short-circuits with 401 on missing / invalid token
+ *  - explicit `host` / `port` properties for lifecycle management
+ *    (the actual port bind is left to the caller's http.Server)
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport, type StreamableHTTPServerTransportOptions } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { OAuthMiddleware } from './oauth-middleware.js';
+export interface StreamableHTTPServerOptions {
+    /** MCP server instance that handles requests */
+    server: McpServer;
+    /** Host to advertise (used for logging / display only) */
+    host?: string;
+    /** Port to advertise (used for logging / display only) */
+    port: number;
+    /** Optional OAuth middleware for Bearer token validation */
+    oauthMiddleware?: OAuthMiddleware;
+    /** Transport options forwarded to StreamableHTTPServerTransport */
+    transportOptions?: StreamableHTTPServerTransportOptions;
+}
+export declare class StreamableHTTPServer {
+    readonly host: string;
+    readonly port: number;
+    private readonly _server;
+    private readonly _oauth?;
+    private readonly _transport;
+    private _connected;
+    constructor(options: StreamableHTTPServerOptions);
+    /** Connect the MCP server to the transport. Call once before handleRequest. */
+    connect(): Promise<void>;
+    /**
+     * Handle an incoming HTTP request. Applies OAuth validation first if
+     * configured, then delegates to the SDK transport.
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse, parsedBody?: unknown): Promise<void>;
+    /** Expose the underlying transport for advanced use cases. */
+    get transport(): StreamableHTTPServerTransport;
+    /** Close the transport and drain any active sessions. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=streamable-http.d.ts.map

package/build/transport/streamable-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable-http.d.ts","sourceRoot":"","sources":["../../src/transport/streamable-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,EACL,6BAA6B,EAC7B,KAAK,oCAAoC,EAC1C,MAAM,oDAAoD,CAAA;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,MAAM,EAAE,SAAS,CAAA;IACjB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,oCAAoC,CAAA;CACxD;AAED,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D,OAAO,CAAC,UAAU,CAAQ;IAE1B,YAAY,OAAO,EAAE,2BAA2B,EAM/C;IAED,+EAA+E;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAI7B;IAED;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlG;IAED,8DAA8D;IAC9D,IAAI,SAAS,IAAI,6BAA6B,CAE7C;IAED,yDAAyD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;CACF"}

package/build/transport/streamable-http.js

@@ -0,0 +1,57 @@
+/**
+ * Streamable HTTP 2025-11-25 transport wrapper for mcp-core TypeScript.
+ *
+ * Thin convenience wrapper around `@modelcontextprotocol/sdk`'s
+ * `StreamableHTTPServerTransport` that pairs it with an `McpServer`
+ * instance and an optional OAuth Bearer validation middleware.
+ *
+ * The SDK already implements the full 2025-11-25 transport spec
+ * (session management, SSE streaming, stateful / stateless modes),
+ * so this wrapper focuses on the mcp-core ergonomics:
+ *
+ *  - one-call `connect()` that wires server <-> transport
+ *  - `handleRequest(req, res)` that applies the OAuth middleware
+ *    first and short-circuits with 401 on missing / invalid token
+ *  - explicit `host` / `port` properties for lifecycle management
+ *    (the actual port bind is left to the caller's http.Server)
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+export class StreamableHTTPServer {
+    constructor(options) {
+        this._connected = false;
+        this._server = options.server;
+        this.host = options.host ?? '127.0.0.1';
+        this.port = options.port;
+        this._oauth = options.oauthMiddleware;
+        this._transport = new StreamableHTTPServerTransport(options.transportOptions ?? { sessionIdGenerator: undefined });
+    }
+    /** Connect the MCP server to the transport. Call once before handleRequest. */
+    async connect() {
+        if (this._connected)
+            return;
+        await this._server.connect(this._transport);
+        this._connected = true;
+    }
+    /**
+     * Handle an incoming HTTP request. Applies OAuth validation first if
+     * configured, then delegates to the SDK transport.
+     */
+    async handleRequest(req, res, parsedBody) {
+        if (this._oauth) {
+            const allowed = await this._oauth.validate(req, res);
+            if (!allowed)
+                return;
+        }
+        await this._transport.handleRequest(req, res, parsedBody);
+    }
+    /** Expose the underlying transport for advanced use cases. */
+    get transport() {
+        return this._transport;
+    }
+    /** Close the transport and drain any active sessions. */
+    async close() {
+        await this._transport.close();
+        this._connected = false;
+    }
+}
+//# sourceMappingURL=streamable-http.js.map

package/build/transport/streamable-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable-http.js","sourceRoot":"","sources":["../../src/transport/streamable-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EACL,6BAA6B,EAE9B,MAAM,oDAAoD,CAAA;AAiB3D,MAAM,OAAO,oBAAoB;IAQ/B,YAAY,OAAoC;QAFxC,eAAU,GAAG,KAAK,CAAA;QAGxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAA;QACvC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,eAAe,CAAA;QACrC,IAAI,CAAC,UAAU,GAAG,IAAI,6BAA6B,CAAC,OAAO,CAAC,gBAAgB,IAAI,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAA;IACpH,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU;YAAE,OAAM;QAC3B,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;IACxB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,GAAoB,EAAE,GAAmB,EAAE,UAAoB;QACjF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YACpD,IAAI,CAAC,OAAO;gBAAE,OAAM;QACtB,CAAC;QACD,MAAM,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAA;IAC3D,CAAC;IAED,8DAA8D;IAC9D,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAA;IACzB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@n24q02m/hull",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0-beta.9",
+  "description": "hull TypeScript core: MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 AS, lifecycle, install",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "streamable-http",
+    "oauth21",
+    "transport",
+    "claude",
+    "cursor",
+    "copilot",
+    "codex",
+    "opencode"
+  ],
+  "author": {
+    "name": "n24q02m",
+    "url": "https://github.com/n24q02m"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n24q02m/hull.git",
+    "directory": "packages/core-ts"
+  },
+  "homepage": "https://github.com/n24q02m/hull",
+  "bugs": {
+    "url": "https://github.com/n24q02m/hull/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build/",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./crypto": {
+      "import": "./build/crypto/index.js",
+      "types": "./build/crypto/index.d.ts"
+    },
+    "./storage": {
+      "import": "./build/storage/index.js",
+      "types": "./build/storage/index.d.ts"
+    },
+    "./relay": {
+      "import": "./build/relay/client.js",
+      "types": "./build/relay/client.d.ts"
+    },
+    "./schema": {
+      "import": "./build/schema/types.js",
+      "types": "./build/schema/types.d.ts"
+    },
+    "./oauth": {
+      "import": "./build/oauth/index.js",
+      "types": "./build/oauth/index.d.ts"
+    },
+    "./auth": {
+      "import": "./build/auth/index.js",
+      "types": "./build/auth/index.d.ts"
+    },
+    "./transport": {
+      "import": "./build/transport/index.js",
+      "types": "./build/transport/index.d.ts"
+    },
+    "./token-auth": {
+      "import": "./build/token-auth/index.js",
+      "types": "./build/token-auth/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "test": "vitest --passWithNoTests",
+    "test:coverage": "vitest --coverage --passWithNoTests",
+    "check": "biome check . && bun run type-check",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "better-sqlite3": "^13.0.3",
+    "env-paths": "^4.0.0",
+    "jose": "^6.2.12",
+    "smol-toml": "^1.9.0"
+  },
+  "trustedDependencies": [
+    "better-sqlite3"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "^5.0.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=24.21.0"
+  },
+  "packageManager": "bun@1.4.3"
+}