@mweinbach/apple-docs-mcp 1.0.0

package/dist/tools/definitions.js

@@ -0,0 +1,690 @@
+/**
+ * Tool definitions for Apple Developer Documentation MCP Server
+ * Optimized for agent context windows with compact output support
+ */
+import { searchFrameworkSymbolsTool } from './search-framework-symbols.js';
+import { API_LIMITS, WWDC_CONFIG } from '../utils/constants.js';
+/**
+ * All available tools
+ */
+export const toolDefinitions = [
+    // ============================================================================
+    // UNIFIED TOOLS - Recommended for most use cases
+    // ============================================================================
+    {
+        name: 'apple_docs',
+        description: 'Universal Apple documentation access. Automatically routes your query to the appropriate tool. BEST STARTING POINT for any Apple development question. Supports: search, docs, wwdc, samples, technologies. WORKFLOW: Use for discovery, then get_apple_doc_content for details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language query or Apple doc URL. Examples: "SwiftUI List docs", "WWDC async/await videos", "https://developer.apple.com/documentation/swiftui/list"',
+                },
+                intent: {
+                    type: 'string',
+                    enum: ['auto', 'search', 'docs', 'wwdc', 'samples', 'technologies'],
+                    description: 'Optional routing hint. "auto" detects from query. Default: "auto"',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output (titles + URLs). Recommended for discovery. Default: false',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'wwdc',
+        description: 'Unified WWDC video access. Actions: list (browse), search (full-text), get (details), code (examples), topics (browse), related (find similar), years (list all). WORKFLOW: Use with compact:true for discovery, then get action for full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'search', 'get', 'code', 'topics', 'related', 'years'],
+                    description: 'Action: list=browse videos, search=full-text search, get=video details, code=code examples, topics=browse topics, related=find related, years=list years',
+                },
+                year: {
+                    type: 'string',
+                    description: 'WWDC year (e.g., "2024", "2025")',
+                },
+                videoId: {
+                    type: 'string',
+                    description: 'Video ID (for get/related actions)',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query (for search action)',
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Topic filter (topic ID or keyword)',
+                },
+                framework: {
+                    type: 'string',
+                    description: 'Framework filter (for code action)',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${WWDC_CONFIG.DEFAULT_VIDEO_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Recommended for discovery. Default: false',
+                },
+                searchIn: {
+                    type: 'string',
+                    enum: ['transcript', 'code', 'both'],
+                    description: 'Search scope (for search action). Default: "both"',
+                },
+                hasCode: {
+                    type: 'boolean',
+                    description: 'Filter by code availability (for list action)',
+                },
+                includeTranscript: {
+                    type: 'boolean',
+                    description: 'Include transcript (for get action). Default: true',
+                },
+                includeCode: {
+                    type: 'boolean',
+                    description: 'Include code examples (for get action). Default: true',
+                },
+                includeVideos: {
+                    type: 'boolean',
+                    description: 'Include videos in topic (for topics action). Default: true',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Filter code by language (swift, objc, etc.)',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'analyze_api',
+        description: 'Unified API analysis. Combines related APIs, similar APIs, and reference resolution. Actions: related (inheritance/protocols), similar (alternatives), references (type resolution), all (comprehensive). WORKFLOW: Use after get_apple_doc_content for deeper analysis.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apiUrl: {
+                    type: 'string',
+                    description: 'Apple documentation URL to analyze',
+                },
+                analysis: {
+                    type: 'string',
+                    enum: ['related', 'similar', 'references', 'all'],
+                    description: 'Analysis type: related=inheritance/protocols, similar=alternatives, references=type resolution, all=comprehensive',
+                },
+                includeInherited: {
+                    type: 'boolean',
+                    description: 'Include inherited APIs (for related). Default: true',
+                },
+                includeConformance: {
+                    type: 'boolean',
+                    description: 'Include protocol conformances (for related). Default: true',
+                },
+                includeSeeAlso: {
+                    type: 'boolean',
+                    description: 'Include "See Also" section (for related). Default: true',
+                },
+                searchDepth: {
+                    type: 'string',
+                    enum: ['shallow', 'medium', 'deep'],
+                    description: 'Search depth (for similar). Default: "medium"',
+                },
+                filterByCategory: {
+                    type: 'string',
+                    description: 'Filter by category (for similar)',
+                },
+                maxReferences: {
+                    type: 'number',
+                    description: `Max references to resolve (default: ${API_LIMITS.DEFAULT_REFERENCES_LIMIT}, max: ${API_LIMITS.MAX_REFERENCES_LIMIT})`,
+                },
+                filterByType: {
+                    type: 'string',
+                    enum: ['all', 'symbol', 'collection', 'article', 'protocol', 'class', 'struct', 'enum'],
+                    description: 'Filter references by type. Default: "all"',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Recommended for discovery. Default: false',
+                },
+            },
+            required: ['apiUrl', 'analysis'],
+        },
+    },
+    {
+        name: 'get_tool_guide',
+        description: 'Get guidance on which tools to use for a specific task. Call when unsure which tool is best. Returns recommended tools and suggested workflows.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'Description of what you want to accomplish. Examples: "learn SwiftUI", "find WWDC videos about concurrency", "check iOS 17 API availability"',
+                },
+            },
+            required: ['task'],
+        },
+    },
+    // ============================================================================
+    // CORE DOCUMENTATION TOOLS
+    // ============================================================================
+    {
+        name: 'search_apple_docs',
+        description: 'Search Apple Developer Documentation. NEXT STEPS: Use returned URLs with get_apple_doc_content for full docs. For WWDC videos, use wwdc tool instead. For samples, use get_sample_code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search query. Tips: Use specific API names (e.g., "UIViewController"), framework names (e.g., "SwiftUI"). Avoid generic terms.',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['all', 'documentation', 'sample'],
+                    description: 'Content type filter. Default: "all"',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output (titles + URLs). Recommended for discovery. Default: false',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_apple_doc_content',
+        description: 'Get detailed content from a specific Apple documentation page. Use after search_apple_docs. NEXT STEPS: Use analyze_api for deeper analysis, or get_platform_compatibility for availability info.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Apple documentation URL. Must start with https://developer.apple.com/documentation/',
+                },
+                includeRelatedApis: {
+                    type: 'boolean',
+                    description: 'Include inheritance/protocols. Default: false',
+                },
+                includeReferences: {
+                    type: 'boolean',
+                    description: 'Resolve referenced types. Default: false',
+                },
+                includeSimilarApis: {
+                    type: 'boolean',
+                    description: 'Find similar APIs. Default: false',
+                },
+                includePlatformAnalysis: {
+                    type: 'boolean',
+                    description: 'Analyze platform availability. Default: false',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'list_technologies',
+        description: 'Browse Apple frameworks by category. NEXT STEPS: Use framework identifiers with search_framework_symbols to explore APIs. Use compact:true for quick overview.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Filter by category. Popular: "App frameworks", "Graphics and games", "App services"',
+                },
+                language: {
+                    type: 'string',
+                    enum: ['swift', 'occ'],
+                    description: 'Filter by language. Leave empty for all.',
+                },
+                includeBeta: {
+                    type: 'boolean',
+                    description: 'Include beta technologies. Default: true',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${API_LIMITS.DEFAULT_TECHNOLOGIES_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Recommended for discovery. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    searchFrameworkSymbolsTool,
+    {
+        name: 'get_sample_code',
+        description: 'Browse complete sample projects from Apple. Full working examples with best practices. NEXT STEPS: Download and explore projects for implementation patterns.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                framework: {
+                    type: 'string',
+                    description: 'Framework filter (case-insensitive). Examples: "SwiftUI", "ARKit", "CoreML"',
+                },
+                beta: {
+                    type: 'string',
+                    enum: ['include', 'exclude', 'only'],
+                    description: 'Beta samples: "include", "exclude", or "only". Default: "include"',
+                },
+                searchQuery: {
+                    type: 'string',
+                    description: 'Search keywords. Most effective approach.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${API_LIMITS.DEFAULT_SAMPLE_CODE_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_documentation_updates',
+        description: 'Track latest Apple platform updates and new APIs. Shows WWDC announcements, framework updates, release notes. For detailed WWDC videos, use wwdc tool.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    enum: ['all', 'wwdc', 'technology', 'release-notes'],
+                    description: 'Update type filter. Default: "all"',
+                },
+                technology: {
+                    type: 'string',
+                    description: 'Filter by framework name (case-sensitive)',
+                },
+                year: {
+                    type: 'string',
+                    description: 'WWDC year filter. Only for wwdc category.',
+                },
+                searchQuery: {
+                    type: 'string',
+                    description: 'Search keywords',
+                },
+                includeBeta: {
+                    type: 'boolean',
+                    description: 'Include beta features. Default: true',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${API_LIMITS.DEFAULT_DOCUMENTATION_UPDATES_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_technology_overviews',
+        description: 'Access comprehensive guides and tutorials. Includes getting started guides, architectural overviews, best practices. NEXT STEPS: Use get_apple_doc_content for specific API details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Topic category. Popular: "app-design-and-ui", "games", "ai-machine-learning"',
+                },
+                platform: {
+                    type: 'string',
+                    enum: ['all', 'ios', 'macos', 'watchos', 'tvos', 'visionos'],
+                    description: 'Target platform. Default: "all"',
+                },
+                searchQuery: {
+                    type: 'string',
+                    description: 'Search terms',
+                },
+                includeSubcategories: {
+                    type: 'boolean',
+                    description: 'Include nested topics. Default: true',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${API_LIMITS.DEFAULT_TECHNOLOGY_OVERVIEWS_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_platform_compatibility',
+        description: 'Check API availability across Apple platforms and OS versions. Critical for cross-platform development. Shows minimum deployment targets and deprecations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apiUrl: {
+                    type: 'string',
+                    description: 'API URL to check compatibility',
+                },
+                compareMode: {
+                    type: 'string',
+                    enum: ['single', 'framework'],
+                    description: 'Check single API or entire framework. Default: "single"',
+                },
+                includeRelated: {
+                    type: 'boolean',
+                    description: 'Also check related APIs. Default: false',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['apiUrl'],
+        },
+    },
+    // ============================================================================
+    // LEGACY TOOLS - Kept for compatibility, prefer unified tools
+    // ============================================================================
+    {
+        name: 'get_related_apis',
+        description: '[Use analyze_api instead] Analyze API relationships. Shows inheritance, protocols, and See Also. NEXT STEPS: Use get_apple_doc_content on returned URLs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apiUrl: {
+                    type: 'string',
+                    description: 'Apple documentation URL to analyze',
+                },
+                includeInherited: {
+                    type: 'boolean',
+                    description: 'Show inherited APIs. Default: true',
+                },
+                includeConformance: {
+                    type: 'boolean',
+                    description: 'Show protocol conformances. Default: true',
+                },
+                includeSeeAlso: {
+                    type: 'boolean',
+                    description: 'Show See Also section. Default: true',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['apiUrl'],
+        },
+    },
+    {
+        name: 'resolve_references_batch',
+        description: '[Use analyze_api instead] Resolve all types referenced in a documentation page. Helps understand dependencies.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sourceUrl: {
+                    type: 'string',
+                    description: 'Documentation URL to analyze',
+                },
+                maxReferences: {
+                    type: 'number',
+                    description: `Max references (default: ${API_LIMITS.DEFAULT_REFERENCES_LIMIT}, max: ${API_LIMITS.MAX_REFERENCES_LIMIT})`,
+                },
+                filterByType: {
+                    type: 'string',
+                    enum: ['all', 'symbol', 'collection', 'article', 'protocol', 'class', 'struct', 'enum'],
+                    description: 'Filter by reference type. Default: "all"',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['sourceUrl'],
+        },
+    },
+    {
+        name: 'find_similar_apis',
+        description: '[Use analyze_api instead] Discover alternative APIs. Finds modern replacements for deprecated APIs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apiUrl: {
+                    type: 'string',
+                    description: 'Starting API URL',
+                },
+                searchDepth: {
+                    type: 'string',
+                    enum: ['shallow', 'medium', 'deep'],
+                    description: 'Search depth. Default: "medium"',
+                },
+                filterByCategory: {
+                    type: 'string',
+                    description: 'Focus on specific functionality',
+                },
+                includeAlternatives: {
+                    type: 'boolean',
+                    description: 'Include similar APIs. Default: true',
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['apiUrl'],
+        },
+    },
+    {
+        name: 'list_wwdc_videos',
+        description: '[Use wwdc tool instead] Browse WWDC videos. NEXT STEPS: Use get_wwdc_video for full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                year: {
+                    type: 'string',
+                    description: 'WWDC year or "all"',
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Topic ID or keyword',
+                },
+                hasCode: {
+                    type: 'boolean',
+                    description: 'Filter by code availability',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max videos (default: ${WWDC_CONFIG.DEFAULT_VIDEO_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'search_wwdc_content',
+        description: '[Use wwdc tool instead] Full-text search across WWDC transcripts and code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search terms',
+                },
+                searchIn: {
+                    type: 'string',
+                    enum: ['transcript', 'code', 'both'],
+                    description: 'Search scope. Default: "both"',
+                },
+                year: {
+                    type: 'string',
+                    description: 'Limit to specific year',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Code language filter',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max results (default: ${WWDC_CONFIG.DEFAULT_SEARCH_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_wwdc_video',
+        description: '[Use wwdc tool instead] Get complete WWDC session content with transcript and code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                year: {
+                    type: 'string',
+                    description: 'WWDC year',
+                },
+                videoId: {
+                    type: 'string',
+                    description: 'Session ID',
+                },
+                includeTranscript: {
+                    type: 'boolean',
+                    description: 'Include transcript. Default: true',
+                },
+                includeCode: {
+                    type: 'boolean',
+                    description: 'Include code examples. Default: true',
+                },
+            },
+            required: ['year', 'videoId'],
+        },
+    },
+    {
+        name: 'get_wwdc_code_examples',
+        description: '[Use wwdc tool instead] Browse code examples from WWDC sessions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                framework: {
+                    type: 'string',
+                    description: 'Framework filter',
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Topic filter',
+                },
+                year: {
+                    type: 'string',
+                    description: 'WWDC year filter',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Programming language filter',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max examples (default: ${WWDC_CONFIG.DEFAULT_CODE_EXAMPLES_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'browse_wwdc_topics',
+        description: '[Use wwdc tool instead] List WWDC topic categories.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topicId: {
+                    type: 'string',
+                    description: 'Topic ID to explore',
+                },
+                includeVideos: {
+                    type: 'boolean',
+                    description: 'Include video list. Default: true',
+                },
+                year: {
+                    type: 'string',
+                    description: 'Filter by year',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max videos (default: ${WWDC_CONFIG.DEFAULT_TOPIC_VIDEOS_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'find_related_wwdc_videos',
+        description: '[Use wwdc tool instead] Find related WWDC sessions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                videoId: {
+                    type: 'string',
+                    description: 'Source video ID',
+                },
+                year: {
+                    type: 'string',
+                    description: 'Source video year',
+                },
+                includeExplicitRelated: {
+                    type: 'boolean',
+                    description: 'Include explicit related. Default: true',
+                },
+                includeTopicRelated: {
+                    type: 'boolean',
+                    description: 'Include topic related. Default: true',
+                },
+                includeYearRelated: {
+                    type: 'boolean',
+                    description: 'Include same year. Default: false',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Max related (default: ${WWDC_CONFIG.DEFAULT_RELATED_VIDEOS_LIMIT})`,
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return minimal output. Default: false',
+                },
+            },
+            required: ['videoId', 'year'],
+        },
+    },
+    {
+        name: 'list_wwdc_years',
+        description: '[Use wwdc tool instead] List available WWDC years with video counts.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+];
+//# sourceMappingURL=definitions.js.map