mcp-server-framework 1.0.0

package/build/server/builder/primitive-collector.js

@@ -0,0 +1,89 @@
+/**
+ * Primitive Collector
+ *
+ * Collects tools, resources, resource templates, and prompts from
+ * providers and direct registrations. Detects duplicates with warnings
+ * and returns frozen, immutable arrays.
+ *
+ * Extracted from McpServerBuilder.build() for single responsibility.
+ *
+ * @module server/builder/primitive-collector
+ */
+import { BuilderLogMessages, BUILDER_LOG_COMPONENT } from "./constants.js";
+import { logger as frameworkLogger } from "../../logger/index.js";
+const logger = frameworkLogger.child({ component: BUILDER_LOG_COMPONENT });
+// ============================================================================
+// Collection
+// ============================================================================
+/**
+ * Collects all MCP primitives from builder state.
+ *
+ * Merges directly registered items with items from providers,
+ * warns about duplicates (last registration wins), and
+ * freezes all arrays for immutability after build.
+ *
+ * @param state - Current builder state with providers and direct registrations
+ * @returns Frozen, immutable primitive arrays
+ */
+export function collectPrimitives(state) {
+    const tools = collectItems(state.tools, state.toolProviders, (p) => p.getTools(), (t) => t.name, BuilderLogMessages.DUPLICATE_TOOL);
+    const resources = collectItems(state.resources, state.resourceProviders, (p) => p.getResources(), (r) => r.uri, BuilderLogMessages.DUPLICATE_RESOURCE);
+    const resourceTemplates = collectItems(state.resourceTemplates, state.resourceProviders, (p) => p.getTemplates(), (t) => t.uriTemplate, BuilderLogMessages.DUPLICATE_TEMPLATE);
+    const prompts = collectItems(state.prompts, state.promptProviders, (p) => p.getPrompts(), (p) => p.name, BuilderLogMessages.DUPLICATE_PROMPT);
+    const taskTools = collectItems(state.taskTools, state.taskToolProviders, (p) => p.getTaskTools(), (t) => t.name, BuilderLogMessages.DUPLICATE_TASK_TOOL);
+    if (tools.length === 0 &&
+        resources.length === 0 &&
+        resourceTemplates.length === 0 &&
+        prompts.length === 0 &&
+        taskTools.length === 0) {
+        logger.warn(BuilderLogMessages.NO_CAPABILITIES);
+    }
+    return {
+        tools: Object.freeze(tools),
+        resources: Object.freeze(resources),
+        resourceTemplates: Object.freeze(resourceTemplates),
+        prompts: Object.freeze(prompts),
+        taskTools: Object.freeze(taskTools),
+    };
+}
+// ============================================================================
+// Generic Collection Helper
+// ============================================================================
+/**
+ * Generic collection helper — merges direct items with provider items and warns about duplicates.
+ *
+ * @param direct - Directly registered items
+ * @param providers - Provider instances
+ * @param getFromProvider - Extracts items from a single provider
+ * @param getKey - Extracts the unique identifier from each item
+ * @param duplicateMessage - Printf-style log message for duplicates
+ */
+function collectItems(direct, providers, getFromProvider, getKey, duplicateMessage) {
+    const all = [...direct];
+    for (const provider of providers) {
+        all.push(...getFromProvider(provider));
+    }
+    warnDuplicates(all, getKey, duplicateMessage);
+    return all;
+}
+// ============================================================================
+// Duplicate Detection
+// ============================================================================
+/**
+ * Warns about duplicate identifiers in a collection.
+ *
+ * @param items - Collection to check
+ * @param getKey - Extracts the unique identifier from each item
+ * @param message - Printf-style log message with %s placeholder for the key
+ */
+function warnDuplicates(items, getKey, message) {
+    const seen = new Set();
+    for (const item of items) {
+        const key = getKey(item);
+        if (seen.has(key)) {
+            logger.warn(message, key);
+        }
+        seen.add(key);
+    }
+}
+//# sourceMappingURL=primitive-collector.js.map

package/build/server/builder/primitive-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-collector.js","sourceRoot":"","sources":["../../../src/server/builder/primitive-collector.ts"],"names":[],"mappings":"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"}

package/build/server/builder/server-builder.d.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP Server Builder
+ *
+ * Provides a fluent, declarative API for constructing MCP servers.
+ * This is the main entry point for the framework's server creation pattern.
+ *
+ * @module server/builder/server-builder
+ */
+import type { ServerInstance } from "../server-options.js";
+import type { ServerBuilder } from "./types.js";
+import type { ToolProvider, ToolDefinition, ResourceProvider, ResourceStaticDefinition, ResourceTemplateDefinition, PromptProvider, PromptDefinition, TaskToolProvider, TaskToolDefinition } from "../../mcp/types/index.js";
+import type { ServerOptions } from "../server-options.js";
+/**
+ * Fluent builder for constructing MCP servers.
+ *
+ * Provides a declarative API for configuring all aspects of an MCP server
+ * including tools, resources, prompts, transport, and lifecycle hooks.
+ *
+ * @example Basic usage with tool provider
+ * ```typescript
+ * const server = new McpServerBuilder()
+ *   .withOptions({
+ *     name: 'my-mcp-server',
+ *     version: '1.0.0',
+ *     transport: { mode: 'stdio' },
+ *   })
+ *   .withToolProvider(myToolRegistry)
+ *   .build();
+ *
+ * await server.start();
+ * ```
+ */
+export declare class McpServerBuilder implements ServerBuilder {
+    private state;
+    private built;
+    constructor();
+    withOptions(options: ServerOptions): ServerBuilder;
+    withToolProvider(provider: ToolProvider): ServerBuilder;
+    withTools(tools: ReadonlyArray<ToolDefinition>): ServerBuilder;
+    withResourceProvider(provider: ResourceProvider): ServerBuilder;
+    withResources(resources: ReadonlyArray<ResourceStaticDefinition>): ServerBuilder;
+    withResourceTemplates(templates: ReadonlyArray<ResourceTemplateDefinition>): ServerBuilder;
+    withPromptProvider(provider: PromptProvider): ServerBuilder;
+    withPrompts(prompts: ReadonlyArray<PromptDefinition>): ServerBuilder;
+    withTaskToolProvider(provider: TaskToolProvider): ServerBuilder;
+    withTaskTools(taskTools: ReadonlyArray<TaskToolDefinition>): ServerBuilder;
+    build(): ServerInstance;
+    /**
+     * Creates the session factory and server instance from validated options.
+     */
+    private createServerInstance;
+}
+//# sourceMappingURL=server-builder.d.ts.map

package/build/server/builder/server-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-builder.d.ts","sourceRoot":"","sources":["../../../src/server/builder/server-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAE9D,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiB1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAS;;IAUtB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa;IAMlD,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa;IAKvD,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,aAAa;IAK9D,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa;IAK/D,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,wBAAwB,CAAC,GAAG,aAAa;IAKhF,qBAAqB,CAAC,SAAS,EAAE,aAAa,CAAC,0BAA0B,CAAC,GAAG,aAAa;IAK1F,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa;IAK3D,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,aAAa;IAKpE,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa;IAK/D,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,aAAa;IAS1E,KAAK,IAAI,cAAc;IAsBvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;CA2B7B"}

package/build/server/builder/server-builder.js

@@ -0,0 +1,132 @@
+/**
+ * MCP Server Builder
+ *
+ * Provides a fluent, declarative API for constructing MCP servers.
+ * This is the main entry point for the framework's server creation pattern.
+ *
+ * @module server/builder/server-builder
+ */
+import { isHttpTransport } from "../server-options.js";
+import { createBuilderState } from "./types.js";
+import { BuilderLogMessages, BUILDER_LOG_COMPONENT } from "./constants.js";
+import { McpServerInstance } from "../server-instance.js";
+import { McpSessionFactory } from "../session/session-factory.js";
+import { validateBuilderState } from "./validation.js";
+import { collectPrimitives } from "./primitive-collector.js";
+import { logger as frameworkLogger } from "../../logger/index.js";
+const logger = frameworkLogger.child({ component: BUILDER_LOG_COMPONENT });
+// ============================================================================
+// Server Builder Implementation
+// ============================================================================
+/**
+ * Fluent builder for constructing MCP servers.
+ *
+ * Provides a declarative API for configuring all aspects of an MCP server
+ * including tools, resources, prompts, transport, and lifecycle hooks.
+ *
+ * @example Basic usage with tool provider
+ * ```typescript
+ * const server = new McpServerBuilder()
+ *   .withOptions({
+ *     name: 'my-mcp-server',
+ *     version: '1.0.0',
+ *     transport: { mode: 'stdio' },
+ *   })
+ *   .withToolProvider(myToolRegistry)
+ *   .build();
+ *
+ * await server.start();
+ * ```
+ */
+export class McpServerBuilder {
+    state;
+    built = false;
+    constructor() {
+        this.state = createBuilderState();
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Fluent Configuration API
+    // ──────────────────────────────────────────────────────────────────────────
+    withOptions(options) {
+        logger.debug(BuilderLogMessages.OPTIONS_CONFIGURED, options.name, options.version);
+        this.state.options = options;
+        return this;
+    }
+    withToolProvider(provider) {
+        this.state.toolProviders.push(provider);
+        return this;
+    }
+    withTools(tools) {
+        this.state.tools.push(...tools);
+        return this;
+    }
+    withResourceProvider(provider) {
+        this.state.resourceProviders.push(provider);
+        return this;
+    }
+    withResources(resources) {
+        this.state.resources.push(...resources);
+        return this;
+    }
+    withResourceTemplates(templates) {
+        this.state.resourceTemplates.push(...templates);
+        return this;
+    }
+    withPromptProvider(provider) {
+        this.state.promptProviders.push(provider);
+        return this;
+    }
+    withPrompts(prompts) {
+        this.state.prompts.push(...prompts);
+        return this;
+    }
+    withTaskToolProvider(provider) {
+        this.state.taskToolProviders.push(provider);
+        return this;
+    }
+    withTaskTools(taskTools) {
+        this.state.taskTools.push(...taskTools);
+        return this;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Build
+    // ──────────────────────────────────────────────────────────────────────────
+    build() {
+        logger.debug(BuilderLogMessages.BUILD_STARTED);
+        // 1. Validate state — throws ConfigurationError on failure
+        const options = validateBuilderState(this.state, this.built);
+        // 2. Collect & deduplicate primitives from providers + direct registrations
+        const primitives = collectPrimitives(this.state);
+        // 3. Create server instance
+        const instance = this.createServerInstance(options, primitives);
+        this.built = true;
+        logger.debug(BuilderLogMessages.BUILD_COMPLETED);
+        return instance;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Internal
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Creates the session factory and server instance from validated options.
+     */
+    createServerInstance(options, primitives) {
+        const transport = options.transport;
+        const stateless = isHttpTransport(transport) ? transport.stateless : undefined;
+        const sessionFactory = new McpSessionFactory({
+            name: options.name,
+            version: options.version,
+            capabilities: options.capabilities,
+            handlers: options.handlers,
+            stateless,
+            tools: primitives.tools,
+            resources: primitives.resources,
+            resourceTemplates: primitives.resourceTemplates,
+            prompts: primitives.prompts,
+            taskTools: primitives.taskTools,
+            scopeFilterCapabilities: options.auth?.scopeFilterCapabilities,
+        });
+        logger.debug(BuilderLogMessages.BUILD_SUMMARY, primitives.tools.length, primitives.resources.length + primitives.resourceTemplates.length, primitives.prompts.length);
+        return new McpServerInstance(options, sessionFactory);
+    }
+}
+//# sourceMappingURL=server-builder.js.map

package/build/server/builder/server-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-builder.js","sourceRoot":"","sources":["../../../src/server/builder/server-builder.ts"],"names":[],"mappings":"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"}

package/build/server/builder/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Server Builder Types
+ *
+ * Type definitions for the declarative MCP server builder pattern.
+ *
+ * @module server/builder/types
+ */
+import type { ServerOptions, ServerInstance } from "../server-options.js";
+import type { ToolDefinition, ToolProvider, ResourceStaticDefinition, ResourceTemplateDefinition, ResourceProvider, PromptDefinition, PromptProvider, TaskToolDefinition, TaskToolProvider } from "../../mcp/types/index.js";
+/**
+ * Fluent builder interface for constructing MCP servers.
+ *
+ * Provides a declarative, type-safe API for configuring servers.
+ *
+ * @example
+ * ```typescript
+ * const server = new McpServerBuilder()
+ *   .withOptions({
+ *     name: 'my-server',
+ *     version: '1.0.0',
+ *     transport: { mode: 'stdio' },
+ *   })
+ *   .withToolProvider(myToolProvider)
+ *   .withResourceProvider(myResourceProvider)
+ *   .build();
+ *
+ * await server.start();
+ * ```
+ */
+export interface ServerBuilder {
+    /** Configure server options. */
+    withOptions(options: ServerOptions): ServerBuilder;
+    /** Register a tool provider. */
+    withToolProvider(provider: ToolProvider): ServerBuilder;
+    /** Register individual tools. */
+    withTools(tools: ReadonlyArray<ToolDefinition>): ServerBuilder;
+    /** Register a resource provider. */
+    withResourceProvider(provider: ResourceProvider): ServerBuilder;
+    /** Register individual static resources. */
+    withResources(resources: ReadonlyArray<ResourceStaticDefinition>): ServerBuilder;
+    /** Register resource templates. */
+    withResourceTemplates(templates: ReadonlyArray<ResourceTemplateDefinition>): ServerBuilder;
+    /** Register a prompt provider. */
+    withPromptProvider(provider: PromptProvider): ServerBuilder;
+    /** Register individual prompts. */
+    withPrompts(prompts: ReadonlyArray<PromptDefinition>): ServerBuilder;
+    /**
+     * Register a task tool provider.
+     * @experimental MCP Tasks is an experimental SDK feature
+     */
+    withTaskToolProvider(provider: TaskToolProvider): ServerBuilder;
+    /**
+     * Register individual task tools.
+     * @experimental MCP Tasks is an experimental SDK feature
+     */
+    withTaskTools(taskTools: ReadonlyArray<TaskToolDefinition>): ServerBuilder;
+    /** Build and return the configured server instance. */
+    build(): ServerInstance;
+}
+/**
+ * Internal state tracked by the builder.
+ * @internal
+ */
+export interface BuilderState {
+    options?: ServerOptions | undefined;
+    toolProviders: ToolProvider[];
+    tools: ToolDefinition[];
+    resourceProviders: ResourceProvider[];
+    resources: ResourceStaticDefinition[];
+    resourceTemplates: ResourceTemplateDefinition[];
+    promptProviders: PromptProvider[];
+    prompts: PromptDefinition[];
+    taskToolProviders: TaskToolProvider[];
+    taskTools: TaskToolDefinition[];
+}
+/**
+ * Creates a fresh builder state.
+ */
+export declare function createBuilderState(): BuilderState;
+/**
+ * Result of collecting primitives from the builder state.
+ *
+ * All arrays are frozen (immutable) after collection.
+ * Used as input for the session factory.
+ */
+export interface CollectedPrimitives {
+    readonly tools: ReadonlyArray<ToolDefinition>;
+    readonly resources: ReadonlyArray<ResourceStaticDefinition>;
+    readonly resourceTemplates: ReadonlyArray<ResourceTemplateDefinition>;
+    readonly prompts: ReadonlyArray<PromptDefinition>;
+    readonly taskTools: ReadonlyArray<TaskToolDefinition>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/server/builder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;IAEnD,gCAAgC;IAChC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,CAAC;IAExD,iCAAiC;IACjC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,aAAa,CAAC;IAE/D,oCAAoC;IACpC,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAAC;IAEhE,4CAA4C;IAC5C,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,wBAAwB,CAAC,GAAG,aAAa,CAAC;IAEjF,mCAAmC;IACnC,qBAAqB,CAAC,SAAS,EAAE,aAAa,CAAC,0BAA0B,CAAC,GAAG,aAAa,CAAC;IAE3F,kCAAkC;IAClC,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa,CAAC;IAE5D,mCAAmC;IACnC,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;IAErE;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAAC;IAEhE;;;OAGG;IACH,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC;IAE3E,uDAAuD;IACvD,KAAK,IAAI,cAAc,CAAC;CACzB;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;IAChD,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAajD;AAMD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,wBAAwB,CAAC,CAAC;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAAC;IACtE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACvD"}

package/build/server/builder/types.js

@@ -0,0 +1,25 @@
+/**
+ * Server Builder Types
+ *
+ * Type definitions for the declarative MCP server builder pattern.
+ *
+ * @module server/builder/types
+ */
+/**
+ * Creates a fresh builder state.
+ */
+export function createBuilderState() {
+    return {
+        options: undefined,
+        toolProviders: [],
+        tools: [],
+        resourceProviders: [],
+        resources: [],
+        resourceTemplates: [],
+        promptProviders: [],
+        prompts: [],
+        taskToolProviders: [],
+        taskTools: [],
+    };
+}
+//# sourceMappingURL=types.js.map

package/build/server/builder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqGH;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,OAAO,EAAE,SAAS;QAClB,aAAa,EAAE,EAAE;QACjB,KAAK,EAAE,EAAE;QACT,iBAAiB,EAAE,EAAE;QACrB,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,EAAE;QACrB,eAAe,EAAE,EAAE;QACnB,OAAO,EAAE,EAAE;QACX,iBAAiB,EAAE,EAAE;QACrB,SAAS,EAAE,EAAE;KACd,CAAC;AACJ,CAAC"}

package/build/server/builder/validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Builder Validation
+ *
+ * Validates builder state before server construction.
+ * Extracted from McpServerBuilder.build() for single responsibility.
+ *
+ * @module server/builder/validation
+ */
+import type { ServerOptions } from "../server-options.js";
+import type { BuilderState } from "./types.js";
+/**
+ * Server options after validation — name and version are guaranteed non-empty.
+ *
+ * This type narrows the optional fields to their required forms
+ * so downstream code doesn't need redundant null checks.
+ */
+export interface ValidatedServerOptions extends ServerOptions {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Validates that the builder state is ready for server construction.
+ *
+ * Checks:
+ * - Builder has not been used before (single-use guard)
+ * - Options have been configured via withOptions()
+ * - Server name is present and non-empty
+ * - Server version is present and non-empty
+ *
+ * @param state - Current builder state
+ * @param built - Whether this builder instance has already been used
+ * @returns Validated options with guaranteed name and version
+ * @throws ConfigurationError if any validation fails
+ */
+export declare function validateBuilderState(state: BuilderState, built: boolean): ValidatedServerOptions;
+//# sourceMappingURL=validation.d.ts.map

package/build/server/builder/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/server/builder/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAmBhG"}

package/build/server/builder/validation.js

@@ -0,0 +1,44 @@
+/**
+ * Builder Validation
+ *
+ * Validates builder state before server construction.
+ * Extracted from McpServerBuilder.build() for single responsibility.
+ *
+ * @module server/builder/validation
+ */
+import { BuilderMessages } from "./constants.js";
+import { ConfigurationError } from "../../errors/categories/validation.js";
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Validates that the builder state is ready for server construction.
+ *
+ * Checks:
+ * - Builder has not been used before (single-use guard)
+ * - Options have been configured via withOptions()
+ * - Server name is present and non-empty
+ * - Server version is present and non-empty
+ *
+ * @param state - Current builder state
+ * @param built - Whether this builder instance has already been used
+ * @returns Validated options with guaranteed name and version
+ * @throws ConfigurationError if any validation fails
+ */
+export function validateBuilderState(state, built) {
+    if (built) {
+        throw ConfigurationError.constraintViolation(BuilderMessages.ALREADY_BUILT, ["build"]);
+    }
+    if (!state.options) {
+        throw ConfigurationError.constraintViolation(BuilderMessages.OPTIONS_REQUIRED, ["options"]);
+    }
+    if (!state.options.name.trim()) {
+        throw ConfigurationError.constraintViolation(BuilderMessages.NAME_REQUIRED, ["options.name"]);
+    }
+    if (!state.options.version.trim()) {
+        throw ConfigurationError.constraintViolation(BuilderMessages.VERSION_REQUIRED, ["options.version"]);
+    }
+    // @type-narrowing — validated above, but TS doesn't narrow through conditionals on readonly props
+    return state.options;
+}
+//# sourceMappingURL=validation.js.map

package/build/server/builder/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/server/builder/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAiB3E,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAmB,EAAE,KAAc;IACtE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,kBAAkB,CAAC,mBAAmB,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACzF,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,kBAAkB,CAAC,mBAAmB,CAAC,eAAe,CAAC,gBAAgB,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,MAAM,kBAAkB,CAAC,mBAAmB,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,kBAAkB,CAAC,mBAAmB,CAAC,eAAe,CAAC,gBAAgB,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtG,CAAC;IAED,kGAAkG;IAClG,OAAO,KAAK,CAAC,OAAiC,CAAC;AACjD,CAAC"}

package/build/server/create-server.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Create Server Function
+ *
+ * High-level API for creating MCP servers with minimal boilerplate.
+ * Automatically uses tools, resources, and prompts from the global registries.
+ *
+ * @module server/create-server
+ */
+import type { CreateServerOptions, CreateServerResult } from "./types.js";
+/**
+ * Create an MCP server with automatic tool, resource, and prompt registration.
+ *
+ * This is the recommended way to create servers in the framework.
+ * It automatically discovers and registers all items defined with
+ * `defineTool()`, `defineResource()`, `defineResourceTemplate()`, and `definePrompt()`.
+ *
+ * @param options - Server configuration options
+ * @returns Server instance with start() and stop() methods
+ *
+ * @example
+ * ```typescript
+ * // Minimal server with stdio transport
+ * import { createServer, defineTool, text } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ *
+ * // This tool is auto-registered when the module loads
+ * export const greetTool = defineTool({
+ *   name: 'greet',
+ *   description: 'Greet a user',
+ *   input: z.object({ name: z.string() }),
+ *   handler: async ({ name }) => text(`Hello, ${name}!`),
+ * });
+ *
+ * // Create and start server
+ * const server = createServer({
+ *   name: 'greeting-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'stdio' },
+ * });
+ *
+ * await server.start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Server with HTTP transport
+ * const server = createServer({
+ *   name: 'http-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'http', port: 3000 },
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+export declare function createServer(options: CreateServerOptions): CreateServerResult;
+//# sourceMappingURL=create-server.d.ts.map

package/build/server/create-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../../src/server/create-server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAM1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAkD7E"}