Cupertino

Cupertino 是一个基于 Swift 的本地化工具，用于爬取、索引并通过模型上下文协议（MCP）向 AI 智能体提供苹果开发者文档。它支持离线访问超过 23 万页的苹果平台文档、Swift 提案、设计指南和示例代码，并通过 SQLite FTS5 搜索引擎实现快速检索。

开发者工具搜索工具 #苹果文档 #本地搜索 #AI助手 #离线开发 .swift

评分 : 2.5分

下载量 : 5.7K

更新时间 : 2025-12-29

打开站点

什么是Cupertino?

Cupertino是一个专门为AI助手设计的本地Apple文档系统。它能够自动抓取、索引并离线存储Apple的官方开发者文档，然后通过Model Context Protocol（MCP）让Claude等AI助手能够准确查询Apple API信息，避免AI幻觉问题。

如何使用Cupertino?

Cupertino提供三种使用方式：1) 一键安装下载预构建数据库（最快，约30秒）；2) 从GitHub流式构建（约45分钟）；3) 完整手动抓取（约20-48小时）。安装后配置Claude Desktop即可使用。

适用场景

Cupertino最适合以下场景：1) 离线开发时需要查阅Apple文档；2) 希望AI助手提供准确的Apple API信息；3) 需要快速搜索Swift Evolution提案；4) 研究Apple设计指南和最佳实践；5) 查找官方示例代码和实现方案。

主要功能

多源文档抓取

支持Apple开发者文档（234,000+页面）、Swift Evolution提案、Swift.org文档、Swift包元数据、Apple示例代码、Apple Archive历史指南、Human Interface Guidelines等7种文档源。

全文搜索引擎

基于SQLite FTS5和BM25排名的快速搜索，支持词干提取（如'running'匹配'run'）、框架过滤、平台版本过滤，查询响应时间<100ms。

MCP协议集成

通过Model Context Protocol为AI助手提供文档访问能力，支持search_docs、search_hig、list_frameworks、read_document等工具调用。

完全离线访问

所有文档本地存储，无需网络连接即可使用。包含287个框架的完整文档，总计234,331个页面。

示例代码搜索

索引606个Apple官方示例项目，18,000+ Swift文件全文搜索，可直接查看项目README和源代码。

预构建数据库

提供一键下载的预构建文档数据库，30秒内完成安装，无需长时间抓取。包含Swift包目录（9,699个包）和示例代码目录。

优势

消除AI幻觉：为AI助手提供准确的Apple API文档，避免错误信息

离线开发：无网络环境下也能访问完整文档

确定性搜索：相同查询总是返回相同结果，可重现

本地控制：完全掌控自己的文档数据，可检查数据库和自定义工作流

AI优先设计：专门为AI助手集成优化，通过MCP协议无缝连接

快速安装：预构建数据库30秒完成安装，无需长时间等待

局限性

仅支持macOS 15+：需要最新macOS系统

初始抓取时间长：完整抓取需要20-48小时（但预构建数据库可避免此问题）

磁盘空间需求：完整文档约需2-3GB存储空间

文档更新延迟：需要手动更新才能获取最新文档

仅限Apple平台：专注于Apple生态，不包含其他平台文档

如何使用

安装Cupertino

选择最适合您的安装方式。推荐使用一键安装命令，最快最简单。

下载文档数据库

使用setup命令下载预构建的文档数据库，这是最快的方式。

配置Claude Desktop

编辑Claude Desktop配置文件，添加Cupertino作为MCP服务器。

重启并开始使用

重启Claude Desktop，现在您可以向Claude询问Apple相关技术问题了。

使用案例

SwiftUI开发查询

在开发SwiftUI应用时，需要查询特定组件的使用方法

Swift语言特性研究

了解Swift Evolution提案中的新语言特性

设计规范查阅

设计iOS应用时需要参考Apple的设计指南

示例代码查找

需要查找特定功能的官方实现示例

API可用性检查

检查某个API支持的最低系统版本

常见问题

Cupertino需要网络连接吗？

为什么抓取文档需要那么长时间？

支持哪些AI助手？

如何更新文档？

可以在非macOS系统上使用吗？

文档数据存储在哪里？

可以只下载特定框架的文档吗？

如何检查服务器是否正常运行？

🚀 ReleaseTool

ReleaseTool 是一款仅由维护者使用的命令行工具（CLI），用于自动化 Cupertino 项目的发布流程，极大地提高了发布效率和准确性。

🚀 快速开始

使用 cupertino-rel 可自动化多步骤的发布流程：

bump - 更新 Constants.swift、README.md、CHANGELOG.md 和 DEPLOYMENT.md 中的版本号。
tag - 提交更改并创建 Git 标签。
databases - 打包并将数据库上传到 cupertino-docs。
homebrew - 用新的 SHA256 更新 Homebrew 公式。
full - 按顺序运行所有步骤（默认）。

📦 安装指南

cd Packages
swift build --product cupertino-rel

💻 使用示例

基础用法

完整发布

# 通过版本号发布
cupertino-rel 0.5.0

# 通过版本更新类型发布
cupertino-rel patch   # 从 0.4.0 到 0.4.1
cupertino-rel minor   # 从 0.4.0 到 0.5.0
cupertino-rel major   # 从 0.4.0 到 1.0.0

# 预览更改而不实际执行
cupertino-rel 0.5.0 --dry-run

单个命令

# 仅更新版本号
cupertino-rel bump 0.5.0
cupertino-rel bump patch --dry-run

# 打标签并推送
cupertino-rel tag --push
cupertino-rel tag --version 0.5.0 --dry-run

# 上传数据库（需要 GITHUB_TOKEN）
export GITHUB_TOKEN="your-cupertino-docs-token"
cupertino-rel databases
cupertino-rel databases --dry-run

# 更新 Homebrew 公式
cupertino-rel homebrew --version 0.5.0
cupertino-rel homebrew --dry-run

跳过选项

# 跳过等待 GitHub Actions
cupertino-rel 0.5.0 --skip-wait

# 跳过数据库上传
cupertino-rel 0.5.0 --skip-databases

# 跳过 Homebrew 更新
cupertino-rel 0.5.0 --skip-homebrew

🔧 技术细节

环境变量

属性	详情
`GITHUB_TOKEN`	用于 `databases` 和 `full` 命令，是对 `cupertino-docs` 仓库具有写入权限的令牌

修改的文件

bump 命令会更新以下文件：

文件	字段
`Packages/Sources/Shared/Constants.swift`	`version = "X.Y.Z"`
`README.md`	`Version: X.Y.Z`
`CHANGELOG.md`	添加 `## X.Y.Z` 章节
`docs/DEPLOYMENT.md`	`Version: X.Y.Z`

为何与 CLI 分离

安全性 - 发布凭证不会暴露给用户。
简洁的用户体验 - 用户仅看到所需的命令。
可维护性 - 发布逻辑可以独立发展。

架构

ReleaseTool/
├── ReleaseCLI.swift           # @main 入口点，共享辅助函数
├── BumpCommand.swift          # 使用正则表达式进行版本更新
├── TagCommand.swift           # Git 操作
├── DatabaseReleaseCommand.swift  # GitHub Releases API
├── HomebrewCommand.swift      # 公式更新
├── FullCommand.swift          # 编排所有步骤
└── README.md                  # 本文件