list_technologies

Instructions

Implementation Reference

• src/tools/list-technologies.ts:35-80 (handler)

  Main handler function for list_technologies tool. Fetches technologies data from Apple's JSON endpoint, applies filters (category, language, includeBeta, limit), caches results, and returns a formatted markdown string.

  export async function handleListTechnologies(
    category?: string,
    language?: string,
    includeBeta: boolean = true,
    limit: number = API_LIMITS.DEFAULT_TECHNOLOGIES_LIMIT,
  ): Promise<string> {
    try {
      logger.info('Fetching technologies list...');
  
      // Generate cache key
      const cacheKey = generateUrlCacheKey('technologies', { category, language, includeBeta, limit });
  
      // Try to get from cache first
      const cachedResult = technologiesCache.get<string>(cacheKey);
      if (cachedResult) {
        logger.debug('Technologies cache hit');
        return cachedResult;
      }
  
      // 获取技术列表
      const data = await httpClient.getJson<TechnologiesData>(APPLE_URLS.TECHNOLOGIES_JSON);
  
      // 解析技术列表
      const technologies = parseTechnologies(data);
  
      // 应用过滤器
      const filteredTechnologies = applyTechnologyFilters(technologies, {
        category,
        language,
        includeBeta,
        limit,
      });
  
      // 格式化输出
      const result = formatTechnologiesList(filteredTechnologies);
  
      // Cache the result
      technologiesCache.set(cacheKey, result);
  
      return result;
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return `Error: Failed to list technologies: ${errorMessage}`;
    }
  }

• src/schemas/technologies.schema.ts:4-9 (schema)

  Zod schema defining input validation for listTechnologies: optional category string, optional language enum (swift/occ), includeBeta boolean (default true), and limit number (positive, max capped).

  export const listTechnologiesSchema = z.object({
    category: z.string().optional().describe('Filter by technology category'),
    language: z.enum(['swift', 'occ']).optional().describe('Filter by programming language'),
    includeBeta: z.boolean().default(true).describe('Include beta technologies'),
    limit: z.number().int().positive().max(API_LIMITS.MAX_TECHNOLOGIES_LIMIT).default(API_LIMITS.DEFAULT_TECHNOLOGIES_LIMIT).describe('Maximum number of technologies to return'),
  });

• src/tools/definitions.ts:69-99 (registration)

  Tool definition registration with name 'list_technologies', description, inputSchema (JSON Schema) including category, language, includeBeta, limit parameters, and annotations.

  {
    name: 'list_technologies',
    description: 'Browse all Apple technologies and frameworks by category. Essential for discovering available frameworks and understanding Apple\'s technology ecosystem. Use this when: exploring what\'s available, finding framework identifiers for search_framework_symbols, checking beta status.',
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: 'Filter by category (case-sensitive). Popular: "App frameworks" (SwiftUI, UIKit), "Graphics and games" (Metal, SpriteKit), "App services" (CloudKit, StoreKit), "Media" (AVFoundation), "System" (Foundation). Leave empty to see all categories.',
        },
        language: {
          type: 'string',
          enum: ['swift', 'occ'],
          description: 'Filter by language support. "swift" for Swift-compatible frameworks, "occ" for Objective-C. Leave empty for all.',
        },
        includeBeta: {
          type: 'boolean',
          description: 'Include beta/preview technologies. Set to false to see only stable frameworks. Default: true',
        },
        limit: {
          type: 'number',
          description: 'Max results per category. Useful for quick overviews. Default: 200',
        },
      },
      required: [],
    },
    annotations: {
      title: 'List Technologies',
      readOnlyHint: true,
    },
  },

• src/tools/handlers.ts:141-149 (handler)

  Dispatcher in toolHandlers map that routes 'list_technologies' calls. Validates args via listTechnologiesSchema, then calls server.listTechnologies() which delegates to handleListTechnologies().

  list_technologies: async (args, server) => {
    const validatedArgs = listTechnologiesSchema.parse(args);
    return await server.listTechnologies(
      validatedArgs.category,
      validatedArgs.language,
      validatedArgs.includeBeta,
      validatedArgs.limit,
    );
  },

• src/utils/cache-warmer.ts:30-54 (helper)

  Cache warmer that pre-loads technologies data on startup by calling handleListTechnologies() with no filters and with popular categories to improve response times.

  async function warmUpTechnologiesCache(): Promise<void> {
    try {
      logger.info('Warming up technologies cache...');
  
      // Load all technologies
      await handleListTechnologies(undefined, undefined, true);
  
      // Load popular categories
      const popularCategories = [
        'app-frameworks',
        'graphics-and-games',
        'app-services',
        'system',
      ];
  
      for (const category of popularCategories) {
        await handleListTechnologies(category, undefined, true);
      }
  
      const stats = technologiesCache.getStats();
      logger.info(`Technologies cache warmed up: ${stats.size} entries`);
    } catch (error) {
      logger.error('Failed to warm up technologies cache:', error);
    }
  }