Apple Docs MCP

Instructions

Implementation Reference

• src/tools/find-similar-apis.ts:48-125 (handler)

  Main handler function that implements the find_similar_apis tool logic. Fetches Apple Developer Documentation, extracts similar APIs from 'See Also' sections and topic sections, performs deep searches, deduplicates results, and formats output.

  export async function handleFindSimilarApis(
    apiUrl: string,
    searchDepth: string = 'medium',
    filterByCategory?: string,
    includeAlternatives: boolean = true,
  ): Promise<string> {
    try {
      logger.info(`Finding similar APIs for: ${apiUrl}`);
  
      const jsonApiUrl = convertToJsonApiUrl(apiUrl);
  
      // Check if conversion failed
      if (!jsonApiUrl) {
        throw new Error('Invalid Apple Developer Documentation URL');
      }
  
      const response = await httpClient.getJson<any>(jsonApiUrl);
  
      // Handle response structure - check if data is wrapped
      let data: AppleDocData;
      let references: Record<string, any> | undefined;
  
      if (response.data) {
        // Response has a data property, extract it
        data = response.data;
        references = response.references || data.references;
      } else {
        // Response is the data itself
        data = response;
        references = data.references;
      }
  
      // 收集相似API
      const similarApis: SimilarAPI[] = [];
  
      // 1. 从"另请参阅"部分收集
      if (data.seeAlsoSections) {
        const seeAlsoApis = extractSeeAlsoApis(data.seeAlsoSections, references, filterByCategory);
        similarApis.push(...seeAlsoApis);
      }
  
      // 2. 从主题部分收集（medium 和 deep 模式）
      if (searchDepth === 'medium' || searchDepth === 'deep') {
        if (data.topicSections && includeAlternatives) {
          const topicApis = extractTopicApis(data.topicSections, references, filterByCategory);
          similarApis.push(...topicApis);
        }
      }
  
      // 3. 深度搜索相关API（deep 模式）
      if (searchDepth === 'deep') {
        const deepApis = await extractDeepRelatedApis(similarApis.slice(0, PROCESSING_LIMITS.MAX_SIMILAR_APIS_FOR_DEEP_SEARCH)); // 限制前3个
        similarApis.push(...deepApis);
      }
  
      // 去重和评分
      const uniqueApis = deduplicateAndScore(similarApis);
  
      // 按相似度排序
      uniqueApis.sort((a, b) => b.confidence - a.confidence);
  
      // 限制结果数量
      const maxResults = SEARCH_DEPTH_LIMITS[searchDepth as keyof typeof SEARCH_DEPTH_LIMITS] || SEARCH_DEPTH_LIMITS.medium;
      const limitedApis = uniqueApis.slice(0, maxResults);
  
      // Get the title from data
      const title = data.title || data.metadata?.title || data.identifier?.split('/').pop() || 'API';
  
      return formatSimilarApis(apiUrl, limitedApis, title, data);
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      if (errorMessage.includes('Invalid Apple Developer Documentation URL')) {
        throw error;
      }
      throw new Error(errorMessage);
    }
  }

• src/schemas/similar-apis.schema.ts:3-8 (schema)

  Zod schema defining input validation for find_similar_apis tool with parameters: apiUrl (string), searchDepth (enum: shallow/medium/deep), filterByCategory (optional string), and includeAlternatives (boolean).

  export const findSimilarApisSchema = z.object({
    apiUrl: z.string().describe('The Apple Developer Documentation API URL to find similar APIs for'),
    searchDepth: z.enum(['shallow', 'medium', 'deep']).default('medium').describe('Search depth for similarity analysis'),
    filterByCategory: z.string().optional().describe('Filter results by category/topic'),
    includeAlternatives: z.boolean().default(true).describe('Include alternative APIs from the same topic section'),
  });

• src/tools/definitions.ts:164-180 (registration)

  Tool registration defining the find_similar_apis tool name, description, and input schema properties for the MCP protocol.

  name: 'find_similar_apis',
  description: 'Discover alternative and related APIs. Finds APIs with similar functionality, modern replacements for deprecated APIs, and platform-specific alternatives. Perfect when looking for better ways to implement functionality.',
  inputSchema: {
    type: 'object',
    properties: {
      apiUrl: {
        type: 'string',
        description: 'Starting API URL. Example: "https://developer.apple.com/documentation/uikit/uialertview" (finds modern alternatives)',
      },
      searchDepth: {
        type: 'string',
        enum: ['shallow', 'medium', 'deep'],
        description: 'How thoroughly to search. "shallow" = direct recommendations only, "medium" = topic siblings, "deep" = full relationship analysis. Default: "medium"',
      },
      filterByCategory: {
        type: 'string',
        description: 'Focus on specific functionality like "Animation", "Navigation", "Data". Case-sensitive partial match.',

• src/tools/handlers.ts:190-198 (registration)

  Handler mapping that connects the find_similar_apis tool to the server method, validates input using findSimilarApisSchema, and delegates to server.findSimilarApis().

  find_similar_apis: async (args, server) => {
    const validatedArgs = findSimilarApisSchema.parse(args);
    return await server.findSimilarApis(
      validatedArgs.apiUrl,
      validatedArgs.searchDepth,
      validatedArgs.filterByCategory,
      validatedArgs.includeAlternatives,
    );
  },

• src/index.ts:218-228 (helper)

  Server method wrapper that calls handleFindSimilarApis with error handling via handleAsyncOperation.

  public async findSimilarApis(
    apiUrl: string,
    searchDepth: string = 'medium',
    filterByCategory?: string,
    includeAlternatives: boolean = true,
  ) {
    return this.handleAsyncOperation(
      () => handleFindSimilarApis(apiUrl, searchDepth, filterByCategory, includeAlternatives),
      'findSimilarApis',
    );
  }