@ubuligan/shared 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,65 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+interface Logger {
+    debug(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error(msg: string, meta?: unknown): void;
+}
+/**
+ * Minimal structured logger with no external dependency. In Node it writes to
+ * `process.stderr` (so it never corrupts stdio MCP protocol traffic); in the
+ * browser it falls back to `console`.
+ */
+declare function createConsoleLogger(level?: LogLevel): Logger;
+declare const noopLogger: Logger;
+
+interface RetryOptions {
+    /** Max attempts including the first try. `1` disables retries. Default 3. */
+    retries?: number;
+    /** Base delay in ms for exponential backoff. Default 200. */
+    minDelayMs?: number;
+    /** Upper bound for a single backoff delay in ms. Default 5000. */
+    maxDelayMs?: number;
+    /** Decide whether an error is worth retrying. Default: retry everything. */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Run `fn` with exponential backoff + full jitter. Used to wrap MCP requests so
+ * transient transport / network blips don't bubble up to callers.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions, logger?: Logger, label?: string): Promise<T>;
+
+interface StdioTransportConfig {
+    type: "stdio";
+    /** Executable to spawn, e.g. "node". */
+    command: string;
+    /** Arguments passed to the command, e.g. ["dist/index.js"]. */
+    args?: string[];
+    /** Extra environment variables merged onto the spawned process env. */
+    env?: Record<string, string>;
+    /** Working directory for the spawned process. */
+    cwd?: string;
+}
+interface HttpTransportConfig {
+    type: "http";
+    /** Endpoint URL of the Streamable HTTP MCP server. */
+    url: string;
+    /** Static headers (merged after auth headers). */
+    headers?: Record<string, string>;
+}
+type TransportConfig = StdioTransportConfig | HttpTransportConfig;
+/**
+ * Resolve dynamic auth into request headers. Either a static record or an async
+ * getter (e.g. to refresh a bearer token before each connection).
+ */
+type AuthConfig = {
+    type: "bearer";
+    token: string | (() => string | Promise<string>);
+} | {
+    type: "headers";
+    headers: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+};
+/** Resolve an {@link AuthConfig} into concrete request headers. */
+declare function resolveAuthHeaders(auth?: AuthConfig): Promise<Record<string, string>>;
+
+export { type AuthConfig, type HttpTransportConfig, type LogLevel, type Logger, type RetryOptions, type StdioTransportConfig, type TransportConfig, createConsoleLogger, noopLogger, resolveAuthHeaders, withRetry };

package/dist/index.js

@@ -0,0 +1,90 @@
+// src/logger.ts
+var LEVEL_ORDER = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+function createConsoleLogger(level = "info") {
+  const threshold = level === "silent" ? Infinity : LEVEL_ORDER[level];
+  const hasStderr = typeof process !== "undefined" && !!process.stderr?.write;
+  const emit = (lvl) => (msg, meta) => {
+    if (LEVEL_ORDER[lvl] < threshold) return;
+    const line = `[mcp-toolkit] ${lvl.toUpperCase()} ${msg}`;
+    if (hasStderr) {
+      process.stderr.write(meta !== void 0 ? `${line} ${safe(meta)}
+` : `${line}
+`);
+    } else {
+      const fn = lvl === "debug" ? console.debug : lvl === "warn" ? console.warn : lvl === "error" ? console.error : console.info;
+      if (meta !== void 0) fn(line, meta);
+      else fn(line);
+    }
+  };
+  return {
+    debug: emit("debug"),
+    info: emit("info"),
+    warn: emit("warn"),
+    error: emit("error")
+  };
+}
+function safe(meta) {
+  try {
+    return typeof meta === "string" ? meta : JSON.stringify(meta);
+  } catch {
+    return String(meta);
+  }
+}
+var noopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+
+// src/retry.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function withRetry(fn, opts = {}, logger, label = "request") {
+  const retries = Math.max(1, opts.retries ?? 3);
+  const minDelay = opts.minDelayMs ?? 200;
+  const maxDelay = opts.maxDelayMs ?? 5e3;
+  const shouldRetry = opts.shouldRetry ?? (() => true);
+  let lastError;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries || !shouldRetry(error, attempt)) break;
+      const backoff = Math.min(maxDelay, minDelay * 2 ** (attempt - 1));
+      const delay = Math.round(Math.random() * backoff);
+      logger?.warn(`${label} failed (attempt ${attempt}/${retries}), retrying in ${delay}ms`, errMsg(error));
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+function errMsg(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/transport-types.ts
+async function resolveAuthHeaders(auth) {
+  if (!auth) return {};
+  if (auth.type === "bearer") {
+    const token = typeof auth.token === "function" ? await auth.token() : auth.token;
+    return { Authorization: `Bearer ${token}` };
+  }
+  return typeof auth.headers === "function" ? await auth.headers() : auth.headers;
+}
+export {
+  createConsoleLogger,
+  noopLogger,
+  resolveAuthHeaders,
+  withRetry
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/retry.ts","../src/transport-types.ts"],"sourcesContent":["export type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\" | \"silent\";\n\nexport interface Logger {\n  debug(msg: string, meta?: unknown): void;\n  info(msg: string, meta?: unknown): void;\n  warn(msg: string, meta?: unknown): void;\n  error(msg: string, meta?: unknown): void;\n}\n\nconst LEVEL_ORDER: Record<Exclude<LogLevel, \"silent\">, number> = {\n  debug: 10,\n  info: 20,\n  warn: 30,\n  error: 40,\n};\n\n/**\n * Minimal structured logger with no external dependency. In Node it writes to\n * `process.stderr` (so it never corrupts stdio MCP protocol traffic); in the\n * browser it falls back to `console`.\n */\nexport function createConsoleLogger(level: LogLevel = \"info\"): Logger {\n  const threshold = level === \"silent\" ? Infinity : LEVEL_ORDER[level];\n  const hasStderr = typeof process !== \"undefined\" && !!process.stderr?.write;\n\n  const emit =\n    (lvl: Exclude<LogLevel, \"silent\">) =>\n    (msg: string, meta?: unknown): void => {\n      if (LEVEL_ORDER[lvl] < threshold) return;\n      const line = `[mcp-toolkit] ${lvl.toUpperCase()} ${msg}`;\n      if (hasStderr) {\n        process.stderr.write(meta !== undefined ? `${line} ${safe(meta)}\\n` : `${line}\\n`);\n      } else {\n        const fn = lvl === \"debug\" ? console.debug : lvl === \"warn\" ? console.warn : lvl === \"error\" ? console.error : console.info;\n        if (meta !== undefined) fn(line, meta);\n        else fn(line);\n      }\n    };\n\n  return {\n    debug: emit(\"debug\"),\n    info: emit(\"info\"),\n    warn: emit(\"warn\"),\n    error: emit(\"error\"),\n  };\n}\n\nfunction safe(meta: unknown): string {\n  try {\n    return typeof meta === \"string\" ? meta : JSON.stringify(meta);\n  } catch {\n    return String(meta);\n  }\n}\n\nexport const noopLogger: Logger = {\n  debug() {},\n  info() {},\n  warn() {},\n  error() {},\n};\n","import type { Logger } from \"./logger.js\";\n\nexport interface RetryOptions {\n  /** Max attempts including the first try. `1` disables retries. Default 3. */\n  retries?: number;\n  /** Base delay in ms for exponential backoff. Default 200. */\n  minDelayMs?: number;\n  /** Upper bound for a single backoff delay in ms. Default 5000. */\n  maxDelayMs?: number;\n  /** Decide whether an error is worth retrying. Default: retry everything. */\n  shouldRetry?: (error: unknown, attempt: number) => boolean;\n}\n\nconst sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));\n\n/**\n * Run `fn` with exponential backoff + full jitter. Used to wrap MCP requests so\n * transient transport / network blips don't bubble up to callers.\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  opts: RetryOptions = {},\n  logger?: Logger,\n  label = \"request\",\n): Promise<T> {\n  const retries = Math.max(1, opts.retries ?? 3);\n  const minDelay = opts.minDelayMs ?? 200;\n  const maxDelay = opts.maxDelayMs ?? 5000;\n  const shouldRetry = opts.shouldRetry ?? (() => true);\n\n  let lastError: unknown;\n  for (let attempt = 1; attempt <= retries; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      lastError = error;\n      if (attempt >= retries || !shouldRetry(error, attempt)) break;\n      const backoff = Math.min(maxDelay, minDelay * 2 ** (attempt - 1));\n      const delay = Math.round(Math.random() * backoff);\n      logger?.warn(`${label} failed (attempt ${attempt}/${retries}), retrying in ${delay}ms`, errMsg(error));\n      await sleep(delay);\n    }\n  }\n  throw lastError;\n}\n\nfunction errMsg(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n","export interface StdioTransportConfig {\n  type: \"stdio\";\n  /** Executable to spawn, e.g. \"node\". */\n  command: string;\n  /** Arguments passed to the command, e.g. [\"dist/index.js\"]. */\n  args?: string[];\n  /** Extra environment variables merged onto the spawned process env. */\n  env?: Record<string, string>;\n  /** Working directory for the spawned process. */\n  cwd?: string;\n}\n\nexport interface HttpTransportConfig {\n  type: \"http\";\n  /** Endpoint URL of the Streamable HTTP MCP server. */\n  url: string;\n  /** Static headers (merged after auth headers). */\n  headers?: Record<string, string>;\n}\n\nexport type TransportConfig = StdioTransportConfig | HttpTransportConfig;\n\n/**\n * Resolve dynamic auth into request headers. Either a static record or an async\n * getter (e.g. to refresh a bearer token before each connection).\n */\nexport type AuthConfig =\n  | { type: \"bearer\"; token: string | (() => string | Promise<string>) }\n  | {\n      type: \"headers\";\n      headers:\n        | Record<string, string>\n        | (() => Record<string, string> | Promise<Record<string, string>>);\n    };\n\n/** Resolve an {@link AuthConfig} into concrete request headers. */\nexport async function resolveAuthHeaders(auth?: AuthConfig): Promise<Record<string, string>> {\n  if (!auth) return {};\n  if (auth.type === \"bearer\") {\n    const token = typeof auth.token === \"function\" ? await auth.token() : auth.token;\n    return { Authorization: `Bearer ${token}` };\n  }\n  return typeof auth.headers === \"function\" ? await auth.headers() : auth.headers;\n}\n"],"mappings":";AASA,IAAM,cAA2D;AAAA,EAC/D,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT;AAOO,SAAS,oBAAoB,QAAkB,QAAgB;AACpE,QAAM,YAAY,UAAU,WAAW,WAAW,YAAY,KAAK;AACnE,QAAM,YAAY,OAAO,YAAY,eAAe,CAAC,CAAC,QAAQ,QAAQ;AAEtE,QAAM,OACJ,CAAC,QACD,CAAC,KAAa,SAAyB;AACrC,QAAI,YAAY,GAAG,IAAI,UAAW;AAClC,UAAM,OAAO,iBAAiB,IAAI,YAAY,CAAC,IAAI,GAAG;AACtD,QAAI,WAAW;AACb,cAAQ,OAAO,MAAM,SAAS,SAAY,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC;AAAA,IAAO,GAAG,IAAI;AAAA,CAAI;AAAA,IACnF,OAAO;AACL,YAAM,KAAK,QAAQ,UAAU,QAAQ,QAAQ,QAAQ,SAAS,QAAQ,OAAO,QAAQ,UAAU,QAAQ,QAAQ,QAAQ;AACvH,UAAI,SAAS,OAAW,IAAG,MAAM,IAAI;AAAA,UAChC,IAAG,IAAI;AAAA,IACd;AAAA,EACF;AAEF,SAAO;AAAA,IACL,OAAO,KAAK,OAAO;AAAA,IACnB,MAAM,KAAK,MAAM;AAAA,IACjB,MAAM,KAAK,MAAM;AAAA,IACjB,OAAO,KAAK,OAAO;AAAA,EACrB;AACF;AAEA,SAAS,KAAK,MAAuB;AACnC,MAAI;AACF,WAAO,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU,IAAI;AAAA,EAC9D,QAAQ;AACN,WAAO,OAAO,IAAI;AAAA,EACpB;AACF;AAEO,IAAM,aAAqB;AAAA,EAChC,QAAQ;AAAA,EAAC;AAAA,EACT,OAAO;AAAA,EAAC;AAAA,EACR,OAAO;AAAA,EAAC;AAAA,EACR,QAAQ;AAAA,EAAC;AACX;;;AC/CA,IAAM,QAAQ,CAAC,OAAe,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAMlE,eAAsB,UACpB,IACA,OAAqB,CAAC,GACtB,QACA,QAAQ,WACI;AACZ,QAAM,UAAU,KAAK,IAAI,GAAG,KAAK,WAAW,CAAC;AAC7C,QAAM,WAAW,KAAK,cAAc;AACpC,QAAM,WAAW,KAAK,cAAc;AACpC,QAAM,cAAc,KAAK,gBAAgB,MAAM;AAE/C,MAAI;AACJ,WAAS,UAAU,GAAG,WAAW,SAAS,WAAW;AACnD,QAAI;AACF,aAAO,MAAM,GAAG;AAAA,IAClB,SAAS,OAAO;AACd,kBAAY;AACZ,UAAI,WAAW,WAAW,CAAC,YAAY,OAAO,OAAO,EAAG;AACxD,YAAM,UAAU,KAAK,IAAI,UAAU,WAAW,MAAM,UAAU,EAAE;AAChE,YAAM,QAAQ,KAAK,MAAM,KAAK,OAAO,IAAI,OAAO;AAChD,cAAQ,KAAK,GAAG,KAAK,oBAAoB,OAAO,IAAI,OAAO,kBAAkB,KAAK,MAAM,OAAO,KAAK,CAAC;AACrG,YAAM,MAAM,KAAK;AAAA,IACnB;AAAA,EACF;AACA,QAAM;AACR;AAEA,SAAS,OAAO,OAAwB;AACtC,SAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;;;ACZA,eAAsB,mBAAmB,MAAoD;AAC3F,MAAI,CAAC,KAAM,QAAO,CAAC;AACnB,MAAI,KAAK,SAAS,UAAU;AAC1B,UAAM,QAAQ,OAAO,KAAK,UAAU,aAAa,MAAM,KAAK,MAAM,IAAI,KAAK;AAC3E,WAAO,EAAE,eAAe,UAAU,KAAK,GAAG;AAAA,EAC5C;AACA,SAAO,OAAO,KAAK,YAAY,aAAa,MAAM,KAAK,QAAQ,IAAI,KAAK;AAC1E;","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ubuligan/shared",
+  "version": "0.1.0",
+  "description": "Shared, dependency-free types and utilities for the MCP Toolkit (logger, retry, transport types)",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "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/shared"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "types",
+    "utils"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}