Apple Dev MCP Server

Instructions

Implementation Reference

• src/tools.ts:224-298 (handler)

  Core handler function for 'search_technical_documentation' tool. Validates input, performs timed API search using AppleContentAPIClient, handles timeouts and errors, returns structured results.

  async searchTechnicalDocumentation(args: {
    query: string;
    framework?: string;
    platform?: string;
  }): Promise<{
    results: TechnicalSearchResult[];
    total: number;
    query: string;
    success: boolean;
    error?: string;
  }> {
    // Input validation
    if (!args || typeof args !== 'object') {
      throw new Error('Invalid arguments: expected object');
    }
    
    const { query, framework, platform } = args;
    const maxResults = 20; // Use sensible default internally
    
    // Validate required parameters
    if (typeof query !== 'string') {
      throw new Error('Invalid query: must be a string');
    }
    
    if (query.trim().length === 0) {
      return {
        results: [],
        total: 0,
        query: query.trim(),
        success: true
      };
    }
    
    if (query.length > 100) {
      throw new Error('Query too long: maximum 100 characters allowed');
    }
    
    try {
      let results: TechnicalSearchResult[] = [];
      
      // Try fast, targeted API search with aggressive timeout
      try {
        const searchPromise = this.performFastAPISearch(query.trim(), { framework, platform, maxResults });
        
        // Race condition: API search vs 15-second timeout (matching MightyDillah's approach)
        const timeoutPromise = new Promise<TechnicalSearchResult[]>((_, reject) => {
          setTimeout(() => reject(new Error('API search timeout')), 15000);
        });
        
        results = await Promise.race([searchPromise, timeoutPromise]);
      } catch {
        // API failed or timed out - return empty results for now
        // This maintains the "no static content" principle
        results = []; 
      }
      
      return {
        results: results.slice(0, maxResults),
        total: results.length,
        query: query.trim(),
        success: results.length > 0,
        error: results.length === 0 ? 'No results found. Try a more specific technical symbol like "UIButton" or "ScrollView".' : undefined
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      
      return {
        results: [],
        total: 0,
        query: query.trim(),
        success: false,
        error: errorMessage
      };
    }
  }

• src/server.ts:179-200 (registration)

  Registration of the 'search_technical_documentation' tool in MCP server's listToolsRequestSchema handler, including name, title, description, and input schema definition.

    name: 'search_technical_documentation',
    title: 'Search Technical Documentation',
    description: 'Search Apple technical documentation and API references',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query (API names, symbols, frameworks)',
        },
        framework: {
          type: 'string',
          description: 'Optional: Search within specific framework (e.g., "SwiftUI", "UIKit")',
        },
        platform: {
          type: 'string',
          description: 'Optional: Filter by platform (iOS, macOS, etc.)',
        },
      },
      required: ['query'],
    },
  },

• src/server.ts:252-255 (registration)

  Dispatch/execution handler in MCP server's CallToolRequestSchema that routes calls to the toolProvider's searchTechnicalDocumentation method.

  case 'search_technical_documentation': {
    result = await this.toolProvider.searchTechnicalDocumentation(args as any);
    break;
  }

• src/tools.ts:303-325 (helper)

  Supporting helper method called by the main handler to execute framework-specific or global API searches via AppleContentAPIClient.

  private async performFastAPISearch(query: string, options: {
    framework?: string;
    platform?: string;
    maxResults?: number;
  }): Promise<TechnicalSearchResult[]> {
    const { framework, platform, maxResults = 10 } = options;
    
    // If framework specified, search only that framework (faster)
    if (framework) {
      return await this.appleContentAPIClient.searchFramework(framework, query, {
        platform,
        maxResults: Math.min(maxResults, 5) // Limit to reduce API calls
      });
    }
    
    // For general searches, use the improved global search with sequential framework processing
    const results = await this.appleContentAPIClient.searchGlobal(query, {
      platform,
      maxResults
    });
    
    return results.slice(0, maxResults);
  }