@mcp-z/cli 1.0.0

package/dist/esm/commands/manifest/validate.js

@@ -0,0 +1,167 @@
+import * as fs from 'fs';
+import { isHttpServer, isStdioServer } from '../../types.js';
+import { MetadataReader } from './metadata-reader.js';
+const metadataReader = new MetadataReader();
+export async function validateCommand(filePath) {
+    // 1. Check file exists
+    if (!fs.existsSync(filePath)) {
+        throw Object.assign(new Error(`File not found: ${filePath}`), {
+            code: 1
+        });
+    }
+    // 2. JSON syntax validation
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        throw Object.assign(new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`), {
+            code: 1
+        });
+    }
+    // 3. Schema validation - check basic structure
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        throw Object.assign(new Error('Config must have "mcpServers" object'), {
+            code: 1
+        });
+    }
+    console.log(`✅ ${filePath} has valid JSON structure\n`);
+    console.log('Server Configuration Validation:\n');
+    // 4. Validate each server
+    let hasErrors = false;
+    let hasWarnings = false;
+    const servers = Object.entries(config.mcpServers);
+    if (servers.length === 0) {
+        console.log('  ⚠️  No servers configured');
+        return;
+    }
+    for (const [serverName, serverConfig] of servers){
+        const validation = await validateServerConfig(serverName, serverConfig);
+        if (validation.valid) {
+            console.log(`  ✅ ${serverName}: Valid configuration`);
+        } else if (validation.severity === 'error') {
+            console.log(`  ❌ ${serverName}: ${validation.message}`);
+            hasErrors = true;
+        } else {
+            console.log(`  ⚠️  ${serverName}: ${validation.message}`);
+            hasWarnings = true;
+        }
+    }
+    console.log('');
+    if (hasErrors) {
+        throw Object.assign(new Error('Validation failed with errors'), {
+            code: 1
+        });
+    }
+    if (hasWarnings) {
+        console.log('⚠️  Validation passed with warnings');
+    } else {
+        console.log('✅ All validations passed');
+    }
+}
+async function validateServerConfig(serverName, serverConfig) {
+    var _serverConfig_start, _serverConfig_start1;
+    // Check basic structure based on server type
+    if (isHttpServer(serverConfig)) {
+        // HTTP server validation
+        if (!serverConfig.url) {
+            return {
+                valid: false,
+                severity: 'error',
+                message: 'HTTP server missing required "url" field'
+            };
+        }
+        // If has start block, validate it
+        if (serverConfig.start) {
+            if (!serverConfig.start.command) {
+                return {
+                    valid: false,
+                    severity: 'error',
+                    message: 'HTTP server "start" block missing required "command" field'
+                };
+            }
+            if (serverConfig.start.args !== undefined && !Array.isArray(serverConfig.start.args)) {
+                return {
+                    valid: false,
+                    severity: 'error',
+                    message: 'HTTP server "start.args" field must be an array'
+                };
+            }
+        }
+    } else {
+        // Stdio server validation
+        if (!serverConfig.command) {
+            return {
+                valid: false,
+                severity: 'error',
+                message: 'Stdio server missing required "command" field'
+            };
+        }
+        if (serverConfig.args !== undefined && !Array.isArray(serverConfig.args)) {
+            return {
+                valid: false,
+                severity: 'error',
+                message: 'Stdio server "args" field must be an array'
+            };
+        }
+    }
+    // Try to load server metadata
+    let metadata;
+    try {
+        metadata = await metadataReader.readServerMetadata(serverName);
+    } catch (error) {
+        return {
+            valid: false,
+            severity: 'warning',
+            message: `Cannot verify: server package not found (${error instanceof Error ? error.message : String(error)})`
+        };
+    }
+    // Detect transport using type guard
+    const transport = isHttpServer(serverConfig) ? 'streamable-http' : 'stdio';
+    // Get package config from server.json
+    const pkg = metadataReader.getPackageForTransport(metadata, transport);
+    if (!pkg) {
+        return {
+            valid: false,
+            severity: 'error',
+            message: `No ${transport} transport configuration found in server.json`
+        };
+    }
+    // Determine which env to check based on server type
+    const envToCheck = isStdioServer(serverConfig) ? serverConfig.env : (_serverConfig_start = serverConfig.start) === null || _serverConfig_start === void 0 ? void 0 : _serverConfig_start.env;
+    // Check for missing required env vars (based on server.json)
+    const missingEnvVars = pkg.environmentVariables.filter((v)=>{
+        if (!v.isRequired) return false; // Skip optional vars
+        const envValue = envToCheck === null || envToCheck === void 0 ? void 0 : envToCheck[v.name];
+        // Consider it missing if it's not set or is a placeholder like ${VAR_NAME}
+        return !envValue || envValue.match(/^\$\{.*\}$/);
+    });
+    if (missingEnvVars.length > 0) {
+        const varNames = missingEnvVars.map((v)=>v.name).join(', ');
+        return {
+            valid: false,
+            severity: 'warning',
+            message: `Missing or placeholder required env vars: ${varNames}`
+        };
+    }
+    // Get args to validate based on server type
+    const argsToCheck = isStdioServer(serverConfig) ? serverConfig.args || [] : ((_serverConfig_start1 = serverConfig.start) === null || _serverConfig_start1 === void 0 ? void 0 : _serverConfig_start1.args) || [];
+    // Get valid args from server.json
+    const validArgNames = new Set(pkg.packageArguments.map((a)=>a.name));
+    // Check for unknown/outdated args
+    const unknownArgs = argsToCheck.filter((arg)=>{
+        if (!arg.startsWith('--')) return false; // Not a flag
+        const argName = arg.split('=')[0]; // Get just the flag name
+        if (!argName) return false; // Skip if somehow empty
+        return !validArgNames.has(argName);
+    });
+    if (unknownArgs.length > 0) {
+        return {
+            valid: false,
+            severity: 'warning',
+            message: `Unknown arguments: ${unknownArgs.join(', ')}. May be outdated - consider regenerating config.`
+        };
+    }
+    return {
+        valid: true
+    };
+}

package/dist/esm/commands/manifest/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/cli/src/commands/manifest/validate.ts"],"sourcesContent":["import * as fs from 'fs';\nimport type { MCPConfiguration, ServerConfig } from '../../types.ts';\nimport { isHttpServer, isStdioServer } from '../../types.ts';\nimport { MetadataReader, type ServerMetadata } from './metadata-reader.ts';\n\ninterface ValidationResult {\n  valid: boolean;\n  severity?: 'error' | 'warning';\n  message?: string;\n}\n\nconst metadataReader = new MetadataReader();\n\nexport async function validateCommand(filePath: string): Promise<void> {\n  // 1. Check file exists\n  if (!fs.existsSync(filePath)) {\n    throw Object.assign(new Error(`File not found: ${filePath}`), { code: 1 });\n  }\n\n  // 2. JSON syntax validation\n  let config: MCPConfiguration;\n  try {\n    config = JSON.parse(fs.readFileSync(filePath, 'utf8')) as MCPConfiguration;\n  } catch (error) {\n    throw Object.assign(new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`), {\n      code: 1,\n    });\n  }\n\n  // 3. Schema validation - check basic structure\n  if (!config.mcpServers || typeof config.mcpServers !== 'object') {\n    throw Object.assign(new Error('Config must have \"mcpServers\" object'), { code: 1 });\n  }\n\n  console.log(`✅ ${filePath} has valid JSON structure\\n`);\n  console.log('Server Configuration Validation:\\n');\n\n  // 4. Validate each server\n  let hasErrors = false;\n  let hasWarnings = false;\n\n  const servers = Object.entries(config.mcpServers);\n\n  if (servers.length === 0) {\n    console.log('  ⚠️  No servers configured');\n    return;\n  }\n\n  for (const [serverName, serverConfig] of servers) {\n    const validation = await validateServerConfig(serverName, serverConfig);\n\n    if (validation.valid) {\n      console.log(`  ✅ ${serverName}: Valid configuration`);\n    } else if (validation.severity === 'error') {\n      console.log(`  ❌ ${serverName}: ${validation.message}`);\n      hasErrors = true;\n    } else {\n      console.log(`  ⚠️  ${serverName}: ${validation.message}`);\n      hasWarnings = true;\n    }\n  }\n\n  console.log('');\n\n  if (hasErrors) {\n    throw Object.assign(new Error('Validation failed with errors'), { code: 1 });\n  }\n\n  if (hasWarnings) {\n    console.log('⚠️  Validation passed with warnings');\n  } else {\n    console.log('✅ All validations passed');\n  }\n}\n\nasync function validateServerConfig(serverName: string, serverConfig: ServerConfig): Promise<ValidationResult> {\n  // Check basic structure based on server type\n  if (isHttpServer(serverConfig)) {\n    // HTTP server validation\n    if (!serverConfig.url) {\n      return {\n        valid: false,\n        severity: 'error',\n        message: 'HTTP server missing required \"url\" field',\n      };\n    }\n    // If has start block, validate it\n    if (serverConfig.start) {\n      if (!serverConfig.start.command) {\n        return {\n          valid: false,\n          severity: 'error',\n          message: 'HTTP server \"start\" block missing required \"command\" field',\n        };\n      }\n      if (serverConfig.start.args !== undefined && !Array.isArray(serverConfig.start.args)) {\n        return {\n          valid: false,\n          severity: 'error',\n          message: 'HTTP server \"start.args\" field must be an array',\n        };\n      }\n    }\n  } else {\n    // Stdio server validation\n    if (!serverConfig.command) {\n      return {\n        valid: false,\n        severity: 'error',\n        message: 'Stdio server missing required \"command\" field',\n      };\n    }\n    if (serverConfig.args !== undefined && !Array.isArray(serverConfig.args)) {\n      return {\n        valid: false,\n        severity: 'error',\n        message: 'Stdio server \"args\" field must be an array',\n      };\n    }\n  }\n\n  // Try to load server metadata\n  let metadata: ServerMetadata;\n  try {\n    metadata = await metadataReader.readServerMetadata(serverName);\n  } catch (error) {\n    return {\n      valid: false,\n      severity: 'warning',\n      message: `Cannot verify: server package not found (${error instanceof Error ? error.message : String(error)})`,\n    };\n  }\n\n  // Detect transport using type guard\n  const transport = isHttpServer(serverConfig) ? 'streamable-http' : 'stdio';\n\n  // Get package config from server.json\n  const pkg = metadataReader.getPackageForTransport(metadata, transport as 'stdio' | 'streamable-http');\n  if (!pkg) {\n    return {\n      valid: false,\n      severity: 'error',\n      message: `No ${transport} transport configuration found in server.json`,\n    };\n  }\n\n  // Determine which env to check based on server type\n  const envToCheck = isStdioServer(serverConfig) ? serverConfig.env : serverConfig.start?.env;\n\n  // Check for missing required env vars (based on server.json)\n  const missingEnvVars = pkg.environmentVariables.filter((v) => {\n    if (!v.isRequired) return false; // Skip optional vars\n    const envValue = envToCheck?.[v.name];\n    // Consider it missing if it's not set or is a placeholder like ${VAR_NAME}\n    return !envValue || envValue.match(/^\\$\\{.*\\}$/);\n  });\n\n  if (missingEnvVars.length > 0) {\n    const varNames = missingEnvVars.map((v) => v.name).join(', ');\n    return {\n      valid: false,\n      severity: 'warning',\n      message: `Missing or placeholder required env vars: ${varNames}`,\n    };\n  }\n\n  // Get args to validate based on server type\n  const argsToCheck = isStdioServer(serverConfig) ? serverConfig.args || [] : serverConfig.start?.args || [];\n\n  // Get valid args from server.json\n  const validArgNames = new Set(pkg.packageArguments.map((a) => a.name));\n\n  // Check for unknown/outdated args\n  const unknownArgs = argsToCheck.filter((arg: string) => {\n    if (!arg.startsWith('--')) return false; // Not a flag\n    const argName = arg.split('=')[0]; // Get just the flag name\n    if (!argName) return false; // Skip if somehow empty\n    return !validArgNames.has(argName);\n  });\n\n  if (unknownArgs.length > 0) {\n    return {\n      valid: false,\n      severity: 'warning',\n      message: `Unknown arguments: ${unknownArgs.join(', ')}. May be outdated - consider regenerating config.`,\n    };\n  }\n\n  return { valid: true };\n}\n"],"names":["fs","isHttpServer","isStdioServer","MetadataReader","metadataReader","validateCommand","filePath","existsSync","Object","assign","Error","code","config","JSON","parse","readFileSync","error","message","String","mcpServers","console","log","hasErrors","hasWarnings","servers","entries","length","serverName","serverConfig","validation","validateServerConfig","valid","severity","url","start","command","args","undefined","Array","isArray","metadata","readServerMetadata","transport","pkg","getPackageForTransport","envToCheck","env","missingEnvVars","environmentVariables","filter","v","isRequired","envValue","name","match","varNames","map","join","argsToCheck","validArgNames","Set","packageArguments","a","unknownArgs","arg","startsWith","argName","split","has"],"mappings":"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"}

package/dist/esm/commands/read-resource.d.ts

@@ -0,0 +1,24 @@
+/**
+ * read-resource.ts
+ *
+ * Read MCP resources from the command line.
+ * Supports stdio (spawned) and http (remote) servers per MCP spec.
+ */
+import { type InlineConfigOptions } from '../lib/resolve-server-config.js';
+export interface ReadResourceOptions extends InlineConfigOptions {
+    uri: string;
+    json?: boolean;
+}
+/**
+ * Main read-resource command implementation.
+ *
+ * @param opts - Read resource options from CLI flags
+ *
+ * @example
+ * // Read a resource by URI
+ * await readResourceCommand({
+ *   server: 'gmail',
+ *   uri: 'gmail://messages/abc123',
+ * });
+ */
+export declare function readResourceCommand(opts: ReadResourceOptions): Promise<void>;

package/dist/esm/commands/read-resource.js

@@ -0,0 +1,95 @@
+/**
+ * read-resource.ts
+ *
+ * Read MCP resources from the command line.
+ * Supports stdio (spawned) and http (remote) servers per MCP spec.
+ */ import { createServerRegistry } from '@mcp-z/client';
+import { resolveServerConfig } from '../lib/resolve-server-config.js';
+import { isHttpServer } from '../types.js';
+/**
+ * Main read-resource command implementation.
+ *
+ * @param opts - Read resource options from CLI flags
+ *
+ * @example
+ * // Read a resource by URI
+ * await readResourceCommand({
+ *   server: 'gmail',
+ *   uri: 'gmail://messages/abc123',
+ * });
+ */ export async function readResourceCommand(opts) {
+    let registry;
+    let client;
+    try {
+        // 1. Resolve server configuration (from config file or inline options)
+        const { serverName, serverConfig, configDir } = resolveServerConfig(opts);
+        // 2. Create registry and connect
+        const start = Date.now();
+        if (isHttpServer(serverConfig)) {
+            // HTTP server - no spawning needed
+            if (!opts.json) {
+                console.log(`🔗 Connecting to ${serverName}...`);
+            }
+        } else {
+            // Stdio server - will be spawned
+            if (!opts.json) {
+                console.log(`🚀 Spawning ${serverName} server...`);
+            }
+            if (!serverConfig.command) {
+                throw new Error(`Stdio server ${serverName} missing required "command" field`);
+            }
+        }
+        // Create registry (spawns stdio servers, registers HTTP servers)
+        registry = createServerRegistry({
+            [serverName]: serverConfig
+        }, {
+            cwd: configDir
+        });
+        client = await registry.connect(serverName);
+        if (!isHttpServer(serverConfig) && !opts.json) {
+            const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+            console.log(`✓ Server ready in ${elapsed}s\n`);
+        }
+        // 5. Read resource
+        if (!opts.json) {
+            console.log(`📖 Reading ${opts.uri}...`);
+        }
+        const resourceResponse = await client.readResource(opts.uri);
+        const resource = resourceResponse.raw();
+        // Success case
+        if (opts.json) {
+            // JSON output mode
+            console.log(JSON.stringify(resource, null, 2));
+        } else {
+            // Human-readable output
+            console.log('✅ Read succeeded\n');
+            // Display contents
+            for (const content of resource.contents){
+                if ('text' in content) {
+                    console.log('Content:');
+                    console.log(content.text);
+                } else if ('blob' in content) {
+                    console.log(`Blob content (${content.mimeType || 'unknown type'}): ${content.blob.length} bytes`);
+                }
+            }
+        }
+    } catch (error) {
+        if (opts.json) {
+            console.log(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error)
+            }, null, 2));
+        } else {
+            console.error(`\n❌ ${error instanceof Error ? error.message : String(error)}`);
+        }
+        throw error;
+    } finally{
+        // 7. Cleanup - registry.close() handles both client and server close
+        if (registry) {
+            try {
+                await registry.close();
+            } catch (_) {
+            // Ignore close errors
+            }
+        }
+    }
+}

package/dist/esm/commands/read-resource.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/cli/src/commands/read-resource.ts"],"sourcesContent":["/**\n * read-resource.ts\n *\n * Read MCP resources from the command line.\n * Supports stdio (spawned) and http (remote) servers per MCP spec.\n */\n\nimport { createServerRegistry, type ManagedClient, type ServerRegistry } from '@mcp-z/client';\nimport { type InlineConfigOptions, resolveServerConfig } from '../lib/resolve-server-config.ts';\nimport { isHttpServer } from '../types.ts';\n\nexport interface ReadResourceOptions extends InlineConfigOptions {\n  uri: string; // Resource URI (positional)\n  json?: boolean; // --json\n}\n\n/**\n * Main read-resource command implementation.\n *\n * @param opts - Read resource options from CLI flags\n *\n * @example\n * // Read a resource by URI\n * await readResourceCommand({\n *   server: 'gmail',\n *   uri: 'gmail://messages/abc123',\n * });\n */\nexport async function readResourceCommand(opts: ReadResourceOptions): Promise<void> {\n  let registry: ServerRegistry | undefined;\n  let client: ManagedClient | undefined;\n\n  try {\n    // 1. Resolve server configuration (from config file or inline options)\n    const { serverName, serverConfig, configDir } = resolveServerConfig(opts);\n\n    // 2. Create registry and connect\n    const start = Date.now();\n\n    if (isHttpServer(serverConfig)) {\n      // HTTP server - no spawning needed\n      if (!opts.json) {\n        console.log(`🔗 Connecting to ${serverName}...`);\n      }\n    } else {\n      // Stdio server - will be spawned\n      if (!opts.json) {\n        console.log(`🚀 Spawning ${serverName} server...`);\n      }\n\n      if (!serverConfig.command) {\n        throw new Error(`Stdio server ${serverName} missing required \"command\" field`);\n      }\n    }\n\n    // Create registry (spawns stdio servers, registers HTTP servers)\n    registry = createServerRegistry({ [serverName]: serverConfig }, { cwd: configDir });\n    client = await registry.connect(serverName);\n\n    if (!isHttpServer(serverConfig) && !opts.json) {\n      const elapsed = ((Date.now() - start) / 1000).toFixed(1);\n      console.log(`✓ Server ready in ${elapsed}s\\n`);\n    }\n\n    // 5. Read resource\n    if (!opts.json) {\n      console.log(`📖 Reading ${opts.uri}...`);\n    }\n\n    const resourceResponse = await client.readResource(opts.uri);\n    const resource = resourceResponse.raw();\n\n    // Success case\n    if (opts.json) {\n      // JSON output mode\n      console.log(JSON.stringify(resource, null, 2));\n    } else {\n      // Human-readable output\n      console.log('✅ Read succeeded\\n');\n\n      // Display contents\n      for (const content of resource.contents) {\n        if ('text' in content) {\n          console.log('Content:');\n          console.log(content.text);\n        } else if ('blob' in content) {\n          console.log(`Blob content (${content.mimeType || 'unknown type'}): ${content.blob.length} bytes`);\n        }\n      }\n    }\n  } catch (error) {\n    if (opts.json) {\n      console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2));\n    } else {\n      console.error(`\\n❌ ${error instanceof Error ? error.message : String(error)}`);\n    }\n    throw error;\n  } finally {\n    // 7. Cleanup - registry.close() handles both client and server close\n    if (registry) {\n      try {\n        await registry.close();\n      } catch (_) {\n        // Ignore close errors\n      }\n    }\n  }\n}\n"],"names":["createServerRegistry","resolveServerConfig","isHttpServer","readResourceCommand","opts","registry","client","serverName","serverConfig","configDir","start","Date","now","json","console","log","command","Error","cwd","connect","elapsed","toFixed","uri","resourceResponse","readResource","resource","raw","JSON","stringify","content","contents","text","mimeType","blob","length","error","message","String","close","_"],"mappings":"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"}

package/dist/esm/commands/search.d.ts

@@ -0,0 +1,31 @@
+/**
+ * search.ts
+ *
+ * Search MCP server capabilities (tools, prompts, resources) without loading full schemas.
+ * Designed for agent discovery workflows.
+ */
+export interface SearchCommandOptions {
+    config?: string;
+    servers?: string;
+    types?: string;
+    fields?: string;
+    limit?: number;
+    threshold?: number;
+    json?: boolean;
+    attach?: boolean;
+}
+/**
+ * Main search command implementation.
+ *
+ * @param query - The search query string
+ * @param opts - Search options from CLI flags
+ *
+ * @example
+ * // Search for email-related capabilities
+ * await searchCommand('send email', {});
+ *
+ * @example
+ * // Search only tools in specific servers
+ * await searchCommand('spreadsheet', { types: 'tool', servers: 'sheets,drive' });
+ */
+export declare function searchCommand(query: string, opts?: SearchCommandOptions): Promise<void>;

package/dist/esm/commands/search.js

@@ -0,0 +1,145 @@
+/**
+ * search.ts
+ *
+ * Search MCP server capabilities (tools, prompts, resources) without loading full schemas.
+ * Designed for agent discovery workflows.
+ */ import { createServerRegistry } from '@mcp-z/client';
+import * as fs from 'fs';
+import * as path from 'path';
+import { findConfigPath } from '../lib/find-config.js';
+/**
+ * Main search command implementation.
+ *
+ * @param query - The search query string
+ * @param opts - Search options from CLI flags
+ *
+ * @example
+ * // Search for email-related capabilities
+ * await searchCommand('send email', {});
+ *
+ * @example
+ * // Search only tools in specific servers
+ * await searchCommand('spreadsheet', { types: 'tool', servers: 'sheets,drive' });
+ */ export async function searchCommand(query, opts = {}) {
+    let registry;
+    try {
+        var _ref, _raw_mcpServers, _opts_limit, _opts_threshold, _searchOptions_servers;
+        const configPath = findConfigPath(opts.config);
+        const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const servers = (_ref = (_raw_mcpServers = raw.mcpServers) !== null && _raw_mcpServers !== void 0 ? _raw_mcpServers : raw.servers) !== null && _ref !== void 0 ? _ref : raw;
+        const configDir = path.dirname(configPath);
+        // Parse options
+        const searchOptions = {
+            types: parseTypes(opts.types),
+            servers: parseServers(opts.servers),
+            searchFields: parseFields(opts.fields),
+            limit: (_opts_limit = opts.limit) !== null && _opts_limit !== void 0 ? _opts_limit : 20,
+            threshold: (_opts_threshold = opts.threshold) !== null && _opts_threshold !== void 0 ? _opts_threshold : 0
+        };
+        // Create registry (spawns stdio servers, registers HTTP servers)
+        // In attach mode, don't spawn - just register for connection
+        registry = createServerRegistry(servers, {
+            cwd: configDir,
+            dialects: opts.attach ? [] : [
+                'servers',
+                'start'
+            ]
+        });
+        // Connect to all servers (or filtered subset)
+        const serverNames = (_searchOptions_servers = searchOptions.servers) !== null && _searchOptions_servers !== void 0 ? _searchOptions_servers : Object.keys(servers || {});
+        for (const serverName of serverNames){
+            try {
+                await registry.connect(serverName);
+            } catch (error) {
+                // Log connection errors but continue with other servers
+                if (!opts.json) {
+                    console.error(`⚠ Failed to connect to ${serverName}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        // Search across connected clients
+        const response = await registry.searchCapabilities(query, searchOptions);
+        // Output results
+        if (opts.json) {
+            outputJSON(response);
+        } else {
+            outputPretty(response);
+        }
+    } finally{
+        // Cleanup - registry.close() handles all clients and servers
+        if (registry) {
+            try {
+                await registry.close();
+            } catch (_) {
+            // Ignore close errors
+            }
+        }
+    }
+}
+/**
+ * Parse comma-separated types into CapabilityType array
+ */ function parseTypes(typesStr) {
+    if (!typesStr) return undefined;
+    const validTypes = [
+        'tool',
+        'prompt',
+        'resource'
+    ];
+    const parsed = typesStr.split(',').map((t)=>t.trim().toLowerCase());
+    const invalid = parsed.filter((t)=>!validTypes.includes(t));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid types: ${invalid.join(', ')}. Valid types: ${validTypes.join(', ')}`);
+    }
+    return parsed;
+}
+/**
+ * Parse comma-separated server names
+ */ function parseServers(serversStr) {
+    if (!serversStr) return undefined;
+    return serversStr.split(',').map((s)=>s.trim());
+}
+/**
+ * Parse comma-separated search fields
+ */ function parseFields(fieldsStr) {
+    if (!fieldsStr) return undefined;
+    const validFields = [
+        'name',
+        'description',
+        'schema',
+        'server'
+    ];
+    const parsed = fieldsStr.split(',').map((f)=>f.trim().toLowerCase());
+    const invalid = parsed.filter((f)=>!validFields.includes(f));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid fields: ${invalid.join(', ')}. Valid fields: ${validFields.join(', ')}`);
+    }
+    return parsed;
+}
+/**
+ * Output results as JSON
+ */ function outputJSON(response) {
+    console.log(JSON.stringify(response, null, 2));
+}
+/**
+ * Output results in human-readable format
+ */ function outputPretty(response) {
+    if (response.results.length === 0) {
+        console.log(`No results found for "${response.query}"`);
+        return;
+    }
+    console.log(`Found ${response.total} result${response.total !== 1 ? 's' : ''} for "${response.query}"${response.total > response.results.length ? ` (showing ${response.results.length})` : ''}:\n`);
+    for (const result of response.results){
+        const typeIcon = result.type === 'tool' ? '🔧' : result.type === 'prompt' ? '💬' : '📄';
+        const score = (result.score * 100).toFixed(0);
+        console.log(`${typeIcon} ${result.name} [${result.type}] (${score}%)`);
+        console.log(`   Server: ${result.server}`);
+        if (result.description) {
+            const desc = result.description.length > 100 ? `${result.description.slice(0, 97)}...` : result.description;
+            console.log(`   ${desc}`);
+        }
+        if (result.matchedOn.length > 0) {
+            console.log(`   Matched: ${result.matchedOn.join(', ')}`);
+        }
+        console.log('');
+    }
+}

package/dist/esm/commands/search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/cli/src/commands/search.ts"],"sourcesContent":["/**\n * search.ts\n *\n * Search MCP server capabilities (tools, prompts, resources) without loading full schemas.\n * Designed for agent discovery workflows.\n */\n\nimport { type CapabilityType, createServerRegistry, type SearchField, type SearchOptions, type SearchResponse, type ServerRegistry } from '@mcp-z/client';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { findConfigPath } from '../lib/find-config.ts';\n\nexport interface SearchCommandOptions {\n  config?: string;\n  servers?: string;\n  types?: string;\n  fields?: string;\n  limit?: number;\n  threshold?: number;\n  json?: boolean;\n  attach?: boolean;\n}\n\n/**\n * Main search command implementation.\n *\n * @param query - The search query string\n * @param opts - Search options from CLI flags\n *\n * @example\n * // Search for email-related capabilities\n * await searchCommand('send email', {});\n *\n * @example\n * // Search only tools in specific servers\n * await searchCommand('spreadsheet', { types: 'tool', servers: 'sheets,drive' });\n */\nexport async function searchCommand(query: string, opts: SearchCommandOptions = {}): Promise<void> {\n  let registry: ServerRegistry | undefined;\n\n  try {\n    const configPath = findConfigPath(opts.config);\n    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));\n    const servers = raw.mcpServers ?? raw.servers ?? raw;\n    const configDir = path.dirname(configPath);\n\n    // Parse options\n    const searchOptions: SearchOptions = {\n      types: parseTypes(opts.types),\n      servers: parseServers(opts.servers),\n      searchFields: parseFields(opts.fields),\n      limit: opts.limit ?? 20,\n      threshold: opts.threshold ?? 0,\n    };\n\n    // Create registry (spawns stdio servers, registers HTTP servers)\n    // In attach mode, don't spawn - just register for connection\n    registry = createServerRegistry(servers, {\n      cwd: configDir,\n      dialects: opts.attach ? [] : ['servers', 'start'], // Empty dialects = no spawning\n    });\n\n    // Connect to all servers (or filtered subset)\n    const serverNames = searchOptions.servers ?? Object.keys(servers || {});\n\n    for (const serverName of serverNames) {\n      try {\n        await registry.connect(serverName);\n      } catch (error) {\n        // Log connection errors but continue with other servers\n        if (!opts.json) {\n          console.error(`⚠ Failed to connect to ${serverName}: ${error instanceof Error ? error.message : String(error)}`);\n        }\n      }\n    }\n\n    // Search across connected clients\n    const response = await registry.searchCapabilities(query, searchOptions);\n\n    // Output results\n    if (opts.json) {\n      outputJSON(response);\n    } else {\n      outputPretty(response);\n    }\n  } finally {\n    // Cleanup - registry.close() handles all clients and servers\n    if (registry) {\n      try {\n        await registry.close();\n      } catch (_) {\n        // Ignore close errors\n      }\n    }\n  }\n}\n\n/**\n * Parse comma-separated types into CapabilityType array\n */\nfunction parseTypes(typesStr?: string): CapabilityType[] | undefined {\n  if (!typesStr) return undefined;\n\n  const validTypes: CapabilityType[] = ['tool', 'prompt', 'resource'];\n  const parsed = typesStr.split(',').map((t) => t.trim().toLowerCase()) as CapabilityType[];\n\n  const invalid = parsed.filter((t) => !validTypes.includes(t));\n  if (invalid.length > 0) {\n    throw new Error(`Invalid types: ${invalid.join(', ')}. Valid types: ${validTypes.join(', ')}`);\n  }\n\n  return parsed;\n}\n\n/**\n * Parse comma-separated server names\n */\nfunction parseServers(serversStr?: string): string[] | undefined {\n  if (!serversStr) return undefined;\n  return serversStr.split(',').map((s) => s.trim());\n}\n\n/**\n * Parse comma-separated search fields\n */\nfunction parseFields(fieldsStr?: string): SearchField[] | undefined {\n  if (!fieldsStr) return undefined;\n\n  const validFields: SearchField[] = ['name', 'description', 'schema', 'server'];\n  const parsed = fieldsStr.split(',').map((f) => f.trim().toLowerCase()) as SearchField[];\n\n  const invalid = parsed.filter((f) => !validFields.includes(f));\n  if (invalid.length > 0) {\n    throw new Error(`Invalid fields: ${invalid.join(', ')}. Valid fields: ${validFields.join(', ')}`);\n  }\n\n  return parsed;\n}\n\n/**\n * Output results as JSON\n */\nfunction outputJSON(response: SearchResponse): void {\n  console.log(JSON.stringify(response, null, 2));\n}\n\n/**\n * Output results in human-readable format\n */\nfunction outputPretty(response: SearchResponse): void {\n  if (response.results.length === 0) {\n    console.log(`No results found for \"${response.query}\"`);\n    return;\n  }\n\n  console.log(`Found ${response.total} result${response.total !== 1 ? 's' : ''} for \"${response.query}\"${response.total > response.results.length ? ` (showing ${response.results.length})` : ''}:\\n`);\n\n  for (const result of response.results) {\n    const typeIcon = result.type === 'tool' ? '🔧' : result.type === 'prompt' ? '💬' : '📄';\n    const score = (result.score * 100).toFixed(0);\n\n    console.log(`${typeIcon} ${result.name} [${result.type}] (${score}%)`);\n    console.log(`   Server: ${result.server}`);\n\n    if (result.description) {\n      const desc = result.description.length > 100 ? `${result.description.slice(0, 97)}...` : result.description;\n      console.log(`   ${desc}`);\n    }\n\n    if (result.matchedOn.length > 0) {\n      console.log(`   Matched: ${result.matchedOn.join(', ')}`);\n    }\n\n    console.log('');\n  }\n}\n"],"names":["createServerRegistry","fs","path","findConfigPath","searchCommand","query","opts","registry","raw","searchOptions","configPath","config","JSON","parse","readFileSync","servers","mcpServers","configDir","dirname","types","parseTypes","parseServers","searchFields","parseFields","fields","limit","threshold","cwd","dialects","attach","serverNames","Object","keys","serverName","connect","error","json","console","Error","message","String","response","searchCapabilities","outputJSON","outputPretty","close","_","typesStr","undefined","validTypes","parsed","split","map","t","trim","toLowerCase","invalid","filter","includes","length","join","serversStr","s","fieldsStr","validFields","f","log","stringify","results","total","result","typeIcon","type","score","toFixed","name","server","description","desc","slice","matchedOn"],"mappings":"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"}

package/dist/esm/commands/up.d.ts

@@ -0,0 +1,49 @@
+import { type ServerRegistry } from '@mcp-z/client';
+/**
+ * Configuration options for the upCommand function
+ * @public
+ */
+export interface UpOptions {
+    /** Optional path to custom .mcp.json configuration file */
+    config?: string;
+    /** Start only stdio servers (Claude Code compatible mode) */
+    stdioOnly?: boolean;
+    /** Start only HTTP servers with start blocks (for Claude Code Desktop) */
+    httpOnly?: boolean;
+}
+/**
+ * MCP server configuration entry per MCP specification.
+ *
+ * Supports two transport types:
+ * - stdio (default if no type): spawned process with stdin/stdout
+ * - http: remote HTTP server
+ *
+ * Transport can be inferred from URL protocol:
+ * - http:// or https:// → http
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
+ */
+/**
+ * Start a cluster of MCP servers from a configuration file or object.
+ *
+ * @param opts - Configuration options
+ * @param opts.config - Optional path to custom .mcp.json file
+ * @returns ServerRegistry with servers map, config, connect method, and close function
+ *
+ * @example
+ * // Auto-discover .mcp.json in current directory
+ * const registry = await upCommand();
+ *
+ * @example
+ * // Load from specific config
+ * const registry = await upCommand({ config: '/path/to/.mcp.json' });
+ *
+ * @example
+ * // Use in-memory config
+ * const registry = await upCommand({
+ *   mcpServers: {
+ *     'echo-stdio': { command: 'node', args: ['test/lib/servers/echo-stdio.ts'] }
+ *   }
+ * });
+ */
+export declare function upCommand(opts?: UpOptions): Promise<ServerRegistry>;

package/dist/esm/commands/up.js

@@ -0,0 +1,74 @@
+import { createServerRegistry } from '@mcp-z/client';
+import * as fs from 'fs';
+import * as path from 'path';
+import { findConfigPath } from '../lib/find-config.js';
+import { hasStartBlock } from '../types.js';
+/**
+ * MCP server configuration entry per MCP specification.
+ *
+ * Supports two transport types:
+ * - stdio (default if no type): spawned process with stdin/stdout
+ * - http: remote HTTP server
+ *
+ * Transport can be inferred from URL protocol:
+ * - http:// or https:// → http
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
+ */ /**
+ * Start a cluster of MCP servers from a configuration file or object.
+ *
+ * @param opts - Configuration options
+ * @param opts.config - Optional path to custom .mcp.json file
+ * @returns ServerRegistry with servers map, config, connect method, and close function
+ *
+ * @example
+ * // Auto-discover .mcp.json in current directory
+ * const registry = await upCommand();
+ *
+ * @example
+ * // Load from specific config
+ * const registry = await upCommand({ config: '/path/to/.mcp.json' });
+ *
+ * @example
+ * // Use in-memory config
+ * const registry = await upCommand({
+ *   mcpServers: {
+ *     'echo-stdio': { command: 'node', args: ['test/lib/servers/echo-stdio.ts'] }
+ *   }
+ * });
+ */ export async function upCommand(opts = {}) {
+    var _ref, _raw_mcpServers;
+    const configPath = findConfigPath(opts.config);
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const servers = (_ref = (_raw_mcpServers = raw.mcpServers) !== null && _raw_mcpServers !== void 0 ? _raw_mcpServers : raw.servers) !== null && _ref !== void 0 ? _ref : raw;
+    const configDir = path.dirname(configPath);
+    // Determine dialects based on flags
+    // Default is ['servers', 'start'] (spawns everything)
+    let dialects = [
+        'servers',
+        'start'
+    ];
+    if (opts.stdioOnly) {
+        dialects = [
+            'servers'
+        ];
+    } else if (opts.httpOnly) {
+        dialects = [
+            'start'
+        ];
+        // In http-only mode, check if there are any servers with start blocks
+        const hasStartBlocks = Object.values(servers || {}).some((entry)=>entry && hasStartBlock(entry));
+        if (!hasStartBlocks) {
+            console.log('  No HTTP servers found with start configuration');
+            console.log('  (stdio servers are spawned automatically by Claude Code)');
+            // Return empty registry
+            return createServerRegistry({}, {
+                cwd: configDir
+            });
+        }
+    }
+    return createServerRegistry(servers, {
+        cwd: configDir,
+        dialects
+    });
+}