@universal-mcp-toolkit/core 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -88,7 +88,13 @@ interface ToolkitToolDefinition<TInputShape extends ZodShape, TOutputShape exten
     inputSchema: TInputShape;
     outputSchema: TOutputShape;
     annotations?: ToolAnnotations;
-    handler: (input: InferShape<TInputShape>, context: ToolkitToolExecutionContext) => Promise<InferShape<TOutputShape>>;
+    timeoutMs?: number;
+    /**
+     * @experimental - Streaming MCP tool responses are not yet widely supported by MCP clients.
+     * Enable only if your host client explicitly supports streaming tool content.
+     */
+    experimental_streamingResponse?: boolean;
+    handler: (input: InferShape<TInputShape>, context: ToolkitToolExecutionContext) => Promise<InferShape<TOutputShape>> | AsyncIterable<string>;
     renderText?: (output: InferShape<TOutputShape>) => string;
 }
 interface ToolkitResourceConfig {
@@ -137,13 +143,41 @@ declare class ExternalServiceError extends ToolkitError {
     constructor(message: string, options?: Omit<ToolkitErrorOptions, "code">);
 }
 declare function normalizeError(error: unknown): ToolkitError;
+declare class ToolTimeoutError extends ToolkitError {
+    readonly toolName: string;
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number);
+}
+
+interface RateLimiterOptions {
+    requestsPerSecond: number;
+    burstLimit: number;
+}
+declare class RateLimiter {
+    private readonly intervalMs;
+    private readonly maxTokens;
+    private tokens;
+    private lastRefill;
+    private readonly waitQueue;
+    constructor(options: RateLimiterOptions);
+    acquire(): Promise<void>;
+    private refill;
+}
 
 type QueryValue = string | number | boolean | null | undefined;
+interface RetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryOn: number[];
+}
 interface HttpServiceClientOptions {
     serviceName: string;
     baseUrl: string;
     logger: Logger;
     defaultHeaders?: HeadersInit | (() => HeadersInit);
+    retryOptions?: Partial<RetryOptions>;
+    rateLimiter?: RateLimiter;
 }
 interface HttpRequestOptions {
     method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
@@ -156,6 +190,8 @@ declare class HttpServiceClient {
     protected readonly logger: Logger;
     private readonly serviceName;
     private readonly defaultHeaders;
+    private readonly retryOptions;
+    private readonly rateLimiter;
     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>;
@@ -175,4 +211,10 @@ declare function runToolkitServer(registration: ToolkitRuntimeRegistration, opti
 
 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 };
+/**
+ * @experimental - Streaming MCP tool responses are not yet widely supported by MCP clients.
+ * Enable only if your host client explicitly supports streaming tool content.
+ */
+declare function createStreamingResponse(iterable: AsyncIterable<string>): AsyncIterable<string>;
+
+export { ConfigurationError, ExternalServiceError, HttpServiceClient, type InferShape, RateLimiter, type RetryOptions, ToolTimeoutError, 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, createStreamingResponse, defineTool, loadEnv, normalizeError, parseRuntimeOptions, runToolkitServer };

package/dist/index.js

@@ -104,6 +104,21 @@ function normalizeError(error) {
     exposeToClient: false
   });
 }
+var ToolTimeoutError = class extends ToolkitError {
+  toolName;
+  timeoutMs;
+  constructor(toolName, timeoutMs) {
+    super(`Tool '${toolName}' timed out after ${timeoutMs}ms.`, {
+      code: "tool_timeout",
+      statusCode: 504,
+      details: { toolName, timeoutMs },
+      exposeToClient: true
+    });
+    this.name = "ToolTimeoutError";
+    this.toolName = toolName;
+    this.timeoutMs = timeoutMs;
+  }
+};
 
 // src/env.ts
 function loadEnv(shape, source = process.env) {
@@ -117,16 +132,54 @@ function loadEnv(shape, source = process.env) {
 }
 
 // src/http.ts
+var DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 1e4,
+  retryOn: [429, 500, 502, 503, 504]
+};
+function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds)) {
+    return seconds * 1e3;
+  }
+  const dateMs = Date.parse(headerValue);
+  if (!Number.isNaN(dateMs)) {
+    const delta = dateMs - Date.now();
+    return delta > 0 ? delta : 0;
+  }
+  return null;
+}
+function computeBackoffDelay(attempt, options, retryAfterHeader) {
+  const retryAfter = parseRetryAfter(retryAfterHeader);
+  if (retryAfter !== null) {
+    return Math.min(retryAfter, options.maxDelayMs);
+  }
+  const exponential = options.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * options.baseDelayMs;
+  return Math.min(exponential + jitter, options.maxDelayMs);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var HttpServiceClient = class {
   baseUrl;
   logger;
   serviceName;
   defaultHeaders;
+  retryOptions;
+  rateLimiter;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
     this.logger = options.logger;
     this.serviceName = options.serviceName;
     this.defaultHeaders = options.defaultHeaders;
+    this.rateLimiter = options.rateLimiter;
+    this.retryOptions = {
+      ...DEFAULT_RETRY_OPTIONS,
+      ...options.retryOptions
+    };
   }
   async getJson(path, schema, options = {}) {
     return this.requestJson(path, schema, {
@@ -180,24 +233,53 @@ var HttpServiceClient = class {
     if (body !== void 0) {
       requestInit.body = body;
     }
-    const response = await fetch(url, requestInit);
-    if (!response.ok) {
-      const text = await response.text();
-      this.logger.error(
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+    let lastResponse;
+    for (let attempt = 0; attempt <= this.retryOptions.maxRetries; attempt++) {
+      if (attempt > 0 && this.rateLimiter) {
+        await this.rateLimiter.acquire();
+      }
+      lastResponse = await fetch(url, requestInit);
+      if (lastResponse.ok) {
+        return lastResponse;
+      }
+      const shouldRetry = this.retryOptions.retryOn.includes(lastResponse.status);
+      if (!shouldRetry || attempt >= this.retryOptions.maxRetries) {
+        break;
+      }
+      const retryAfterHeader = lastResponse.headers.get("retry-after");
+      const delay = computeBackoffDelay(attempt, this.retryOptions, retryAfterHeader);
+      this.logger.warn(
         {
           service: this.serviceName,
-          status: response.status,
+          status: lastResponse.status,
           url: url.toString(),
-          body: text
+          attempt: attempt + 1,
+          maxRetries: this.retryOptions.maxRetries,
+          delayMs: Math.round(delay)
         },
-        "Upstream request failed"
+        "Retrying failed upstream request"
       );
-      throw new ExternalServiceError(`${this.serviceName} request failed with status ${response.status}.`, {
-        statusCode: response.status,
-        details: text
-      });
+      await lastResponse.text().catch(() => void 0);
+      await sleep(delay);
     }
-    return response;
+    const response = lastResponse;
+    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
+    });
   }
 };
 
@@ -219,6 +301,55 @@ function createLogger(options) {
   );
 }
 
+// src/rate-limiter.ts
+var RateLimiter = class {
+  intervalMs;
+  maxTokens;
+  tokens;
+  lastRefill;
+  waitQueue = [];
+  constructor(options) {
+    if (options.requestsPerSecond <= 0) {
+      throw new Error("requestsPerSecond must be positive.");
+    }
+    if (options.burstLimit <= 0) {
+      throw new Error("burstLimit must be positive.");
+    }
+    this.intervalMs = 1e3 / options.requestsPerSecond;
+    this.maxTokens = options.burstLimit;
+    this.tokens = options.burstLimit;
+    this.lastRefill = Date.now();
+  }
+  async acquire() {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return;
+    }
+    const waitMs = this.intervalMs;
+    await new Promise((resolve) => {
+      const entry = { resolve };
+      this.waitQueue.push(entry);
+      setTimeout(() => {
+        const index = this.waitQueue.indexOf(entry);
+        if (index !== -1) {
+          this.waitQueue.splice(index, 1);
+        }
+        this.refill();
+        this.tokens = Math.max(0, this.tokens - 1);
+        resolve();
+      }, waitMs);
+    });
+  }
+  refill() {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const tokensToAdd = elapsed / this.intervalMs;
+    this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
+    this.lastRefill = now;
+  }
+};
+
 // src/runtime.ts
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
@@ -436,6 +567,8 @@ var ToolkitServer = class {
     if (!inputSchema || !outputSchema) {
       throw new ValidationError(`Tool '${definition.name}' requires both input and output schemas.`);
     }
+    const timeoutMs = definition.timeoutMs ?? 3e4;
+    const isStreaming = definition.experimental_streamingResponse ?? false;
     const storedTool = {
       name: definition.name,
       invoke: async (input, sessionId) => {
@@ -462,7 +595,34 @@ var ToolkitServer = class {
         if (sessionId !== void 0) {
           context.sessionId = sessionId;
         }
-        const output = await definition.handler(parsedInputResult.data, context);
+        const controller = new AbortController();
+        const timeoutPromise = new Promise((_, reject) => {
+          const timer = setTimeout(() => {
+            reject(new ToolTimeoutError(definition.name, timeoutMs));
+          }, timeoutMs);
+          controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+        });
+        const handlerResult = await Promise.race([
+          definition.handler(parsedInputResult.data, context),
+          timeoutPromise
+        ]);
+        controller.abort();
+        if (isStreaming && handlerResult !== null && typeof handlerResult === "object" && Symbol.asyncIterator in handlerResult) {
+          const chunks = [];
+          for await (const chunk of handlerResult) {
+            chunks.push(chunk);
+          }
+          const combined = chunks.join("");
+          const parsedOutputResult2 = await safeParseAsync(outputSchema, { text: combined });
+          if (!parsedOutputResult2.success) {
+            throw new ValidationError(
+              `Output validation failed for tool '${definition.name}': ${getParseErrorMessage(parsedOutputResult2.error)}`,
+              parsedOutputResult2.error
+            );
+          }
+          return parsedOutputResult2.data;
+        }
+        const output = handlerResult;
         const parsedOutputResult = await safeParseAsync(outputSchema, output);
         if (!parsedOutputResult.success) {
           throw new ValidationError(
@@ -571,15 +731,23 @@ var ToolkitServer = class {
 function defineTool(definition) {
   return definition;
 }
+
+// src/index.ts
+function createStreamingResponse(iterable) {
+  return iterable;
+}
 export {
   ConfigurationError,
   ExternalServiceError,
   HttpServiceClient,
+  RateLimiter,
+  ToolTimeoutError,
   ToolkitError,
   ToolkitServer,
   ValidationError,
   createLogger,
   createServerCard,
+  createStreamingResponse,
   defineTool,
   loadEnv,
   normalizeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@universal-mcp-toolkit/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Shared runtime, validation, logging, transport, and DX primitives for universal-mcp-toolkit.",
   "license": "MIT",