@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/services/hub-tools/types.d.ts

@@ -0,0 +1,42 @@
+import type { ServerConfig, ServerInstanceConfig } from '../../config/config.schema.js';
+/**
+ * Configuration options for server instance selection in multi-instance scenarios.
+ *
+ * This interface defines request options that can be used to select specific server instances
+ * when multiple instances of the same MCP server are available. The current implementation
+ * uses the first available instance, but the interface is designed to support future
+ * extensions for intelligent instance selection based on various criteria.
+ *
+ * @interface RequestOptions
+ * @property {string} [sessionId] - Session identifier for selecting instance associated with specific session
+ * @property {Record<string, string>} [tags] - Key-value tags for matching against server instance tags
+ *
+ * @example
+ * ```typescript
+ * // Select instance based on session
+ * const options: RequestOptions = { sessionId: 'session-123' };
+ *
+ * // Select instance based on tags
+ * const options: RequestOptions = { tags: { environment: 'production' } };
+ * ```
+ */
+export interface RequestOptions {
+    sessionId?: string;
+    tags?: Record<string, string>;
+}
+/**
+ * Type for server information with configuration and instance details.
+ */
+export type ServerInstanceInfo = {
+    name: string;
+    config: ServerConfig;
+    instance: ServerInstanceConfig & Record<string, unknown>;
+};
+/**
+ * Type guard return type.
+ */
+export type ValidServer = {
+    name: string;
+    config: ServerConfig;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/src/services/hub-tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAG/B;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC"}

package/dist/server/src/services/hub-tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/src/services/hub-tools.service.d.ts

@@ -0,0 +1,235 @@
+import type { Tool } from '../../shared/models/tool.model.js';
+import type { Resource } from '../../shared/models/resource.model.js';
+import { LIST_SERVERS_TOOL, FIND_SERVERS_TOOL, LIST_ALL_TOOLS_IN_SERVER_TOOL, FIND_TOOLS_IN_SERVER_TOOL, GET_TOOL_TOOL, CALL_TOOL_TOOL, FIND_TOOLS_TOOL } from '../models/system-tools.constants.js';
+import type { SystemToolName, ListServersParams, FindServersParams, ListAllToolsInServerParams, FindToolsInServerParams, GetToolParams, CallToolParams, FindToolsParams } from '../models/system-tools.constants.js';
+/**
+ * Central service for managing system tools and MCP server interactions in the MCP Hub Lite gateway.
+ *
+ * The HubToolsService provides a unified interface for discovering, managing, and interacting with
+ * all connected MCP (Model Context Protocol) servers. It serves as the primary orchestration layer
+ * between client applications and the underlying MCP infrastructure, offering both system-level
+ * management capabilities and direct tool execution functionality.
+ *
+ * ## Core Responsibilities
+ *
+ * - **System Tool Management**: Exposes a standardized set of system tools for server discovery and management
+ * - **Tool Discovery**: Enables searching and listing tools across all connected MCP servers
+ * - **Tool Execution**: Provides safe, monitored execution of tools with comprehensive event tracking
+ * - **Resource Management**: Dynamically generates and serves virtual resources representing server state
+ * - **Instance Selection**: Handles intelligent server instance selection for multi-instance scenarios
+ * - **Error Handling**: Implements consistent error handling and logging across all operations
+ *
+ * ## System Tools Provided
+ *
+ * The service exposes the following system tools through the `getSystemTools()` method:
+ * - `list-servers`: Retrieve all connected server names
+ * - `find-servers`: Search servers by pattern matching
+ * - `list-all-tools-in-server`: List all tools from a specific server
+ * - `find-tools-in-server`: Search tools within a specific server
+ * - `get-tool`: Retrieve complete schema for a specific tool
+ * - `call-tool`: Execute a tool on a specific server
+ * - `find-tools`: Search tools across all connected servers
+ *
+ * ## Architecture Integration
+ *
+ * This service integrates tightly with other core components:
+ * - **HubManagerService**: For server configuration and instance management
+ * - **McpConnectionManager**: For actual tool execution and connection management
+ * - **EventBusService**: For publishing tool call events and system notifications
+ * - **GatewayService**: For system tool routing and aggregation
+ *
+ * All operations include comprehensive logging, error handling, and event publishing
+ * to support observability, debugging, and monitoring of the MCP Hub Lite system.
+ *
+ * @example
+ * ```typescript
+ * const hubTools = new HubToolsService();
+ *
+ * // List all connected servers
+ * const servers = await hubTools.listServers();
+ *
+ * // Call a tool on a specific server
+ * const result = await hubTools.callTool('file-system-server', 'list-files', { directory: '/home' });
+ *
+ * // Search for tools across all servers
+ * const matchingTools = await hubTools.findTools('search');
+ * ```
+ */
+export declare class HubToolsService {
+    /**
+     * Cached dynamic resource list to avoid regenerating on every request
+     */
+    private generatedResourcesCache;
+    constructor();
+    /**
+     * Retrieves the complete list of system tools provided by this service.
+     *
+     * This method generates system tool configurations based on the SYSTEM_TOOL_NAMES constant,
+     * ensuring consistency with the defined system tool names. Each tool includes its name,
+     * description, input schema, and annotations for proper client-side rendering and behavior.
+     *
+     * @returns {Array<{ name: string; description: string; inputSchema: JsonSchema; annotations?: ToolAnnotations }>}
+     * Array of system tool configurations
+     */
+    getSystemTools(): import("./hub-tools/system-tool-definitions.js").SystemToolDefinition[];
+    /**
+     * Lists all connected MCP servers by name.
+     *
+     * This method retrieves all configured servers from the hub manager, filters out
+     * invalid entries using the hasValidId type guard, and returns an array of server names.
+     * It provides a simple way to discover available servers in the system.
+     *
+     * @returns {Promise<string[]>} Array of connected server names
+     */
+    listServers(): Promise<string[]>;
+    /**
+     * Finds servers matching a specified regex pattern.
+     *
+     * This method searches through all configured servers using the provided regex pattern,
+     * supporting flexible search options including case sensitivity and search scope
+     * (name, description, or both). It returns an array of matching server names.
+     *
+     * @param {FindServersParams} args - Search parameters
+     * @returns {Promise<string[]>} Array of matching server names
+     */
+    findServers(args: FindServersParams): Promise<string[]>;
+    /**
+     * Lists all tools available from a specific MCP server.
+     *
+     * This method retrieves all tools from the specified server, handling both regular
+     * MCP servers and the special MCP Hub Lite server (which returns system tools).
+     * It uses the selectBestInstance function to resolve server names to instances
+     * and leverages the MCP connection manager for tool retrieval.
+     *
+     * @param {ListAllToolsInServerParams} args - Server name and request options
+     * @returns {Promise<{ serverName: string; tools: Tool[] }>} Object containing server name and tools array
+     * @throws {Error} If the specified server is not found or not connected
+     */
+    listAllToolsInServer(args: ListAllToolsInServerParams): Promise<{
+        serverName: string;
+        tools: Tool[];
+    }>;
+    /**
+     * Finds tools matching a pattern within a specific MCP server.
+     *
+     * This method searches through all tools available from the specified server using
+     * the provided regex pattern, supporting flexible search options including case
+     * sensitivity and search scope (name, description, or both). It returns matching
+     * tools grouped by server name.
+     *
+     * @param {FindToolsInServerParams} args - Search parameters
+     * @returns {Promise<{ serverName: string; tools: Tool[] }>} Object containing server name and matching tools
+     * @throws {Error} If the specified server is not found or not connected
+     */
+    findToolsInServer(args: FindToolsInServerParams): Promise<{
+        serverName: string;
+        tools: Tool[];
+    }>;
+    /**
+     * Retrieves the complete schema for a specific tool from a specific server.
+     *
+     * This method returns the full tool definition including name, description, input schema,
+     * and any annotations. It's useful for clients that need detailed information about
+     * a tool's capabilities and expected parameters before execution.
+     *
+     * @param {GetToolParams} args - Tool retrieval parameters
+     * @returns {Promise<Tool | undefined>} Complete tool schema or undefined if not found
+     * @throws {Error} If the specified server is not found or not connected
+     */
+    getTool(args: GetToolParams): Promise<Tool | undefined>;
+    /**
+     * Calls a specific system tool directly with type-safe conditional return types.
+     *
+     * This method provides a unified entry point for all system tool calls, using TypeScript's
+     * conditional types to ensure type safety based on the tool name. It handles logging,
+     * error handling, and delegates to the appropriate internal methods based on the tool name.
+     *
+     * @param {T} toolName - System tool name with generic type constraint
+     * @param {SystemToolArgs} toolArgs - Type-safe arguments based on tool name
+     * @returns {Promise<ConditionalReturnType>} Tool execution result with accurate type safety matching actual method return types
+     * @throws {Error} If the system tool is not found or execution fails
+     */
+    callSystemTool<T extends SystemToolName>(toolName: T, toolArgs: T extends typeof LIST_SERVERS_TOOL ? ListServersParams : T extends typeof FIND_SERVERS_TOOL ? FindServersParams : T extends typeof LIST_ALL_TOOLS_IN_SERVER_TOOL ? ListAllToolsInServerParams : T extends typeof FIND_TOOLS_IN_SERVER_TOOL ? FindToolsInServerParams : T extends typeof GET_TOOL_TOOL ? GetToolParams : T extends typeof CALL_TOOL_TOOL ? CallToolParams : T extends typeof FIND_TOOLS_TOOL ? FindToolsParams : never): Promise<T extends typeof LIST_SERVERS_TOOL ? string[] : T extends typeof FIND_SERVERS_TOOL ? string[] : T extends typeof LIST_ALL_TOOLS_IN_SERVER_TOOL ? {
+        serverName: string;
+        tools: Tool[];
+    } : T extends typeof FIND_TOOLS_IN_SERVER_TOOL ? {
+        serverName: string;
+        tools: Tool[];
+    } : T extends typeof GET_TOOL_TOOL ? Tool | undefined : T extends typeof CALL_TOOL_TOOL ? unknown : T extends typeof FIND_TOOLS_TOOL ? Record<string, {
+        tools: Tool[];
+    }> : never>;
+    /**
+     * Calls a specific tool from a specific MCP server with comprehensive event tracking.
+     *
+     * This method handles both regular MCP server tool calls and system tool calls (when
+     * serverName is 'mcp-hub-lite'). It publishes TOOL_CALL_STARTED, TOOL_CALL_COMPLETED,
+     * and TOOL_CALL_ERROR events for monitoring and debugging purposes, and includes
+     * detailed logging for observability.
+     *
+     * @param {CallToolParams} args - Tool call parameters
+     * @returns {Promise<unknown>} Tool execution result as returned by the server
+     * @throws {Error} If the server is not found, not connected, or tool execution fails
+     */
+    callTool(args: CallToolParams): Promise<unknown>;
+    /**
+     * Lists all available tools from all connected servers including system tools.
+     *
+     * This method aggregates tools from all configured and connected MCP servers, including
+     * the system tools provided by the MCP Hub Lite server itself. It returns a structured
+     * object mapping server names to their respective tool arrays.
+     *
+     * @returns {Promise<Record<string, { tools: Tool[] }>>} Object mapping server names to tool arrays
+     */
+    listAllTools(): Promise<Record<string, {
+        tools: Tool[];
+    }>>;
+    /**
+     * Finds tools matching a pattern across all connected MCP servers.
+     *
+     * This method searches through all available tools from all connected servers using the
+     * provided regex pattern, supporting flexible search options including case sensitivity
+     * and search scope (name, description, or both). It returns matching tools grouped by
+     * their originating server names.
+     *
+     * @param {FindToolsParams} args - Search parameters
+     * @returns {Promise<Record<string, { tools: Tool[] }>>} Object mapping server names to matching tools
+     */
+    findTools(args: FindToolsParams): Promise<Record<string, {
+        tools: Tool[];
+    }>>;
+    /**
+     * Lists all dynamically generated Hub resources based on connected MCP servers.
+     *
+     * This method returns an array of virtual resources that represent the current state
+     * of connected servers, providing a unified interface for resource discovery and access.
+     * The resources are generated on-demand based on the current server configuration.
+     *
+     * @returns {Promise<Resource[]>} Array of MCP resource objects representing Hub resources
+     */
+    listResources(): Promise<Resource[]>;
+    /**
+     * Reads content from a specific Hub resource URI.
+     *
+     * This method provides access to dynamically generated Hub resources by parsing the URI
+     * and returning the appropriate content based on the resource type. It supports three
+     * types of resources:
+     * - Server metadata: hub://servers/{serverName}
+     * - Tools list: hub://servers/{serverName}/tools
+     * - Resources list: hub://servers/{serverName}/resources
+     *
+     * @param {string} uri - Resource URI to read (e.g., hub://servers/server-name)
+     * @returns {Promise<ServerMetadata | Tool[] | Resource[]>} Resource content based on URI type
+     * @throws {Error} If URI format is invalid, server not found, or resource type unknown
+     */
+    readResource(uri: string): Promise<{
+        name: string;
+        status: unknown;
+        toolsCount: number;
+        resourcesCount: number;
+        tags: Record<string, string>;
+        lastHeartbeat: number;
+        uptime: number;
+    } | Tool[] | Resource[]>;
+}
+export declare const hubToolsService: HubToolsService;
+//# sourceMappingURL=hub-tools.service.d.ts.map

package/dist/server/src/services/hub-tools.service.d.ts.map

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