@ubuligan/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsznpm
+
+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/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Logger, LogLevel } from '@ubuligan/shared';
+export { LogLevel, Logger } from '@ubuligan/shared';
+
+interface CreateServerOptions {
+    name: string;
+    version?: string;
+}
+/**
+ * Create an MCP server. Returns the SDK `McpServer` directly — register tools,
+ * resources and prompts on it with the standard `registerTool` / etc. methods,
+ * then boot it with {@link serve}.
+ */
+declare function createMCPServer(opts: CreateServerOptions): McpServer;
+/** Start a server over stdio (Claude Desktop / local MCP clients). */
+declare function startStdio(server: McpServer, logger?: Logger | LogLevel): Promise<void>;
+interface HttpOptions {
+    /** Port to listen on. Default 3000. */
+    port?: number;
+    /** HTTP path the MCP endpoint is mounted at. Default "/mcp". */
+    path?: string;
+    logger?: Logger | LogLevel;
+}
+/**
+ * Start a server over Streamable HTTP (the production transport). Runs in
+ * stateless mode: a fresh transport per request. Resolves once listening.
+ */
+declare function startHttp(serverFactory: McpServer | (() => McpServer), opts?: HttpOptions): Promise<{
+    port: number;
+    close: () => Promise<void>;
+}>;
+interface ServeOptions {
+    transport: "stdio" | "http";
+    port?: number;
+    path?: string;
+    logger?: Logger | LogLevel;
+}
+/**
+ * Boot a server over the chosen transport. For stdio pass the server instance;
+ * for http you may pass a factory to get a fresh server per request.
+ */
+declare function serve(serverOrFactory: McpServer | (() => McpServer), opts: ServeOptions): Promise<void>;
+
+export { type CreateServerOptions, type HttpOptions, type ServeOptions, createMCPServer, serve, startHttp, startStdio };

package/dist/index.js

@@ -0,0 +1,68 @@
+// src/index.ts
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createConsoleLogger, noopLogger } from "@ubuligan/shared";
+function createMCPServer(opts) {
+  return new McpServer({ name: opts.name, version: opts.version ?? "0.1.0" });
+}
+function resolveLogger(logger) {
+  if (!logger) return noopLogger;
+  return typeof logger === "string" ? createConsoleLogger(logger) : logger;
+}
+async function startStdio(server, logger) {
+  const log = resolveLogger(logger);
+  await server.connect(new StdioServerTransport());
+  log.info("MCP server running on stdio");
+}
+function startHttp(serverFactory, opts = {}) {
+  const port = opts.port ?? 3e3;
+  const path = opts.path ?? "/mcp";
+  const log = resolveLogger(opts.logger);
+  const makeServer = typeof serverFactory === "function" ? serverFactory : () => serverFactory;
+  const app = express();
+  app.use(express.json());
+  app.post(path, async (req, res) => {
+    const server = makeServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    res.on("close", () => {
+      transport.close();
+      if (typeof serverFactory === "function") server.close();
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      log.error("request failed", error instanceof Error ? error.message : String(error));
+      if (!res.headersSent) res.status(500).json({ error: "internal error" });
+    }
+  });
+  return new Promise((resolve) => {
+    const httpServer = app.listen(port, () => {
+      const addr = httpServer.address();
+      const actualPort = addr && typeof addr === "object" ? addr.port : port;
+      log.info(`MCP server on http://localhost:${actualPort}${path}`);
+      resolve({
+        port: actualPort,
+        close: () => new Promise((res, rej) => httpServer.close((err) => err ? rej(err) : res()))
+      });
+    });
+  });
+}
+async function serve(serverOrFactory, opts) {
+  if (opts.transport === "http") {
+    await startHttp(serverOrFactory, opts);
+    return;
+  }
+  const server = typeof serverOrFactory === "function" ? serverOrFactory() : serverOrFactory;
+  await startStdio(server, opts.logger);
+}
+export {
+  McpServer,
+  createMCPServer,
+  serve,
+  startHttp,
+  startStdio
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import express from \"express\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { createConsoleLogger, noopLogger, type Logger, type LogLevel } from \"@ubuligan/shared\";\n\nexport type { Logger, LogLevel } from \"@ubuligan/shared\";\n\nexport interface CreateServerOptions {\n  name: string;\n  version?: string;\n}\n\n/**\n * Create an MCP server. Returns the SDK `McpServer` directly — register tools,\n * resources and prompts on it with the standard `registerTool` / etc. methods,\n * then boot it with {@link serve}.\n */\nexport function createMCPServer(opts: CreateServerOptions): McpServer {\n  return new McpServer({ name: opts.name, version: opts.version ?? \"0.1.0\" });\n}\n\nfunction resolveLogger(logger: Logger | LogLevel | undefined): Logger {\n  if (!logger) return noopLogger;\n  return typeof logger === \"string\" ? createConsoleLogger(logger) : logger;\n}\n\n/** Start a server over stdio (Claude Desktop / local MCP clients). */\nexport async function startStdio(server: McpServer, logger?: Logger | LogLevel): Promise<void> {\n  const log = resolveLogger(logger);\n  await server.connect(new StdioServerTransport());\n  log.info(\"MCP server running on stdio\");\n}\n\nexport interface HttpOptions {\n  /** Port to listen on. Default 3000. */\n  port?: number;\n  /** HTTP path the MCP endpoint is mounted at. Default \"/mcp\". */\n  path?: string;\n  logger?: Logger | LogLevel;\n}\n\n/**\n * Start a server over Streamable HTTP (the production transport). Runs in\n * stateless mode: a fresh transport per request. Resolves once listening.\n */\nexport function startHttp(\n  serverFactory: McpServer | (() => McpServer),\n  opts: HttpOptions = {},\n): Promise<{ port: number; close: () => Promise<void> }> {\n  const port = opts.port ?? 3000;\n  const path = opts.path ?? \"/mcp\";\n  const log = resolveLogger(opts.logger);\n  const makeServer = typeof serverFactory === \"function\" ? serverFactory : () => serverFactory;\n\n  const app = express();\n  app.use(express.json());\n\n  app.post(path, async (req, res) => {\n    const server = makeServer();\n    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });\n    res.on(\"close\", () => {\n      transport.close();\n      if (typeof serverFactory === \"function\") server.close();\n    });\n    try {\n      await server.connect(transport);\n      await transport.handleRequest(req, res, req.body);\n    } catch (error) {\n      log.error(\"request failed\", error instanceof Error ? error.message : String(error));\n      if (!res.headersSent) res.status(500).json({ error: \"internal error\" });\n    }\n  });\n\n  return new Promise((resolve) => {\n    const httpServer = app.listen(port, () => {\n      const addr = httpServer.address();\n      const actualPort = addr && typeof addr === \"object\" ? addr.port : port;\n      log.info(`MCP server on http://localhost:${actualPort}${path}`);\n      resolve({\n        port: actualPort,\n        close: () =>\n          new Promise<void>((res, rej) => httpServer.close((err) => (err ? rej(err) : res()))),\n      });\n    });\n  });\n}\n\nexport interface ServeOptions {\n  transport: \"stdio\" | \"http\";\n  port?: number;\n  path?: string;\n  logger?: Logger | LogLevel;\n}\n\n/**\n * Boot a server over the chosen transport. For stdio pass the server instance;\n * for http you may pass a factory to get a fresh server per request.\n */\nexport async function serve(\n  serverOrFactory: McpServer | (() => McpServer),\n  opts: ServeOptions,\n): Promise<void> {\n  if (opts.transport === \"http\") {\n    await startHttp(serverOrFactory, opts);\n    return;\n  }\n  const server = typeof serverOrFactory === \"function\" ? serverOrFactory() : serverOrFactory;\n  await startStdio(server, opts.logger);\n}\n\nexport { McpServer };\n"],"mappings":";AAAC,OAAO,aAAa;AACrB,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AACrC,SAAS,qCAAqC;AAC9C,SAAS,qBAAqB,kBAA8C;AAcrE,SAAS,gBAAgB,MAAsC;AACpE,SAAO,IAAI,UAAU,EAAE,MAAM,KAAK,MAAM,SAAS,KAAK,WAAW,QAAQ,CAAC;AAC5E;AAEA,SAAS,cAAc,QAA+C;AACpE,MAAI,CAAC,OAAQ,QAAO;AACpB,SAAO,OAAO,WAAW,WAAW,oBAAoB,MAAM,IAAI;AACpE;AAGA,eAAsB,WAAW,QAAmB,QAA2C;AAC7F,QAAM,MAAM,cAAc,MAAM;AAChC,QAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;AAC/C,MAAI,KAAK,6BAA6B;AACxC;AAcO,SAAS,UACd,eACA,OAAoB,CAAC,GACkC;AACvD,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,MAAM,cAAc,KAAK,MAAM;AACrC,QAAM,aAAa,OAAO,kBAAkB,aAAa,gBAAgB,MAAM;AAE/E,QAAM,MAAM,QAAQ;AACpB,MAAI,IAAI,QAAQ,KAAK,CAAC;AAEtB,MAAI,KAAK,MAAM,OAAO,KAAK,QAAQ;AACjC,UAAM,SAAS,WAAW;AAC1B,UAAM,YAAY,IAAI,8BAA8B,EAAE,oBAAoB,OAAU,CAAC;AACrF,QAAI,GAAG,SAAS,MAAM;AACpB,gBAAU,MAAM;AAChB,UAAI,OAAO,kBAAkB,WAAY,QAAO,MAAM;AAAA,IACxD,CAAC;AACD,QAAI;AACF,YAAM,OAAO,QAAQ,SAAS;AAC9B,YAAM,UAAU,cAAc,KAAK,KAAK,IAAI,IAAI;AAAA,IAClD,SAAS,OAAO;AACd,UAAI,MAAM,kBAAkB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAClF,UAAI,CAAC,IAAI,YAAa,KAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,iBAAiB,CAAC;AAAA,IACxE;AAAA,EACF,CAAC;AAED,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,aAAa,IAAI,OAAO,MAAM,MAAM;AACxC,YAAM,OAAO,WAAW,QAAQ;AAChC,YAAM,aAAa,QAAQ,OAAO,SAAS,WAAW,KAAK,OAAO;AAClE,UAAI,KAAK,kCAAkC,UAAU,GAAG,IAAI,EAAE;AAC9D,cAAQ;AAAA,QACN,MAAM;AAAA,QACN,OAAO,MACL,IAAI,QAAc,CAAC,KAAK,QAAQ,WAAW,MAAM,CAAC,QAAS,MAAM,IAAI,GAAG,IAAI,IAAI,CAAE,CAAC;AAAA,MACvF,CAAC;AAAA,IACH,CAAC;AAAA,EACH,CAAC;AACH;AAaA,eAAsB,MACpB,iBACA,MACe;AACf,MAAI,KAAK,cAAc,QAAQ;AAC7B,UAAM,UAAU,iBAAiB,IAAI;AACrC;AAAA,EACF;AACA,QAAM,SAAS,OAAO,oBAAoB,aAAa,gBAAgB,IAAI;AAC3E,QAAM,WAAW,QAAQ,KAAK,MAAM;AACtC;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ubuligan/server",
+  "version": "0.1.0",
+  "description": "Thin DX layer over the MCP SDK server: create a server and boot it over stdio or Streamable HTTP in one call",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^4.21.2",
+    "@ubuligan/shared": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "zod": "^3.23.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "jsznpm",
+  "homepage": "https://github.com/jsznpm/create-mcp-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/jsznpm/create-mcp-toolkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsznpm/create-mcp-toolkit.git",
+    "directory": "packages/server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "server",
+    "stdio",
+    "http"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}