bn-telegram-mcp-server 0.0.1

package/dist/schemas.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+/**
+ * Flexible identifier that accepts either:
+ * - A numeric ID (number or numeric string)
+ * - A name/title to search for (string)
+ *
+ * Examples:
+ * - 8572674464 (numeric ID)
+ * - "8572674464" (numeric string, treated as ID)
+ * - "Gong Zhe" (name, will be resolved)
+ * - "@username" (username, will be resolved)
+ */
+const FlexibleChatId = z.union([z.number(), z.string()]).describe("Chat identifier: either a numeric ID (e.g., -1001234567890) or chat title/name to search (e.g., \"Gong Zhe\", \"BlueNexus Team\")");
+const FlexibleUserId = z.union([z.number(), z.string()]).describe("User identifier: either a numeric ID (e.g., 8572674464), username (e.g., \"@johndoe\"), or name to search (e.g., \"John Doe\")");
+const FlexibleGroupId = z.union([z.number(), z.string()]).describe("Group identifier: either a numeric ID or group name to search");
+// ===== Tool 1: getMe =====
+export const GetMeSchema = z.object({});
+// ===== Tool 2: getChat (consolidated from getChats + getChat) =====
+export const GetChatSchema = z.object({
+    chat: FlexibleChatId.optional().describe("Chat to get info for. If not provided, lists all chats. Can be a numeric ID or chat title/name"),
+    chat_list: z
+        .enum(["main", "archive"])
+        .optional()
+        .default("main")
+        .describe("Which chat list to retrieve when listing chats (default: main)"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(4000)
+        .optional()
+        .default(100)
+        .describe("Maximum number of chats to return when listing (default: 100, max: 4000)"),
+});
+// ===== Tool 3: getMessages (consolidated from getChatHistory + getMessages + searchMessages) =====
+export const GetMessagesSchema = z.object({
+    chat: FlexibleChatId.optional().describe("Chat to get messages from. Required for 'history' and 'specific' modes. Optional for 'search' mode (global search if omitted)"),
+    mode: z
+        .enum(["history", "specific", "search"])
+        .optional()
+        .default("history")
+        .describe("Mode: 'history' for paginated history, 'specific' for exact message IDs, 'search' for text search"),
+    // For mode="history"
+    from_message_id: z
+        .number()
+        .optional()
+        .default(0)
+        .describe("(history mode) Message ID to start from (0 for latest)"),
+    offset: z
+        .number()
+        .optional()
+        .default(0)
+        .describe("(history mode) Numeric offset for pagination"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .default(50)
+        .describe("Maximum messages to return (default: 50, max: 100)"),
+    only_local: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("(history mode) Only return locally cached messages"),
+    // For mode="specific"
+    message_ids: z
+        .array(z.number())
+        .optional()
+        .describe("(specific mode) Array of message IDs to retrieve"),
+    // For mode="search"
+    query: z
+        .string()
+        .optional()
+        .describe("(search mode) Search query text"),
+    next_offset: z
+        .string()
+        .optional()
+        .default("")
+        .describe("(search mode) Cursor for pagination - pass the next_offset from previous response"),
+});
+// ===== Tool 4: sendMessage (consolidated from sendMessage + forwardMessages) =====
+export const SendMessageSchema = z.object({
+    chat: FlexibleChatId.describe("Target chat to send/forward to. Can be a numeric ID or chat title/name"),
+    action: z
+        .enum(["send", "forward"])
+        .optional()
+        .default("send")
+        .describe("Action: 'send' to compose new message, 'forward' to forward existing messages"),
+    // For action="send"
+    text: z
+        .string()
+        .optional()
+        .describe("(send action) Text content of the message"),
+    reply_to_message_id: z
+        .number()
+        .optional()
+        .describe("(send action) ID of message to reply to"),
+    // For action="forward"
+    from_chat: FlexibleChatId.optional().describe("(forward action) Source chat to forward from. Can be a numeric ID or chat title"),
+    message_ids: z
+        .array(z.number())
+        .optional()
+        .describe("(forward action) Array of message IDs to forward"),
+    send_copy: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("(forward action) Send copies without forwarding header"),
+    remove_caption: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("(forward action) Remove media captions when forwarding"),
+});
+// ===== Tool 5: getUser =====
+export const GetUserSchema = z.object({
+    user: FlexibleUserId.describe("User to get info for. Can be a numeric ID, @username, or name (e.g., \"John Doe\")"),
+});
+// ===== Tool 6: getContacts (consolidated from getContacts + searchContacts) =====
+export const GetContactsSchema = z.object({
+    query: z
+        .string()
+        .optional()
+        .describe("Search query to filter contacts. If not provided, returns all contacts"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .default(50)
+        .describe("Maximum results when searching (default: 50, max: 200)"),
+});
+// ===== Tool 7: getFile =====
+export const GetFileSchema = z.object({
+    file_id: z
+        .number()
+        .describe("Identifier of the file to get metadata for"),
+});
+// ===== Tool 8: getGroup (consolidated from getSupergroup + getBasicGroup) =====
+export const GetGroupSchema = z.object({
+    group: FlexibleGroupId.describe("Group to get info for. Can be a numeric ID or group name"),
+    type: z
+        .enum(["supergroup", "basic_group", "auto"])
+        .optional()
+        .default("auto")
+        .describe("Group type: 'supergroup', 'basic_group', or 'auto' to detect automatically"),
+});
+// ===== Tool 9: getChatMembers (consolidated from getSupergroupMembers + getChatAdministrators) =====
+export const GetChatMembersSchema = z.object({
+    chat: FlexibleChatId.describe("Chat to get members from. Can be a numeric ID or chat title"),
+    filter: z
+        .enum(["recent", "administrators", "banned", "bots", "search"])
+        .optional()
+        .default("recent")
+        .describe("Member filter type (default: recent)"),
+    query: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Search query (only used with 'search' filter)"),
+    offset: z
+        .number()
+        .int()
+        .optional()
+        .default(0)
+        .describe("Offset for pagination"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .default(200)
+        .describe("Maximum members to return (default: 200, max: 200)"),
+});
+// ===== Tool 10: getMessageContext =====
+// Retrieves surrounding messages to provide context around a specific message or search result
+export const GetMessageContextSchema = z.object({
+    chat: FlexibleChatId.optional().describe("Chat to get message context from. Required for 'message_id' mode, optional for 'search' mode (searches globally if omitted)"),
+    mode: z
+        .enum(["message_id", "search"])
+        .optional()
+        .default("message_id")
+        .describe("Mode: 'message_id' to get context around a specific message, 'search' to find messages and get context around each match"),
+    // For mode="message_id"
+    message_id: z
+        .number()
+        .optional()
+        .describe("(message_id mode) The message ID to get context around"),
+    // For mode="search"
+    query: z
+        .string()
+        .optional()
+        .describe("(search mode) Search query to find messages"),
+    search_limit: z
+        .number()
+        .int()
+        .positive()
+        .max(20)
+        .optional()
+        .default(5)
+        .describe("(search mode) Maximum number of search results to get context for (default: 5, max: 20)"),
+    // Shared parameters
+    context_count: z
+        .number()
+        .int()
+        .positive()
+        .max(50)
+        .optional()
+        .default(5)
+        .describe("Number of messages to fetch before AND after the target message (default: 5, max: 50)"),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

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

package/dist/telegram-client.d.ts

@@ -0,0 +1,19 @@
+import tdl from "tdl";
+export type { Client } from "tdl";
+/**
+ * Create a TDLib client with a restored session from binlog
+ *
+ * @param sessionId - Unique session identifier (used for temp directory)
+ * @param binlog - TDLib binlog buffer (decrypted session data)
+ * @param apiId - Telegram API ID
+ * @param apiHash - Telegram API Hash
+ * @returns Configured and authorized TDLib client
+ */
+export declare function createTelegramClient(sessionId: string, binlog: Buffer, apiId: number, apiHash: string): Promise<tdl.Client>;
+/**
+ * Clean up session files after use
+ *
+ * @param sessionId - Session identifier
+ */
+export declare function cleanupSession(sessionId: string): Promise<void>;
+//# sourceMappingURL=telegram-client.d.ts.map

package/dist/telegram-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-client.d.ts","sourceRoot":"","sources":["../src/telegram-client.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAC;AAatB,YAAY,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAElC;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAmCrB;AAwDD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrE"}

package/dist/telegram-client.js

@@ -0,0 +1,112 @@
+import tdl from "tdl";
+import { getTdjson } from "prebuilt-tdlib";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { createLogger } from "./logger.js";
+// Configure TDLib once at startup
+tdl.configure({ tdjson: getTdjson() });
+const logger = createLogger("TelegramClient");
+/**
+ * Create a TDLib client with a restored session from binlog
+ *
+ * @param sessionId - Unique session identifier (used for temp directory)
+ * @param binlog - TDLib binlog buffer (decrypted session data)
+ * @param apiId - Telegram API ID
+ * @param apiHash - Telegram API Hash
+ * @returns Configured and authorized TDLib client
+ */
+export async function createTelegramClient(sessionId, binlog, apiId, apiHash) {
+    // Create temp directory for this session
+    const dbPath = path.join(os.tmpdir(), "tdlib-sessions", sessionId);
+    await fs.mkdir(dbPath, { recursive: true });
+    // Write binlog file to restore session
+    const binlogPath = path.join(dbPath, "td.binlog");
+    await fs.writeFile(binlogPath, binlog);
+    // Check if we should use test DC (must match how the session was created)
+    const useTestDc = process.env.TELEGRAM_USE_TEST_DC === "true";
+    // Create TDLib client with parameters matching the backend
+    const client = tdl.createClient({
+        apiId,
+        apiHash,
+        databaseDirectory: dbPath,
+        filesDirectory: path.join(dbPath, "files"),
+        useTestDc,
+        tdlibParameters: {
+            // Enable databases for chat/message operations
+            use_message_database: true,
+            use_chat_info_database: true,
+            use_file_database: true,
+            use_secret_chats: false,
+            device_model: "BlueNexus MCP Server",
+            application_version: "1.0.0",
+            system_language_code: "en",
+        },
+    });
+    // Wait for authorization to complete
+    await waitForAuthorization(client);
+    return client;
+}
+/**
+ * Wait for TDLib client to be authorized
+ *
+ * @param client - TDLib client
+ * @returns Promise that resolves when client is authorized
+ */
+function waitForAuthorization(client) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error("Authorization timeout: Session may be expired or invalid"));
+        }, 30000);
+        const onUpdate = (update) => {
+            if (update._ === "updateAuthorizationState") {
+                const state = update.authorization_state?._;
+                if (state === "authorizationStateReady") {
+                    cleanup();
+                    resolve();
+                }
+                else if (state === "authorizationStateClosed") {
+                    cleanup();
+                    reject(new Error("Session closed: The TDLib session has been terminated"));
+                }
+                else if (state === "authorizationStateWaitPhoneNumber" ||
+                    state === "authorizationStateWaitCode" ||
+                    state === "authorizationStateWaitPassword") {
+                    cleanup();
+                    reject(new Error(`Session requires re-authentication: ${state}. The stored session may be expired or invalid.`));
+                }
+            }
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            client.off("update", onUpdate);
+            client.off("error", onError);
+        };
+        client.on("update", onUpdate);
+        client.on("error", onError);
+    });
+}
+/**
+ * Clean up session files after use
+ *
+ * @param sessionId - Session identifier
+ */
+export async function cleanupSession(sessionId) {
+    const dbPath = path.join(os.tmpdir(), "tdlib-sessions", sessionId);
+    try {
+        await fs.rm(dbPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        // Log but don't throw - cleanup failures shouldn't break the flow
+        logger.warn("Failed to cleanup session", {
+            sessionId,
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+}
+//# sourceMappingURL=telegram-client.js.map

package/dist/telegram-client.js.map

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

package/dist/tool-loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tool configuration loader
+ * Loads tool definitions from tools.json and validates them
+ *
+ * Supports loading from (in priority order):
+ * 1. Custom path via TOOLS_CONFIG_PATH environment variable
+ * 2. tools.json in current working directory (for development)
+ * 3. tools.json in package installation directory (for npx/installed usage)
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface ToolsConfig {
+    [toolName: string]: ToolDefinition;
+}
+/**
+ * Load tool definitions from tools.json
+ * Uses caching in production, always reloads in development
+ */
+export declare function loadToolDefinitions(forceReload?: boolean): ToolDefinition[];
+/**
+ * Clear the tool cache (useful for testing or forced reloads)
+ */
+export declare function clearToolCache(): void;
+//# sourceMappingURL=tool-loader.d.ts.map

package/dist/tool-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loader.d.ts","sourceRoot":"","sources":["../src/tool-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAAC;CACpC;AAmDD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,UAAQ,GAAG,cAAc,EAAE,CAkEzE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAIrC"}

package/dist/tool-loader.js

@@ -0,0 +1,121 @@
+/**
+ * Tool configuration loader
+ * Loads tool definitions from tools.json and validates them
+ *
+ * Supports loading from (in priority order):
+ * 1. Custom path via TOOLS_CONFIG_PATH environment variable
+ * 2. tools.json in current working directory (for development)
+ * 3. tools.json in package installation directory (for npx/installed usage)
+ */
+import { readFileSync, existsSync } from "fs";
+import { resolve, isAbsolute, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { createLogger } from "./logger.js";
+const logger = createLogger("ToolLoader");
+let cachedTools = null;
+let lastLoadTime = 0;
+let lastLoadPath = "";
+/**
+ * Resolve the tools configuration file path
+ * Supports:
+ * - Environment variable: TOOLS_CONFIG_PATH
+ * - Absolute paths: /Users/username/Desktop/tools.json
+ * - Relative paths: ./tools.json, ../config/tools.json
+ * - Home directory: ~/Desktop/tools.json
+ * - Default: tools.json in current working directory
+ * - Fallback: tools.json in package installation directory
+ */
+function resolveToolsPath() {
+    // Check environment variable first
+    const envPath = process.env.TOOLS_CONFIG_PATH;
+    if (envPath) {
+        // Expand ~ to home directory
+        const expandedPath = envPath.startsWith("~/")
+            ? resolve(homedir(), envPath.slice(2))
+            : envPath;
+        // If absolute path, use as-is
+        if (isAbsolute(expandedPath)) {
+            return expandedPath;
+        }
+        // Otherwise resolve relative to current working directory
+        return resolve(process.cwd(), expandedPath);
+    }
+    // Try current working directory first (for dev mode)
+    const cwdPath = resolve(process.cwd(), "tools.json");
+    if (existsSync(cwdPath)) {
+        return cwdPath;
+    }
+    // Fallback: tools.json in package installation directory (for npx/installed usage)
+    // Get the directory of this module file
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    // Go up from dist/tool-loader.js to package root
+    const packageRoot = resolve(moduleDir, "..");
+    const packagePath = resolve(packageRoot, "tools.json");
+    return packagePath;
+}
+/**
+ * Load tool definitions from tools.json
+ * Uses caching in production, always reloads in development
+ */
+export function loadToolDefinitions(forceReload = false) {
+    const isDev = process.env.NODE_ENV !== "production";
+    const now = Date.now();
+    // Get the tools config path
+    const toolsPath = resolveToolsPath();
+    // In production, cache tools and only reload if forced or path changed
+    // In development, reload every time (for nodemon compatibility)
+    if (!isDev &&
+        !forceReload &&
+        cachedTools &&
+        now - lastLoadTime < 60000 &&
+        lastLoadPath === toolsPath) {
+        return cachedTools;
+    }
+    try {
+        // Check if file exists
+        if (!existsSync(toolsPath)) {
+            throw new Error(`Tools configuration file not found: ${toolsPath}`);
+        }
+        const toolsJson = readFileSync(toolsPath, "utf-8");
+        const toolsConfig = JSON.parse(toolsJson);
+        // Convert config object to array of tool definitions
+        const tools = Object.values(toolsConfig);
+        // Validate tool definitions
+        for (const tool of tools) {
+            if (!tool.name || !tool.description || !tool.inputSchema) {
+                throw new Error(`Invalid tool definition: ${JSON.stringify(tool)}`);
+            }
+        }
+        cachedTools = tools;
+        lastLoadTime = now;
+        lastLoadPath = toolsPath;
+        logger.info("Tool definitions loaded", {
+            count: tools.length,
+            path: toolsPath,
+            mode: isDev ? "development" : "production",
+            customPath: !!process.env.TOOLS_CONFIG_PATH,
+        });
+        return tools;
+    }
+    catch (error) {
+        logger.error("Error loading tools.json", {
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+        // In case of error, return cached tools if available
+        if (cachedTools) {
+            logger.warn("Using cached tool definitions due to load error");
+            return cachedTools;
+        }
+        throw new Error(`Failed to load tool definitions: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error instanceof Error ? error : undefined });
+    }
+}
+/**
+ * Clear the tool cache (useful for testing or forced reloads)
+ */
+export function clearToolCache() {
+    cachedTools = null;
+    lastLoadTime = 0;
+    logger.info("Tool cache cleared");
+}
+//# sourceMappingURL=tool-loader.js.map

package/dist/tool-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loader.js","sourceRoot":"","sources":["../src/tool-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;AAgB1C,IAAI,WAAW,GAA4B,IAAI,CAAC;AAChD,IAAI,YAAY,GAAG,CAAC,CAAC;AACrB,IAAI,YAAY,GAAG,EAAE,CAAC;AAEtB;;;;;;;;;GASG;AACH,SAAS,gBAAgB;IACvB,mCAAmC;IACnC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAE9C,IAAI,OAAO,EAAE,CAAC;QACZ,6BAA6B;QAC7B,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAC3C,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACtC,CAAC,CAAC,OAAO,CAAC;QAEZ,8BAA8B;QAC9B,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,0DAA0D;QAC1D,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;IAC9C,CAAC;IAED,qDAAqD;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;IACrD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,mFAAmF;IACnF,wCAAwC;IACxC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,iDAAiD;IACjD,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEvD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAW,GAAG,KAAK;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,4BAA4B;IAC5B,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IAErC,uEAAuE;IACvE,gEAAgE;IAChE,IACE,CAAC,KAAK;QACN,CAAC,WAAW;QACZ,WAAW;QACX,GAAG,GAAG,YAAY,GAAG,KAAK;QAC1B,YAAY,KAAK,SAAS,EAC1B,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,CAAC;QACH,uBAAuB;QACvB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,uCAAuC,SAAS,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAEvD,qDAAqD;QACrD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEzC,4BAA4B;QAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACzD,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QAED,WAAW,GAAG,KAAK,CAAC;QACpB,YAAY,GAAG,GAAG,CAAC;QACnB,YAAY,GAAG,SAAS,CAAC;QAEzB,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE;YACrC,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY;YAC1C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB;SAC5C,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE;YACvC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SACjE,CAAC,CAAC;QAEH,qDAAqD;QACrD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;YAC/D,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,MAAM,IAAI,KAAK,CACb,oCAAoC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,EAC9F,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE,CACtD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,WAAW,GAAG,IAAI,CAAC;IACnB,YAAY,GAAG,CAAC,CAAC;IACjB,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;AACpC,CAAC"}

package/dist/tool-registry.d.ts

@@ -0,0 +1,47 @@
+import type { Request } from "express";
+import type { z } from "zod";
+import type { ToolResponse } from "./types.js";
+/**
+ * Type for tool handler functions
+ * Uses z.infer<TSchema> to get the output type of the schema (after defaults are applied)
+ */
+type ToolHandler<TSchema extends z.ZodTypeAny, TOutput = unknown> = (req: Request, args: z.infer<TSchema>) => Promise<TOutput>;
+/**
+ * Registry for managing and executing MCP tools with automatic debug wrapping
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * Register a new tool in the registry
+     *
+     * @param name - Unique name of the tool
+     * @param schema - Zod schema for validating tool input
+     * @param handler - Async function that executes the tool logic
+     */
+    register<TSchema extends z.ZodTypeAny, TOutput>(name: string, schema: TSchema, handler: ToolHandler<TSchema, TOutput>): void;
+    /**
+     * Execute a tool by name with automatic validation and debug wrapping
+     *
+     * @param toolName - Name of the tool to execute
+     * @param rawInput - Raw input arguments (will be validated against schema)
+     * @param req - Express request object for accessing headers/context
+     * @returns ToolResponse with data and optional debug metadata
+     * @throws Error if tool is not found or validation fails
+     */
+    execute(toolName: string, rawInput: unknown, req: Request): Promise<ToolResponse<unknown>>;
+    /**
+     * Check if a tool exists in the registry
+     *
+     * @param toolName - Name of the tool to check
+     * @returns True if the tool is registered
+     */
+    has(toolName: string): boolean;
+    /**
+     * Get all registered tool names
+     *
+     * @returns Array of registered tool names
+     */
+    getToolNames(): string[];
+}
+export {};
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;GAGG;AACH,KAAK,WAAW,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,IAAI,CAClE,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;AAWtB;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqC;IAElD;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,EAC5C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,GACrC,IAAI;IAQP;;;;;;;;OAQG;IACG,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAcjC;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE;CAGzB"}

package/dist/tool-registry.js

@@ -0,0 +1,58 @@
+import { wrapWithDebug } from "./debug-middleware.js";
+/**
+ * Registry for managing and executing MCP tools with automatic debug wrapping
+ */
+export class ToolRegistry {
+    tools = new Map();
+    /**
+     * Register a new tool in the registry
+     *
+     * @param name - Unique name of the tool
+     * @param schema - Zod schema for validating tool input
+     * @param handler - Async function that executes the tool logic
+     */
+    register(name, schema, handler) {
+        this.tools.set(name, {
+            name,
+            schema,
+            handler: handler,
+        });
+    }
+    /**
+     * Execute a tool by name with automatic validation and debug wrapping
+     *
+     * @param toolName - Name of the tool to execute
+     * @param rawInput - Raw input arguments (will be validated against schema)
+     * @param req - Express request object for accessing headers/context
+     * @returns ToolResponse with data and optional debug metadata
+     * @throws Error if tool is not found or validation fails
+     */
+    async execute(toolName, rawInput, req) {
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            throw new Error(`Unknown tool: ${toolName}`);
+        }
+        // Validate input against schema
+        const args = tool.schema.parse(rawInput);
+        // Execute with debug wrapping
+        return wrapWithDebug(toolName, args, () => tool.handler(req, args));
+    }
+    /**
+     * Check if a tool exists in the registry
+     *
+     * @param toolName - Name of the tool to check
+     * @returns True if the tool is registered
+     */
+    has(toolName) {
+        return this.tools.has(toolName);
+    }
+    /**
+     * Get all registered tool names
+     *
+     * @returns Array of registered tool names
+     */
+    getToolNames() {
+        return Array.from(this.tools.keys());
+    }
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAoBtD;;GAEG;AACH,MAAM,OAAO,YAAY;IACf,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAElD;;;;;;OAMG;IACH,QAAQ,CACN,IAAY,EACZ,MAAe,EACf,OAAsC;QAEtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE;YACnB,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,OAA4D;SACtE,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CACX,QAAgB,EAChB,QAAiB,EACjB,GAAY;QAEZ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEtC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;QAC/C,CAAC;QAED,gCAAgC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAEzC,8BAA8B;QAC9B,OAAO,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,QAAgB;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACF"}