mcp-server-framework 1.0.0

package/build/server/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Create Server Types
+ *
+ * Types for the createServer() high-level API.
+ *
+ * @module server/types
+ */
+import type { TransportOptions, ServerCapabilities, HealthConfig, SessionConfigOptions } from "./server-options.js";
+import type { ServerLifecycleHooks, ShutdownConfig } from "./lifecycle.js";
+import type { AuthOptions } from "./auth/types.js";
+/**
+ * Options for createServer() - simplified high-level API.
+ *
+ * This interface provides sensible defaults while allowing customization.
+ * All fields are optional except for name and version (which have defaults).
+ *
+ * @example
+ * ```typescript
+ * // Minimal - just use auto-registered tools
+ * const server = createServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'stdio' },
+ * });
+ * ```
+ */
+export interface CreateServerOptions {
+    /**
+     * Server name displayed to MCP clients.
+     *
+     * @default 'mcp-server'
+     */
+    name?: string;
+    /**
+     * Server version.
+     *
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * Transport configuration (required).
+     *
+     * Explicitly specify how the server communicates with clients.
+     * Use `{ mode: 'stdio' }` for CLI usage or `{ mode: 'http' }` for network usage.
+     *
+     * @see TransportOptions for details
+     */
+    transport: TransportOptions;
+    /**
+     * Server capabilities to advertise.
+     *
+     * @default { tools: { listChanged: true }, logging: true }
+     */
+    capabilities?: ServerCapabilities;
+    /**
+     * Lifecycle hooks for startup/shutdown.
+     */
+    lifecycle?: ServerLifecycleHooks;
+    /**
+     * Shutdown configuration.
+     */
+    shutdown?: Partial<ShutdownConfig>;
+    /**
+     * Health endpoint configuration for API connectivity monitoring.
+     *
+     * Wires a {@link ConnectionStateManager} to the `/ready` endpoint so
+     * readiness probes reflect the actual API connection state.
+     *
+     * @see HealthConfig
+     */
+    health?: HealthConfig;
+    /**
+     * Session management configuration.
+     *
+     * Fine-tune session lifecycle (timeouts, cleanup, capacity).
+     * Only effective for HTTP-based transports.
+     *
+     * @see SessionConfigOptions
+     */
+    session?: SessionConfigOptions;
+    /**
+     * Authentication configuration.
+     *
+     * Enables OAuth 2.1 or custom token verification on the server.
+     * Only effective for HTTP-based transports.
+     *
+     * @see AuthOptions
+     */
+    auth?: AuthOptions;
+    /**
+     * Enable OpenTelemetry integration.
+     *
+     * When not set, falls back to `OTEL_ENABLED` env var or config file.
+     * Set explicitly to `true` or `false` to override the config.
+     *
+     * @default undefined (falls back to OTEL_ENABLED)
+     */
+    telemetry?: boolean;
+    /**
+     * Called before the OpenTelemetry SDK is initialized.
+     *
+     * Power users can use this callback to configure low-level OTEL APIs
+     * before the framework creates the NodeSDK instance. Common use cases:
+     *
+     * - Set a custom `DiagLogger` via `diag.setLogger()` for SDK-level
+     *   diagnostics (by default no DiagLogger is set — output is suppressed)
+     * - Register custom instrumentation
+     * - Configure global propagators or samplers
+     *
+     * The callback runs after framework config resolution but before
+     * `OTEL_LOG_LEVEL` is consumed from `process.env` and SDK construction.
+     *
+     * **Important**: Custom DiagLoggers must NOT write to stdout (reserved
+     * for MCP protocol data in stdio transport mode).
+     *
+     * @see ServerOptions.onBeforeTelemetryInit for the full documentation
+     */
+    onBeforeTelemetryInit?: () => void;
+}
+/**
+ * Result returned from createServer().
+ */
+export interface CreateServerResult {
+    /**
+     * Start the server.
+     *
+     * @returns Promise that resolves when server is fully started
+     */
+    start: () => Promise<void>;
+    /**
+     * Stop the server gracefully.
+     *
+     * @returns Promise that resolves when server is stopped
+     */
+    stop: () => Promise<void>;
+    /**
+     * Initialize OpenTelemetry before starting the server.
+     *
+     * Call as early as possible so OTEL auto-instrumentation can
+     * hook into HTTP/Express modules before they are loaded.
+     * No-op if telemetry is disabled. Falls back automatically
+     * in `start()` if not called explicitly.
+     */
+    initTelemetry: () => Promise<void>;
+    /**
+     * Notify all connected MCP clients that the tool list has changed.
+     *
+     * Call this when external state changes affect tool availability
+     * (e.g., API connection state, feature flags).
+     */
+    notifyToolListChanged: () => void;
+    /**
+     * Notify all connected MCP clients that the resource list has changed.
+     */
+    notifyResourceListChanged: () => void;
+    /**
+     * Notify all connected MCP clients that the prompt list has changed.
+     */
+    notifyPromptListChanged: () => void;
+    /**
+     * Notify subscribed MCP clients that a specific resource has been updated.
+     *
+     * Only clients that previously sent `resources/subscribe` for the given URI
+     * receive the `notifications/resources/updated` notification.
+     *
+     * Requires `capabilities: { resources: { subscribe: true } }` to be set.
+     *
+     * @param uri - The resource URI that has changed
+     */
+    notifyResourceUpdated: (uri: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACpH,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAKlC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAMjB;;;;;;;OAOG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAM5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAMlC;;OAEG;IACH,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAMnC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAMtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAM/B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAMnB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAElC;;OAEG;IACH,yBAAyB,EAAE,MAAM,IAAI,CAAC;IAEtC;;OAEG;IACH,uBAAuB,EAAE,MAAM,IAAI,CAAC;IAEpC;;;;;;;;;OASG;IACH,qBAAqB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C"}

package/build/server/types.js

@@ -0,0 +1,9 @@
+/**
+ * Create Server Types
+ *
+ * Types for the createServer() high-level API.
+ *
+ * @module server/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/build/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/build/telemetry/connection-telemetry-bridge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Connection Telemetry Bridge
+ *
+ * Factory that creates a real ConnectionTelemetry implementation using
+ * the server's OpenTelemetry tracing and metrics infrastructure.
+ *
+ * This bridges the api/connection module (which defines the interface)
+ * with the server/telemetry module (which provides the implementation),
+ * maintaining proper Dependency Inversion: api/ depends on abstractions,
+ * server/ provides the concrete implementation.
+ *
+ * @module server/telemetry/connection-telemetry-bridge
+ */
+import type { ConnectionTelemetry } from "../connection/index.js";
+/**
+ * Creates a ConnectionTelemetry implementation backed by real OpenTelemetry.
+ *
+ * Use this when creating a ConnectionStateManager that should emit
+ * distributed tracing spans and metrics.
+ *
+ * @example
+ * ```typescript
+ * import { createConnectionTelemetry } from 'mcp-server-framework/telemetry';
+ * import { ConnectionStateManager } from 'mcp-server-framework/connection';
+ *
+ * const manager = new ConnectionStateManager(createConnectionTelemetry());
+ * ```
+ */
+export declare function createConnectionTelemetry(): ConnectionTelemetry;
+//# sourceMappingURL=connection-telemetry-bridge.d.ts.map

package/build/telemetry/connection-telemetry-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-telemetry-bridge.d.ts","sourceRoot":"","sources":["../../src/telemetry/connection-telemetry-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,wBAAwB,CAAC;AAOjF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,CAwB/D"}

package/build/telemetry/connection-telemetry-bridge.js

@@ -0,0 +1,54 @@
+/**
+ * Connection Telemetry Bridge
+ *
+ * Factory that creates a real ConnectionTelemetry implementation using
+ * the server's OpenTelemetry tracing and metrics infrastructure.
+ *
+ * This bridges the api/connection module (which defines the interface)
+ * with the server/telemetry module (which provides the implementation),
+ * maintaining proper Dependency Inversion: api/ depends on abstractions,
+ * server/ provides the concrete implementation.
+ *
+ * @module server/telemetry/connection-telemetry-bridge
+ */
+import { withSpan, addSpanAttributes, addSpanEvent, getServerMetrics } from "./index.js";
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a ConnectionTelemetry implementation backed by real OpenTelemetry.
+ *
+ * Use this when creating a ConnectionStateManager that should emit
+ * distributed tracing spans and metrics.
+ *
+ * @example
+ * ```typescript
+ * import { createConnectionTelemetry } from 'mcp-server-framework/telemetry';
+ * import { ConnectionStateManager } from 'mcp-server-framework/connection';
+ *
+ * const manager = new ConnectionStateManager(createConnectionTelemetry());
+ * ```
+ */
+export function createConnectionTelemetry() {
+    return {
+        async withSpan(name, fn) {
+            return withSpan(name, (otelSpan) => {
+                // Adapt OpenTelemetry Span → TelemetrySpan interface
+                const bridgeSpan = {
+                    setAttribute: (key, value) => otelSpan.setAttribute(key, value),
+                };
+                return fn(bridgeSpan);
+            });
+        },
+        addSpanAttributes(attrs) {
+            addSpanAttributes(attrs);
+        },
+        addSpanEvent(name, attrs) {
+            addSpanEvent(name, attrs);
+        },
+        recordConnectionStateChange(previousState, newState) {
+            getServerMetrics().recordConnectionStateChange(previousState, newState);
+        },
+    };
+}
+//# sourceMappingURL=connection-telemetry-bridge.js.map

package/build/telemetry/connection-telemetry-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-telemetry-bridge.js","sourceRoot":"","sources":["../../src/telemetry/connection-telemetry-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEzF,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,KAAK,CAAC,QAAQ,CAAI,IAAY,EAAE,EAAuC;YACrE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE;gBACjC,qDAAqD;gBACrD,MAAM,UAAU,GAAkB;oBAChC,YAAY,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;iBAChE,CAAC;gBACF,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,iBAAiB,CAAC,KAA4D;YAC5E,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QAED,YAAY,CAAC,IAAY,EAAE,KAA6D;YACtF,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;QAED,2BAA2B,CAAC,aAAqB,EAAE,QAAgB;YACjE,gBAAgB,EAAE,CAAC,2BAA2B,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/build/telemetry/core/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Telemetry Configuration
+ *
+ * Provides type-safe access to OpenTelemetry settings from the central config.
+ * Delegates to the application's centralized environment configuration.
+ *
+ * Both framework-managed and standard OTEL settings are routed through
+ * the config system. This ensures a single source of truth and allows
+ * all settings to be configured via environment variables OR config file.
+ *
+ * @module server/telemetry/core/config
+ */
+import type { TelemetryConfig } from "./types.js";
+/**
+ * Get telemetry configuration from centralized application config.
+ *
+ * Framework-managed:
+ * - `OTEL_ENABLED` — Master toggle (default: false)
+ * - `OTEL_SERVICE_NAME` — Service name (default: MCP server name from `createServer()`)
+ * - `OTEL_METRICS_EXPORTER` — Metric exporters (default: 'otlp,prometheus')
+ *
+ * Standard OTEL (pass-through):
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL
+ * - `OTEL_TRACES_EXPORTER` — Trace exporter selection
+ * - `OTEL_LOGS_EXPORTER` — Log exporter selection (default: 'none')
+ * - `OTEL_LOG_LEVEL` — SDK diagnostic log level
+ * - `OTEL_METRIC_EXPORT_INTERVAL` — Periodic metric export interval
+ *
+ * @returns Telemetry configuration object
+ */
+export declare function getTelemetryConfig(): TelemetryConfig;
+/**
+ * Check if OpenTelemetry is enabled.
+ *
+ * @returns true if OTEL_ENABLED=true
+ */
+export declare function isTelemetryEnabled(): boolean;
+//# sourceMappingURL=config.d.ts.map

package/build/telemetry/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/telemetry/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAapD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C"}

package/build/telemetry/core/config.js

@@ -0,0 +1,54 @@
+/**
+ * Telemetry Configuration
+ *
+ * Provides type-safe access to OpenTelemetry settings from the central config.
+ * Delegates to the application's centralized environment configuration.
+ *
+ * Both framework-managed and standard OTEL settings are routed through
+ * the config system. This ensures a single source of truth and allows
+ * all settings to be configured via environment variables OR config file.
+ *
+ * @module server/telemetry/core/config
+ */
+import { getFrameworkConfig } from "../../config/index.js";
+import { TELEMETRY_DEFAULTS } from "./constants.js";
+/**
+ * Get telemetry configuration from centralized application config.
+ *
+ * Framework-managed:
+ * - `OTEL_ENABLED` — Master toggle (default: false)
+ * - `OTEL_SERVICE_NAME` — Service name (default: MCP server name from `createServer()`)
+ * - `OTEL_METRICS_EXPORTER` — Metric exporters (default: 'otlp,prometheus')
+ *
+ * Standard OTEL (pass-through):
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL
+ * - `OTEL_TRACES_EXPORTER` — Trace exporter selection
+ * - `OTEL_LOGS_EXPORTER` — Log exporter selection (default: 'none')
+ * - `OTEL_LOG_LEVEL` — SDK diagnostic log level
+ * - `OTEL_METRIC_EXPORT_INTERVAL` — Periodic metric export interval
+ *
+ * @returns Telemetry configuration object
+ */
+export function getTelemetryConfig() {
+    const config = getFrameworkConfig();
+    return {
+        enabled: config.OTEL_ENABLED,
+        serviceName: config.OTEL_SERVICE_NAME ?? TELEMETRY_DEFAULTS.SERVICE_NAME,
+        serviceVersion: config.VERSION,
+        endpoint: config.OTEL_EXPORTER_OTLP_ENDPOINT ?? TELEMETRY_DEFAULTS.OTLP_ENDPOINT,
+        tracesExporter: config.OTEL_TRACES_EXPORTER,
+        logsExporter: config.OTEL_LOGS_EXPORTER,
+        logLevel: config.OTEL_LOG_LEVEL,
+        metricExportInterval: config.OTEL_METRIC_EXPORT_INTERVAL,
+        metricsExporters: config.OTEL_METRICS_EXPORTER,
+    };
+}
+/**
+ * Check if OpenTelemetry is enabled.
+ *
+ * @returns true if OTEL_ENABLED=true
+ */
+export function isTelemetryEnabled() {
+    return getFrameworkConfig().OTEL_ENABLED;
+}
+//# sourceMappingURL=config.js.map

package/build/telemetry/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,YAAY;QAC5B,WAAW,EAAE,MAAM,CAAC,iBAAiB,IAAI,kBAAkB,CAAC,YAAY;QACxE,cAAc,EAAE,MAAM,CAAC,OAAO;QAC9B,QAAQ,EAAE,MAAM,CAAC,2BAA2B,IAAI,kBAAkB,CAAC,aAAa;QAChF,cAAc,EAAE,MAAM,CAAC,oBAAoB;QAC3C,YAAY,EAAE,MAAM,CAAC,kBAAkB;QACvC,QAAQ,EAAE,MAAM,CAAC,cAAc;QAC/B,oBAAoB,EAAE,MAAM,CAAC,2BAA2B;QACxD,gBAAgB,EAAE,MAAM,CAAC,qBAAqB;KAC/C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,kBAAkB,EAAE,CAAC,YAAY,CAAC;AAC3C,CAAC"}

package/build/telemetry/core/constants.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Telemetry Module Constants
+ *
+ * Centralized constants for the OpenTelemetry integration module including:
+ * - Semantic attribute names for MCP operations
+ * - Metric attribute names
+ * - Log component identifiers
+ * - Log messages
+ * - Metric names
+ *
+ * @module server/telemetry/core/constants
+ */
+/**
+ * Default telemetry configuration values.
+ */
+export declare const TELEMETRY_DEFAULTS: {
+    /** Default service name (last resort when options.name is also missing) */
+    readonly SERVICE_NAME: "mcp-server";
+    /** Default service version when not available */
+    readonly SERVICE_VERSION_FALLBACK: "unknown";
+    /** Default metric exporters */
+    readonly METRICS_EXPORTER: "otlp,prometheus";
+    /** OTEL standard OTLP/HTTP endpoint (per OTEL specification) */
+    readonly OTLP_ENDPOINT: "http://localhost:4318";
+};
+/**
+ * Environment variable names for telemetry configuration.
+ *
+ * Includes both framework-managed and standard OTEL variables.
+ * Standard vars are parsed in the config system so they can be set
+ * via config file, then passed through to the SDK and exporters.
+ * See: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+ */
+export declare const TELEMETRY_ENV_VARS: {
+    /** Enable/disable OpenTelemetry (framework master toggle) */
+    readonly OTEL_ENABLED: "OTEL_ENABLED";
+    /** Service name (also read natively by SDK resource detector) */
+    readonly OTEL_SERVICE_NAME: "OTEL_SERVICE_NAME";
+    /** Metric exporters: otlp, prometheus, console, none (comma-separated) */
+    readonly OTEL_METRICS_EXPORTER: "OTEL_METRICS_EXPORTER";
+    /** OTLP exporter endpoint URL */
+    readonly OTEL_EXPORTER_OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
+    /** Trace exporter selection */
+    readonly OTEL_TRACES_EXPORTER: "OTEL_TRACES_EXPORTER";
+    /** Log exporter selection (default: 'none' — framework has own logger) */
+    readonly OTEL_LOGS_EXPORTER: "OTEL_LOGS_EXPORTER";
+    /** SDK diagnostic log level */
+    readonly OTEL_LOG_LEVEL: "OTEL_LOG_LEVEL";
+    /** Periodic metric export interval (ms) */
+    readonly OTEL_METRIC_EXPORT_INTERVAL: "OTEL_METRIC_EXPORT_INTERVAL";
+};
+/**
+ * Semantic attribute names for MCP operations.
+ * Follow OpenTelemetry semantic conventions pattern.
+ *
+ * Note: Application-specific attributes should be defined in the
+ * app layer (src/app/telemetry.ts) to keep the framework generic.
+ */
+export declare const MCP_ATTRIBUTES: {
+    /** MCP tool name */
+    readonly TOOL_NAME: "mcp.tool.name";
+    /** MCP resource URI */
+    readonly RESOURCE_URI: "mcp.resource.uri";
+    /** MCP resource template URI */
+    readonly RESOURCE_TEMPLATE: "mcp.resource.template";
+    /** MCP prompt name */
+    readonly PROMPT_NAME: "mcp.prompt.name";
+    /** MCP request ID */
+    readonly REQUEST_ID: "mcp.request.id";
+    /** MCP session ID */
+    readonly SESSION_ID: "mcp.session.id";
+    /** Operation type (tool_call, resource_read, prompt_generate) */
+    readonly OPERATION: "mcp.operation";
+    /** Whether the operation succeeded */
+    readonly SUCCESS: "mcp.success";
+    /** Result content type count */
+    readonly RESULT_CONTENT_COUNT: "mcp.result.content_count";
+    /** Whether the result indicates an error */
+    readonly RESULT_IS_ERROR: "mcp.result.is_error";
+};
+/**
+ * Semantic attribute names for server metrics.
+ */
+export declare const METRIC_ATTRIBUTES: {
+    /** Tool name being invoked */
+    readonly TOOL_NAME: "tool.name";
+    /** Transport type (http, sse, stdio) */
+    readonly TRANSPORT: "transport";
+    /** Request success status */
+    readonly SUCCESS: "success";
+    /** Error type */
+    readonly ERROR_TYPE: "error.type";
+    /** Component where error occurred */
+    readonly COMPONENT: "component";
+    /** Previous connection state */
+    readonly PREVIOUS_STATE: "connection.state.previous";
+    /** Current connection state */
+    readonly CURRENT_STATE: "connection.state.current";
+};
+/**
+ * OpenTelemetry metric instrument names.
+ */
+export declare const METRIC_NAMES: {
+    /** Counter for total requests */
+    readonly REQUESTS_TOTAL: "mcp.server.requests";
+    /** Histogram for request duration */
+    readonly REQUEST_DURATION: "mcp.server.request.duration";
+    /** UpDownCounter for active sessions */
+    readonly SESSIONS_ACTIVE: "mcp.server.sessions.active";
+    /** Counter for connection state changes */
+    readonly CONNECTION_STATE_CHANGES: "mcp.server.connection.state_changes";
+    /** Counter for errors */
+    readonly ERRORS_TOTAL: "mcp.server.errors";
+    /** Gauge for server uptime */
+    readonly UPTIME: "mcp.server.uptime";
+    /** Gauge for heap memory used */
+    readonly MEMORY_HEAP_USED: "mcp.server.memory.heap_used";
+    /** Gauge for RSS memory */
+    readonly MEMORY_RSS: "mcp.server.memory.rss";
+};
+/**
+ * Metric descriptions for documentation.
+ */
+export declare const METRIC_DESCRIPTIONS: {
+    readonly "mcp.server.requests": "Total number of MCP requests processed";
+    readonly "mcp.server.request.duration": "Duration of MCP requests in milliseconds";
+    readonly "mcp.server.sessions.active": "Number of active sessions";
+    readonly "mcp.server.connection.state_changes": "Number of connection state changes";
+    readonly "mcp.server.errors": "Total number of errors";
+    readonly "mcp.server.uptime": "Server uptime in seconds";
+    readonly "mcp.server.memory.heap_used": "Heap memory used in bytes";
+    readonly "mcp.server.memory.rss": "Resident set size in bytes";
+};
+/**
+ * Metric units following OpenTelemetry conventions.
+ */
+export declare const METRIC_UNITS: {
+    readonly COUNT: "1";
+    readonly MILLISECONDS: "ms";
+    readonly SECONDS: "s";
+    readonly BYTES: "By";
+};
+/**
+ * Logger component identifiers for the telemetry module.
+ * Used for consistent log categorization.
+ */
+export declare const TELEMETRY_LOG_COMPONENTS: {
+    /** SDK initialization component */
+    readonly SDK: "TelemetrySDK";
+    /** Tracing utilities component */
+    readonly TRACING: "Tracing";
+    /** Metrics manager component */
+    readonly METRICS: "Metrics";
+    /** Configuration component */
+    readonly CONFIG: "TelemetryConfig";
+};
+/**
+ * Centralized log messages for SDK lifecycle.
+ */
+export declare const SdkLogMessages: {
+    readonly INIT_START: "Initializing OpenTelemetry SDK";
+    readonly INIT_SUCCESS: "OpenTelemetry initialized: service=%s, endpoint=%s";
+    readonly INIT_SKIPPED: "OpenTelemetry disabled - skipping initialization";
+    readonly INIT_PACKAGES_MISSING: "OpenTelemetry packages not installed (%s). OTEL_ENABLED=true requires: npm install @opentelemetry/sdk-node @opentelemetry/sdk-metrics @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-prometheus @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express @opentelemetry/resources @opentelemetry/semantic-conventions — disabling telemetry";
+    readonly METRICS_EXPORTERS_CONFIGURED: "Metric exporters configured: %s";
+    readonly PROMETHEUS_EXPORTER_ADDED: "Prometheus MetricReader added (embedded at /metrics)";
+    readonly UNKNOWN_METRIC_EXPORTER: "Unknown metric exporter '%s' — ignored. Supported: otlp, prometheus, console, none";
+    readonly TRACE_EXPORTER_CONFIGURED: "Trace exporter configured: %s";
+    readonly UNKNOWN_TRACE_EXPORTER: "Unknown trace exporter '%s' — falling back to OTLP. Supported: otlp, console, none";
+    readonly SHUTDOWN_START: "Shutting down OpenTelemetry SDK";
+    readonly SHUTDOWN_SUCCESS: "OpenTelemetry SDK shut down successfully";
+    readonly SHUTDOWN_ERROR: "Error shutting down OpenTelemetry SDK: %s";
+    readonly SHUTDOWN_SKIPPED: "OpenTelemetry SDK not initialized - nothing to shutdown";
+};
+/**
+ * Known transport types for session tracking.
+ */
+export declare const TRANSPORT_TYPES: {
+    readonly HTTP: "http";
+    readonly SSE: "sse";
+    readonly STDIO: "stdio";
+};
+//# sourceMappingURL=constants.d.ts.map

package/build/telemetry/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/telemetry/core/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B,2EAA2E;;IAE3E,iDAAiD;;IAEjD,+BAA+B;;IAE/B,gEAAgE;;CAExD,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;IAE7B,6DAA6D;;IAE7D,iEAAiE;;IAEjE,0EAA0E;;IAI1E,iCAAiC;;IAEjC,+BAA+B;;IAE/B,0EAA0E;;IAE1E,+BAA+B;;IAE/B,2CAA2C;;CAEnC,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;IACzB,oBAAoB;;IAEpB,uBAAuB;;IAEvB,gCAAgC;;IAEhC,sBAAsB;;IAEtB,qBAAqB;;IAErB,qBAAqB;;IAErB,iEAAiE;;IAEjE,sCAAsC;;IAEtC,gCAAgC;;IAEhC,4CAA4C;;CAEpC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,8BAA8B;;IAE9B,wCAAwC;;IAExC,6BAA6B;;IAE7B,iBAAiB;;IAEjB,qCAAqC;;IAErC,gCAAgC;;IAEhC,+BAA+B;;CAEvB,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,iCAAiC;;IAEjC,qCAAqC;;IAErC,wCAAwC;;IAExC,2CAA2C;;IAE3C,yBAAyB;;IAEzB,8BAA8B;;IAE9B,iCAAiC;;IAEjC,2BAA2B;;CAEnB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;CAStB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAMX;;;GAGG;AACH,eAAO,MAAM,wBAAwB;IACnC,mCAAmC;;IAEnC,kCAAkC;;IAElC,gCAAgC;;IAEhC,8BAA8B;;CAEtB,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;CAsBjB,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC"}