faf_guide

Instructions

Implementation Reference

• src/handlers/tools.ts:1012-1088 (handler)

  The main handler function that returns a hardcoded guide string about FAF MCP usage conventions for Claude Desktop.

    private async handleFafGuide(_args: any): Promise<CallToolResult> {
      const guide = `# FAF MCP - Claude Desktop Guide
  
  ## Path Convention (CRITICAL)
  **Default**: \`~/Projects/[project-name]/project.faf\`
  
  **Project name from:**
  1. AI inference (README, files, context)
  2. User statement
  3. User custom path (always wins)
  
  **Example Flow:**
  - User uploads README for "Heritage Club Dubai"
  - Infer: \`~/Projects/heritage-club-dubai/project.faf\`
  - Confirm: "Creating at ~/Projects/heritage-club-dubai/"
  
  ## Real Filesystem Only
  - ✅ \`/Users/wolfejam/Projects/my-app/\`
  - ❌ \`/mnt/user-data/\` (container paths)
  - ❌ \`/home/claude/\` (container paths)
  
  ## Commands
  All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
  
  **Core:**
  - \`faf init\` - create FAF (infer path from context)
  - \`faf score\` - show AI-readiness
  - \`faf sync\` - synchronize files
  - \`faf quick\` - rapid FAF creation
  
  **Extensions:**
  - \`new\` - force overwrite existing
  - \`full\` - detailed output
  - \`bi\` - bi-directional sync
  
  ## UX Rules
  1. **Don't offer option menus** - just solve it
  2. **Infer project name** from context
  3. **Suggest Projects path** if ambiguous
  4. **User path always wins**
  5. **No CLI talk** - you ARE the FAF system
  
  ## Quick Patterns
  
  **User uploads README:**
  → Infer project name
  → Create at \`~/Projects/[name]/project.faf\`
  → Confirm location
  
  **User gives path:**
  → Use exactly as provided
  → No validation needed
  
  **No context available:**
  → Ask once: "Project name or path?"
  → Use Projects convention with answer
  
  ## Username Detection
  - Check \`$HOME\` environment
  - Default to \`~/Projects/\` structure
  - Works across macOS/Linux/Windows
  
  ## Test Your Understanding
  ❌ "I need more information" (when README uploaded)
  ❌ "Option 1, Option 2, Option 3..." (option menus)
  ❌ Creating files in \`/mnt/user-data/\`
  ✅ "Creating FAF for [project] at ~/Projects/[name]/"
  ✅ Using context to infer and act
  ✅ Real filesystem paths only`;
  
      return {
        content: [{
          type: 'text',
          text: guide
        }]
      };
    }

• src/handlers/tools.ts:213-219 (registration)

  Registration entry defining the tool name, description, and an empty input schema.

  {
    name: 'faf_guide',
    description: 'FAF MCP usage guide for Claude Desktop - Projects convention, path resolution, and UX patterns',
    inputSchema: {
      type: 'object',
      properties: {},
    }

• src/handlers/tools.ts:292-293 (helper)

  Dispatch case in the tool handler switch statement that routes 'faf_guide' to handleFafGuide.

  case 'faf_guide':
    return await this.handleFafGuide(args);