Cupertino MCP 服务器（本地文档服务端）

项目简介

Cupertino 是一个用 Swift 实现的 MCP（Model Context Protocol）服务器，专注于将 Apple 开发文档离线化、结构化并通过标准化的 JSON-RPC 方式向 AI 客户端提供上下文信息和功能。其核心能力包括托管文档资源、注册并执行工具、定义并渲染提示模板，以及通过多种传输协议与客户端通信。

主要功能点

• MCP 服务器核心能力：处理资源读取、工具执行、提示模板等 JSON-RPC 请求，向 AI 客户端提供一致的上下文服务。
• 本地离线索引与资源托管：使用 SQLite FTS5 构建离线索引，支持快速全文搜索、框架过滤、版本筛选等，资源覆盖 Apple 文档、Swift Evolution、Swift.org 文档、示例代码等。
• 工具与资源提供：提供文档检索、读取、示例代码查询等工具，结合离线数据实现快速响应。
• 多传输协议支持：支持传统的标准输入输出（stdio）、服务器推送（SSE）、WebSocket 等传输方式，满足不同客户端接入场景。
• 会话与能力声明：服务器端管理会话状态与能力声明，确保安全、可扩展的上下文服务。
• 一体化开发与扩展性：包含 CLI、TUI、Mock 测试工具等，方便本地开发、测试以及二次扩展。

安装步骤

• 先决条件：macOS 15+、Swift 6.2+、Xcode 16+（如需要从源码构建）。
• 安装方式：
  • 通过一键脚本安装：执行一个命令即可获取预构建二进制并放置到 /usr/local/bin。
  • 使用 Homebrew 安装 cupertino（taps/入口见 README）。
  • 从源码构建：克隆仓库后在 Packages 目录使用 Swift Package Manager 构建并安装到 /usr/local/bin。
• 前期准备（可选但推荐）：
  • 运行 cupertino setup 下载预构建数据库，以实现快速上线体验。
  • 或执行 cupertino fetch/save 等命令自行下载并构建离线数据与索引。
• 运行服务器：执行 cupertino serve 启动 MCP 服务器。

服务器配置

以下配置用于 MCP 客户端了解如何启动并连接服务器，实际客户端配置请按需使用（为便于理解以 JSON 展示，客户端通常不需要直接嵌入以下内容）： { "servers": { "cupertino": { "name": "cupertino", "command": "/usr/local/bin/cupertino", "args": ["serve"], "transport": "stdio" // 备用选项：stdio、sse、websocket } } } 说明：

• name：服务器名称，客户端用来标识要连接的 MCP 服务器。
• command：启动服务器的可执行路径（如系统安装路径）。
• args：启动参数，serve 表示启动 MCP 服务。
• transport：通信传输方式，服务器默认使用 stdio，亦可通过配置改为 SSE 或 WebSocket 等。 注：该配置仅用于描述客户端如何启动并连接到服务器，实际客户端实现往往不需要将此信息硬编码在应用中。

基本使用方法

• 启动服务器：在安装路径下执行 cupertino serve。
• 连接与使用场景：让 Claude、OpenAI 等客户端通过 MCP 对接，调用文档读取、搜索、示例代码等能力，获取结构化数据或渲染内容。
• 快速体验：执行 cupertino setup 下载数据库，然后 cupertino serve 即可进行测试与演示。
• 常用工作流：setup -> serve；需要离线索引时再执行 save/index 等命令以更新本地数据。