@theyahia/mcp-core 1.0.0

package/dist/auth/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Authentication strategies for MCP servers.
+ *
+ * Strategy Pattern: each auth type implements AuthStrategy interface.
+ * Covers all 5 auth methods used across the 53 servers:
+ * - API Key (Bearer token)
+ * - Basic Auth (username:password)
+ * - OAuth2 Client Credentials
+ * - HMAC/Signature-based
+ * - No Auth (pass-through)
+ */
+export interface AuthStrategy {
+    readonly type: string;
+    authenticate(request: RequestInit): Promise<RequestInit>;
+    /** Called when server returns 401 — clear cached credentials */
+    invalidate?(): void;
+}
+/** Bearer token or custom header API key auth */
+export declare class ApiKeyStrategy implements AuthStrategy {
+    private readonly key;
+    private readonly header;
+    private readonly prefix;
+    readonly type = "api_key";
+    constructor(key: string, header?: string, prefix?: string);
+    authenticate(req: RequestInit): Promise<RequestInit>;
+}
+/** HTTP Basic Authentication (base64 encoded) */
+export declare class BasicAuthStrategy implements AuthStrategy {
+    readonly type = "basic";
+    private readonly encoded;
+    constructor(username: string, password: string);
+    authenticate(req: RequestInit): Promise<RequestInit>;
+}
+/** OAuth2 Client Credentials flow with auto-refresh and concurrent request dedup */
+export declare class OAuthStrategy implements AuthStrategy {
+    private readonly config;
+    readonly type = "oauth";
+    private token;
+    private expiresAt;
+    private refreshPromise;
+    constructor(config: {
+        tokenUrl: string;
+        clientId: string;
+        clientSecret: string;
+        /** Safety margin in ms before token expiry (default: 60s) */
+        expiryBuffer?: number;
+    });
+    invalidate(): void;
+    authenticate(req: RequestInit): Promise<RequestInit>;
+    private getToken;
+    private refresh;
+}
+/** Dual auth: tries Bearer token first, falls back to Basic */
+export declare class DualAuthStrategy implements AuthStrategy {
+    readonly type = "dual";
+    private readonly strategy;
+    constructor(config: {
+        token?: string;
+        login?: string;
+        password?: string;
+    });
+    authenticate(req: RequestInit): Promise<RequestInit>;
+}
+/** No-auth pass-through for public APIs (CBR, CBU) */
+export declare class NoAuthStrategy implements AuthStrategy {
+    readonly type = "none";
+    authenticate(req: RequestInit): Promise<RequestInit>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACzD,gEAAgE;IAChE,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB;AAED,iDAAiD;AACjD,qBAAa,cAAe,YAAW,YAAY;IAI/C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,QAAQ,CAAC,IAAI,aAAa;gBAGP,GAAG,EAAE,MAAM,EACX,MAAM,SAAkB,EACxB,MAAM,SAAW;IAG9B,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAK3D;AAED,iDAAiD;AACjD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAIxC,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAK3D;AAED,oFAAoF;AACpF,qBAAa,aAAc,YAAW,YAAY;IAO9C,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,cAAc,CAAgC;gBAGnC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,6DAA6D;QAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;IAGH,UAAU,IAAI,IAAI;IAKZ,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;YAO5C,QAAQ;YAiBR,OAAO;CA4BtB;AAED,+DAA+D;AAC/D,qBAAa,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAE5B,MAAM,EAAE;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAYK,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAG3D;AAED,sDAAsD;AACtD,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,UAAU;IAEjB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAG3D"}

package/dist/auth/index.js

@@ -0,0 +1,126 @@
+/**
+ * Authentication strategies for MCP servers.
+ *
+ * Strategy Pattern: each auth type implements AuthStrategy interface.
+ * Covers all 5 auth methods used across the 53 servers:
+ * - API Key (Bearer token)
+ * - Basic Auth (username:password)
+ * - OAuth2 Client Credentials
+ * - HMAC/Signature-based
+ * - No Auth (pass-through)
+ */
+/** Bearer token or custom header API key auth */
+export class ApiKeyStrategy {
+    key;
+    header;
+    prefix;
+    type = "api_key";
+    constructor(key, header = "Authorization", prefix = "Bearer") {
+        this.key = key;
+        this.header = header;
+        this.prefix = prefix;
+    }
+    async authenticate(req) {
+        const headers = new Headers(req.headers);
+        headers.set(this.header, `${this.prefix} ${this.key}`);
+        return { ...req, headers };
+    }
+}
+/** HTTP Basic Authentication (base64 encoded) */
+export class BasicAuthStrategy {
+    type = "basic";
+    encoded;
+    constructor(username, password) {
+        this.encoded = Buffer.from(`${username}:${password}`).toString("base64");
+    }
+    async authenticate(req) {
+        const headers = new Headers(req.headers);
+        headers.set("Authorization", `Basic ${this.encoded}`);
+        return { ...req, headers };
+    }
+}
+/** OAuth2 Client Credentials flow with auto-refresh and concurrent request dedup */
+export class OAuthStrategy {
+    config;
+    type = "oauth";
+    token = null;
+    expiresAt = 0;
+    refreshPromise = null;
+    constructor(config) {
+        this.config = config;
+    }
+    invalidate() {
+        this.token = null;
+        this.expiresAt = 0;
+    }
+    async authenticate(req) {
+        const token = await this.getToken();
+        const headers = new Headers(req.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        return { ...req, headers };
+    }
+    async getToken() {
+        const buffer = this.config.expiryBuffer ?? 60_000;
+        if (this.token && Date.now() < this.expiresAt - buffer) {
+            return this.token;
+        }
+        // Deduplicate concurrent refresh requests
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.refresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async refresh() {
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+        });
+        const response = await fetch(this.config.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`OAuth token error (HTTP ${response.status}). Проверьте client_id и client_secret. ${text}`);
+        }
+        const data = (await response.json());
+        this.token = data.access_token;
+        this.expiresAt = Date.now() + data.expires_in * 1000;
+        return this.token;
+    }
+}
+/** Dual auth: tries Bearer token first, falls back to Basic */
+export class DualAuthStrategy {
+    type = "dual";
+    strategy;
+    constructor(config) {
+        if (config.token) {
+            this.strategy = new ApiKeyStrategy(config.token);
+        }
+        else if (config.login && config.password) {
+            this.strategy = new BasicAuthStrategy(config.login, config.password);
+        }
+        else {
+            throw new Error("Auth not configured. Provide token OR login+password.");
+        }
+    }
+    async authenticate(req) {
+        return this.strategy.authenticate(req);
+    }
+}
+/** No-auth pass-through for public APIs (CBR, CBU) */
+export class NoAuthStrategy {
+    type = "none";
+    async authenticate(req) {
+        return req;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Base HTTP client with retry, timeout, and exponential backoff.
+ *
+ * Consolidates the retry/timeout/error pattern duplicated across all 53 servers
+ * into a single reusable class.
+ */
+import type { AuthStrategy } from "./auth/index.js";
+import type { Logger } from "./logging.js";
+export interface BaseClientOptions {
+    baseUrl: string;
+    timeout?: number;
+    maxRetries?: number;
+    auth?: AuthStrategy;
+    logger?: Logger;
+    /** Custom headers applied to every request */
+    headers?: Record<string, string>;
+}
+export interface RequestOptions {
+    method?: string;
+    path: string;
+    body?: unknown;
+    params?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Override timeout for this specific request */
+    timeout?: number;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body?: string | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, body?: string | undefined, headers?: Record<string, string> | undefined, code?: string | undefined);
+}
+export declare class BaseHttpClient {
+    protected readonly baseUrl: string;
+    protected readonly timeout: number;
+    protected readonly maxRetries: number;
+    protected readonly auth?: AuthStrategy;
+    protected readonly logger?: Logger;
+    protected readonly defaultHeaders: Record<string, string>;
+    constructor(options: BaseClientOptions);
+    get(path: string, params?: Record<string, string>): Promise<unknown>;
+    post(path: string, body?: unknown): Promise<unknown>;
+    put(path: string, body?: unknown): Promise<unknown>;
+    delete(path: string): Promise<unknown>;
+    request(opts: RequestOptions): Promise<unknown>;
+}
+/**
+ * Token bucket rate limiter.
+ * Used by MoySklad (45 req/3s) and similar APIs with strict rate limits.
+ */
+export declare class TokenBucketLimiter {
+    private readonly maxTokens;
+    private readonly refillMs;
+    private tokens;
+    private lastRefill;
+    constructor(maxTokens: number, refillMs: number);
+    acquire(): Promise<void>;
+}
+/**
+ * Extended client with token bucket rate limiting.
+ */
+export declare class RateLimitedClient extends BaseHttpClient {
+    private readonly limiter;
+    constructor(options: BaseClientOptions & {
+        bucketMax: number;
+        bucketRefillMs: number;
+    });
+    request(opts: RequestOptions): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,188 @@
+/**
+ * Base HTTP client with retry, timeout, and exponential backoff.
+ *
+ * Consolidates the retry/timeout/error pattern duplicated across all 53 servers
+ * into a single reusable class.
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    headers;
+    code;
+    constructor(status, message, body, headers, code) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+        this.code = code;
+        this.name = "ApiError";
+    }
+}
+export class BaseHttpClient {
+    baseUrl;
+    timeout;
+    maxRetries;
+    auth;
+    logger;
+    defaultHeaders;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.timeout = options.timeout ?? 15_000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.auth = options.auth;
+        this.logger = options.logger;
+        this.defaultHeaders = {
+            "Content-Type": "application/json",
+            ...options.headers,
+        };
+    }
+    async get(path, params) {
+        return this.request({ method: "GET", path, params });
+    }
+    async post(path, body) {
+        return this.request({ method: "POST", path, body });
+    }
+    async put(path, body) {
+        return this.request({ method: "PUT", path, body });
+    }
+    async delete(path) {
+        return this.request({ method: "DELETE", path });
+    }
+    async request(opts) {
+        const method = opts.method ?? "GET";
+        const query = opts.params
+            ? "?" + new URLSearchParams(opts.params).toString()
+            : "";
+        const url = opts.path.startsWith("http")
+            ? `${opts.path}${query}`
+            : `${this.baseUrl}${opts.path}${query}`;
+        const requestTimeout = opts.timeout ?? this.timeout;
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), requestTimeout);
+            try {
+                let reqInit = {
+                    method,
+                    headers: { ...this.defaultHeaders, ...opts.headers },
+                    body: opts.body ? JSON.stringify(opts.body) : undefined,
+                    signal: controller.signal,
+                };
+                // Apply auth strategy
+                if (this.auth) {
+                    reqInit = await this.auth.authenticate(reqInit);
+                }
+                const response = await fetch(url, reqInit);
+                clearTimeout(timer);
+                if (response.ok) {
+                    const text = await response.text();
+                    if (!text)
+                        return null;
+                    try {
+                        return JSON.parse(text);
+                    }
+                    catch {
+                        return text;
+                    }
+                }
+                // Auth expired — invalidate and retry
+                if ((response.status === 401 || response.status === 403) &&
+                    attempt < this.maxRetries &&
+                    this.auth?.invalidate) {
+                    this.auth.invalidate();
+                    this.logger?.warn("Auth token expired, refreshing", {
+                        attempt,
+                        status: response.status,
+                    });
+                    continue;
+                }
+                const errorBody = await response.text();
+                // Retryable server errors
+                if ((response.status === 429 || response.status >= 500) &&
+                    attempt < this.maxRetries) {
+                    const delay = Math.min(1000 * 2 ** (attempt - 1), 8000);
+                    this.logger?.warn("Retryable error, backing off", {
+                        status: response.status,
+                        delay,
+                        attempt,
+                        path: opts.path,
+                    });
+                    await new Promise((r) => setTimeout(r, delay));
+                    continue;
+                }
+                // Build response headers map for ApiError
+                const respHeaders = {};
+                response.headers.forEach((v, k) => {
+                    respHeaders[k] = v;
+                });
+                throw new ApiError(response.status, `HTTP ${response.status}: ${response.statusText}`, errorBody, respHeaders);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                if (error instanceof ApiError)
+                    throw error;
+                if (error instanceof DOMException &&
+                    error.name === "AbortError") {
+                    if (attempt < this.maxRetries) {
+                        this.logger?.warn("Request timeout, retrying", {
+                            attempt,
+                            path: opts.path,
+                        });
+                        continue;
+                    }
+                    throw new ApiError(0, `Таймаут запроса (${requestTimeout / 1000}с). API не ответил вовремя.`);
+                }
+                throw error;
+            }
+        }
+        throw new ApiError(0, "Все попытки запроса исчерпаны");
+    }
+}
+/**
+ * Token bucket rate limiter.
+ * Used by MoySklad (45 req/3s) and similar APIs with strict rate limits.
+ */
+export class TokenBucketLimiter {
+    maxTokens;
+    refillMs;
+    tokens;
+    lastRefill;
+    constructor(maxTokens, refillMs) {
+        this.maxTokens = maxTokens;
+        this.refillMs = refillMs;
+        this.tokens = maxTokens;
+        this.lastRefill = Date.now();
+    }
+    async acquire() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        if (elapsed >= this.refillMs) {
+            this.tokens = this.maxTokens;
+            this.lastRefill = now;
+        }
+        if (this.tokens > 0) {
+            this.tokens--;
+            return;
+        }
+        const waitMs = this.refillMs - (Date.now() - this.lastRefill);
+        if (waitMs > 0) {
+            await new Promise((r) => setTimeout(r, waitMs));
+        }
+        this.tokens = this.maxTokens - 1;
+        this.lastRefill = Date.now();
+    }
+}
+/**
+ * Extended client with token bucket rate limiting.
+ */
+export class RateLimitedClient extends BaseHttpClient {
+    limiter;
+    constructor(options) {
+        super(options);
+        this.limiter = new TokenBucketLimiter(options.bucketMax, options.bucketRefillMs);
+    }
+    async request(opts) {
+        await this.limiter.acquire();
+        return super.request(opts);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Centralized error handling for MCP tool responses.
+ *
+ * Key insight from MCP spec: tool execution errors with `isError: true`
+ * are injected back into the LLM context — the model can self-recover.
+ * Protocol-level errors go to UI and are thrown. This distinction is critical.
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export type ErrorCategory = "validation" | "auth" | "rate_limit" | "not_found" | "server_error" | "timeout" | "unknown";
+export interface ApiErrorInfo {
+    status: number;
+    message?: string;
+    headers?: Record<string, string>;
+    code?: string;
+}
+/**
+ * Converts any error into an MCP-compliant CallToolResult with `isError: true`
+ * and a next-action suggestion so the LLM can self-recover.
+ */
+export declare function createToolError(error: unknown): CallToolResult;
+/**
+ * Wraps a tool handler with automatic error handling.
+ * Returns `isError: true` result instead of throwing.
+ */
+export declare function withErrorHandling<T = Record<string, unknown>>(handler: (params: T) => Promise<CallToolResult>): (params: T) => Promise<CallToolResult>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA8F9D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,GAC9C,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAQxC"}

package/dist/errors.js

@@ -0,0 +1,138 @@
+/**
+ * Centralized error handling for MCP tool responses.
+ *
+ * Key insight from MCP spec: tool execution errors with `isError: true`
+ * are injected back into the LLM context — the model can self-recover.
+ * Protocol-level errors go to UI and are thrown. This distinction is critical.
+ */
+import { ZodError } from "zod";
+function isApiError(e) {
+    return typeof e === "object" && e !== null && "status" in e;
+}
+function isDOMAbortError(e) {
+    return e instanceof DOMException && e.name === "AbortError";
+}
+function categorize(error) {
+    if (error instanceof ZodError)
+        return "validation";
+    if (isDOMAbortError(error))
+        return "timeout";
+    if (!isApiError(error))
+        return "unknown";
+    const { status } = error;
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limit";
+    if (status === 404)
+        return "not_found";
+    if (status >= 500)
+        return "server_error";
+    return "unknown";
+}
+/**
+ * Converts any error into an MCP-compliant CallToolResult with `isError: true`
+ * and a next-action suggestion so the LLM can self-recover.
+ */
+export function createToolError(error) {
+    const category = categorize(error);
+    switch (category) {
+        case "validation": {
+            const zodErr = error;
+            const details = zodErr.errors
+                .map((e) => `${e.path.join(".")}: ${e.message}`)
+                .join("; ");
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Ошибка валидации: ${details}. Исправьте параметры и повторите запрос.`,
+                    },
+                ],
+            };
+        }
+        case "auth":
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Ошибка авторизации. Токен истёк или неверен. Попросите пользователя проверить и перенастроить API-ключ.`,
+                    },
+                ],
+            };
+        case "rate_limit": {
+            const apiErr = error;
+            const retryAfter = apiErr.headers?.["retry-after"] || "60";
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Rate limit. Повторите через ${retryAfter}с. Если это 3-й раз подряд — сообщите пользователю о превышении лимита API.`,
+                    },
+                ],
+            };
+        }
+        case "not_found":
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Ресурс не найден. Проверьте ID или параметры. Используйте search/list tool для поиска корректного идентификатора.`,
+                    },
+                ],
+            };
+        case "server_error": {
+            const apiErr = error;
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Ошибка сервера (HTTP ${apiErr.status}). Внешний API временно недоступен. Повторите запрос через 10-30 секунд.`,
+                    },
+                ],
+            };
+        }
+        case "timeout":
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Таймаут запроса. Внешний API не ответил вовремя. Повторите запрос. Если проблема повторяется — сообщите пользователю.`,
+                    },
+                ],
+            };
+        default: {
+            const msg = error instanceof Error ? error.message : "Неизвестная ошибка";
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Ошибка: ${msg}. Повторите запрос или попробуйте другой подход.`,
+                    },
+                ],
+            };
+        }
+    }
+}
+/**
+ * Wraps a tool handler with automatic error handling.
+ * Returns `isError: true` result instead of throwing.
+ */
+export function withErrorHandling(handler) {
+    return async (params) => {
+        try {
+            return await handler(params);
+        }
+        catch (error) {
+            return createToolError(error);
+        }
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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