choose_technology

Instructions

Implementation Reference

• src/server/handlers/choose-technology.ts:37-111 (handler)

  Core handler implementation for the 'choose_technology' tool. Builds a function that selects a technology/framework by name or identifier using exact, fuzzy matching, validates it, updates server state, and returns markdown response with success or suggestions.

  export const buildChooseTechnologyHandler = ({client, state}: ServerContext) =>
  	async (args: {name?: string; identifier?: string}): Promise<ToolResponse> => {
  		const {name, identifier} = args;
  		const technologies = await client.getTechnologies();
  		const candidates = Object.values(technologies).filter(tech => typeof tech?.title === 'string' && typeof tech?.identifier === 'string');
  
  		// Normalize search terms - case insensitive
  		const normalizedName = name?.toLowerCase().trim();
  		const normalizedIdentifier = identifier?.toLowerCase().trim();
  
  		let chosen: typeof candidates[0] | undefined;
  
  		// Try identifier first (most specific)
  		if (normalizedIdentifier) {
  			chosen = candidates.find(tech => tech.identifier?.toLowerCase() === normalizedIdentifier);
  		}
  
  		// Try exact name match (case-insensitive)
  		if (!chosen && normalizedName) {
  			chosen = candidates.find(tech => tech.title?.toLowerCase() === normalizedName);
  		}
  
  		// Try fuzzy match on name only if we have a name
  		if (!chosen && normalizedName) {
  			const scored = candidates
  				.map(tech => ({tech, score: fuzzyScore(tech.title, name)}))
  				.sort((a, b) => a.score - b.score);
  			// Only use fuzzy match if it's reasonably good (score < 3)
  			if (scored[0] && scored[0].score < 3) {
  				chosen = scored[0].tech;
  			}
  		}
  
  		if (!chosen) {
  			const searchTerm = normalizedName ?? normalizedIdentifier ?? '';
  			const suggestions = candidates
  				.filter(tech => tech.title?.toLowerCase().includes(searchTerm))
  				.slice(0, 5)
  				.map(tech => `• ${tech.title} — \`choose_technology "${tech.title}"\``);
  
  			const lines = [
  				header(1, '❌ Technology Not Found'),
  				`Could not resolve "${name ?? identifier ?? 'unknown'}".`,
  				'',
  				header(2, 'Suggestions'),
  				...(suggestions.length > 0
  					? suggestions
  					: ['• Use `discover_technologies { "query": "keyword" }` to find candidates']),
  			];
  
  			return {
  				content: [{text: lines.join('\n'), type: 'text'}],
  			};
  		}
  
  		ensureFramework(chosen);
  		state.setActiveTechnology(chosen);
  		state.clearActiveFrameworkData();
  
  		const lines = [
  			header(1, '✅ Technology Selected'),
  			'',
  			bold('Name', chosen.title),
  			bold('Identifier', chosen.identifier ?? 'Unknown'),
  			'',
  			header(2, 'Next actions'),
  			'• `search_symbols { "query": "keyword" }` — fuzzy search within this framework',
  			'• `get_documentation { "path": "SymbolName" }` — open a symbol page',
  			'• `discover_technologies` — pick another framework',
  		];
  
  		return {
  			content: [{text: lines.join('\n'), type: 'text'}],
  		};
  	};

• src/server/tools.ts:46-59 (schema)

  Input schema for 'choose_technology' tool defining optional 'identifier' and 'name' parameters.

  inputSchema: {
  	type: 'object',
  	required: [],
  	properties: {
  		identifier: {
  			type: 'string',
  			description: 'Optional technology identifier (e.g. doc://.../SwiftUI)',
  		},
  		name: {
  			type: 'string',
  			description: 'Technology name/title (e.g. SwiftUI)',
  		},
  	},
  },

• src/server/tools.ts:43-61 (registration)

  Tool definition object registering 'choose_technology' with name, description, input schema, and handler reference.

  {
  	name: 'choose_technology',
  	description: 'Select the framework/technology to scope all subsequent searches and documentation lookups',
  	inputSchema: {
  		type: 'object',
  		required: [],
  		properties: {
  			identifier: {
  				type: 'string',
  				description: 'Optional technology identifier (e.g. doc://.../SwiftUI)',
  			},
  			name: {
  				type: 'string',
  				description: 'Technology name/title (e.g. SwiftUI)',
  			},
  		},
  	},
  	handler: buildChooseTechnologyHandler(context),
  },

• src/server/app.ts:32-32 (registration)

  Top-level call to register all tools, including 'choose_technology', to the MCP Server instance.

  registerTools(server, {client, state});

• src/server/handlers/choose-technology.ts:6-26 (helper)

  Fuzzy matching utility function used by the handler to score and select technology names.

  const fuzzyScore = (a: string | undefined, b: string | undefined): number => {
  	if (!a || !b) {
  		return Number.POSITIVE_INFINITY;
  	}
  
  	const lowerA = a.toLowerCase();
  	const lowerB = b.toLowerCase();
  	if (lowerA === lowerB) {
  		return 0;
  	}
  
  	if (lowerA.startsWith(lowerB) || lowerB.startsWith(lowerA)) {
  		return 1;
  	}
  
  	if (lowerA.includes(lowerB) || lowerB.includes(lowerA)) {
  		return 2;
  	}
  
  	return 3;
  };