Apple Dev MCP Server

Instructions

Implementation Reference

• src/tools.ts:30-102 (handler)

  The core handler function implementing the tool logic: input validation, static content search with fallback to hardcoded HIG results, and result formatting.
  async searchHumanInterfaceGuidelines(args: SearchGuidelinesArgs): Promise<{ results: SearchResult[]; total: number; query: string; filters: { platform?: ApplePlatform; category?: string; }; }> { // Input validation if (!args || typeof args !== 'object') { throw new Error('Invalid arguments: expected object'); } const { query, platform } = args; const limit = 3; // Return top 3 results with full content // Validate required parameters if (typeof query !== 'string') { throw new Error('Invalid query: must be a string'); } // Handle empty/whitespace queries gracefully if (query.trim().length === 0) { return { results: [], total: 0, query: query.trim(), filters: { platform } }; } if (query.length > 100) { throw new Error('Query too long: maximum 100 characters allowed'); } // Validate optional parameters if (platform && !['iOS', 'macOS', 'watchOS', 'tvOS', 'visionOS', 'universal'].includes(platform)) { args.platform = 'universal'; } try { let results: SearchResult[] = []; // Use static content search as primary source (fast and reliable) try { results = await this.staticContentSearch.searchContent(query.trim(), args.platform, undefined, limit); // If static content search returns no results, fall back to minimal results if (results.length === 0) { results = this.getMinimalFallbackResults(query.trim(), platform, limit); } } catch { // Fall back to minimal hardcoded results results = this.getMinimalFallbackResults(query.trim(), platform, limit); } return { results: results.slice(0, limit), total: results.length, query: query.trim(), filters: { platform } }; } catch (error) { const errorMessage = error instanceof Error ? error.message : 'Unknown error'; throw new Error(`Search failed: ${errorMessage}`); } }
• src/server.ts:137-154 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, title, description, and input schema.
  name: 'search_human_interface_guidelines', title: 'Search HIG Guidelines', description: 'Search Apple Human Interface Guidelines by keywords', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query (keywords, component names, design concepts)', }, platform: { type: 'string', enum: ['iOS', 'macOS', 'watchOS', 'tvOS', 'visionOS', 'universal'], description: 'Optional: Filter by Apple platform', }, }, required: ['query'], },
• src/types.ts:164-169 (schema)

  TypeScript interface defining the input arguments for the handler function.
  export interface SearchGuidelinesArgs { query: string; platform?: ApplePlatform; category?: HIGCategory; limit?: number; }
• src/server.ts:243-245 (registration)

  Tool dispatch in the CallToolRequestSchema handler, routing calls to the HIGToolProvider method.
  case 'search_human_interface_guidelines': { result = await this.toolProvider.searchHumanInterfaceGuidelines(args as any); break;
• src/tools.ts:107-182 (helper)

  Helper method providing fallback search results using hardcoded HIG data when primary search fails.
  private getMinimalFallbackResults(query: string, platform?: ApplePlatform, limit: number = 3): SearchResult[] { const queryLower = query.toLowerCase(); const fallbackData = [ // Buttons & Touch Targets { keywords: ['button', 'btn', 'press', 'tap', 'click'], title: 'Buttons', platform: 'iOS', category: 'visual-design', url: 'https://developer.apple.com/design/human-interface-guidelines/buttons', snippet: 'Buttons initiate app-specific actions, have customizable backgrounds, and can include a title or an icon. Minimum touch target size is 44pt x 44pt.' }, { keywords: ['touch', 'targets', '44pt', 'minimum', 'size', 'accessibility'], title: 'Touch Targets & Accessibility', platform: 'iOS', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/accessibility', snippet: 'Interactive elements must be large enough for people to interact with easily. A minimum touch target size of 44pt x 44pt ensures accessibility.' }, // Navigation { keywords: ['navigation', 'nav', 'navigate', 'menu', 'bar'], title: 'Navigation Bars', platform: 'iOS', category: 'navigation', url: 'https://developer.apple.com/design/human-interface-guidelines/navigation-bars', snippet: 'A navigation bar appears at the top of an app screen, enabling navigation through a hierarchy of content.' }, { keywords: ['tab', 'tabs', 'bottom'], title: 'Tab Bars', platform: 'iOS', category: 'navigation', url: 'https://developer.apple.com/design/human-interface-guidelines/tab-bars', snippet: 'A tab bar appears at the bottom of an app screen and provides the ability to quickly switch between different sections of an app.' }, // Layout & Design { keywords: ['layout', 'grid', 'spacing', 'margin'], title: 'Layout', platform: 'universal', category: 'layout', url: 'https://developer.apple.com/design/human-interface-guidelines/layout', snippet: 'A consistent layout that adapts to various devices and contexts makes your app easier to use and helps people feel confident.' }, { keywords: ['color', 'colours', 'theme', 'dark', 'light'], title: 'Color', platform: 'universal', category: 'color-and-materials', url: 'https://developer.apple.com/design/human-interface-guidelines/color', snippet: 'Color can indicate interactivity, impart vitality, and provide visual continuity.' }, { keywords: ['typography', 'text', 'font', 'size'], title: 'Typography', platform: 'universal', category: 'typography', url: 'https://developer.apple.com/design/human-interface-guidelines/typography', snippet: 'Typography can help you clarify a hierarchy of information and make it easy for people to find what they\'re looking for.' }, // Accessibility & Contrast { keywords: ['accessibility', 'a11y', 'voiceover', 'accessible'], title: 'Accessibility', platform: 'universal', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/accessibility', snippet: 'People use Apple accessibility features to personalize how they interact with their devices in ways that work for them.' }, { keywords: ['contrast', 'color', 'wcag', 'visibility', 'readability'], title: 'Color Contrast & Accessibility', platform: 'universal', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/accessibility', snippet: 'Ensure sufficient color contrast for text and UI elements. Follow WCAG guidelines with minimum 4.5:1 contrast ratio for normal text.' }, // Custom Interface Patterns { keywords: ['custom', 'interface', 'patterns', 'design', 'user', 'expectations'], title: 'Custom Interface Patterns', platform: 'universal', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/', snippet: 'When creating custom interfaces, maintain consistency with platform conventions and user expectations to ensure familiarity and usability.' }, { keywords: ['user', 'interface', 'standards', 'guidelines', 'principles'], title: 'User Interface Standards', platform: 'universal', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/', snippet: 'Follow established interface standards and design principles to create intuitive, accessible, and consistent user experiences across Apple platforms.' }, // Visual Effects { keywords: ['gradients', 'materials', 'visual', 'effects'], title: 'Materials & Visual Effects', platform: 'universal', category: 'color-and-materials', url: 'https://developer.apple.com/design/human-interface-guidelines/materials', snippet: 'Use system materials and visual effects thoughtfully to create depth and hierarchy while maintaining clarity and performance.' }, // Input & Controls { keywords: ['input', 'field', 'form', 'text'], title: 'Text Fields', platform: 'iOS', category: 'selection-and-input', url: 'https://developer.apple.com/design/human-interface-guidelines/text-fields', snippet: 'A text field is a rectangular area in which people enter or edit small, specific pieces of text.' }, { keywords: ['picker', 'select', 'choose'], title: 'Pickers', platform: 'iOS', category: 'selection-and-input', url: 'https://developer.apple.com/design/human-interface-guidelines/pickers', snippet: 'A picker displays one or more scrollable lists of distinct values that people can choose from.' }, // Platform specific { keywords: ['vision', 'visionos', 'spatial', 'immersive', 'ar', 'vr'], title: 'Designing for visionOS', platform: 'visionOS', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos', snippet: 'visionOS brings together digital and physical worlds, creating opportunities for new types of immersive experiences.' }, { keywords: ['watch', 'watchos', 'complication', 'crown'], title: 'Designing for watchOS', platform: 'watchOS', category: 'foundations', url: 'https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos', snippet: 'Apple Watch is a highly personal device that people wear on their wrist, making it instantly accessible.' } ]; const results: SearchResult[] = []; fallbackData.forEach((item, index) => { let relevanceScore = 0; // Check for keyword matches const hasKeywordMatch = item.keywords.some(keyword => queryLower.includes(keyword) || keyword.includes(queryLower)); if (hasKeywordMatch) { relevanceScore = 1.0; } // Check title match if (item.title.toLowerCase().includes(queryLower)) { relevanceScore = Math.max(relevanceScore, 0.8); } // Apply platform filter if (platform && platform !== 'universal' && item.platform !== platform && item.platform !== 'universal') { return; } if (relevanceScore > 0) { results.push({ id: `fallback-${index}`, title: item.title, url: item.url, platform: item.platform as ApplePlatform, relevanceScore, content: item.snippet, type: 'guideline' as const }); } }); // Sort by relevance score and return top results return results .sort((a, b) => b.relevanceScore - a.relevanceScore) .slice(0, limit); }