grok-faf-mcp

Instructions

Implementation Reference

• src/handlers/tools.ts:846-915 (handler)

  The handler function 'handleFafDebug' that collects environment, write permissions, and FAF CLI status, returning a formatted debug report.

    private async handleFafDebug(_args: any): Promise<CallToolResult> {  // ✅ FIXED: Prefixed unused args
      try {
        const fs = await import('fs');
        const path = await import('path');
        const { exec } = await import('child_process');
        const { promisify } = await import('util');
        const execAsync = promisify(exec);
  
        const cwd = this.engineAdapter.getWorkingDirectory();
        const debugInfo = {
          workingDirectory: cwd,
          canWrite: false,
          fafCliPath: null as string | null,
          fafVersion: null as string | null,
          permissions: {} as any,
          enginePath: this.engineAdapter.getEnginePath(),
          pathEnv: process.env.PATH?.split(':') || []
        };
        
        // Check write permissions
        try {
          const testFile = path.join(cwd, '.claude-faf-test');
          fs.writeFileSync(testFile, 'test');
          fs.unlinkSync(testFile);
          debugInfo.canWrite = true;
        } catch (error) {
          debugInfo.permissions.writeError = error instanceof Error ? error.message : String(error);
        }
        
        // Check FAF CLI availability using championship auto-detection
        try {
          const cliInfo = this.engineAdapter.getCliInfo();
  
          if (cliInfo.detected && cliInfo.path) {
            debugInfo.fafCliPath = cliInfo.path;
            debugInfo.fafVersion = cliInfo.version || null;
          } else {
            debugInfo.fafCliPath = null;
            debugInfo.fafVersion = null;
          }
        } catch (error) {
          debugInfo.permissions.fafError = error instanceof Error ? error.message : String(error);
        }
        
        // Check for existing FAF file (v1.2.0: project.faf, *.faf, or .faf)
        const fafResult = await findFafFile(cwd);
        const hasFaf = fafResult !== null;
  
        const debugOutput = `🔍 Claude FAF MCP Server Debug Information:
  
  📂 Working Directory: ${debugInfo.workingDirectory}
  ✏️ Write Permissions: ${debugInfo.canWrite ? '✅ Yes' : '❌ No'}
  ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeError}\n` : ''}🤖 FAF Engine Path: ${debugInfo.enginePath}
  🏎️ FAF CLI Path: ${debugInfo.fafCliPath || '❌ Not found'}
  📋 FAF Version: ${debugInfo.fafVersion || 'Unknown'}
  ${debugInfo.permissions.fafError ? `   FAF Error: ${debugInfo.permissions.fafError}\n` : ''}📄 FAF File: ${hasFaf ? `✅ ${fafResult.filename} exists` : '❌ Not found (run faf_init)'}
  🛤️ System PATH: ${debugInfo.pathEnv.slice(0, 3).join(', ')}${debugInfo.pathEnv.length > 3 ? '...' : ''}
  
  💡 Quick Start:
     1. If FAF CLI not found: npm install -g faf-cli
     2. If .faf file missing: use faf_init tool
     3. For optimization: use faf_enhance tool with model="claude"
  `;
        
        return {
          content: [{
            type: 'text',
            text: debugOutput
          }]
        };

• src/handlers/tools.ts:125-126 (registration)

  Registration of the 'faf_debug' tool name in the tools list.

  name: 'faf_debug',
  description: 'Debug Claude FAF MCP environment - show working directory, permissions, and FAF CLI status',

• src/handlers/tools.ts:276-277 (registration)

  Dispatcher logic routing the 'faf_debug' tool call to 'handleFafDebug'.

  case 'faf_debug':
    return await this.handleFafDebug(args);