@universal-mcp-toolkit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 universal-mcp-toolkit
+
+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,178 @@
+import { McpServer, PromptCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ReadResourceResult, GetPromptResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { Logger } from 'pino';
+import { ZodRawShapeCompat, ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { z } from 'zod';
+
+declare abstract class ToolkitServer {
+    readonly metadata: ToolkitServerMetadata;
+    readonly logger: Logger;
+    readonly server: McpServer;
+    private readonly tools;
+    private readonly resources;
+    private readonly prompts;
+    protected constructor(metadata: ToolkitServerMetadata, logger?: Logger);
+    close(): Promise<void>;
+    getToolNames(): readonly string[];
+    getResourceNames(): readonly string[];
+    getPromptNames(): readonly string[];
+    invokeTool<TOutput>(name: string, input: unknown, sessionId?: string): Promise<TOutput>;
+    protected registerTool<TInputShape extends ZodShape, TOutputShape extends ZodShape>(definition: ToolkitToolDefinition<TInputShape, TOutputShape>): void;
+    protected registerStaticResource(name: string, uri: string, config: ToolkitResourceConfig, read: ToolkitStaticResourceHandler): void;
+    protected registerTemplateResource(name: string, template: string, config: ToolkitResourceConfig, read: ToolkitTemplateResourceHandler): void;
+    protected registerPrompt<TArgs extends ZodShape>(name: string, config: ToolkitPromptConfig<TArgs>, handler: ToolkitPromptHandler<TArgs>): void;
+    protected createJsonResource(uri: string, payload: unknown): ReadResourceResult;
+    protected createTextPrompt(text: string): GetPromptResult;
+}
+
+type ToolkitTransport = "stdio" | "sse";
+type ToolkitLogLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+type ZodShape = ZodRawShapeCompat;
+type InferShape<TShape extends ZodShape> = ShapeOutput<TShape>;
+interface ToolkitServerMetadata {
+    id: string;
+    title: string;
+    description: string;
+    version: string;
+    packageName: string;
+    homepage: string;
+    repositoryUrl?: string;
+    documentationUrl?: string;
+    envVarNames: readonly string[];
+    transports: readonly ToolkitTransport[];
+    toolNames: readonly string[];
+    resourceNames: readonly string[];
+    promptNames: readonly string[];
+}
+interface ToolkitServerCard {
+    name: string;
+    title: string;
+    description: string;
+    version: string;
+    packageName: string;
+    homepage: string;
+    repositoryUrl?: string;
+    documentationUrl?: string;
+    transports: readonly ToolkitTransport[];
+    authentication: {
+        mode: "environment-variables";
+        required: readonly string[];
+    };
+    capabilities: {
+        tools: boolean;
+        resources: boolean;
+        prompts: boolean;
+    };
+    tools: readonly string[];
+    resources: readonly string[];
+    prompts: readonly string[];
+}
+interface ToolkitRuntimeOptions {
+    transport: ToolkitTransport;
+    host: string;
+    port: number;
+    ssePath: string;
+    messagesPath: string;
+    wellKnownPath: string;
+    healthPath: string;
+}
+interface ToolkitToolExecutionContext {
+    logger: Logger;
+    sessionId?: string;
+    log: (level: ToolkitLogLevel, message: string) => Promise<void>;
+}
+interface ToolkitToolDefinition<TInputShape extends ZodShape, TOutputShape extends ZodShape> {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: TInputShape;
+    outputSchema: TOutputShape;
+    annotations?: ToolAnnotations;
+    handler: (input: InferShape<TInputShape>, context: ToolkitToolExecutionContext) => Promise<InferShape<TOutputShape>>;
+    renderText?: (output: InferShape<TOutputShape>) => string;
+}
+interface ToolkitResourceConfig {
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+interface ToolkitPromptConfig<TArgs extends ZodShape> {
+    title?: string;
+    description?: string;
+    argsSchema: TArgs;
+}
+type ToolkitPromptHandler<TArgs extends ZodShape> = PromptCallback<TArgs>;
+type ToolkitStaticResourceHandler = (uri: URL) => Promise<ReadResourceResult> | ReadResourceResult;
+type ToolkitTemplateResourceHandler = (uri: URL, params: Record<string, string | string[]>) => Promise<ReadResourceResult> | ReadResourceResult;
+interface ToolkitRuntimeRegistration {
+    createServer: () => Promise<ToolkitServer> | ToolkitServer;
+    serverCard: ToolkitServerCard;
+}
+
+declare function createServerCard(metadata: ToolkitServerMetadata): ToolkitServerCard;
+
+declare function loadEnv<TShape extends z.ZodRawShape>(shape: TShape, source?: NodeJS.ProcessEnv): z.infer<z.ZodObject<TShape>>;
+
+interface ToolkitErrorOptions {
+    code: string;
+    statusCode?: number;
+    details?: unknown;
+    exposeToClient?: boolean;
+}
+declare class ToolkitError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    readonly exposeToClient: boolean;
+    constructor(message: string, options: ToolkitErrorOptions);
+    toClientMessage(): string;
+}
+declare class ConfigurationError extends ToolkitError {
+    constructor(message: string, details?: unknown);
+}
+declare class ValidationError extends ToolkitError {
+    constructor(message: string, details?: unknown);
+}
+declare class ExternalServiceError extends ToolkitError {
+    constructor(message: string, options?: Omit<ToolkitErrorOptions, "code">);
+}
+declare function normalizeError(error: unknown): ToolkitError;
+
+type QueryValue = string | number | boolean | null | undefined;
+interface HttpServiceClientOptions {
+    serviceName: string;
+    baseUrl: string;
+    logger: Logger;
+    defaultHeaders?: HeadersInit | (() => HeadersInit);
+}
+interface HttpRequestOptions {
+    method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    headers?: HeadersInit;
+    query?: Record<string, QueryValue>;
+    body?: BodyInit | object;
+}
+declare class HttpServiceClient {
+    protected readonly baseUrl: string;
+    protected readonly logger: Logger;
+    private readonly serviceName;
+    private readonly defaultHeaders;
+    constructor(options: HttpServiceClientOptions);
+    getJson<T>(path: string, schema: z.ZodType<T>, options?: Omit<HttpRequestOptions, "method">): Promise<T>;
+    postJson<T>(path: string, schema: z.ZodType<T>, options?: Omit<HttpRequestOptions, "method">): Promise<T>;
+    requestJson<T>(path: string, schema: z.ZodType<T>, options?: HttpRequestOptions): Promise<T>;
+    requestText(path: string, options?: HttpRequestOptions): Promise<string>;
+    protected fetch(path: string, options?: HttpRequestOptions): Promise<Response>;
+}
+
+interface LoggerOptions {
+    name: string;
+    level?: string;
+}
+declare function createLogger(options: LoggerOptions): Logger;
+
+declare function parseRuntimeOptions(argv?: readonly string[]): ToolkitRuntimeOptions;
+declare function runToolkitServer(registration: ToolkitRuntimeRegistration, options?: ToolkitRuntimeOptions): Promise<void>;
+
+declare function defineTool<TInputShape extends ZodShape, TOutputShape extends ZodShape>(definition: ToolkitToolDefinition<TInputShape, TOutputShape>): ToolkitToolDefinition<TInputShape, TOutputShape>;
+
+export { ConfigurationError, ExternalServiceError, HttpServiceClient, type InferShape, ToolkitError, type ToolkitLogLevel, type ToolkitPromptConfig, type ToolkitPromptHandler, type ToolkitResourceConfig, type ToolkitRuntimeOptions, type ToolkitRuntimeRegistration, ToolkitServer, type ToolkitServerCard, type ToolkitServerMetadata, type ToolkitStaticResourceHandler, type ToolkitTemplateResourceHandler, type ToolkitToolDefinition, type ToolkitToolExecutionContext, type ToolkitTransport, ValidationError, type ZodShape, createLogger, createServerCard, defineTool, loadEnv, normalizeError, parseRuntimeOptions, runToolkitServer };

package/dist/index.js

@@ -0,0 +1,588 @@
+// src/card.ts
+function createServerCard(metadata) {
+  const card = {
+    name: metadata.id,
+    title: metadata.title,
+    description: metadata.description,
+    version: metadata.version,
+    packageName: metadata.packageName,
+    homepage: metadata.homepage,
+    transports: metadata.transports,
+    authentication: {
+      mode: "environment-variables",
+      required: metadata.envVarNames
+    },
+    capabilities: {
+      tools: metadata.toolNames.length > 0,
+      resources: metadata.resourceNames.length > 0,
+      prompts: metadata.promptNames.length > 0
+    },
+    tools: metadata.toolNames,
+    resources: metadata.resourceNames,
+    prompts: metadata.promptNames
+  };
+  if (metadata.repositoryUrl) {
+    card.repositoryUrl = metadata.repositoryUrl;
+  }
+  if (metadata.documentationUrl) {
+    card.documentationUrl = metadata.documentationUrl;
+  }
+  return card;
+}
+
+// src/env.ts
+import dotenv from "dotenv";
+import { z } from "zod";
+
+// src/errors.ts
+var ToolkitError = class extends Error {
+  code;
+  statusCode;
+  details;
+  exposeToClient;
+  constructor(message, options) {
+    super(message);
+    this.name = "ToolkitError";
+    this.code = options.code;
+    this.statusCode = options.statusCode ?? 500;
+    this.details = options.details;
+    this.exposeToClient = options.exposeToClient ?? true;
+  }
+  toClientMessage() {
+    return this.exposeToClient ? this.message : "The upstream service returned an unexpected error.";
+  }
+};
+var ConfigurationError = class extends ToolkitError {
+  constructor(message, details) {
+    super(message, {
+      code: "configuration_error",
+      statusCode: 500,
+      details,
+      exposeToClient: true
+    });
+    this.name = "ConfigurationError";
+  }
+};
+var ValidationError = class extends ToolkitError {
+  constructor(message, details) {
+    super(message, {
+      code: "validation_error",
+      statusCode: 400,
+      details,
+      exposeToClient: true
+    });
+    this.name = "ValidationError";
+  }
+};
+var ExternalServiceError = class extends ToolkitError {
+  constructor(message, options) {
+    super(message, {
+      code: "external_service_error",
+      statusCode: options?.statusCode ?? 502,
+      details: options?.details,
+      exposeToClient: options?.exposeToClient ?? true
+    });
+    this.name = "ExternalServiceError";
+  }
+};
+function normalizeError(error) {
+  if (error instanceof ToolkitError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new ToolkitError(error.message, {
+      code: "unexpected_error",
+      statusCode: 500,
+      details: error.stack,
+      exposeToClient: true
+    });
+  }
+  return new ToolkitError("An unexpected non-error value was thrown.", {
+    code: "unexpected_error",
+    statusCode: 500,
+    details: error,
+    exposeToClient: false
+  });
+}
+
+// src/env.ts
+function loadEnv(shape, source = process.env) {
+  dotenv.config();
+  const schema = z.object(shape);
+  const result = schema.safeParse(source);
+  if (!result.success) {
+    throw new ConfigurationError("Environment validation failed.", result.error.flatten());
+  }
+  return result.data;
+}
+
+// src/http.ts
+var HttpServiceClient = class {
+  baseUrl;
+  logger;
+  serviceName;
+  defaultHeaders;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.logger = options.logger;
+    this.serviceName = options.serviceName;
+    this.defaultHeaders = options.defaultHeaders;
+  }
+  async getJson(path, schema, options = {}) {
+    return this.requestJson(path, schema, {
+      ...options,
+      method: "GET"
+    });
+  }
+  async postJson(path, schema, options = {}) {
+    return this.requestJson(path, schema, {
+      ...options,
+      method: "POST"
+    });
+  }
+  async requestJson(path, schema, options = {}) {
+    const response = await this.fetch(path, options);
+    const payload = await response.json();
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new ExternalServiceError(`${this.serviceName} returned a response that failed schema validation.`, {
+        details: parsed.error.flatten()
+      });
+    }
+    return parsed.data;
+  }
+  async requestText(path, options = {}) {
+    const response = await this.fetch(path, options);
+    return response.text();
+  }
+  async fetch(path, options = {}) {
+    const url = new URL(path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0 && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = new Headers();
+    const resolvedDefaultHeaders = typeof this.defaultHeaders === "function" ? this.defaultHeaders() : this.defaultHeaders ?? {};
+    new Headers(resolvedDefaultHeaders).forEach((value, key) => headers.set(key, value));
+    new Headers(options.headers).forEach((value, key) => headers.set(key, value));
+    let body;
+    if (options.body instanceof URLSearchParams || typeof options.body === "string" || options.body instanceof ArrayBuffer || options.body instanceof Blob || options.body instanceof FormData) {
+      body = options.body;
+    } else if (options.body !== void 0) {
+      headers.set("content-type", headers.get("content-type") ?? "application/json");
+      body = JSON.stringify(options.body);
+    }
+    const requestInit = {
+      method: options.method ?? "GET",
+      headers
+    };
+    if (body !== void 0) {
+      requestInit.body = body;
+    }
+    const response = await fetch(url, requestInit);
+    if (!response.ok) {
+      const text = await response.text();
+      this.logger.error(
+        {
+          service: this.serviceName,
+          status: response.status,
+          url: url.toString(),
+          body: text
+        },
+        "Upstream request failed"
+      );
+      throw new ExternalServiceError(`${this.serviceName} request failed with status ${response.status}.`, {
+        statusCode: response.status,
+        details: text
+      });
+    }
+    return response;
+  }
+};
+
+// src/logger.ts
+import pino from "pino";
+function createLogger(options) {
+  const destination = pino.destination({
+    dest: 2,
+    sync: false
+  });
+  return pino(
+    {
+      name: options.name,
+      level: options.level ?? process.env.LOG_LEVEL ?? "info",
+      base: null,
+      timestamp: pino.stdTimeFunctions.isoTime
+    },
+    destination
+  );
+}
+
+// src/runtime.ts
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseArgs } from "util";
+var DEFAULT_OPTIONS = {
+  transport: "stdio",
+  host: "127.0.0.1",
+  port: 3333,
+  ssePath: "/sse",
+  messagesPath: "/messages",
+  wellKnownPath: "/.well-known/mcp-server.json",
+  healthPath: "/healthz"
+};
+function parsePort(raw) {
+  const port = Number.parseInt(raw, 10);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new ConfigurationError(`Invalid port value '${raw}'.`);
+  }
+  return port;
+}
+function parseRuntimeOptions(argv = process.argv.slice(2)) {
+  const parsed = parseArgs({
+    args: [...argv],
+    options: {
+      transport: { type: "string", default: DEFAULT_OPTIONS.transport },
+      host: { type: "string", default: DEFAULT_OPTIONS.host },
+      port: { type: "string", default: String(DEFAULT_OPTIONS.port) },
+      "sse-path": { type: "string", default: DEFAULT_OPTIONS.ssePath },
+      "messages-path": { type: "string", default: DEFAULT_OPTIONS.messagesPath },
+      "well-known-path": { type: "string", default: DEFAULT_OPTIONS.wellKnownPath },
+      "health-path": { type: "string", default: DEFAULT_OPTIONS.healthPath }
+    },
+    allowPositionals: false
+  });
+  const transport = parsed.values.transport;
+  if (transport !== "stdio" && transport !== "sse") {
+    throw new ConfigurationError(`Unsupported transport '${transport}'. Expected 'stdio' or 'sse'.`);
+  }
+  return {
+    transport,
+    host: parsed.values.host,
+    port: parsePort(parsed.values.port),
+    ssePath: parsed.values["sse-path"],
+    messagesPath: parsed.values["messages-path"],
+    wellKnownPath: parsed.values["well-known-path"],
+    healthPath: parsed.values["health-path"]
+  };
+}
+async function runToolkitServer(registration, options = DEFAULT_OPTIONS) {
+  const runtimeLogger = createLogger({
+    name: registration.serverCard.packageName
+  });
+  if (options.transport === "stdio") {
+    const server = await registration.createServer();
+    const transport = new StdioServerTransport();
+    await server.server.connect(transport);
+    runtimeLogger.info("MCP server listening on stdio");
+    return;
+  }
+  const app = createMcpExpressApp({ host: options.host });
+  const sessions = /* @__PURE__ */ new Map();
+  app.get(options.wellKnownPath, (_request, response) => {
+    response.json(registration.serverCard);
+  });
+  app.get(options.healthPath, (_request, response) => {
+    response.json({
+      status: "ok",
+      name: registration.serverCard.name,
+      version: registration.serverCard.version,
+      transport: options.transport
+    });
+  });
+  app.get(options.ssePath, async (_request, response) => {
+    try {
+      const server = await registration.createServer();
+      const transport = new SSEServerTransport(options.messagesPath, response);
+      sessions.set(transport.sessionId, { server, transport });
+      transport.onclose = () => {
+        void server.close();
+        sessions.delete(transport.sessionId);
+      };
+      await server.server.connect(transport);
+    } catch (error) {
+      runtimeLogger.error({ error }, "Failed to establish SSE session");
+      if (!response.headersSent) {
+        response.status(500).send("Failed to establish SSE session.");
+      }
+    }
+  });
+  app.post(options.messagesPath, async (request, response) => {
+    const sessionId = typeof request.query.sessionId === "string" ? request.query.sessionId : void 0;
+    if (!sessionId) {
+      response.status(400).send("Missing sessionId query parameter.");
+      return;
+    }
+    const session = sessions.get(sessionId);
+    if (!session) {
+      response.status(404).send("Unknown sessionId.");
+      return;
+    }
+    try {
+      await session.transport.handlePostMessage(request, response, request.body);
+    } catch (error) {
+      runtimeLogger.error({ error, sessionId }, "Failed to handle incoming SSE message");
+      if (!response.headersSent) {
+        response.status(500).send("Failed to process request.");
+      }
+    }
+  });
+  const listener = app.listen(options.port, options.host, () => {
+    runtimeLogger.info(
+      {
+        host: options.host,
+        port: options.port,
+        ssePath: options.ssePath,
+        messagesPath: options.messagesPath
+      },
+      "MCP server listening over HTTP+SSE"
+    );
+  });
+  const shutdown = async () => {
+    runtimeLogger.info("Shutting down MCP server");
+    for (const [sessionId, session] of sessions.entries()) {
+      runtimeLogger.info({ sessionId }, "Closing active session");
+      await session.transport.close();
+      await session.server.close();
+      sessions.delete(sessionId);
+    }
+    await new Promise((resolve, reject) => {
+      listener.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  };
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => {
+      void shutdown().finally(() => process.exit(0));
+    });
+  }
+}
+
+// src/server.ts
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getParseErrorMessage, normalizeObjectSchema, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+function toText(output) {
+  return JSON.stringify(output, null, 2);
+}
+function mapLogLevel(level) {
+  switch (level) {
+    case "debug":
+      return "debug";
+    case "info":
+    case "notice":
+      return "info";
+    case "warning":
+      return "warn";
+    case "error":
+      return "error";
+    case "critical":
+    case "alert":
+    case "emergency":
+      return "fatal";
+  }
+}
+var ToolkitServer = class {
+  metadata;
+  logger;
+  server;
+  tools = /* @__PURE__ */ new Map();
+  resources = /* @__PURE__ */ new Set();
+  prompts = /* @__PURE__ */ new Set();
+  constructor(metadata, logger) {
+    this.metadata = metadata;
+    this.logger = logger ?? createLogger({ name: metadata.packageName });
+    this.server = new McpServer(
+      {
+        name: metadata.id,
+        version: metadata.version,
+        websiteUrl: metadata.homepage
+      },
+      {
+        capabilities: {
+          logging: {}
+        }
+      }
+    );
+  }
+  async close() {
+    await this.server.close();
+  }
+  getToolNames() {
+    return [...this.tools.keys()].sort();
+  }
+  getResourceNames() {
+    return [...this.resources].sort();
+  }
+  getPromptNames() {
+    return [...this.prompts].sort();
+  }
+  async invokeTool(name, input, sessionId) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Tool '${name}' is not registered.`);
+    }
+    return await tool.invoke(input, sessionId);
+  }
+  registerTool(definition) {
+    const inputSchema = normalizeObjectSchema(definition.inputSchema);
+    const outputSchema = normalizeObjectSchema(definition.outputSchema);
+    if (!inputSchema || !outputSchema) {
+      throw new ValidationError(`Tool '${definition.name}' requires both input and output schemas.`);
+    }
+    const storedTool = {
+      name: definition.name,
+      invoke: async (input, sessionId) => {
+        const parsedInputResult = await safeParseAsync(inputSchema, input);
+        if (!parsedInputResult.success) {
+          throw new ValidationError(
+            `Input validation failed for tool '${definition.name}': ${getParseErrorMessage(parsedInputResult.error)}`,
+            parsedInputResult.error
+          );
+        }
+        const context = {
+          logger: this.logger.child({ tool: definition.name }),
+          log: async (level, message) => {
+            this.logger[mapLogLevel(level)]({ sessionId, tool: definition.name }, message);
+            if (this.server.isConnected()) {
+              if (sessionId === void 0) {
+                await this.server.sendLoggingMessage({ level, data: message });
+              } else {
+                await this.server.sendLoggingMessage({ level, data: message }, sessionId);
+              }
+            }
+          }
+        };
+        if (sessionId !== void 0) {
+          context.sessionId = sessionId;
+        }
+        const output = await definition.handler(parsedInputResult.data, context);
+        const parsedOutputResult = await safeParseAsync(outputSchema, output);
+        if (!parsedOutputResult.success) {
+          throw new ValidationError(
+            `Output validation failed for tool '${definition.name}': ${getParseErrorMessage(parsedOutputResult.error)}`,
+            parsedOutputResult.error
+          );
+        }
+        return parsedOutputResult.data;
+      }
+    };
+    const renderText = definition.renderText;
+    if (renderText) {
+      storedTool.renderText = (output) => renderText(output);
+    }
+    this.tools.set(definition.name, storedTool);
+    const toolConfig = {
+      description: definition.description,
+      inputSchema: definition.inputSchema,
+      outputSchema: definition.outputSchema
+    };
+    if (definition.title) {
+      toolConfig.title = definition.title;
+    }
+    if (definition.annotations) {
+      toolConfig.annotations = definition.annotations;
+    }
+    const toolCallback = (async (input, extra) => {
+      try {
+        const output = await this.invokeTool(definition.name, input, extra.sessionId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: definition.renderText ? definition.renderText(output) : toText(output)
+            }
+          ],
+          structuredContent: output
+        };
+      } catch (error) {
+        const normalized = normalizeError(error);
+        this.logger.error(
+          {
+            tool: definition.name,
+            code: normalized.code,
+            details: normalized.details
+          },
+          normalized.message
+        );
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: normalized.toClientMessage()
+            }
+          ]
+        };
+      }
+    });
+    this.server.registerTool(definition.name, toolConfig, toolCallback);
+  }
+  registerStaticResource(name, uri, config, read) {
+    this.resources.add(name);
+    this.server.registerResource(name, uri, config, read);
+  }
+  registerTemplateResource(name, template, config, read) {
+    this.resources.add(name);
+    this.server.registerResource(
+      name,
+      new ResourceTemplate(template, { list: void 0 }),
+      config,
+      (uri, variables) => read(uri, variables)
+    );
+  }
+  registerPrompt(name, config, handler) {
+    this.prompts.add(name);
+    this.server.registerPrompt(name, config, handler);
+  }
+  createJsonResource(uri, payload) {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(payload, null, 2)
+        }
+      ]
+    };
+  }
+  createTextPrompt(text) {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text
+          }
+        }
+      ]
+    };
+  }
+};
+
+// src/tool.ts
+function defineTool(definition) {
+  return definition;
+}
+export {
+  ConfigurationError,
+  ExternalServiceError,
+  HttpServiceClient,
+  ToolkitError,
+  ToolkitServer,
+  ValidationError,
+  createLogger,
+  createServerCard,
+  defineTool,
+  loadEnv,
+  normalizeError,
+  parseRuntimeOptions,
+  runToolkitServer
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@universal-mcp-toolkit/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared runtime, validation, logging, transport, and DX primitives for universal-mcp-toolkit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Markgatcha/universal-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/Markgatcha/universal-mcp-toolkit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "developer-tools",
+    "typescript",
+    "core",
+    "sdk",
+    "transports",
+    "zod",
+    "pino"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "pino": "^10.3.1",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}