MCP Troubleshooter

Implementation Reference

• src/index.ts:374-513 (handler)

  Complete tool registration and handler implementation for 'validate-mcp-server-config'. The handler reads claude_desktop_config.json, parses MCP servers section, validates each server's command (checks if in PATH using 'which' or 'where'), ensures 'args' is array and flags relative paths, checks 'env' is object, and generates a markdown validation report listing valid/invalid servers with issues.

  server.tool(
    "validate-mcp-server-config",
    {
      serverName: z.string().optional().describe("Specific server configuration to validate")
    },
    async ({ serverName }) => {
      try {
        try {
          await fs.access(configPath);
        } catch (error) {
          return {
            content: [{ type: "text", text: `Configuration file not found at ${configPath}.` }]
          };
        }
  
        const configContent = await fs.readFile(configPath, 'utf-8');
        
        try {
          const configObject = JSON.parse(configContent);
          
          if (!configObject.mcpServers) {
            return {
              content: [{ type: "text", text: "Configuration file does not contain an 'mcpServers' section." }]
            };
          }
          
          const servers = configObject.mcpServers;
          const serverNames = Object.keys(servers);
          
          if (serverNames.length === 0) {
            return {
              content: [{ type: "text", text: "No MCP servers are configured." }]
            };
          }
          
          // If a specific server is requested, only validate that one
          const targetsToValidate = serverName ? 
            (serverNames.includes(serverName) ? [serverName] : []) : 
            serverNames;
            
          if (serverName && targetsToValidate.length === 0) {
            return {
              content: [{ type: "text", text: `Server '${serverName}' not found in configuration.` }]
            };
          }
          
          // Validate each server configuration
          let validationResults = [];
          
          for (const name of targetsToValidate) {
            const serverConfig = servers[name];
            let issues = [];
            
            // Check command exists
            if (!serverConfig.command) {
              issues.push("Missing 'command' field");
            } else {
              // Try to find the command in PATH
              try {
                await execAsync(`which ${serverConfig.command}`);
              } catch (error) {
                try {
                  await execAsync(`where ${serverConfig.command}`);
                } catch (error2) {
                  issues.push(`Command '${serverConfig.command}' not found in PATH`);
                }
              }
            }
            
            // Check args
            if (!serverConfig.args) {
              issues.push("Missing 'args' field");
            } else if (!Array.isArray(serverConfig.args)) {
              issues.push("'args' field must be an array");
            }
            
            // Check for relative paths in args that might cause issues
            if (Array.isArray(serverConfig.args)) {
              const relativePathArgs = serverConfig.args.filter(arg => 
                typeof arg === 'string' && 
                arg.includes('/') && 
                !arg.startsWith('/') && 
                !arg.includes(':/')
              );
              
              if (relativePathArgs.length > 0) {
                issues.push(`Potential relative path issues in args: ${relativePathArgs.join(', ')}`);
              }
            }
            
            // Check env vars if present
            if (serverConfig.env && typeof serverConfig.env !== 'object') {
              issues.push("'env' field must be an object");
            }
            
            // Add validation result
            validationResults.push({
              server: name,
              config: serverConfig,
              valid: issues.length === 0,
              issues: issues
            });
          }
          
          // Format the results
          let validationReport = "# MCP Server Configuration Validation\n\n";
          
          for (const result of validationResults) {
            validationReport += `## ${result.server}\n\n`;
            validationReport += `Status: ${result.valid ? '✅ Valid' : '❌ Invalid'}\n\n`;
            
            if (!result.valid) {
              validationReport += "Issues:\n";
              for (const issue of result.issues) {
                validationReport += `- ${issue}\n`;
              }
              validationReport += "\n";
            }
            
            validationReport += `Configuration:\n\`\`\`json\n${JSON.stringify(result.config, null, 2)}\n\`\`\`\n\n`;
          }
          
          return {
            content: [{ type: "text", text: validationReport }]
          };
          
        } catch (error) {
          return {
            isError: true,
            content: [{ type: "text", text: `Error parsing configuration: ${error.message}` }]
          };
        }
      } catch (error) {
        return {
          isError: true,
          content: [{ type: "text", text: `Error validating configuration: ${error.message}` }]
        };
      }
    }
  );

• src/index.ts:376-377 (schema)

  Input schema using Zod: optional serverName string to validate specific server.

  {
    serverName: z.string().optional().describe("Specific server configuration to validate")

• src/index.ts:374-375 (registration)

  Registration of the tool via server.tool() call.

  server.tool(
    "validate-mcp-server-config",