Swift Developer MCP Server

Swift 开发者 MCP 服务

一个功能全面的模型上下文协议（MCP）服务，为 macOS 和 Linux 环境提供 Swift 开发工具、调试能力和项目管理功能。此服务支持 AI 助手与 Swift 项目、构建系统和开发工具交互。

功能

🔨 构建与测试工具

• swift_build - 构建 Swift 项目，并提供配置选项（debug/release、指定目标、详细输出）
• swift_test - 运行 Swift 测试，支持筛选、并行执行控制和详细输出
• run_target - 使用自定义参数执行指定的 Swift 目标

🐛 调试工具

• debug_start - 为 Swift 目标启动调试会话
• debug_set_breakpoint - 设置断点，可选添加条件
• debug_step - 单步执行代码（跳过、进入、跳出）
• debug_continue - 继续执行，直到遇到下一个断点
• debug_inspect_variable - 检查变量并计算表达式

📦 Swift 包管理

• get_package_info - 获取全面的 Swift 包信息和依赖项
• print_dependency_public_api - 提取并显示任意依赖项的公共 API

🔧 Swiftly 工具链管理

• swiftly_install - 从不同渠道安装 Swift 工具链
• swiftly_list - 列出已安装的 Swift 工具链
• swiftly_list_available - 列出可供安装的 Swift 版本
• swiftly_use - 全局或按项目切换 Swift 版本
• swiftly_run - 使用指定的 Swift 版本运行命令
• swiftly_uninstall - 移除 Swift 工具链

📊 资源

• swift://project/info - 当前项目信息和结构
• swift://build/status - 构建状态和历史记录
• swift://debug/sessions - 活动调试会话和断点

💡 提示词

• swift_debug_session - 引导式调试会话设置，并提供针对目标的建议
• swift_build_analysis - 智能分析构建错误并提供解决方案建议

安装

前提条件

1. Swift：安装 Swift 5.9+，或使用 Swiftly 管理版本
2. macOS 或 Linux：此服务支持 macOS 和 Linux 环境
3. Make：用于使用便捷的构建目标

快速设置

1. 克隆仓库：

   git clone https://github.com/edgeengineer/swift-developer-mcp-server.git
   cd swift-developer-mcp-server
   

2. 构建并获取路径（自动复制到剪贴板）：

   make path
   

   这将：

   • ✅ 以 release 模式构建服务
   • ✅ 显示可执行文件路径
   • ✅ 将路径复制到剪贴板
   • ✅ 显示适用于常用 AI 客户端的配置示例

其他 Make 目标

make build    # Build the server in release mode
make clean    # Clean build artifacts
make install  # Install to /usr/local/bin
make help     # Show all available targets

AI 客户端配置

Cursor

将以下内容添加到 Cursor 设置（.cursor-settings/settings.json）：

{
  "mcp": {
    "servers": {
      "swift-developer": {
        "command": "PASTE_PATH_FROM_CLIPBOARD_HERE",
        "args": [],
        "env": {}
      }
    }
  }
}

Windsurf

将以下内容添加到 Windsurf 配置（.windsurf/mcp_servers.json）：

{
  "servers": {
    "swift-developer": {
      "command": "PASTE_PATH_FROM_CLIPBOARD_HERE",
      "args": [],
      "env": {}
    }
  }
}

Claude Desktop

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

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "swift-developer": {
      "command": "PASTE_PATH_FROM_CLIPBOARD_HERE",
      "args": [],
      "env": {}
    }
  }
}

Claude Code（终端应用程序）

将以下内容添加到 Claude Code 配置（在终端应用程序中）：

claude mcp add swift-developer PASTE_PATH_FROM_CLIPBOARD_HERE

Claude Code（VS Code 扩展）

将以下内容添加到 VS Code 设置（.vscode/settings.json）：

{
  "claude-dev.mcpServers": {
    "swift-developer": {
      "command": "PASTE_PATH_FROM_CLIPBOARD_HERE",
      "args": [],
      "env": {}
    }
  }
}

💡 实用提示：运行 make path 可获取适用于每个客户端、可直接复制的配置示例！

使用示例

构建 Swift 项目

Use the swift_build tool to build the current project in release mode with verbose output.

运行测试

Use the swift_test tool to run all tests in parallel with verbose output.

启动调试会话

Use the swift_debug_session prompt to set up debugging for the "MyApp" target, focusing on the "ViewController.swift" file.

管理 Swift 版本

Use swiftly_list to see installed Swift versions, then swiftly_use to switch to Swift 5.9.

提取依赖项 API

Use print_dependency_public_api with dependency_name "Alamofire" to see the public API of the Alamofire dependency.

获取项目信息

Access the swift://project/info resource to see the current project structure and Package.swift contents.

开发

项目结构

swift-developer-mcp-server/
├── Package.swift                 # Swift Package Manager configuration
├── Makefile                     # Build automation and convenience targets
├── Sources/
│   ├── main.swift               # Server entry point and MCP handler setup
│   ├── Utilities.swift          # Common types and helper functions
│   ├── BuildTestTools.swift     # Swift build and test tools
│   ├── DebugTools.swift         # Debug session management and tools
│   ├── PackageInfoTools.swift   # Swift package information tools
│   ├── SwiftlyTools.swift       # Swiftly toolchain management
│   ├── Resources.swift          # MCP resources (project info, build status, etc.)
│   └── Prompts.swift            # MCP prompts (debug session, build analysis)
└── README.md                    # This file

添加新工具

1. 在相应的模块文件中定义工具结构体：
   • BuildTestTools.swift，用于构建和测试功能
   • DebugTools.swift，用于调试功能
   • PackageInfoTools.swift，用于包管理
   • SwiftlyTools.swift，用于工具链管理
   • 如有需要，可为其他类别创建新模块
2. 在 main.swift 的 ListTools 处理程序中添加该工具
3. 在 CallTool switch 语句中添加该工具的 handle 方法
4. 重新构建服务

测试

你可以手动运行服务并发送 JSON-RPC 消息来测试：

swift run SwiftDeveloperMCPServer

然后通过 stdin 发送初始化和工具调用消息。

要求

• macOS 13.0+ 或 Linux（Ubuntu 20.04+，以及其他支持 Swift 的发行版）
• Swift 5.9+
• Make（用于构建目标）
• Xcode Command Line Tools（仅限 macOS）

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交 pull request

许可证

本项目采用 Apache 2.0 License 授权。详情请参阅 LICENSE 文件。

故障排除

常见问题

1. “Command not found”：

   • 运行 make path 以重新构建并获取正确的路径
   • 确保 AI 客户端配置中的路径与输出一致

2. “Permission denied”：确保可执行文件具有正确的权限：

   chmod +x .build/release/SwiftDeveloperMCPServer
   # Or simply run 'make path' which handles this automatically
   

3. Swift 版本冲突：如果安装了多个 Swift 版本，请使用 swiftly 管理 Swift 版本。

4. 构建失败：

   • 确保安装了最新的 Xcode Command Line Tools（macOS）：

     xcode-select --install
     

   • 如果发生构建错误，make path 命令会显示详细信息

5. 配置问题：make path 命令会提供适用于所有受支持 AI 客户端、可直接复制的配置示例。

调试服务

要调试服务本身，可以在 main.swift 文件中添加日志，或使用详细的 Swift 输出运行服务：

swift run -v SwiftDeveloperMCPServer

使用 ExampleLib 进行测试

仓库包含 ExampleLib/，这是一个完整的 Swift 包，其中包含异步斐波那契计算，非常适合测试 MCP 服务的调试功能。

构建和运行 ExampleLib

进入 ExampleLib 目录并使用标准 Swift 命令：

cd ExampleLib

# Build the library and executable
swift build

# Run the demo application
swift run ExampleApp

# Run tests
swift test

使用 MCP 服务调试工具进行测试

ExampleLib 项目为测试 MCP 服务的调试功能提供了理想环境。以下是完整调试工作流的测试方法：

1. 基本构建和测试

使用 MCP 服务工具进行构建和测试：

Use swift_build tool with:
- target: "ExampleApp" 
- project_path: "/path/to/swift-developer-mcp-server/ExampleLib"
- configuration: "debug"
- verbose: true

Use swift_test tool with:
- project_path: "/path/to/swift-developer-mcp-server/ExampleLib"
- verbose: true

2. 设置调试会话

为 ExampleApp 启动调试会话：

Use debug_start tool with:
- target: "ExampleApp"
- project_path: "/path/to/swift-developer-mcp-server/ExampleLib"
- arguments: [] (optional)

这将：

• 构建 ExampleApp 目标
• 启动 LLDB 会话
• 加载可执行文件以进行调试

3. 设置断点

设置关键断点，以检查斐波那契计算：

Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Sources/ExampleApp/main.swift"
- line_number: 89 (in performanceTest function)
- session_id: "your_session_id"

Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Sources/ExampleLib/FibonacciCalculator.swift" 
- line_number: 37 (inside calculate method)
- session_id: "your_session_id"

4. 运行并逐步执行代码

# Start execution
Use debug_continue tool with:
- session_id: "your_session_id"

# Step through code when breakpoint hits
Use debug_step tool with:
- session_id: "your_session_id"
- step_type: "over" (or "into", "out")

5. 检查变量和 Actor 状态

FibonacciCalculator 是一个 actor，非常适合测试异步调试：

# Inspect the calculator actor
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- variable_name: "calculator"

# Inspect specific values
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- variable_name: "result"

# Evaluate expressions
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- expression: "await calculator.getCalculationCount()"

6. 测试并发操作

ExampleLib 包含并发斐波那契计算，非常适合测试异步操作调试：

# Set breakpoint in concurrent calculation method
Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Sources/ExampleLib/FibonacciCalculator.swift"
- line_number: 57 (in calculateMultiple method)
- session_id: "your_session_id"

# Inspect concurrent task state
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- variable_name: "tasks"

7. 分析缓存行为

测试异步 actor 中的缓存行为调试：

# Set conditional breakpoint for cache hits
Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Sources/ExampleLib/FibonacciCalculator.swift"
- line_number: 19 (cache hit check)
- condition: "cached != nil"
- session_id: "your_session_id"

# Inspect cache state
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- expression: "await calculator.getCacheState()"

8. 测试 Swift Testing 框架

ExampleLib 使用 Swift Testing 框架。测试对测试执行过程的调试：

# Build and run tests with debugging
Use debug_start tool with:
- target: "ExampleLibTests"
- project_path: "/path/to/ExampleLib"

# Set breakpoints in test methods
Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Tests/ExampleLibTests/FibonacciCalculatorTests.swift"
- line_number: 15 (in testBasicCalculations)
- session_id: "your_session_id"

9. 调试状态下的性能测试

通过调试测试性能测试函数：

# Set breakpoint in performance test
Use debug_set_breakpoint tool with:
- file_path: "/path/to/ExampleLib/Sources/ExampleApp/main.swift"
- line_number: 95 (inside performanceTest)
- session_id: "your_session_id"

# Inspect timing variables
Use debug_inspect_variable tool with:
- session_id: "your_session_id"
- variable_name: "totalTime"

10. 清理会话

完成后务必清理调试会话：

Use debug_terminate tool with:
- session_id: "your_session_id"

预期的调试场景

ExampleLib 提供以下调试场景：

1. Actor 状态检查：调试异步 Actor 状态和并发访问
2. 缓存行为：实时观察缓存命中／未命中
3. 递归计算：逐步调试递归斐波那契计算
4. 并发操作：调试多个同时进行的计算
5. 错误处理：测试错误条件的调试
6. 性能瓶颈：识别缓慢的计算路径
7. 测试执行：调试 Swift Testing 框架测试

调试输出示例

调试 ExampleLib 时，你应该会看到：

Debug session started successfully.
Session ID: debug_12345678-1234-1234-1234-123456789abc
Target: ExampleApp
Executable: /path/to/ExampleLib/.build/debug/ExampleApp

Breakpoint set successfully.
File: /path/to/ExampleLib/Sources/ExampleApp/main.swift
Line: 89

Debug execution continued.
Session: debug_12345678-1234-1234-1234-123456789abc
Command: process launch
Running: true

Variable inspection results.
Session: debug_12345678-1234-1234-1234-123456789abc
Target: calculator

这种全面的测试方法可验证：

• 真实的 LLDB 集成
• Swift Actor 调试
• 并发代码调试
• 断点管理
• 变量检查
• 会话生命周期管理

支持

如有问题或功能请求，请在 GitHub 仓库中提交 issue。