claude-task-master/docs/ai-client-utils-example.md

AI Client Utilities for MCP Tools

This document provides examples of how to use the new AI client utilities with AsyncOperationManager in MCP tools.

Basic Usage with Direct Functions

// In your direct function implementation:
import { 
  getAnthropicClientForMCP, 
  getModelConfig, 
  handleClaudeError 
} from '../utils/ai-client-utils.js';

export async function someAiOperationDirect(args, log, context) {
  try {
    // Initialize Anthropic client with session from context
    const client = getAnthropicClientForMCP(context.session, log);
    
    // Get model configuration with defaults or session overrides
    const modelConfig = getModelConfig(context.session);
    
    // Make API call with proper error handling
    try {
      const response = await client.messages.create({
        model: modelConfig.model,
        max_tokens: modelConfig.maxTokens,
        temperature: modelConfig.temperature,
        messages: [
          { role: 'user', content: 'Your prompt here' }
        ]
      });
      
      return {
        success: true,
        data: response
      };
    } catch (apiError) {
      // Use helper to get user-friendly error message
      const friendlyMessage = handleClaudeError(apiError);
      
      return {
        success: false,
        error: {
          code: 'AI_API_ERROR',
          message: friendlyMessage
        }
      };
    }
  } catch (error) {
    // Handle client initialization errors
    return {
      success: false,
      error: {
        code: 'AI_CLIENT_ERROR',
        message: error.message
      }
    };
  }
}

Integration with AsyncOperationManager

// In your MCP tool implementation:
import { AsyncOperationManager, StatusCodes } from '../../utils/async-operation-manager.js';
import { someAiOperationDirect } from '../../core/direct-functions/some-ai-operation.js';

export async function someAiOperation(args, context) {
  const { session, mcpLog } = context;
  const log = mcpLog || console;
  
  try {
    // Create operation description
    const operationDescription = `AI operation: ${args.someParam}`;
    
    // Start async operation
    const operation = AsyncOperationManager.createOperation(
      operationDescription,
      async (reportProgress) => {
        try {
          // Initial progress report
          reportProgress({
            progress: 0,
            status: 'Starting AI operation...'
          });
          
          // Call direct function with session and progress reporting
          const result = await someAiOperationDirect(
            args, 
            log, 
            {
              reportProgress,
              mcpLog: log,
              session
            }
          );
          
          // Final progress update
          reportProgress({
            progress: 100,
            status: result.success ? 'Operation completed' : 'Operation failed',
            result: result.data,
            error: result.error
          });
          
          return result;
        } catch (error) {
          // Handle errors in the operation
          reportProgress({
            progress: 100,
            status: 'Operation failed',
            error: {
              message: error.message,
              code: error.code || 'OPERATION_FAILED'
            }
          });
          throw error;
        }
      }
    );
    
    // Return immediate response with operation ID
    return {
      status: StatusCodes.ACCEPTED,
      body: {
        success: true,
        message: 'Operation started',
        operationId: operation.id
      }
    };
  } catch (error) {
    // Handle errors in the MCP tool
    log.error(`Error in someAiOperation: ${error.message}`);
    return {
      status: StatusCodes.INTERNAL_SERVER_ERROR,
      body: {
        success: false,
        error: {
          code: 'OPERATION_FAILED',
          message: error.message
        }
      }
    };
  }
}

Using Research Capabilities with Perplexity

// In your direct function:
import { 
  getPerplexityClientForMCP, 
  getBestAvailableAIModel 
} from '../utils/ai-client-utils.js';

export async function researchOperationDirect(args, log, context) {
  try {
    // Get the best AI model for this operation based on needs
    const { type, client } = await getBestAvailableAIModel(
      context.session, 
      { requiresResearch: true },
      log
    );
    
    // Report which model we're using
    if (context.reportProgress) {
      await context.reportProgress({
        progress: 10,
        status: `Using ${type} model for research...`
      });
    }
    
    // Make API call based on the model type
    if (type === 'perplexity') {
      // Call Perplexity
      const response = await client.chat.completions.create({
        model: context.session?.env?.PERPLEXITY_MODEL || 'sonar-medium-online',
        messages: [
          { role: 'user', content: args.researchQuery }
        ],
        temperature: 0.1
      });
      
      return {
        success: true,
        data: response.choices[0].message.content
      };
    } else {
      // Call Claude as fallback
      // (Implementation depends on specific needs)
      // ...
    }
  } catch (error) {
    // Handle errors
    return {
      success: false,
      error: {
        code: 'RESEARCH_ERROR',
        message: error.message
      }
    };
  }
}

Model Configuration Override Example

// In your direct function:
import { getModelConfig } from '../utils/ai-client-utils.js';

// Using custom defaults for a specific operation
const operationDefaults = {
  model: 'claude-3-haiku-20240307',  // Faster, smaller model
  maxTokens: 1000,                  // Lower token limit
  temperature: 0.2                  // Lower temperature for more deterministic output
};

// Get model config with operation-specific defaults
const modelConfig = getModelConfig(context.session, operationDefaults);

// Now use modelConfig in your API calls
const response = await client.messages.create({
  model: modelConfig.model,
  max_tokens: modelConfig.maxTokens,
  temperature: modelConfig.temperature,
  // Other parameters...
});

Best Practices

1. Error Handling:

   • Always use try/catch blocks around both client initialization and API calls
   • Use handleClaudeError to provide user-friendly error messages
   • Return standardized error objects with code and message

2. Progress Reporting:

   • Report progress at key points (starting, processing, completing)
   • Include meaningful status messages
   • Include error details in progress reports when failures occur

3. Session Handling:

   • Always pass the session from the context to the AI client getters
   • Use getModelConfig to respect user settings from session

4. Model Selection:

   • Use getBestAvailableAIModel when you need to select between different models
   • Set requiresResearch: true when you need Perplexity capabilities

5. AsyncOperationManager Integration:

   • Create descriptive operation names
   • Handle all errors within the operation function
   • Return standardized results from direct functions
   • Return immediate responses with operation IDs