mcp-server-framework 1.0.0

package/build/utils/zod-helpers.js

@@ -0,0 +1,120 @@
+/**
+ * Zod Schema Helpers
+ *
+ * Reusable Zod schema primitives for environment variable parsing.
+ * These helpers eliminate repetition in `env.ts` and ensure consistent
+ * coercion behavior for common patterns:
+ *
+ * - Boolean env vars (`"true"` / `"false"` strings)
+ * - Comma-separated lists (`"a,b,c"` → `string[]`)
+ *
+ * @module utils/zod-helpers
+ */
+import { z } from "zod";
+import { splitCommaSeparated, parseByteSize } from "./string-helpers.js";
+// ============================================================================
+// Boolean Coercion
+// ============================================================================
+/**
+ * Zod schema for boolean environment variables.
+ *
+ * Accepts both native booleans (from config files) and string values
+ * from process.env. Only `"true"` (case-insensitive) maps to `true`,
+ * everything else maps to `false`.
+ *
+ * @param defaultValue - Default value when the env var is not set
+ * @returns Zod schema that outputs a `boolean`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * OTEL_ENABLED: booleanFromEnv(false),
+ * MCP_LEGACY_SSE_ENABLED: booleanFromEnv(false),
+ * ```
+ */
+export function booleanFromEnv(defaultValue) {
+    return z
+        .boolean()
+        .or(z.string().transform((val) => val.toLowerCase() === "true"))
+        .default(defaultValue);
+}
+// ============================================================================
+// Comma-Separated Lists
+// ============================================================================
+/**
+ * Zod schema for comma-separated string list env vars.
+ *
+ * Splits on `,`, trims whitespace, removes empty segments.
+ * Optionally lowercases all values.
+ *
+ * Use for **required** list fields that always produce a `string[]`.
+ * For optional fields that should return `undefined` when empty,
+ * use {@link optionalCommaSeparatedList}.
+ *
+ * @param options - Configuration for list parsing
+ * @param options.lowercase - Lowercase all values (default: false)
+ * @returns Zod schema that outputs `string[]`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * OTEL_METRICS_EXPORTER: commaSeparatedList({ lowercase: true }).default('otlp,prometheus'),
+ * ```
+ */
+export function commaSeparatedList(options = {}) {
+    return z.string().transform((val) => splitCommaSeparated(val, options));
+}
+/**
+ * Zod schema for optional comma-separated string list env vars.
+ *
+ * Like {@link commaSeparatedList}, but returns `undefined` when the
+ * input is empty or produces no items after trimming. The resulting
+ * field type is `string[] | undefined`.
+ *
+ * Use for optional list fields where absence has semantic meaning
+ * (e.g., "use defaults" for allowed origins/hosts).
+ *
+ * @returns Zod schema that outputs `string[] | undefined`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * MCP_ALLOWED_ORIGINS: optionalCommaSeparatedList(),
+ * MCP_ALLOWED_HOSTS: optionalCommaSeparatedList(),
+ * ```
+ */
+export function optionalCommaSeparatedList() {
+    return z
+        .string()
+        .transform((val) => {
+        const list = splitCommaSeparated(val);
+        return list.length > 0 ? list : undefined;
+    })
+        .optional();
+}
+// ============================================================================
+// Byte Size
+// ============================================================================
+/**
+ * Zod schema for human-readable byte size environment variables.
+ *
+ * Accepts strings like `"10mb"`, `"500kb"`, `"1.5gb"`, or plain byte
+ * counts like `"1048576"`. Transforms the input to a `number` (bytes)
+ * via {@link parseByteSize}.
+ *
+ * @param defaultValue - Default value as human-readable string (e.g. `'10mb'`)
+ * @returns Zod schema that accepts `string` and outputs `number` (bytes)
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * LOG_MAX_FILE_SIZE: byteSizeSchema('10mb').pipe(z.number().int().min(1024)),
+ * ```
+ */
+export function byteSizeSchema(defaultValue) {
+    return z
+        .string()
+        .transform((val) => parseByteSize(val))
+        .default(defaultValue);
+}
+//# sourceMappingURL=zod-helpers.js.map

package/build/utils/zod-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-helpers.js","sourceRoot":"","sources":["../../src/utils/zod-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzE,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,YAAqB;IAClD,OAAO,CAAC;SACL,OAAO,EAAE;SACT,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;SAC/D,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B,CAAC;AAED,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAmC,EAAE;IACtE,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC;SACL,MAAM,EAAE;SACR,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;QACjB,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5C,CAAC,CAAC;SACD,QAAQ,EAAE,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,YAAoB;IACjD,OAAO,CAAC;SACL,MAAM,EAAE;SACR,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;SACtC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "mcp-server-framework",
+  "version": "1.0.0",
+  "description": "Production-ready MCP Server Framework with built-in logging, metrics, sessions, and multi-transport support.",
+  "license": "LGPL-3.0",
+  "author": "Marcel Pfennig",
+  "homepage": "https://github.com/MP-Tool/mcp-server-framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MP-Tool/mcp-server-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MP-Tool/mcp-server-framework/issues"
+  },
+  "keywords": [
+    "model-context-protocol",
+    "mcp",
+    "mcp-server",
+    "framework",
+    "ai",
+    "llm",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    },
+    "./config": {
+      "types": "./build/config/index.d.ts",
+      "import": "./build/config/index.js"
+    },
+    "./connection": {
+      "types": "./build/connection/index.d.ts",
+      "import": "./build/connection/index.js"
+    },
+    "./errors": {
+      "types": "./build/errors/index.d.ts",
+      "import": "./build/errors/index.js"
+    },
+    "./http": {
+      "types": "./build/server/http/index.d.ts",
+      "import": "./build/server/http/index.js"
+    },
+    "./logger": {
+      "types": "./build/logger/index.d.ts",
+      "import": "./build/logger/index.js"
+    },
+    "./session": {
+      "types": "./build/server/session/index.d.ts",
+      "import": "./build/server/session/index.js"
+    },
+    "./telemetry": {
+      "types": "./build/telemetry/index.d.ts",
+      "import": "./build/telemetry/index.js"
+    }
+  },
+  "sideEffects": [
+    "./build/mcp/capabilities/registry/tool-registry.js",
+    "./build/mcp/capabilities/registry/resource-registry.js",
+    "./build/mcp/capabilities/registry/prompt-registry.js",
+    "./build/mcp/capabilities/registry/task-tool-registry.js"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.js.map",
+    "build/**/*.d.ts",
+    "build/**/*.d.ts.map",
+    "README.md",
+    "LICENSE.md",
+    "LICENSE-GPL.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"*.json\" \"*.js\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-prometheus": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/instrumentation-express": "^0.61.0",
+    "@opentelemetry/instrumentation-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "cors": "^2.8.5",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "helmet": "^8.1.0",
+    "smol-toml": "^1.3.1",
+    "yaml": "^2.7.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.9",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.7.4",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-mermaid": "^1.12.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.57.1",
+    "vitest": "^4.1.0"
+  }
+}