Integrations
Xcode MCP 服务器
MCP(模型上下文协议)服务器,为 AI 助手提供全面的 Xcode 集成。该服务器使 AI 代理能够与 Xcode 项目交互、管理 iOS 模拟器,并执行各种与 Xcode 相关的任务,同时增强错误处理功能并支持多种项目类型。
特征
项目管理
- 设置活跃项目并获取详细项目信息
- 从模板创建新的 Xcode 项目(iOS、macOS、watchOS、tvOS)
- 使用目标和组规范将文件添加到 Xcode 项目
- 解析工作区文档以查找相关项目
- 列出项目和工作区中可用的方案
文件操作
- 支持不同编码的读/写文件
- 使用 base64 编码/解码处理二进制文件
- 使用模式和正则表达式搜索文件中的文本内容
- 检查文件存在并获取文件元数据
- 自动创建目录结构
构建和测试
- 使用可自定义的选项构建项目
- 运行测试并报告详细的故障
- 分析代码以查找潜在问题
- 清理构建目录
- 存档项目以供分发
CocoaPods 集成
- 在项目中初始化 CocoaPods
- 安装和更新 Pod
- 添加和删除 pod 依赖项
- 执行任意 pod 命令
Swift 包管理器
- 初始化新的 Swift 包
- 添加和删除具有各种版本要求的软件包依赖项
- 更新软件包并解决依赖关系
- 使用 DocC 为 Swift 软件包生成文档
- 运行测试并构建 Swift 包
iOS模拟器工具
- 列出可用的模拟器及其详细信息
- 启动和关闭模拟器
- 在模拟器上安装和启动应用程序
- 截取屏幕截图并录制视频
- 管理模拟器设置和状态
Xcode 实用程序
- 通过 xcrun 执行 Xcode 命令
- 编译资产目录
- 从源图像生成应用程序图标集
- 跟踪应用程序性能
- 导出并验证存档以供 App Store 提交
- 在不同的 Xcode 版本之间切换
安装
先决条件
- 安装了 Xcode 14.0 或更高版本的 macOS
- Node.js 16 或更高版本
- npm 或 yarn
- Swift 5.5+ 的 Swift 包管理器功能
- CocoaPods(可选,用于 CocoaPods 集成)
设置
选项 1:自动设置(推荐)
使用附带的安装脚本自动执行安装和配置过程:
Copy
安装脚本的作用:
- 环境验证:
- 检查您是否在 macOS 上运行
- 验证 Xcode 是否已安装并可访问
- 确认 Node.js (v16+) 和 npm 可用
- 检查 Ruby 安装
- 验证 CocoaPods 安装(如果缺失则提供安装)
- 依赖项安装:
- 运行
npm install
来安装所有必需的 Node.js 包 - 执行
npm run build
来编译 TypeScript 代码
- 运行
- 配置设置:
- 如果不存在则创建一个
.env
文件 - 提示输入项目基目录
- 询问您是否要启用调试日志记录
- 保存您的配置偏好
- 如果不存在则创建一个
- Claude 桌面集成(可选):
- 提供为 Claude Desktop 配置服务器
- 创建或更新 Claude Desktop 配置文件
- 设置适当的命令和参数来启动服务器
何时使用安装脚本:
- 首次安装以确保满足所有先决条件
- 当您需要使用交互式提示进行引导配置时
- 如果你想快速设置 Claude Desktop 集成
- 验证您的环境是否具有所有必需的组件
该脚本将通过清晰的提示和有用的反馈指导您完成配置过程。
选项 2:手动设置
何时使用手动设置:
- 您更喜欢明确控制每个安装步骤
- 您有一个自定义环境或非标准配置
- 您正在设置 CI/CD 管道或自动化环境
- 您想要自定义安装过程的特定方面
- 您是一位熟悉 Node.js 项目的经验丰富的开发人员
请按照以下步骤进行手动安装:
- 克隆存储库:Copy
- 验证先决条件(必须安装这些):
- Xcode 和 Xcode 命令行工具
- Node.js v16 或更高版本
- npm
- Ruby(用于 CocoaPods 支持)
- CocoaPods(可选,用于与 pod 相关的功能)
- 安装依赖项:Copy
- 构建项目:Copy
- 创建配置文件:编辑Copy
.env
文件以设置您的首选配置。 - 对于 Claude Desktop 集成(可选):
- 编辑或创建
~/Library/Application Support/Claude/claude_desktop_config.json
- 添加以下配置(根据需要调整路径):GXP6
- 编辑或创建
设置故障排除
常见设置问题:
- 构建错误:
- 确保您拥有正确的 Node.js 版本(v16+)
- 尝试删除
node_modules
并再次运行npm install
- 使用
npx tsc --noEmit
检查 TypeScript 错误 - 确保代码中的所有导入都得到正确解析
- 缺少依赖项:
- 如果您看到有关缺少模块的错误,请再次运行
npm install
- 对于本机依赖项,您可能需要 Xcode 命令行工具:
xcode-select --install
- 如果您看到有关缺少模块的错误,请再次运行
- 权限问题:
- 确保您对安装目录具有写入权限
- 对于 CocoaPods 安装,您可能需要使用
sudo gem install cocoapods
- 配置问题:
- 验证您的
.env
文件具有正确的格式和有效的路径 - 确保
PROJECTS_BASE_DIR
指向现有目录 - 检查路径不包含需要转义的特殊字符
- 验证您的
- Claude 桌面集成:
- 确保 Claude 配置中的路径指向
index.js
的正确位置 - 更改配置后重新启动 Claude Desktop
- 在尝试使用 Claude 之前,请检查服务器是否正在运行
- 确保 Claude 配置中的路径指向
用法
启动服务器
Copy
对于自动重启的开发模式:
Copy
配置选项
您可以通过两种方式配置服务器:
.env
文件中的环境变量:Copy- 命令行参数:Copy
关键配置参数
PROJECTS_BASE_DIR
/--projects-dir
:项目的基本目录(必需)ALLOWED_PATHS
/--allowed-paths
:允许访问的附加目录(以逗号分隔)PORT
/--port
:运行服务器的端口(默认值:3000)DEBUG
/--debug
:启用调试日志记录(默认值:false)LOG_LEVEL
/--log-level
:设置日志级别(默认值:info)
连接AI助手
该服务器实现了模型上下文协议 (MCP),使其能够与支持此协议的各种 AI 助手兼容。连接方法如下:
- 启动 Xcode MCP 服务器
- 配置你的AI助手使用服务器URL(通常为
http://localhost:3000
) - AI 助手现在可以访问服务器提供的所有 Xcode 工具
工具文档
有关所有可用工具及其用法的全面概述,请参阅工具概述。
有关详细的使用示例和最佳实践,请参阅用户指南。
常见工作流程
建立新项目
Copy
使用文件
Copy
构建和测试
Copy
项目结构
Copy
工作原理
Xcode MCP 服务器使用模型上下文协议 (MCP) 为 AI 模型与 Xcode 项目交互提供标准化接口。该服务器架构由以下几个关键组件设计而成:
核心组件
- 服务器实现:处理工具注册和请求处理的主要 MCP 服务器。
- 路径管理:通过验证所有路径是否与允许的目录一致,确保文件访问的安全。
- 项目管理:检测、加载和管理不同类型的 Xcode 项目:
- 标准 Xcode 项目(.xcodeproj)
- Xcode 工作区(.xcworkspace)
- Swift 包管理器项目(Package.swift)
- 目录状态:维护相对路径解析的活动目录上下文。
- 工具注册表:将工具组织成逻辑类别,以用于不同的 Xcode 操作。
请求流程
- AI助手向MCP服务器发送工具执行请求。
- 服务器验证请求参数和权限。
- 使用经过验证的参数调用适当的工具处理程序。
- 该工具执行请求的操作,通常使用本机 Xcode 命令。
- 结果被格式化并返回给AI助手。
- 全面的错误处理为故障排除提供了有意义的反馈。
安全功能
- 路径验证:所有文件操作都限制在允许的目录中。
- 错误处理:详细的错误消息有助于诊断问题。
- 参数验证:使用 Zod 模式验证输入参数。
- 流程管理:通过适当的错误处理,外部流程可以安全执行。
项目类型支持
服务器智能地处理不同的项目类型:
- 标准项目:直接 .xcodeproj 操作
- 工作区:管理工作区内的多个项目
- SPM 项目:处理 Swift 包管理器特定的操作
这种架构允许 AI 助手无缝地与任何类型的 Xcode 项目协作,同时保持安全性并提供详细的反馈。
贡献
欢迎贡献代码!欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支(
git checkout -b feature/amazing-feature
) - 提交您的更改(
git commit -m 'Add some amazing feature'
) - 推送到分支(
git push origin feature/amazing-feature
) - 打开拉取请求
开发指南
- 遵循现有的代码风格和组织
- 添加带有特定错误消息的全面错误处理
- 为新功能编写测试
- 更新文档以反映您的更改
- 确保与不同项目类型(标准、工作区、SPM)的兼容性
添加新工具
要向服务器添加新工具:
- 在
src/tools/
目录中确定适当的类别 - 使用 Zod 模式验证的现有模式来实现该工具
- 在类别的
index.ts
文件中注册该工具 - 添加带有特定错误消息的错误处理
- 在适当的文档文件中记录该工具
故障排除
常见问题
- 路径访问错误:确保您尝试访问的路径在允许的目录内
- 构建失败:检查 Xcode 命令行工具是否已安装且为最新版本
- 未找到工具:验证工具名称是否正确且已正确注册
- 参数验证错误:检查工具文档中的参数类型和要求
调试
- 启动启用调试日志记录的服务器:
npm start -- --debug
- 检查控制台输出以获取详细的错误消息
- 检查服务器日志以获取请求和响应详细信息
- 对于特定于工具的问题,请尝试直接在终端中运行等效的 Xcode 命令
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息,请参阅 LICENSE 文件。
致谢
- 感谢模型上下文协议团队提供的 MCP SDK
- 使用 TypeScript 和 Node.js 构建
- 使用 Xcode 命令行工具和 Swift 包管理器
- 特别感谢所有帮助改善服务器功能和稳健性的贡献者
You must be authenticated.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
将 Claude AI 与 Xcode 连接起来,在本地机器上安全地实现 AI 驱动的代码协助、项目管理和自动化开发任务。
- Features
- Installation
- Usage
- Project Structure
- How It Works
- Contributing
- Troubleshooting
- License
- Acknowledgments
Related Resources
Related MCP Servers
- -securityAlicense-qualityProvides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.Last updated -8PythonMIT License
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.Last updated -29TypeScript
- -securityAlicense-qualityConnects to Xcode's build system to extract, parse, and display errors and warnings from your Swift projects, helping AI assistants quickly identify code issues without manually searching through build logs.Last updated -1PythonMIT License
- -securityFlicense-qualityA server that bridges Claude AI with the Plane project management platform, enabling AI-powered project management tasks including project creation, task management, team collaboration, and automated workflows.Last updated -TypeScript