search_symbols

Instructions

Implementation Reference

• src/server/handlers/search-symbols.ts:6-162 (handler)

  The buildSearchSymbolsHandler function that executes the search_symbols tool logic. It searches a local symbol index (built from cache if needed), falls back to framework search if index is small, applies filters, and returns formatted Markdown results.

  export const buildSearchSymbolsHandler = (context: ServerContext) => {
  	const {client, state} = context;
  	const noTechnology = buildNoTechnologyMessage(context);
  
  	return async (args: {maxResults?: number; platform?: string; query: string; symbolType?: string}): Promise<ToolResponse> => {
  		const activeTechnology = state.getActiveTechnology();
  		if (!activeTechnology) {
  			return noTechnology();
  		}
  
  		const {query, maxResults = 20, platform, symbolType} = args;
  
  		// Get or create technology-specific local index from state
  		const techLocalIndex = state.getLocalSymbolIndex(client);
  
  		// Build local index from cached files if not already built
  		if (techLocalIndex.getSymbolCount() === 0) {
  			try {
  				console.error('📚 Building symbol index from cache...');
  				await techLocalIndex.buildIndexFromCache();
  				console.error(`✅ Index built with ${techLocalIndex.getSymbolCount()} symbols`);
  			} catch (error) {
  				console.warn('Failed to build local symbol index:', error instanceof Error ? error.message : String(error));
  			}
  		}
  
  		// Comprehensive download disabled - it was broken and blocking
  		// If local index is empty/small, use direct framework search as fallback
  		let symbolResults = techLocalIndex.search(query, maxResults * 2);
  
  		if (symbolResults.length === 0 && techLocalIndex.getSymbolCount() < 50) {
  			// Fallback: search framework.references directly (fast, no download needed)
  			console.error('📋 Using framework references for search...');
  			const frameworkResults = await client.searchFramework(activeTechnology.title, query, {maxResults: maxResults * 2, platform, symbolType});
  			symbolResults = frameworkResults.map(r => ({
  				id: r.path ?? r.title,
  				title: r.title,
  				path: r.path ?? '',
  				kind: r.symbolKind ?? 'symbol',
  				abstract: r.description,
  				platforms: r.platforms ? r.platforms.split(', ') : [],
  				tokens: [],
  				filePath: '',
  			}));
  		}
  
  		// Apply filters
  		let filteredResults = symbolResults;
  		if (platform) {
  			const platformLower = platform.toLowerCase();
  			filteredResults = filteredResults.filter(result =>
  				result.platforms.some(p => p.toLowerCase().includes(platformLower)));
  		}
  
  		if (symbolType) {
  			const typeLower = symbolType.toLowerCase();
  			filteredResults = filteredResults.filter(result =>
  				result.kind.toLowerCase().includes(typeLower));
  		}
  
  		filteredResults = filteredResults.slice(0, maxResults);
  
  		// Validate result relevance
  		const technologyIdentifier = activeTechnology.identifier.replace('doc://com.apple.documentation/', '').replace(/^documentation\//, '');
  		const isRelevantResult = (result: LocalSymbolIndexEntry) => {
  			const resultPath = result.path.toLowerCase();
  			const technologyPath = technologyIdentifier.toLowerCase();
  			return resultPath.includes(technologyPath);
  		};
  
  		const relevantResults = filteredResults.filter(result => isRelevantResult(result));
  		const hasIrrelevantResults = relevantResults.length < filteredResults.length;
  
  		const lines = [
  			header(1, `🔍 Search Results for "${query}"`),
  			'',
  			bold('Technology', activeTechnology.title),
  			bold('Matches', filteredResults.length.toString()),
  			bold('Total Symbols Indexed', techLocalIndex.getSymbolCount().toString()),
  			'',
  		];
  
  		// Add status information
  		if (techLocalIndex.getSymbolCount() < 50) {
  			lines.push(
  				'⚠️ **Limited Results:** Only basic symbols are indexed.',
  				'For comprehensive results, additional symbols are being downloaded in the background.',
  				'',
  			);
  		} else {
  			lines.push(
  				'✅ **Comprehensive Index:** Full symbol database is available.',
  				'',
  			);
  		}
  
  		lines.push(header(2, 'Symbols'), '');
  
  		// Show warning if results seem irrelevant
  		if (hasIrrelevantResults && filteredResults.length > 0) {
  			lines.push(
  				'⚠️ **Note:** Some results may not be from the selected technology.',
  				'For specific symbol names, try using `get_documentation` instead.',
  				'',
  			);
  		}
  
  		if (filteredResults.length > 0) {
  			for (const result of filteredResults) {
  				const platforms = result.platforms.length > 0 ? result.platforms.join(', ') : 'All platforms';
  				lines.push(
  					`### ${result.title}`,
  					`   • **Kind:** ${result.kind}`,
  					`   • **Path:** ${result.path}`,
  					`   • **Platforms:** ${platforms}`,
  					`   ${result.abstract}`,
  					'',
  				);
  			}
  		} else {
  			// Check if this looks like a specific symbol name that should use direct documentation lookup
  			const isSpecificSymbol = /^[A-Z][a-zA-Z\d]*$/.test(query) || /^[A-Z][a-zA-Z\d]*\.[A-Z][a-zA-Z\d]*$/.test(query);
  
  			lines.push(
  				'No symbols matched those terms within this technology.',
  				'',
  				'**Search Tips:**',
  				'• Try wildcards: `Grid*` or `*Item`',
  				'• Use broader keywords: "grid" instead of "griditem"',
  				'• Check spelling and try synonyms',
  				'',
  			);
  
  			if (isSpecificSymbol) {
  				lines.push(
  					'**💡 Suggestion:** This looks like a specific symbol name.',
  					'Try using `get_documentation` instead for direct access:',
  					'',
  					'```',
  					`get_documentation { "path": "${query}" }`,
  					'```',
  					'',
  				);
  			}
  
  			lines.push(
  				'**Note:** If this is your first search, symbols are being downloaded in the background.',
  				'Try searching again in a few moments for more comprehensive results.',
  				'',
  			);
  		}
  
  		return {
  			content: [{text: lines.join('\n'), type: 'text'}],
  		};
  	};
  };

• src/server/tools.ts:88-116 (registration)

  Tool definition object for search_symbols, including name, description, input schema, and handler assignment, added to the toolDefinitions array for MCP server registration.

  {
  	name: 'search_symbols',
  	description: 'Search and discover symbols within the currently selected technology. '
  		+ 'Use this for exploration and finding symbols by keywords. Supports wildcards (* and ?). '
  		+ 'For specific known symbols, use get_documentation instead.',
  	inputSchema: {
  		type: 'object',
  		required: ['query'],
  		properties: {
  			maxResults: {
  				type: 'number',
  				description: 'Optional maximum number of results (default 20)',
  			},
  			platform: {
  				type: 'string',
  				description: 'Optional platform filter (iOS, macOS, etc.)',
  			},
  			query: {
  				type: 'string',
  				description: 'Search keywords with wildcard support (* for any characters, ? for single character)',
  			},
  			symbolType: {
  				type: 'string',
  				description: 'Optional symbol kind filter (class, protocol, etc.)',
  			},
  		},
  	},
  	handler: buildSearchSymbolsHandler(context),
  },

• src/server/tools.ts:93-114 (schema)

  Input schema defining parameters for the search_symbols tool: required query string, optional maxResults, platform, and symbolType.

  inputSchema: {
  	type: 'object',
  	required: ['query'],
  	properties: {
  		maxResults: {
  			type: 'number',
  			description: 'Optional maximum number of results (default 20)',
  		},
  		platform: {
  			type: 'string',
  			description: 'Optional platform filter (iOS, macOS, etc.)',
  		},
  		query: {
  			type: 'string',
  			description: 'Search keywords with wildcard support (* for any characters, ? for single character)',
  		},
  		symbolType: {
  			type: 'string',
  			description: 'Optional symbol kind filter (class, protocol, etc.)',
  		},
  	},
  },