Apple Doc MCP

Instructions

Implementation Reference

• src/server/handlers/discover.ts:22-73 (handler)

  Core handler factory for discover_technologies tool: fetches all technologies via client.getTechnologies(), filters frameworks by query, handles pagination, stores last discovery in state, and generates formatted markdown response with select instructions.

  export const buildDiscoverHandler = ({client, state}: ServerContext) =>
  	async (args: {query?: string; page?: number; pageSize?: number}): Promise<ToolResponse> => {
  		const {query, page = 1, pageSize = 25} = args;
  		const technologies = await client.getTechnologies();
  		const frameworks = Object.values(technologies).filter(tech => tech.kind === 'symbol' && tech.role === 'collection');
  
  		let filtered = frameworks;
  		if (query) {
  			const lowerQuery = query.toLowerCase();
  			filtered = frameworks.filter(tech =>
  				tech.title.toLowerCase().includes(lowerQuery)
  				|| client.extractText(tech.abstract).toLowerCase().includes(lowerQuery));
  		}
  
  		const totalPages = Math.max(1, Math.ceil(filtered.length / pageSize));
  		const currentPage = Math.min(Math.max(page, 1), totalPages);
  		const start = (currentPage - 1) * pageSize;
  		const pageItems = filtered.slice(start, start + pageSize);
  
  		state.setLastDiscovery({query, results: pageItems});
  
  		const lines: string[] = [
  			header(1, `Discover Apple Technologies${query ? ` (filtered by "${query}")` : ''}`),
  			'\n',
  			bold('Total frameworks', frameworks.length.toString()),
  			bold('Matches', filtered.length.toString()),
  			bold('Page', `${currentPage} / ${totalPages}`),
  			'\n',
  			header(2, 'Available Frameworks'),
  		];
  
  		for (const framework of pageItems) {
  			const description = client.extractText(framework.abstract);
  			lines.push(`### ${framework.title}`);
  			if (description) {
  				lines.push(`   ${trimWithEllipsis(description, 180)}`);
  			}
  
  			lines.push(`   • **Identifier:** ${framework.identifier}`, `   • **Select:** \`choose_technology "${framework.title}"\``, '');
  		}
  
  		lines.push(...formatPagination(query, currentPage, totalPages), '\n## Next Step', 'Call `choose_technology` with the framework title or identifier to make it active.');
  
  		return {
  			content: [
  				{
  					text: lines.join('\n'),
  					type: 'text',
  				},
  			],
  		};
  	};

• src/server/tools.ts:23-40 (schema)

  Input schema definition for discover_technologies tool, defining optional page, pageSize, and query parameters.

  inputSchema: {
  	type: 'object',
  	required: [],
  	properties: {
  		page: {
  			type: 'number',
  			description: 'Optional page number (default 1)',
  		},
  		pageSize: {
  			type: 'number',
  			description: 'Optional page size (default 25, max 100)',
  		},
  		query: {
  			type: 'string',
  			description: 'Optional keyword to filter technologies',
  		},
  	},
  },

• src/server/tools.ts:20-42 (registration)

  Tool registration entry in toolDefinitions array, including name, description, inputSchema, and handler factory call.

  {
  	name: 'discover_technologies',
  	description: 'Explore and filter available Apple technologies/frameworks before choosing one',
  	inputSchema: {
  		type: 'object',
  		required: [],
  		properties: {
  			page: {
  				type: 'number',
  				description: 'Optional page number (default 1)',
  			},
  			pageSize: {
  				type: 'number',
  				description: 'Optional page size (default 25, max 100)',
  			},
  			query: {
  				type: 'string',
  				description: 'Optional keyword to filter technologies',
  			},
  		},
  	},
  	handler: buildDiscoverHandler(context),
  },

• src/server/handlers/discover.ts:4-20 (helper)

  Helper function to generate pagination navigation strings for the tool response.

  const formatPagination = (query: string | undefined, currentPage: number, totalPages: number): string[] => {
  	if (totalPages <= 1) {
  		return [];
  	}
  
  	const safeQuery = query ?? '';
  	const items: string[] = [];
  	if (currentPage > 1) {
  		items.push(`• Previous: \`discover_technologies { "query": "${safeQuery}", "page": ${currentPage - 1} }\``);
  	}
  
  	if (currentPage < totalPages) {
  		items.push(`• Next: \`discover_technologies { "query": "${safeQuery}", "page": ${currentPage + 1} }\``);
  	}
  
  	return ['*Pagination*', ...items];
  };