技术文档摘要

🚀 XCF Xcode MCP Server

使用 Swift 超级加速你的 AI 工作流程！

🖌️ 1.0.5 版本的新特性！

• ✅ 文件操作
• ✅ 目录操作
• ✅ 脚本桥接 Xcode 文档操作
• ✅ AI 编码差异工具
• ✅ 模糊逻辑
• ✅ 在 Xcode 中无需构建即可分析 Swift 代码

使用 xcf 加速编写 Xcode 应用程序，这是一个专门为 Cursor 设计的简单 Swift 基础的 MCP 服务器。与 VSCode 和 Claude 完美兼容，无需 TypeScript、JavaScript 或任何其他依赖项！

🧰 XCF 安装与配置

安装步骤

1. 下载 XCF 应用程序并将其拖放到您的 /Applications 文件夹中。
2. 启动应用程序以批准互联网下载。

<img width="372" alt="截图 2025-05-11 下午9点15分35秒" src="https://gips1.baidu.com/it/u=1327346412,1463444662&fm=3081&app=3081&f=PNG?w=744&h=752" />

4. 您会看到以下警告（这是预期的）：

<img width="414" alt="XCF 警告" src="https://gips1.baidu.com/it/u=255829588,2484857882&fm=3081&app=3081&f=PNG?w=828&h=632" />

6. 点击“点击退出此 XCF Xcode MCP 服务器”按钮。

💡 故障排除： 如果 XCF 没有显示警告，请运行以下命令：

codesign --force --deep --sign - /Applications/xcf.app

您也可以使用 Xcode 从源代码构建 xcf。它是 100% Swift，并且易于本地构建。

🔧 快速设置

最低要求：

在您的 MCP 配置文件中添加 xcf：

{
  "mcpServers": {
    "xcf": {
      "type": "stdio",
      "command": "Applications/xcf.app/Contents/MacOS/xcf",
      "args": ["server"]
    }
  }
}          

配置位置

• Cursor: ~/.cursor/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

⚠️ 重要提示： 设置后请重启您的 AI 助手或刷新工具。

⚙️ 高级配置

对于非 Cursor 客户端或需要严格项目级别控制的用户：

{
  "mcpServers": {
    "xcf": {
      "type": "stdio",
      "command": "Applications/xcf.app/Contents/MacOS/xcf",
      "args": ["server"],
      "env": {
          "XCODE_PROJECT_FOLDER": "/path/to/project/",
          "XCODE_PROJECT": "/path/to/project/project.xcodeproj"
      }
    }
  }
}

这些环境变量允许您：

• 预选一个特定的 Xcode 项目进行工作
• 定义自定义的工作区边界以确保安全

✨ 关键功能

• 零依赖项： 安装简单，不依赖其他 MCP 服务器
• 自动项目检测： 自动选择您的 Xcode 项目，让您立即开始编码
• 实时错误处理： xcf build 或 xcf run 将 Xcode 的错误和警告直接发送到您的 AI IDE
• AI 功能修复： 让 Claude 在您的编码过程中修复错误和问题
• 直观的命令： 简单、面向开发者的命令结构，以实现最大生产力
• 全面的文件操作： 轻松读取、写入、编辑和删除文件
• 目录管理： 导航、列出、创建和删除目录
• Xcode 文档集成： 直接打开、创建、读取、保存、编辑和关闭 Xcode 文档
• 高级代码分析： 在 Xcode 中无需构建即可获得详细的 Swift 代码分析

🛠️ 适用于 Swift 开发者

该工具由 Swift 开发者设计，供 Swift 开发者使用。命令如 build、run、show 以及我们的新文件和目录操作使工作流程直观自然。

📋 命令参考

xcf 命令	动作描述
show	列出打开的 Xcode 项目
open #	通过编号选择项目
run	运行当前项目
build	构建当前项目
current	显示选定的项目
env	显示环境变量
pwd	显示当前文件夹（别名：dir, path）
help	显示所有可用命令

文件操作

命令	描述
read_file <file>	从文件中读取内容
write_file <file> <content>	写入文件内容
edit_file <file> <start> <end> <content>	编辑文件中的特定行
delete_file <file>	删除文件
move_file <source> <destination>	将文件从一个位置移动到另一个位置

目录操作

命令	描述
cd_dir <path>	更改目录
read_dir [path] [extension]	列出目录内容
add_dir <path>	创建目录
rm_dir <path>	删除目录
move_dir <source> <destination>	将目录从一个位置移动到另一个位置

Xcode 文档操作

命令	描述
open_doc <file>	在 Xcode 中打开文档
create_doc <file> [content]	创建新的 Xcode 文档
read_doc <file>	读取 Xcode 文档
save_doc <file>	保存 Xcode 文档

| close_doc <file> <saving> | 在 Xcode 中关闭文档 |

分析工具

命令	描述
snippet <file> [start] [end]	提取代码片段
analyzer <file> [start] [end]	分析 Swift 代码
lz <file>	分析器的缩写

📄 使用代码片段

对于人类命令

xcf 支持简化、用户友好的代码片段命令：

要获取整个文件，只需使用文件名：

xcf snippet filename.swift

许多情况下不需要完整的路径 - xcf 会智能地找到并显示完整的文件内容。

对于特定的行范围：

xcf snippet filename.swift 10 20

您可以使用这两种格式进行文件操作：

xcf snippet /path/to/file.swift                 // 直接路径
xcf snippet filePath=/path/to/file.swift        // 命名参数

xcf analyze /path/to/file.swift                 // 直接路径
xcf analyze filePath=/path/to/file.swift        // 命名参数

xcf lz /path/to/file.swift                      // 直接路径（缩写）
xcf lz filePath=/path/to/file.swift             // 命名参数（缩写）

对于特定的行范围：

xcf snippet /path/to/file.swift 10 20           // 直接路径带行范围
xcf snippet filePath=/path/to/file.swift startLine=11 endLine=20  // 命名参数

对于 AI 助手

当通过 MCP 工具使用 xcf 时，请使用以下语法：

mcp_xcf_snippet filePath="filename.swift" entireFile=true

对于特定的行范围：

mcp_xcf_snippet filePath="filename.swift" startLine=10 endLine=20

智能路径解析

当无法在确切路径下找到文件时，xcf 会智能搜索：

1. 首先尝试提供的确切路径
2. 使用当前工作目录解析相对路径
3. 在当前项目目录及其上一级目录中搜索
4. 在由 WORKSPACE_FOLDER_PATHS 定义的工作区文件夹中搜索
5. 在工作区文件夹中递归搜索，深度有限
6. 作为最后手段，执行类似文件名的模糊搜索

这种智能路径解析在 xcf 的所有文件操作中一致使用，包括：

• 文件读写
• 代码片段提取和分析
• 目录操作
• 文件编辑和删除
• Xcode 文档操作

这意味着您通常可以只使用文件名而无需任何路径进行任何操作：

xcf snippet Constants.swift    // 对于人类
xcf analyze Constants.swift    // 对于人类
xcf edit Constants.swift       // 对于人类

或者对于 AI 助手：

mcp_xcf_snippet filePath="Constants.swift" entireFile=true
mcp_xcf_analyzer filePath="Constants.swift" entireFile=true
mcp_xcf_xcf action="edit Constants.swift"

🔍 Swift 代码分析

对于人类命令

分析整个 Swift 文件以查找潜在问题：

xcf analyze filename.swift

或者使用缩写版本：

xcf lz filename.swift

对于特定的行范围：

xcf analyze filename.swift --startLine 10 --endLine 50

对于 AI 助手

当通过 MCP 工具使用 xcf 时，请使用以下语法：

mcp_xcf_analyzer filePath="filename.swift" entireFile=true

或者使用缩写版本：

mcp_xcf_xcf action="lz filename.swift"

对于特定的行范围：

mcp_xcf_analyzer filePath="filename.swift" startLine=10 endLine=50

分析识别的问题包括：

• 代码风格和格式问题
• 复杂度高的函数
• 未使用的变量和符号
• 魔法数字
• 长方法
• 以及其他更多问题

🧩 MCP 工具

函数型工具

• mcp_xcf_xcf: 执行 xcf 动作/命令

• mcp_xcf_list: 显示所有可用工具

• mcp_xcf_snippet: 从文件中提取代码片段

• mcp_xcf_analyzer: 分析 Swift 代码以查找潜在问题

• mcp_xcf_help: 获取帮助信息

• mcp_xcf_xcf_help: 获取 xcf 动作的帮助信息

• mcp_xcf_tools: 显示所有工具的详细参考

• mcp_xcf_read_dir: 列出目录内容

• mcp_xcf_read_file: 从文件中读取内容

• mcp_xcf_write_file: 写入文件内容

• mcp_xcf_edit_file: 编辑文件内容

• mcp_xcf_delete_file: 删除文件

• mcp_xcf_cd_dir: 更改当前目录

• mcp_xcf_add_dir: 创建新目录

• mcp_xcf_rm_dir: 删除目录

• mcp_xcf_move_file: 将文件从一个位置移动到另一个位置

• mcp_xcf_move_dir: 将目录从一个位置移动到另一个位置

• mcp_xcf_open_doc: 在 Xcode 中打开文档

• mcp_xcf_close_doc: 在 Xcode 中关闭文档

• mcp_xcf_create_doc: 在 Xcode 中创建新文档

• mcp_xcf_read_doc: 从 Xcode 中读取文档内容

• mcp_xcf_save_doc: 在 Xcode 中保存文档

• mcp_xcf_use_xcf: 激活 XCF 模式

单独动作工具

• mcp_xcf_show_help: 显示关于可用命令的帮助信息
• mcp_xcf_grant_permission: 授予 Xcode 自动化权限
• mcp_xcf_run_project: 运行当前 Xcode 项目
• mcp_xcf_build_project: 构建当前 Xcode 项目
• mcp_xcf_show_current_project: 显示当前选定项目的相关信息
• mcp_xcf_show_env: 显示所有环境变量
• mcp_xcf_show_folder: 显示当前工作目录
• mcp_xcf_list_projects: 列出所有打开的 Xcode 项目
• mcp_xcf_select_project: 通过编号选择 Xcode 项目
• mcp_xcf_analyze_swift_code: 分析 Swift 代码以查找潜在问题

对于 AI 函数调用

要获取整个文件：

mcp_xcf_snippet(filePath="/full/path/to/file.swift", entireFile=true)

对于特定的行范围：

mcp_xcf_snippet(filePath="/full/path/to/file.swift", startLine=10, endLine=20)

要分析整个文件：

mcp_xcf_analyzer(filePath="/full/path/to/file.swift", entireFile=true)

对于特定的行范围：

mcp_xcf_analyzer(filePath="/full/path/to/file.swift", startLine=10, endLine=50)

文件和目录操作

读取文件：

mcp_xcf_read_file filePath="main.swift"

写入文件：

mcp_xcf_write_file filePath="test.txt" content="Hello World"

编辑文件中的特定行：

mcp_xcf_edit_file filePath="main.swift" startLine=10 endLine=20 replacement="new code here"

列出目录内容：

mcp_xcf_read_dir directoryPath="."

创建新目录：

mcp_xcf_add_dir directoryPath="new_folder"

Xcode 文档操作

在 Xcode 中打开文档：

mcp_xcf_open_doc filePath="main.swift"

创建新文档：

mcp_xcf_create_doc filePath="new_file.swift" content="import Foundation"

编辑文档：

在 Xcode 中关闭文档：

mcp_xcf_close_doc filePath="main.swift" saving=true

🔒 安全特性

• 安全地与您指定工作区内的项目一起工作
• 自动防止访问超出工作区边界
• 当需要时重定向到安全替代方案
• 使用环境变量定义安全边界

🔄 工作流示例

基本工作流（针对人类）

1. xcf show - 查看可用项目
2. xcf open 1 - 选择一个项目
3. xcf build - 构建项目
4. xcf run - 运行项目

代码分析工作流（针对人类）

1. xcf current - 检查当前项目
2. xcf snippet filename.swift - 检查代码
3. xcf lz filename.swift - 分析代码
4. xcf build - 解决问题后构建

文件操作工作流（针对人类）

1. read_dir . - 列出现有目录中的文件
2. read_file main.swift - 查看文件内容
3. edit_file main.swift 10 15 "// 更新的代码" - 编辑文件
4. xcf build - 修改后构建

Xcode 文档工作流（针对人类）

1. open_doc main.swift - 在 Xcode 中打开文档

2. save_doc main.swift - 保存文档

3. xcf build - 修改后构建

基本工作流（针对 AI 助手）

2. mcp_xcf_xcf action="show" - 查看可用项目
3. mcp_xcf_xcf action="open 1" - 选择一个项目
4. mcp_xcf_xcf action="build" - 构建项目
5. mcp_xcf_xcf action="run" - 运行项目

代码分析工作流（针对 AI 助手）

2. mcp_xcf_xcf action="current" - 检查当前项目
3. mcp_xcf_snippet filePath="filename.swift" entireFile=true - 检查代码
4. mcp_xcf_analyzer filePath="filename.swift" entireFile=true - 分析代码
5. mcp_xcf_xcf action="build" - 解决问题后构建

文件操作工作流（针对 AI 助手）

2. mcp_xcf_read_dir directoryPath="." - 列出现有目录中的文件
3. mcp_xcf_read_file filePath="main.swift" - 查看文件内容
4. mcp_xcf_edit_file filePath="main.swift" startLine=10 endLine=15 replacement="// 更新的代码" - 编辑文件
5. `