mcp-doctor 0.1.0

package/src/config/locations.ts

@@ -0,0 +1,141 @@
+import { homedir, platform } from 'os';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { ConfigLocation } from './types.js';
+
+export function getConfigLocations(projectDir?: string): ConfigLocation[] {
+  const home = homedir();
+  const os = platform();
+  const cwd = projectDir || process.cwd();
+
+  const locations: Array<Omit<ConfigLocation, 'exists'>> = [];
+
+  // ============================================
+  // Claude Desktop
+  // ============================================
+  if (os === 'darwin') {
+    locations.push({
+      client: 'Claude Desktop',
+      scope: 'global',
+      path: join(home, 'Library/Application Support/Claude/claude_desktop_config.json'),
+    });
+  } else if (os === 'win32') {
+    locations.push({
+      client: 'Claude Desktop',
+      scope: 'global',
+      path: join(process.env.APPDATA || join(home, 'AppData/Roaming'), 'Claude/claude_desktop_config.json'),
+    });
+  } else {
+    // Linux
+    locations.push({
+      client: 'Claude Desktop',
+      scope: 'global',
+      path: join(home, '.config/claude/claude_desktop_config.json'),
+    });
+  }
+
+  // ============================================
+  // Claude Code
+  // ============================================
+  locations.push({
+    client: 'Claude Code',
+    scope: 'global',
+    path: join(home, '.claude.json'),
+  });
+  locations.push({
+    client: 'Claude Code',
+    scope: 'project',
+    path: join(cwd, '.mcp.json'),
+  });
+
+  // ============================================
+  // Cursor
+  // ============================================
+  if (os === 'darwin') {
+    locations.push({
+      client: 'Cursor',
+      scope: 'global',
+      path: join(home, 'Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json'),
+    });
+  } else if (os === 'win32') {
+    locations.push({
+      client: 'Cursor',
+      scope: 'global',
+      path: join(process.env.APPDATA || join(home, 'AppData/Roaming'), 'Cursor/User/globalStorage/cursor.mcp/mcp.json'),
+    });
+  } else {
+    locations.push({
+      client: 'Cursor',
+      scope: 'global',
+      path: join(home, '.config/Cursor/User/globalStorage/cursor.mcp/mcp.json'),
+    });
+  }
+  // Also check older Cursor location
+  locations.push({
+    client: 'Cursor',
+    scope: 'global',
+    path: join(home, '.cursor/mcp.json'),
+  });
+  locations.push({
+    client: 'Cursor',
+    scope: 'project',
+    path: join(cwd, '.cursor/mcp.json'),
+  });
+
+  // ============================================
+  // VS Code (MCP extension)
+  // ============================================
+  if (os === 'darwin') {
+    locations.push({
+      client: 'VS Code',
+      scope: 'global',
+      path: join(home, 'Library/Application Support/Code/User/settings.json'),
+    });
+  } else if (os === 'win32') {
+    locations.push({
+      client: 'VS Code',
+      scope: 'global',
+      path: join(process.env.APPDATA || join(home, 'AppData/Roaming'), 'Code/User/settings.json'),
+    });
+  } else {
+    locations.push({
+      client: 'VS Code',
+      scope: 'global',
+      path: join(home, '.config/Code/User/settings.json'),
+    });
+  }
+  locations.push({
+    client: 'VS Code',
+    scope: 'project',
+    path: join(cwd, '.vscode/settings.json'),
+  });
+
+  // ============================================
+  // Windsurf
+  // ============================================
+  locations.push({
+    client: 'Windsurf',
+    scope: 'global',
+    path: join(home, '.codeium/windsurf/mcp_config.json'),
+  });
+
+  // Check existence and return
+  return locations.map((loc) => ({
+    ...loc,
+    exists: existsSync(loc.path),
+  }));
+}
+
+export function getServersFromConfig(config: Record<string, unknown>): Record<string, unknown> | null {
+  // Try different config formats
+  if (config.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, unknown>;
+  }
+  if (config['mcp.servers'] && typeof config['mcp.servers'] === 'object') {
+    return config['mcp.servers'] as Record<string, unknown>;
+  }
+  if (config.servers && typeof config.servers === 'object') {
+    return config.servers as Record<string, unknown>;
+  }
+  return null;
+}

package/src/config/types.ts

@@ -0,0 +1,45 @@
+export interface MCPServerConfig {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  // HTTP transport
+  url?: string;
+}
+
+export interface MCPConfig {
+  mcpServers?: Record<string, MCPServerConfig>;
+  // VS Code style
+  'mcp.servers'?: Record<string, MCPServerConfig>;
+  // Claude Code style (servers at root)
+  servers?: Record<string, MCPServerConfig>;
+}
+
+export interface ConfigLocation {
+  client: string;
+  scope: 'global' | 'project';
+  path: string;
+  exists: boolean;
+}
+
+export interface ValidationResult {
+  level: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  file: string;
+  line?: number;
+  suggestion?: string;
+}
+
+export interface ServerTestResult {
+  name: string;
+  healthy: boolean;
+  responseTime?: number;
+  error?: string;
+}
+
+export interface CheckResults {
+  configsFound: ConfigLocation[];
+  validationResults: ValidationResult[];
+  serverResults: ServerTestResult[];
+}

package/src/utils/output.ts

@@ -0,0 +1,128 @@
+import chalk from 'chalk';
+import { ValidationResult, ServerTestResult, ConfigLocation } from '../config/types.js';
+
+export function printHeader(text: string): void {
+  console.log(chalk.bold(`\n${text}\n`));
+}
+
+export function printConfigsFound(configs: ConfigLocation[]): void {
+  const found = configs.filter((c) => c.exists);
+  const notFound = configs.filter((c) => !c.exists);
+
+  if (found.length === 0) {
+    console.log(chalk.yellow('No MCP configuration files found.\n'));
+    console.log(chalk.gray('Looked in:'));
+    notFound.slice(0, 5).forEach((c) => {
+      console.log(chalk.gray(`  ${c.client}: ${c.path}`));
+    });
+    if (notFound.length > 5) {
+      console.log(chalk.gray(`  ... and ${notFound.length - 5} more locations`));
+    }
+    return;
+  }
+
+  console.log(chalk.green(`Found ${found.length} config file${found.length > 1 ? 's' : ''}:\n`));
+  found.forEach((c) => {
+    const scope = c.scope === 'project' ? chalk.gray(' (project)') : '';
+    console.log(`  ${chalk.cyan(c.client)}${scope}`);
+    console.log(chalk.gray(`  ${c.path}\n`));
+  });
+}
+
+export function printValidationResults(results: ValidationResult[]): void {
+  const errors = results.filter((r) => r.level === 'error');
+  const warnings = results.filter((r) => r.level === 'warning');
+
+  if (errors.length > 0) {
+    console.log(chalk.red(`❌ ${errors.length} Error${errors.length > 1 ? 's' : ''}\n`));
+    errors.forEach((e) => {
+      const location = e.line ? `:${e.line}` : '';
+      console.log(chalk.red(`  ${shortPath(e.file)}${location}`));
+      console.log(chalk.red(`  ${e.message}`));
+      if (e.suggestion) {
+        console.log(chalk.gray(`  💡 ${e.suggestion}`));
+      }
+      console.log('');
+    });
+  }
+
+  if (warnings.length > 0) {
+    console.log(chalk.yellow(`⚠️  ${warnings.length} Warning${warnings.length > 1 ? 's' : ''}\n`));
+    warnings.forEach((w) => {
+      const location = w.line ? `:${w.line}` : '';
+      console.log(chalk.yellow(`  ${shortPath(w.file)}${location}`));
+      console.log(chalk.yellow(`  ${w.message}`));
+      if (w.suggestion) {
+        console.log(chalk.gray(`  💡 ${w.suggestion}`));
+      }
+      console.log('');
+    });
+  }
+}
+
+export function printServerResults(results: ServerTestResult[]): void {
+  if (results.length === 0) {
+    console.log(chalk.gray('No servers to test.\n'));
+    return;
+  }
+
+  const healthy = results.filter((s) => s.healthy);
+  const unhealthy = results.filter((s) => !s.healthy);
+
+  console.log(
+    `🔌 Server Health: ${chalk.green(healthy.length)} healthy, ${
+      unhealthy.length > 0 ? chalk.red(unhealthy.length + ' failed') : chalk.gray('0 failed')
+    }\n`
+  );
+
+  healthy.forEach((s) => {
+    const time = s.responseTime ? chalk.gray(` (${s.responseTime}ms)`) : '';
+    console.log(chalk.green(`  ✓ ${s.name}${time}`));
+  });
+
+  unhealthy.forEach((s) => {
+    console.log(chalk.red(`  ✗ ${s.name}`));
+    if (s.error) {
+      console.log(chalk.gray(`    ${s.error}`));
+    }
+  });
+
+  console.log('');
+}
+
+export function printSummary(
+  errors: number,
+  warnings: number,
+  healthyServers: number,
+  totalServers: number
+): void {
+  console.log(chalk.gray('─'.repeat(50)));
+
+  if (errors === 0 && warnings === 0) {
+    console.log(chalk.green('\n✓ All configurations valid'));
+  } else if (errors === 0) {
+    console.log(chalk.yellow(`\n⚠️  Configuration valid with ${warnings} warning${warnings > 1 ? 's' : ''}`));
+  } else {
+    console.log(chalk.red(`\n❌ Found ${errors} error${errors > 1 ? 's' : ''} that need${errors === 1 ? 's' : ''} fixing`));
+  }
+
+  if (totalServers > 0) {
+    if (healthyServers === totalServers) {
+      console.log(chalk.green(`✓ All ${totalServers} server${totalServers > 1 ? 's' : ''} responding`));
+    } else {
+      console.log(
+        chalk.yellow(`⚠️  ${healthyServers}/${totalServers} servers responding`)
+      );
+    }
+  }
+
+  console.log('');
+}
+
+function shortPath(path: string): string {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home && path.startsWith(home)) {
+    return '~' + path.slice(home.length);
+  }
+  return path;
+}

package/src/validators/env-vars.ts

@@ -0,0 +1,85 @@
+import { ValidationResult, MCPServerConfig } from '../config/types.js';
+import { getServersFromConfig } from '../config/locations.js';
+
+export function validateEnvVars(
+  config: Record<string, unknown>,
+  configPath: string
+): ValidationResult[] {
+  const results: ValidationResult[] = [];
+  const servers = getServersFromConfig(config);
+
+  if (!servers) {
+    return results;
+  }
+
+  for (const [name, serverRaw] of Object.entries(servers)) {
+    const server = serverRaw as MCPServerConfig;
+
+    if (!server.env) continue;
+
+    for (const [key, value] of Object.entries(server.env)) {
+      if (typeof value !== 'string') continue;
+
+      // Check for ${VAR} or $VAR references
+      const varRefs = value.match(/\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g) || [];
+
+      for (const ref of varRefs) {
+        const varName = ref.replace(/^\$\{?|\}?$/g, '');
+
+        if (!process.env[varName]) {
+          results.push({
+            level: 'warning',
+            code: 'ENV_VAR_MISSING',
+            message: `Server "${name}": Environment variable ${varName} is not set`,
+            file: configPath,
+            suggestion: `Set it with: export ${varName}="your-value"`,
+          });
+        }
+      }
+
+      // Check for empty values that look like they should be set
+      if (value === '' || value === '""' || value === "''") {
+        results.push({
+          level: 'warning',
+          code: 'ENV_VAR_EMPTY',
+          message: `Server "${name}": Environment variable ${key} is empty`,
+          file: configPath,
+          suggestion: 'This may cause authentication or configuration issues',
+        });
+      }
+
+      // Warn about hardcoded secrets
+      const secretKeyPatterns = [
+        /^(api[_-]?key|secret|token|password|pwd|auth|credential)/i,
+        /_(api[_-]?key|secret|token|password|pwd|auth|credential)$/i,
+      ];
+
+      const secretValuePatterns = [
+        /^sk[-_][a-zA-Z0-9]{20,}$/,           // OpenAI-style keys
+        /^[a-f0-9]{32,}$/i,                    // Hex strings (32+ chars)
+        /^eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/, // JWT tokens
+        /^ghp_[a-zA-Z0-9]{36}$/,               // GitHub tokens
+        /^github_pat_[a-zA-Z0-9_]{22,}/,       // GitHub PAT
+        /^xoxb-[0-9]{10,}/,                    // Slack bot tokens
+        /^xoxp-[0-9]{10,}/,                    // Slack user tokens
+        /^AKIA[A-Z0-9]{16}$/,                  // AWS access keys
+      ];
+
+      const isSecretKey = secretKeyPatterns.some((p) => p.test(key));
+      const looksLikeSecret = secretValuePatterns.some((p) => p.test(value));
+
+      // Only warn if it's not a variable reference
+      if ((isSecretKey || looksLikeSecret) && !value.includes('$')) {
+        results.push({
+          level: 'warning',
+          code: 'HARDCODED_SECRET',
+          message: `Server "${name}": Possible hardcoded secret in ${key}`,
+          file: configPath,
+          suggestion: 'Use an environment variable reference like ${' + key.toUpperCase() + '} instead',
+        });
+      }
+    }
+  }
+
+  return results;
+}

package/src/validators/index.ts

@@ -0,0 +1,4 @@
+export { validateJsonSyntax } from './json-syntax.js';
+export { validatePaths } from './paths.js';
+export { validateEnvVars } from './env-vars.js';
+export { testServerHealth } from './server-health.js';

package/src/validators/json-syntax.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { ValidationResult } from '../config/types.js';
+
+export function validateJsonSyntax(filePath: string): { valid: boolean; results: ValidationResult[]; config?: Record<string, unknown> } {
+  const results: ValidationResult[] = [];
+
+  let content: string;
+  try {
+    content = readFileSync(filePath, 'utf-8');
+  } catch (error) {
+    results.push({
+      level: 'error',
+      code: 'FILE_READ_ERROR',
+      message: `Cannot read file: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      file: filePath,
+    });
+    return { valid: false, results };
+  }
+
+  // Check for empty file
+  if (!content.trim()) {
+    results.push({
+      level: 'warning',
+      code: 'EMPTY_FILE',
+      message: 'Config file is empty',
+      file: filePath,
+    });
+    return { valid: true, results, config: {} };
+  }
+
+  // Try to parse JSON
+  try {
+    const config = JSON.parse(content);
+    return { valid: true, results, config };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      // Try to find the line number
+      const match = error.message.match(/position\s+(\d+)/i);
+      let line: number | undefined;
+      let column: number | undefined;
+
+      if (match) {
+        const position = parseInt(match[1], 10);
+        const lines = content.substring(0, position).split('\n');
+        line = lines.length;
+        column = lines[lines.length - 1].length + 1;
+      }
+
+      // Check for common issues
+      const trailingCommaMatch = content.match(/,\s*([}\]])/);
+      if (trailingCommaMatch) {
+        // Find line of trailing comma
+        const beforeMatch = content.substring(0, content.indexOf(trailingCommaMatch[0]));
+        const trailingCommaLine = beforeMatch.split('\n').length;
+
+        results.push({
+          level: 'error',
+          code: 'JSON_TRAILING_COMMA',
+          message: 'Trailing comma detected (not allowed in JSON)',
+          file: filePath,
+          line: trailingCommaLine,
+          suggestion: 'Remove the comma before the closing bracket/brace',
+        });
+      } else {
+        // Generic JSON error
+        let message = error.message;
+        if (line && column) {
+          message = `Invalid JSON at line ${line}, column ${column}: ${error.message}`;
+        }
+
+        results.push({
+          level: 'error',
+          code: 'JSON_SYNTAX',
+          message,
+          file: filePath,
+          line,
+        });
+      }
+    }
+
+    return { valid: false, results };
+  }
+}

package/src/validators/paths.ts

@@ -0,0 +1,140 @@
+import { existsSync, accessSync, constants } from 'fs';
+import { isAbsolute, resolve, dirname } from 'path';
+import { ValidationResult, MCPServerConfig } from '../config/types.js';
+import { getServersFromConfig } from '../config/locations.js';
+
+export function validatePaths(
+  config: Record<string, unknown>,
+  configPath: string
+): ValidationResult[] {
+  const results: ValidationResult[] = [];
+  const servers = getServersFromConfig(config);
+
+  if (!servers) {
+    return results;
+  }
+
+  const configDir = dirname(configPath);
+
+  for (const [name, serverRaw] of Object.entries(servers)) {
+    const server = serverRaw as MCPServerConfig;
+
+    // Skip HTTP/URL-based servers
+    if (server.url) continue;
+
+    // Skip if no command specified
+    if (!server.command) {
+      results.push({
+        level: 'error',
+        code: 'MISSING_COMMAND',
+        message: `Server "${name}": No command specified`,
+        file: configPath,
+        suggestion: 'Add a "command" field specifying how to start the server',
+      });
+      continue;
+    }
+
+    const command = server.command;
+
+    // Check if command is a path (contains / or \)
+    if (command.includes('/') || command.includes('\\')) {
+      const resolvedPath = isAbsolute(command)
+        ? command
+        : resolve(configDir, command);
+
+      // Check existence
+      if (!existsSync(resolvedPath)) {
+        results.push({
+          level: 'error',
+          code: 'PATH_NOT_FOUND',
+          message: `Server "${name}": Command path does not exist: ${command}`,
+          file: configPath,
+          suggestion: `Check the path is correct. Resolved to: ${resolvedPath}`,
+        });
+      } else {
+        // Check executable permission (Unix only)
+        if (process.platform !== 'win32') {
+          try {
+            accessSync(resolvedPath, constants.X_OK);
+          } catch {
+            results.push({
+              level: 'error',
+              code: 'PATH_NOT_EXECUTABLE',
+              message: `Server "${name}": Command is not executable: ${command}`,
+              file: configPath,
+              suggestion: `Run: chmod +x "${resolvedPath}"`,
+            });
+          }
+        }
+      }
+
+      // Warn about relative paths
+      if (!isAbsolute(command)) {
+        results.push({
+          level: 'warning',
+          code: 'PATH_RELATIVE',
+          message: `Server "${name}": Using relative path "${command}"`,
+          file: configPath,
+          suggestion: `Consider using absolute path: ${resolvedPath}`,
+        });
+      }
+    } else {
+      // Command is not a path (e.g., "npx", "node", "python")
+      // We can't easily validate these as they depend on PATH
+      // But we can warn if it looks like a typo
+
+      const commonCommands = ['npx', 'node', 'python', 'python3', 'uv', 'uvx', 'deno', 'bun'];
+      const looksLikePath = command.includes('.') && !commonCommands.includes(command);
+
+      if (looksLikePath) {
+        results.push({
+          level: 'warning',
+          code: 'POSSIBLE_PATH_TYPO',
+          message: `Server "${name}": "${command}" looks like a filename but isn't a path`,
+          file: configPath,
+          suggestion: 'If this is a file, use a full path like "./server.js" or "/path/to/server.js"',
+        });
+      }
+    }
+
+    // Check cwd if specified
+    if (server.cwd) {
+      const cwdPath = isAbsolute(server.cwd)
+        ? server.cwd
+        : resolve(configDir, server.cwd);
+
+      if (!existsSync(cwdPath)) {
+        results.push({
+          level: 'error',
+          code: 'CWD_NOT_FOUND',
+          message: `Server "${name}": Working directory does not exist: ${server.cwd}`,
+          file: configPath,
+          suggestion: `Create the directory or update the path. Resolved to: ${cwdPath}`,
+        });
+      }
+    }
+
+    // Check args for paths
+    if (server.args && Array.isArray(server.args)) {
+      for (const arg of server.args) {
+        // If arg looks like an absolute path, check it exists
+        if (typeof arg === 'string' && isAbsolute(arg) && (arg.includes('/') || arg.includes('\\'))) {
+          // Only check if it looks like a file path (not a URL or flag)
+          if (!arg.startsWith('-') && !arg.startsWith('http')) {
+            if (!existsSync(arg)) {
+              results.push({
+                level: 'warning',
+                code: 'ARG_PATH_NOT_FOUND',
+                message: `Server "${name}": Argument path may not exist: ${arg}`,
+                file: configPath,
+                suggestion: 'Verify this path is correct',
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return results;
+}