Apple Docs MCP - 苹果开发者文档模型上下文协议服务器

苹果开发者文档 MCP 服务器——通过模型上下文协议访问苹果官方开发者文档、框架、API、SwiftUI、UIKit 以及 WWDC 视频。使用人工智能驱动的自然语言查询搜索 iOS、macOS、watchOS、tvOS 和 visionOS 文档。直接在 Claude、Cursor 或任何兼容 MCP 的 AI 助手中即时获取 Swift/Objective-C 代码示例、API 参考和技术指南。

English | 日本語 | 한국어 | 简体中文

✨ 特性

• 🔍 智能搜索：跨 SwiftUI、UIKit、Foundation、CoreData、ARKit 等苹果开发者文档进行智能搜索
• 📚 完整文档访问：全面访问苹果的 JSON API，涵盖 Swift、Objective-C 和框架文档
• 🔧 框架索引：浏览 iOS、macOS、watchOS、tvOS、visionOS 框架的层级式 API 结构
• 📋 技术目录：探索包括 SwiftUI、UIKit、Metal、Core ML、Vision 和 ARKit 在内的苹果技术
• 📰 文档更新：跟踪 WWDC 2024/2025 发布内容、iOS 26、macOS 26 以及最新 SDK 发布信息
• 🎯 技术概览：针对 Swift、SwiftUI、UIKit 和所有苹果开发平台的全面指南
• 💻 示例代码库：适用于 iOS、macOS 和跨平台开发的 Swift 和 Objective-C 代码示例
• 🎥 WWDC 视频库：可搜索 2014–2025 年的 WWDC 会议视频，附带字幕、Swift/SwiftUI 代码示例及资源
• 🔗 相关 API 发现：查找 SwiftUI 视图、UIKit 控制器以及特定框架的 API 关系
• 📊 平台兼容性：分析 iOS 13+、macOS 10.15+、watchOS 6+、tvOS 13+ 和 visionOS 的兼容性
• ⚡ 高性能：专为 Xcode、Swift Playgrounds 和人工智能驱动的开发环境优化
• 🔄 智能 UserAgent 池：具备自动故障恢复和性能监控的智能 UserAgent 轮换系统
• 🌐 多平台支持：全面支持 iOS、iPadOS、macOS、watchOS、tvOS 和 visionOS 文档
• 🏷️ Beta 版与状态追踪：追踪 iOS 26 Beta 版 API、已弃用的 UIKit 方法以及新的 SwiftUI 功能

🚀 快速入门

Claude Desktop（推荐）

将以下内容添加到你的 Claude Desktop 配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

注意：如果遇到旧版本被使用的问题，请添加 @latest 强制使用最新版本：

"args": ["-y", "@kimsungwhee/apple-docs-mcp@latest"]

重启 Claude Desktop，即可开始询问关于苹果 API 的问题！

📦 安装

claude mcp add apple-docs -- npx -y @kimsungwhee/apple-docs-mcp@latest

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "apple-docs": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
      }
    }
  }
}

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

{
  "context_servers": {
    "Apple Docs": {
      "command": {
        "path": "npx",
        "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
      },
      "settings": {}
    }
  }
}

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

{
  "mcpServers": {
    "apple-docs": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@kimsungwhee/apple-docs-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

# 使用 pnpm（推荐）
pnpm add -g @kimsungwhee/apple-docs-mcp

# 使用 npm
npm install -g @kimsungwhee/apple-docs-mcp

npx @kimsungwhee/apple-docs-mcp --help

git clone https://github.com/kimsungwhee/apple-docs-mcp.git
cd apple-docs-mcp

# 使用 pnpm（推荐）
pnpm install && pnpm run build

# 使用 npm
npm install && npm run build

💬 使用示例

🔍 智能搜索

“搜索 SwiftUI 动画”
“查找 withAnimation API 文档”
“在 Swift 中查找 async/await 模式”
“给我看看 UITableView 的代理方法”
“搜索 Core Data NSPersistentContainer 示例”
“查找 AVFoundation 视频播放 API”

📚 文档访问

"获取 SwiftUI 框架的详细信息"
"向我展示 withAnimation API 及其相关 API"
"获取 SwiftData 的平台兼容性信息"
"访问 UIViewController 文档及其类似 API"
"向我展示 NSManagedObjectContext 文档"
"获取 URLSession 的 async/await 方法"

🔧 框架探索

"向我展示 SwiftUI 框架的 API 索引"
"列出所有 UIKit 类和方法"
"浏览 ARKit 框架的结构"
"获取 WeatherKit API 层次结构"
"探索 Core ML 模型加载 API"
"展示 Vision 框架的图像分析 API"

🔗 API 发现

"查找与 UIViewController 相关的 API"
"向我展示与 withAnimation 类似的 API"
"从 SwiftData 文档中获取所有引用"
"发现 Core Data NSManagedObject 的替代方案"

📋 技术与平台分析

"列出 iOS 26 中的所有 Beta 框架"
"向我展示图形与游戏技术"
"有哪些可用的机器学习框架？"
"分析 Vision 框架的平台兼容性"

📰 文档更新

"向我展示最新的 WWDC 更新"
"SwiftUI 有哪些新功能？"
"获取 iOS 的技术更新"
"向我展示 Xcode 的发布说明"
"在最新更新中查找 Beta 功能"

🎯 技术概览

"向我展示用于应用设计和 UI 的技术概览"
"获取游戏开发的综合指南"
"探索 AI 和机器学习的技术概览"
"向我展示 iOS 特有的技术指南"
"获取数据管理技术概览"

💻 示例代码库

"展示 SwiftUI 示例代码项目"
"查找机器学习示例代码"
"获取 UIKit 示例项目"
"展示 WWDC 精选示例代码"
"查找 Core Data 示例实现"
"仅展示 Beta 示例代码项目"

🎥 WWDC 视频搜索

"搜索关于 SwiftUI 的 WWDC 视频"
"查找关于机器学习的 WWDC 会议"
"向我展示 2024 年 WWDC 视频"
"搜索关于 async/await 的 WWDC 演讲"
"查找关于 Swift 并发的 WWDC 视频"
"展示以无障碍为主题的 WWDC 会议"

📺 WWDC 视频详情

"获取 WWDC 会议 10176 的详细信息"
"向我展示 WWDC23 关于 SwiftData 会议的逐字稿"
"从 WWDC 视频 10019 中获取代码示例"
"展示 Vision Pro WWDC 会议的相关资源"
"获取 '了解 Swift 中的 async/await' 会议的逐字稿"

📋 WWDC 主题与年份

"列出所有 WWDC 主题"
"向我展示关于 Swift 主题的 WWDC 视频"
"获取关于开发者工具的 WWDC 视频"
"列出 2023 年的 WWDC 视频"
"展示所有关于 SwiftUI 和 UI 框架的会议"
"获取关于机器学习的 WWDC 内容"

🛠️ 高级用法

"结合平台分析，查找 @State 的相关 API"
"解析 SwiftUI 文档中的所有引用"
"获取 Vision 框架的平台兼容性分析"
"通过深度搜索找到与 UIViewController 类似的 API"

🛠️ 可用工具

🏗️ Apple 开发者文档访问的技术架构

apple-docs-mcp/
├── 🔧 src/
│   ├── index.ts                      # MCP 服务器入口，包含所有工具
│   ├── tools/                        # MCP 工具实现
│   │   ├── search-parser.ts          # 解析 HTML 搜索结果
│   │   ├── doc-fetcher.ts            # 使用 JSON API 获取文档
│   │   ├── list-technologies.ts      # 处理技术目录
│   │   ├── get-documentation-updates.ts # 跟踪文档更新
│   │   ├── get-technology-overviews.ts # 技术概览和指南
│   │   ├── get-sample-code.ts        # 浏览示例代码库
│   │   ├── get-framework-index.ts    # 构建框架结构索引
│   │   ├── get-related-apis.ts       # 发现相关 API
│   │   ├── resolve-references-batch.ts # 批量解析引用
│   │   ├── get-platform-compatibility.ts # 进行平台分析
│   │   ├── find-similar-apis.ts      # 推荐相似 API
│   │   └── wwdc/                     # WWDC 视频工具
│   │       ├── wwdc-handlers.ts      # WWDC 工具处理程序
│   │       ├── content-extractor.ts  # 提取视频内容
│   │       ├── topics-extractor.ts   # 提取主题
│   │       └── video-list-extractor.ts # 解析视频列表
│   └── utils/                        # 实用函数和辅助工具
│       ├── cache.ts                  # 带有 TTL 支持的内存缓存
│       ├── constants.ts              # 应用常量和 URL
│       ├── error-handler.ts          # 错误处理和验证
│       ├── http-client.ts            # 带性能监控的 HTTP 客户端
│       ├── user-agent-pool.ts        # 智能 UserAgent 轮换系统
│       ├── http-headers-generator.ts # 动态浏览器头生成
│       └── url-converter.ts          # URL 转换实用工具
├── 📦 dist/                          # 编译后的 JavaScript
├── 📄 package.json                   # 包配置文件
└── 📖 README.md                      # 本文件

🚀 性能特性

• 基于内存的缓存：自定义缓存实现，支持自动清理和 TTL
• 智能 UserAgent 池：具备自动故障恢复和性能监控的智能轮转系统
• 动态请求头：生成逼真的浏览器请求头（Accept、Accept-Language、User-Agent）
• 智能搜索：使用官方 Apple 搜索 API，并优化结果格式
• 增强分析功能：可选的相关 API、平台兼容性及相似度分析
• 错误韧性：优雅降级与全面的错误处理机制
• 类型安全：完全采用 TypeScript，结合 Zod v4.0.5 进行运行时验证
• 最新依赖：MCP SDK v1.15.1，优化了包体积

💾 缓存策略

📦 WWDC 数据

所有 WWDC 视频数据（2014–2025 年）都直接打包在 npm 包中，提供以下优势：

• ✅ 零网络延迟：无需调用 API 即可获取 WWDC 内容
• ✅ 100% 离线访问：无需互联网连接即可使用
• ✅ 无速率限制：无限进行 WWDC 搜索和浏览
• ✅ 即时响应：所有数据均本地可用

包内包含：

• 📹 1,260+ 场 WWDC 会议视频，附完整字幕
• 🏷️ 20 个主题分类，便于有序浏览
• 📅 13 年的内容（2012–2025 年）
• 💾 35MB 优化后的 JSON 数据

注意：请保持包的更新，以获取最新的 WWDC 内容。

⚙️ 配置

🔄 UserAgent 池配置

MCP 服务器内置智能 UserAgent 轮转系统，以提升 API 可靠性：

环境变量

自定义池配置

# 配置自定义 UserAgent 池
export USER_AGENT_POOL_CONFIG='[
  {"userAgent": "MyApp/1.0 (compatible)", "weight": 3, "maxUsageCount": 1000},
  {"userAgent": "MyApp/2.0 (advanced)", "weight": 2, "maxUsageCount": 800}
]'

# 设置轮转策略（random/sequential/smart）
export USER_AGENT_POOL_STRATEGY=smart

# 启用调试模式
export NODE_ENV=development

可用策略

• random：快速随机选择（性能最佳）
• sequential：轮询轮转（顺序可预测）
• smart：根据成功率优化（可靠性最高）

内置 UserAgent

服务器预置了 12+ 种 UserAgent 字符串，覆盖：

• Chrome（Mac Intel/Apple Silicon、Windows、Linux）
• Firefox（Mac Intel/Apple Silicon、Windows、Linux）
• Safari（Mac Intel/Apple Silicon，最新版本）
• Edge（Windows、Mac Intel/Apple Silicon）

🧪 开发

快速命令

# 开发模式，自动重载
pnpm run dev    # 或：npm run dev

# 生产构建
pnpm run build  # 或：npm run build

# 类型检查
pnpm exec tsc --noEmit  # 或：npx tsc --noEmit

# 清理构建产物
pnpm run clean  # 或：npm run clean

本地测试

# 直接测试 MCP 服务器
node dist/index.js

# 使用示例查询测试
npx @kimsungwhee/apple-docs-mcp --test

🤝 贡献

欢迎贡献代码！开始方法如下：

1. Fork 仓库
2. 创建 功能分支：git checkout -b feature/amazing-feature
3. 提交 更改：git commit -m '添加惊艳功能'
4. 推送 到分支：git push origin feature/amazing-feature
5. 打开 Pull Request

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

⚠️ 免责声明

本项目与 Apple Inc. 无任何关联，亦未获其认可。它仅使用公开的 Apple Developer Documentation API，用于教育和开发目的。

Apple Docs MCP 快速上手指南

Apple Docs MCP 是一个基于模型上下文协议（MCP）的服务器工具，允许 AI 助手（如 Claude、Cursor 等）直接访问 Apple 官方开发者文档、API 参考、Swift/Objective-C 代码示例以及 WWDC 视频资源。通过自然语言查询，即可快速获取 iOS、macOS、watchOS、tvOS 和 visionOS 的最新技术信息。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • macOS 10.15+ (推荐)
  • Windows 10/11
  • Linux
• 前置依赖：
  • Node.js: 需安装 Node.js (建议 v18 或更高版本)，因为该工具通过 npx 运行。
  • MCP 兼容客户端: 已安装并配置好支持 MCP 的 AI 编辑器或桌面应用，例如：
    • Claude Desktop
    • Cursor
    • VS Code (需安装 MCP 相关插件)
    • Windsurf
    • Zed
    • Cline

注意：国内用户若遇到 npm 或 npx 下载缓慢的问题，建议配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

根据您使用的 AI 客户端，选择对应的配置方式。工具无需全局安装，可通过 npx 按需加载。

1. Claude Desktop (推荐)

编辑 Claude Desktop 的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置内容：

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

提示：如果担心版本缓存问题，可将 args 改为 ["-y", "@kimsungwhee/apple-docs-mcp@latest"] 以强制使用最新版。保存后重启 Claude Desktop。

2. Cursor

方法一：通过设置界面 进入 Settings → Cursor Settings → MCP → 点击 Add new global MCP server，输入名称 apple-docs 和命令 npx -y @kimsungwhee/apple-docs-mcp。

方法二：编辑配置文件 编辑 ~/.cursor/mcp.json (Windows 下位于用户目录)，添加：

{
  "mcpServers": {
    "apple-docs": {
      "command": "npx",
      "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

3. VS Code

在 VS Code 的 MCP 配置文件（通常在 .vscode/mcp.json 或通过命令面板配置）中添加：

{
  "mcp": {
    "servers": {
      "apple-docs": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@kimsungwhee/apple-docs-mcp"]
      }
    }
  }
}

4. 其他客户端 (Windsurf / Zed / Cline)

• Windsurf: 配置 mcp.json，结构与 Claude Desktop 类似。
• Zed: 在 settings.json 中配置 context_servers。
• Cline: 可在 Marketplace 搜索 "Apple Docs MCP" 一键安装，或手动编辑 cline_mcp_settings.json。

Windows 用户特别说明： 如果在 Windows 上直接使用 npx 命令失败，请将 command 改为 cmd，并调整 args：

{
  "mcpServers": {
    "apple-docs": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@kimsungwhee/apple-docs-mcp"]
    }
  }
}

基本使用

配置完成后，重启您的 AI 客户端。您可以在对话框中直接使用自然语言询问 Apple 开发相关问题，工具会自动调用文档数据。

简单示例

查询 API 用法：

"查找 SwiftUI 中 withAnimation 的 API 文档和使用示例"

搜索特定框架：

"列出 UIKit 中 UITableView 的所有代理方法"

获取代码示例：

"展示 Core Data 中 NSPersistentContainer 的 Swift 初始化代码"

查询 WWDC 视频：

"搜索关于 Swift 并发编程 (async/await) 的 WWDC 视频会话"

平台兼容性分析：

"分析 Vision 框架在 iOS 和 visionOS 上的兼容性差异"

高级技巧

• 关联发现：询问 "找出与 UIViewController 相关的 API" 可获取继承关系和推荐用法。
• 最新动态：询问 "iOS 26 Beta 有哪些新框架？" 或 "WWDC 2024 有哪些 SwiftUI 更新？" 以获取最新资讯。
• 深度解析：要求 "获取 WWDC session 10176 的文字实录和代码资源" 可深入挖掘会议内容。

现在，您可以开始在 AI 助手中自由探索 Apple 开发生态了！