npm - @loop_ouroboros/mcp-hub-lite - Versions diffs - 1.1.0 → 1.2.0 - Mend

@loop_ouroboros/mcp-hub-lite 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (100) hide show

package/dist/client/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <link rel="icon" href="/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>MCP Server Manager</title>
-    <script type="module" crossorigin src="/assets/index-vhkqgpmN.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/vue-vendor-BLHLXXJK.js">
+    <script type="module" crossorigin src="/assets/index-CTB6oe-9.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/vue-vendor-CbgVSHIh.js">
     <link rel="stylesheet" crossorigin href="/assets/index-DpH6ZSbs.css">
   </head>
   <body>

package/dist/server/src/api/mcp/debug-response-wrapper.js CHANGED Viewed

@@ -269,10 +269,10 @@ export function wrapReplyForDebug(reply, sessionId) {
                     }
                 }
                 if (headers) {
-                    logger.debug(`MCP Gateway error response: ${statusCode} ${statusMessage || ''} Headers: ${stringifyForLogging(headers)}`, LOG_MODULES.COMMUNICATION);
+                    logger.debug(`Full error response context - statusCode: ${statusCode}, statusMessage: ${statusMessage || 'none'}, headers: ${stringifyForLogging(headers)}`, LOG_MODULES.COMMUNICATION);
                 }
                 else {
-                    logger.debug(`MCP Gateway error response: ${statusCode} ${statusMessage || ''}`, LOG_MODULES.COMMUNICATION);
+                    logger.debug(`Full error response context - statusCode: ${statusCode}, statusMessage: ${statusMessage || 'none'}`, LOG_MODULES.COMMUNICATION);
                 }
             }
         }

package/dist/server/src/api/mcp/gateway.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/gateway.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAM7E;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,~~iBA0F9D~~"}
1	+ {"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/gateway.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAM7E;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,iBAqH9D"}

package/dist/server/src/api/mcp/gateway.js CHANGED Viewed

@@ -5,7 +5,7 @@
 import { logger, LOG_MODULES } from '../../utils/logger/index.js';
 import { stringifyForLogging, getMcpCommDebugSetting } from '../../utils/json-utils.js';
 import { wrapReplyForDebug } from './debug-response-wrapper.js';
-import { globalTransport } from '../../services/gateway/global-transport.js';
+import { createSessionTransport } from '../../services/gateway/global-transport.js';
 /**
  * MCP Gateway routes registration.
  *
@@ -44,11 +44,25 @@ export async function mcpGatewayRoutes(fastify) {
         wrapReplyForDebug(reply, '');
         reply.hijack();
         try {
-            await globalTransport.handleRequest(request.raw, reply.raw, request.body);
+            logger.debug(`About to create session transport for MCP request`, LOG_MODULES.GATEWAY);
+            const { transport, server } = await createSessionTransport();
+            logger.debug(`Created session transport successfully, handling MCP request`, LOG_MODULES.GATEWAY);
+            try {
+                await transport.handleRequest(request.raw, reply.raw, request.body);
+                logger.debug(`Successfully handled MCP request with server: ${server.constructor.name}`, LOG_MODULES.GATEWAY);
+            }
+            finally {
+                // Resources will be automatically cleaned up by garbage collection
+                // since transport and server are local to this request scope
+                logger.debug(`Session transport request completed, resources will be GC'd`, LOG_MODULES.GATEWAY);
+            }
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error(`Error handling MCP request: ${errorMessage}`, error, LOG_MODULES.GATEWAY);
+            const errorStack = error instanceof Error ? error.stack : 'No stack available';
+            logger.error(`Error handling MCP request: ${errorMessage}`, LOG_MODULES.GATEWAY);
+            logger.error(`Full error stack: ${errorStack}`, LOG_MODULES.GATEWAY);
+            logger.error(`Request body that caused error: ${JSON.stringify(request.body)}`, LOG_MODULES.GATEWAY);
             if (!reply.raw.headersSent) {
                 reply.raw.writeHead(500, { 'Content-Type': 'application/json' });
                 reply.raw.end(JSON.stringify({

package/dist/server/src/api/mcp/session-context-extractor.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"session-context-extractor.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/session-context-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAI7E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE;YACX,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC;QACF,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC;IAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,cAAc,CAAC;CAChC,~~CAyFA~~"}
1	+ {"version":3,"file":"session-context-extractor.d.ts","sourceRoot":"","sources":["../../../../../src/api/mcp/session-context-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAI7E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE;YACX,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC;QACF,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC;IAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,cAAc,CAAC;CAChC,CAsGA"}

package/dist/server/src/api/mcp/session-context-extractor.js CHANGED Viewed

@@ -49,14 +49,14 @@ export function extractSessionContext(request) {
             logger.debug(`Extracted sessionId from URL: ${sessionId}`, LOG_MODULES.CONTEXT);
         }
     }
-    // If sessionId was extracted, check if it exists in memory (for debugging)
+    // If sessionId was extracted, check if it exists in persisted sessions (for debugging)
     if (sessionId) {
-        const hasSession = mcpSessionManager.hasSession(sessionId);
-        if (hasSession) {
-            logger.debug(`Session ${sessionId} found in active sessions`, LOG_MODULES.CONTEXT);
+        const persistedSession = mcpSessionManager.getSessionState(sessionId);
+        if (persistedSession) {
+            logger.debug(`Session ${sessionId} found in persisted sessions`, LOG_MODULES.CONTEXT);
         }
         else {
-            logger.debug(`Session ${sessionId} not found in active sessions (will create new)`, LOG_MODULES.CONTEXT);
+            logger.debug(`Session ${sessionId} not found in persisted sessions (will create new)`, LOG_MODULES.CONTEXT);
         }
     }
     // Extract client info from headers and request body
@@ -90,11 +90,20 @@ export function extractSessionContext(request) {
             logger.debug(`Generated new sessionId: ${sessionId}`, LOG_MODULES.CONTEXT);
         }
     }
+    // Add consistency check before returning session information
+    if (sessionId && mcpSessionManager.getSessionState(sessionId)) {
+        const hasSessionObject = mcpSessionManager.hasSession(sessionId);
+        if (!hasSessionObject) {
+            logger.warn(`Session state exists but session object missing for ${sessionId}`, LOG_MODULES.CONTEXT);
+        }
+    }
     const sessionContext = {
         sessionId,
         clientName,
         clientVersion,
         protocolVersion,
+        cwd: undefined, // Will be populated from roots/list response later
+        project: undefined, // Will be populated from roots/list response later
         ip: request.ip,
         userAgent: headers['user-agent'],
         timestamp: Date.now()

package/dist/server/src/cli/commands/mcp-tool-use.d.ts ADDED Viewed

@@ -0,0 +1,62 @@
+import { Command } from 'commander';
+/**
+ * CLI command for dynamic MCP server tool operations via API.
+ *
+ * This command provides a simplified CLI interface for interacting with MCP server tools,
+ * supporting four actions: list-servers, list-tools, get-tool, and call-tool. It wraps
+ * the HTTP API endpoints and requires the MCP Hub Lite server to be running.
+ *
+ * ## Command Format
+ *
+ * ```
+ * mcp-tool-use <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * Or via npm:
+ * ```
+ * npm run tool-use <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * ## Supported Actions
+ *
+ * - `list-servers` - List all connected MCP servers
+ * - `list-tools` - List all tools from the specified server
+ * - `get-tool <toolName>` - Get complete schema for a specific tool
+ * - `call-tool <toolName>` - Call a tool on the specified server
+ *
+ * ## Options
+ *
+ * - `--args <json>` - JSON string of tool arguments (for call-tool action)
+ * - `--tags <json>` - JSON object of instance selection tags (call-tool only, for multi-instance servers)
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List all connected servers
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite list-servers
+ *
+ * # List all tools from a specific server
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite list-tools
+ *
+ * # Get tool schema
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite get-tool list_tools
+ *
+ * # Call a tool with arguments
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite call-tool list_tools --args '{"serverName":"mcp-hub-lite"}'
+ *
+ * # Call a tool with tags for multi-instance selection
+ * mcp-hub-lite mcp-tool-use baidu-search call-tool search --args '{"query":"天气"}' --tags '{"env":"prod"}'
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Exits with code 1 if the server is not running
+ * - Exits with code 1 if action is unknown
+ * - Exits with code 1 if toolName is required but not provided
+ * - Exits with code 1 if JSON parsing fails for --args or --tags
+ * - Exits with code 1 if the underlying API call fails
+ *
+ * @returns {Command} The configured mcp-tool-use command instance for registration with Commander.js
+ */
+export declare const mcpToolUseCommand: Command;
+//# sourceMappingURL=mcp-tool-use.d.ts.map

package/dist/server/src/cli/commands/mcp-tool-use.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"mcp-tool-use.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/mcp-tool-use.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,iBAAiB,SAkI1B,CAAC"}

package/dist/server/src/cli/commands/mcp-tool-use.js ADDED Viewed

@@ -0,0 +1,174 @@
+import { Command } from 'commander';
+import { getServerStatus } from '../server.js';
+/**
+ * CLI command for dynamic MCP server tool operations via API.
+ *
+ * This command provides a simplified CLI interface for interacting with MCP server tools,
+ * supporting four actions: list-servers, list-tools, get-tool, and call-tool. It wraps
+ * the HTTP API endpoints and requires the MCP Hub Lite server to be running.
+ *
+ * ## Command Format
+ *
+ * ```
+ * mcp-tool-use <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * Or via npm:
+ * ```
+ * npm run tool-use <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * ## Supported Actions
+ *
+ * - `list-servers` - List all connected MCP servers
+ * - `list-tools` - List all tools from the specified server
+ * - `get-tool <toolName>` - Get complete schema for a specific tool
+ * - `call-tool <toolName>` - Call a tool on the specified server
+ *
+ * ## Options
+ *
+ * - `--args <json>` - JSON string of tool arguments (for call-tool action)
+ * - `--tags <json>` - JSON object of instance selection tags (call-tool only, for multi-instance servers)
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List all connected servers
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite list-servers
+ *
+ * # List all tools from a specific server
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite list-tools
+ *
+ * # Get tool schema
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite get-tool list_tools
+ *
+ * # Call a tool with arguments
+ * mcp-hub-lite mcp-tool-use mcp-hub-lite call-tool list_tools --args '{"serverName":"mcp-hub-lite"}'
+ *
+ * # Call a tool with tags for multi-instance selection
+ * mcp-hub-lite mcp-tool-use baidu-search call-tool search --args '{"query":"天气"}' --tags '{"env":"prod"}'
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Exits with code 1 if the server is not running
+ * - Exits with code 1 if action is unknown
+ * - Exits with code 1 if toolName is required but not provided
+ * - Exits with code 1 if JSON parsing fails for --args or --tags
+ * - Exits with code 1 if the underlying API call fails
+ *
+ * @returns {Command} The configured mcp-tool-use command instance for registration with Commander.js
+ */
+export const mcpToolUseCommand = new Command('tool-use')
+    .description('Manage MCP server tools via API (list-servers, list-tools, get-tool, call-tool)')
+    .argument('<serverName>', 'Server name to target (use "mcp-hub-lite" for system tools)')
+    .argument('<action>', 'Action: list-servers, list-tools, get-tool, call-tool')
+    .argument('[toolName]', 'Tool name (required for get-tool and call-tool actions)')
+    .option('--args <json>', 'JSON string of tool arguments (call-tool only)')
+    .option('--tags <json>', 'JSON object of instance selection tags (call-tool only, for multi-instance servers)')
+    .action(async (serverName, action, toolName, options) => {
+    try {
+        // Check if server is running and get connection info
+        const status = await getServerStatus();
+        if (!status.running) {
+            console.error('Error: MCP Hub Lite server is not running.');
+            console.error('Start the server with: mcp-hub-lite start');
+            process.exit(1);
+        }
+        const baseUrl = `http://${status.host}:${status.port}`;
+        switch (action) {
+            case 'list-servers': {
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers`, {
+                    headers: { Accept: 'application/json' }
+                });
+                if (!response.ok) {
+                    throw new Error(`API error: ${response.status} ${response.statusText}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'list-tools': {
+                const tagsParam = options.tags ? `?tags=${encodeURIComponent(options.tags)}` : '';
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools${tagsParam}`, {
+                    headers: { Accept: 'application/json' }
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'get-tool': {
+                if (!toolName) {
+                    console.error('Error: toolName is required for get-tool action');
+                    process.exit(1);
+                }
+                const tagsParam = options.tags ? `?tags=${encodeURIComponent(options.tags)}` : '';
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools/${toolName}${tagsParam}`, { headers: { Accept: 'application/json' } });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'call-tool': {
+                if (!toolName) {
+                    console.error('Error: toolName is required for call-tool action');
+                    process.exit(1);
+                }
+                // Parse tool arguments
+                let toolArgs = {};
+                if (options.args) {
+                    try {
+                        toolArgs = JSON.parse(options.args);
+                    }
+                    catch {
+                        console.error('Error: Invalid JSON in --args option');
+                        process.exit(1);
+                    }
+                }
+                // Parse tags for instance selection (call-tool only)
+                let requestOptions;
+                if (options.tags) {
+                    try {
+                        requestOptions = { tags: JSON.parse(options.tags) };
+                    }
+                    catch {
+                        console.error('Error: Invalid JSON in --tags option');
+                        process.exit(1);
+                    }
+                }
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools/${toolName}/call`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Accept: 'application/json'
+                    },
+                    body: JSON.stringify({ toolArgs, requestOptions })
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            default: {
+                console.error(`Unknown action: ${action}`);
+                console.error('Valid actions: list-servers, list-tools, get-tool, call-tool');
+                process.exit(1);
+            }
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});

package/dist/server/src/cli/commands/server.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+/**
+ * CLI command for dynamic MCP server tool operations via API.
+ *
+ * This command provides a simplified CLI interface for interacting with MCP server tools,
+ * supporting four actions: list-servers, list-tools, get-tool, and call-tool. It wraps
+ * the HTTP API endpoints and requires the MCP Hub Lite server to be running.
+ *
+ * ## Command Format
+ *
+ * ```
+ * npm run server <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * ## Supported Actions
+ *
+ * - `list-servers` - List all connected MCP servers
+ * - `list-tools` - List all tools from the specified server
+ * - `get-tool <toolName>` - Get complete schema for a specific tool
+ * - `call-tool <toolName>` - Call a tool on the specified server
+ *
+ * ## Options
+ *
+ * - `--args <json>` - JSON string of tool arguments (for call-tool action)
+ * - `--tags <json>` - JSON object of instance selection tags (call-tool only, for multi-instance servers)
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List all connected servers
+ * npm run server mcp-hub-lite list-servers
+ *
+ * # List all tools from a specific server
+ * npm run server mcp-hub-lite list-tools
+ *
+ * # Get tool schema
+ * npm run server mcp-hub-lite get-tool list_tools
+ *
+ * # Call a tool with arguments
+ * npm run server mcp-hub-lite call-tool list_tools --args '{"serverName":"mcp-hub-lite"}'
+ *
+ * # Call a tool with tags for multi-instance selection
+ * npm run server baidu-search call-tool search --args '{"query":"天气"}' --tags '{"env":"prod"}'
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Exits with code 1 if the server is not running
+ * - Exits with code 1 if action is unknown
+ * - Exits with code 1 if toolName is required but not provided
+ * - Exits with code 1 if JSON parsing fails for --args or --tags
+ * - Exits with code 1 if the underlying API call fails
+ *
+ * @returns {Command} The configured server command instance for registration with Commander.js
+ */
+export declare const serverCommand: Command;
+//# sourceMappingURL=server.d.ts.map

package/dist/server/src/cli/commands/server.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,aAAa,SAkItB,CAAC"}

package/dist/server/src/cli/commands/server.js ADDED Viewed

@@ -0,0 +1,169 @@
+import { Command } from 'commander';
+import { getServerStatus } from '../server.js';
+/**
+ * CLI command for dynamic MCP server tool operations via API.
+ *
+ * This command provides a simplified CLI interface for interacting with MCP server tools,
+ * supporting four actions: list-servers, list-tools, get-tool, and call-tool. It wraps
+ * the HTTP API endpoints and requires the MCP Hub Lite server to be running.
+ *
+ * ## Command Format
+ *
+ * ```
+ * npm run server <serverName> <action> [toolName] [--args <json>] [--tags <json>]
+ * ```
+ *
+ * ## Supported Actions
+ *
+ * - `list-servers` - List all connected MCP servers
+ * - `list-tools` - List all tools from the specified server
+ * - `get-tool <toolName>` - Get complete schema for a specific tool
+ * - `call-tool <toolName>` - Call a tool on the specified server
+ *
+ * ## Options
+ *
+ * - `--args <json>` - JSON string of tool arguments (for call-tool action)
+ * - `--tags <json>` - JSON object of instance selection tags (call-tool only, for multi-instance servers)
+ *
+ * ## Usage Examples
+ *
+ * ```bash
+ * # List all connected servers
+ * npm run server mcp-hub-lite list-servers
+ *
+ * # List all tools from a specific server
+ * npm run server mcp-hub-lite list-tools
+ *
+ * # Get tool schema
+ * npm run server mcp-hub-lite get-tool list_tools
+ *
+ * # Call a tool with arguments
+ * npm run server mcp-hub-lite call-tool list_tools --args '{"serverName":"mcp-hub-lite"}'
+ *
+ * # Call a tool with tags for multi-instance selection
+ * npm run server baidu-search call-tool search --args '{"query":"天气"}' --tags '{"env":"prod"}'
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Exits with code 1 if the server is not running
+ * - Exits with code 1 if action is unknown
+ * - Exits with code 1 if toolName is required but not provided
+ * - Exits with code 1 if JSON parsing fails for --args or --tags
+ * - Exits with code 1 if the underlying API call fails
+ *
+ * @returns {Command} The configured server command instance for registration with Commander.js
+ */
+export const serverCommand = new Command('server')
+    .description('Manage MCP server tools via API (list-servers, list-tools, get-tool, call-tool)')
+    .argument('<serverName>', 'Server name to target (use "mcp-hub-lite" for system tools)')
+    .argument('<action>', 'Action: list-servers, list-tools, get-tool, call-tool')
+    .argument('[toolName]', 'Tool name (required for get-tool and call-tool actions)')
+    .option('--args <json>', 'JSON string of tool arguments (call-tool only)')
+    .option('--tags <json>', 'JSON object of instance selection tags (call-tool only, for multi-instance servers)')
+    .action(async (serverName, action, toolName, options) => {
+    try {
+        // Check if server is running and get connection info
+        const status = await getServerStatus();
+        if (!status.running) {
+            console.error('Error: MCP Hub Lite server is not running.');
+            console.error('Start the server with: mcp-hub-lite start');
+            process.exit(1);
+        }
+        const baseUrl = `http://${status.host}:${status.port}`;
+        switch (action) {
+            case 'list-servers': {
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers`, {
+                    headers: { Accept: 'application/json' }
+                });
+                if (!response.ok) {
+                    throw new Error(`API error: ${response.status} ${response.statusText}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'list-tools': {
+                const tagsParam = options.tags ? `?tags=${encodeURIComponent(options.tags)}` : '';
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools${tagsParam}`, {
+                    headers: { Accept: 'application/json' }
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'get-tool': {
+                if (!toolName) {
+                    console.error('Error: toolName is required for get-tool action');
+                    process.exit(1);
+                }
+                const tagsParam = options.tags ? `?tags=${encodeURIComponent(options.tags)}` : '';
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools/${toolName}${tagsParam}`, { headers: { Accept: 'application/json' } });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'call-tool': {
+                if (!toolName) {
+                    console.error('Error: toolName is required for call-tool action');
+                    process.exit(1);
+                }
+                // Parse tool arguments
+                let toolArgs = {};
+                if (options.args) {
+                    try {
+                        toolArgs = JSON.parse(options.args);
+                    }
+                    catch {
+                        console.error('Error: Invalid JSON in --args option');
+                        process.exit(1);
+                    }
+                }
+                // Parse tags for instance selection (call-tool only)
+                let requestOptions;
+                if (options.tags) {
+                    try {
+                        requestOptions = { tags: JSON.parse(options.tags) };
+                    }
+                    catch {
+                        console.error('Error: Invalid JSON in --tags option');
+                        process.exit(1);
+                    }
+                }
+                const response = await fetch(`${baseUrl}/web/hub-tools/servers/${serverName}/tools/${toolName}/call`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Accept: 'application/json'
+                    },
+                    body: JSON.stringify({ toolArgs, requestOptions })
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ message: response.statusText }));
+                    throw new Error(error.message || `API error: ${response.status}`);
+                }
+                const result = await response.json();
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            default: {
+                console.error(`Unknown action: ${action}`);
+                console.error('Valid actions: list-servers, list-tools, get-tool, call-tool');
+                process.exit(1);
+            }
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});