swift-mcp-server

🚀 Swift MCP Server

这是一个面向Swift项目的生产级模型上下文协议（MCP）服务器，采用企业级双传输架构，具备全面的分析能力，能为Swift开发者提供可靠、快速且智能的项目分析，无缝集成到开发工作流中。

🚀 快速开始

一键设置

# 一体化脚本 - 构建、配置、测试所有内容
./swift-mcp.sh

# 或者运行特定功能：
./swift-mcp.sh build    # 仅构建
./swift-mcp.sh stdio    # 运行持久化STDIO模式
./swift-mcp.sh test     # 测试功能

手动安装

# 构建生产二进制文件
swift build --configuration release

# 验证安装
./.build/release/swift-mcp-server --help

✨ 主要特性

🏗️ 坚如磐石的基础

• 🔄 双传输模式：HTTP服务器 + 用于VS Code/Serena集成的STDIO
• 🛠️ 15+ 分析工具：符号搜索、引用查找、架构分析等
• 🏢 企业级就绪：支持JSON配置、结构化日志记录和优雅关闭
• ⚡ 兼容Swift 6：采用现代并发和生产级架构
• 📊 实时分析：实时编译反馈和性能指标
• 🎯 VS Code集成：直接支持MCP扩展的STDIO

🚀 开发者体验

• 一键设置：运行 ./swift-mcp.sh ，在30秒内完成构建、配置和测试
• 自动IDE配置：VS Code开箱即用
• 全面测试：所有功能自动验证
• 自动修复常见问题：./swift-mcp.sh 可解决90%的问题
• 零退出代码64错误：强大的参数解析，支持位置参数

🔧 生产级特性

• 跨平台支持：支持macOS和Linux
• 专业CLI：使用ArgumentParser，提供全面的选项
• 错误恢复：优雅处理边缘情况
• 性能优化：中型项目的分析时间低于1秒
• 内存高效：资源使用最少，并进行清理

📦 安装指南

一键安装

./swift-mcp.sh

手动安装

swift build --configuration release
./.build/release/swift-mcp-server --help

💻 使用示例

基础用法

# 运行一体化脚本
./swift-mcp.sh

# 运行特定功能
./swift-mcp.sh build
./swift-mcp.sh stdio
./swift-mcp.sh test

高级用法

# 手动配置VS Code MCP
{
  "mcp.servers": {
    "swift-mcp-server": {
      "command": "/path/to/swift-mcp-server/.build/release/swift-mcp-server",
      "args": ["--transport", "stdio", "${workspaceFolder}"],
      "env": {"SWIFT_MCP_MODE": "vscode"}
    }
  }
}

# 运行企业级HTTP API
swift-mcp-server --config http-config.json --transport http --port 9000

📚 详细文档

📊 可用分析工具

核心分析

• list_symbols - 查找所有函数、类、协议和变量
• find_references - 定位符号在代码库中的使用位置
• analyze_architecture - 检测模式、依赖关系和代码组织
• generate_documentation - 自动创建全面的文档
• analyze_project - 全面分析项目的健康状况和结构

高级特性

• iOS框架分析 - 检测UIKit、SwiftUI、Core Data的使用模式
• 依赖映射 - 可视化模块关系和耦合度
• 性能分析 - 识别优化机会
• 现代并发分析 - 分析async/await和actor的使用
• 内存安全检测 - 检测潜在的保留循环和内存问题

🎛️ 传输模式

VS Code集成（推荐）

# 自动配置VS Code
./swift-mcp.sh vscode

# 手动配置VS Code MCP
{
  "mcp.servers": {
    "swift-mcp-server": {
      "command": "/path/to/swift-mcp-server/.build/release/swift-mcp-server",
      "args": ["--transport", "stdio", "${workspaceFolder}"],
      "env": {"SWIFT_MCP_MODE": "vscode"}
    }
  }
}

持久化STDIO模式

# 运行服务器，不关闭（用于多个请求）
./swift-mcp.sh stdio

企业级HTTP API

# 运行生产级HTTP服务器
swift-mcp-server --config http-config.json --transport http --port 9000

🔧 配置

项目文件结构

swift-mcp-server/
├── 📄 README.md                     # 主文档（你正在查看）
├──  CONFIG_GUIDE.md              # 高级配置指南
├── 📦 Package.swift                # Swift包定义

├── 🛠️ Management/
│   └── swift-mcp.sh                # ⚡ 一体化管理脚本

├── ⚙️ Configuration/
│   ├── vscode-mcp-config.json      # VS Code MCP扩展设置
│   ├── stdio-config.json           # STDIO传输配置
│   └── http-config.json            # HTTP服务器配置

└── 💻 Sources/
    ├── SwiftMCPServer/             # 主应用程序入口点
    ├── SwiftMCPCore/               # 核心MCP协议实现
    └── ModernConcurrency/          # Swift 6并发实用工具

命令行选项

swift-mcp-server --help

# 关键选项:
--transport <mode>        # http, stdio (默认: http)
--workspace <path>        # Swift项目路径
--config <file>          # JSON配置文件
--port-min <min>         # 自动端口选择范围
--port-max <max>         # 自动端口选择范围
--log-level <level>      # 日志详细程度
--json-logs             # 结构化JSON输出

企业级配置

{
  "mcpServer": {
    "transport": {
      "type": "http",
      "host": "0.0.0.0", 
      "portRange": {"min": 9000, "max": 9010}
    }
  },
  "performance": {
    "maxConcurrentTasks": 10,
    "taskTimeoutSeconds": 30.0
  }
}

🚨 故障排除

常见问题

退出代码64（已修复 ✅）

# 现在通过支持位置参数解决了此问题
# VS Code MCP扩展将工作区作为位置参数传递
swift-mcp-server /path/to/workspace  # 完美运行

权限问题

./swift-mcp.sh            # 自动修复所有问题

未找到SourceKit-LSP

./swift-mcp.sh health     # 验证SourceKit-LSP安装

VS Code集成问题

./swift-mcp.sh vscode     # 设置VS Code MCP配置

详细的故障排除信息请参阅 EXIT_CODE_64_FIX.md。

📈 项目状态

✅ 阶段1：基础建设（100% 完成）

• 双传输架构（HTTP + STDIO）
• VS Code和Serena集成
• 15+ 分析工具可用
• 跨平台支持（macOS + Linux）
• 零退出代码64错误
• 全面的健康检查
• 生产级错误处理

🚀 阶段2：智能引擎（计划于2025年第一季度）

• Swift 6合规性分析器
• 架构模式检测
• 性能优化建议
• 高级内存安全分析
• 智能代码补全
• 自动重构建议

当前状态：具备生产级基础，并有清晰的增强 roadmap。

🤝 贡献

开发指南请参阅 CONTRIBUTING.md。

快速开发设置

git clone https://github.com/your-username/swift-mcp-server.git
cd swift-mcp-server
./swift-mcp.sh             # 为开发设置一切
swift test                 # 运行测试套件

📄 文档

• CONFIG_GUIDE.md - 高级配置
• EXIT_CODE_64_FIX.md - 故障排除指南
• SERENA_INTEGRATION.md - Serena应用集成

可用工具

• find_symbols - 智能过滤搜索Swift符号
• find_references - 查找符号的所有引用
• get_definition - 导航到符号定义
• analyze_project - 完整的项目分析和指标
• generate_documentation - 自动生成项目文档
• analyze_architecture - 架构模式检测

🔧 技术细节

项目结构

Sources/
├── SwiftMCPServer/           # 主应用程序入口点
│   └── SwiftMCPApp.swift     # 具有双传输的CLI接口
├── SwiftMCPCore/             # 核心MCP服务器实现
│   ├── MCPServer.swift       # HTTP传输服务器
│   ├── StdioTransport.swift  # 用于VS Code的STDIO传输
│   ├── ServerConfiguration.swift # 企业级配置
│   └── SwiftLanguageServer.swift # Swift分析引擎
└── ModernConcurrency/        # 高级并发功能
    ├── FCITaskManager.swift  # 任务管理和协调
    └── FCIModernThreadSafety.swift # 基于Actor的线程安全实用工具

传输架构

• HTTP传输：具备智能端口管理的RESTful API服务器
• STDIO传输：用于VS Code集成的直接JSON-RPC通信
• 统一核心：共享分析引擎，支持两种传输模式

现代并发

// 兼容Swift 6的并发模式
ModernConcurrency/
├── FCITaskManager.swift         # 异步任务协调
├── FCIModernThreadSafety.swift  # 基于Actor的安全机制
└── FCIModernContinuationManager.swift # 延续处理

高级配置

企业级HTTP服务器

{
  "mcpServer": {
    "transport": {
      "type": "http",
      "host": "0.0.0.0",
      "portRange": {"min": 9000, "max": 9010}
    },
    "performance": {
      "maxConcurrentTasks": 10,
      "taskTimeoutSeconds": 30.0
    },
    "logging": {
      "level": "info",
      "format": "json",
      "enableMetrics": true
    }
  }
}

VS Code STDIO配置

{
  "mcp.servers": {
    "swift-mcp-server": {
      "command": "/path/to/.build/release/swift-mcp-server",
      "args": ["--transport", "stdio", "${workspaceFolder}"],
      "env": {
        "SWIFT_MCP_MODE": "vscode",
        "LOG_LEVEL": "info"
      }
    }
  }
}

🧪 开发与测试

要求

• Swift：5.9+（兼容Swift 6）
• 平台：macOS 13.0+ 或 Linux Ubuntu 18.04+
• Xcode：15.0+（包含SourceKit-LSP）
• 工具：ArgumentParser、Logging、Foundation

快速开发

# 克隆并设置开发环境
git clone https://github.com/your-username/swift-mcp-server.git
cd swift-mcp-server
./swift-mcp.sh                      # 完整的开发设置

# 开发工作流
swift build                         # 调试构建  
swift test                          # 运行测试套件
./swift-mcp.sh test                 # 测试服务器功能
swift build                         # 调试构建
swift test                          # 运行测试套件  
swift build --configuration release # 生产构建

测试

# 全面测试
./swift-mcp.sh test                 # 完整功能测试
swift test                          # 单元测试

# 手动测试  
./.build/release/swift-mcp-server --help
./.build/release/swift-mcp-server --workspace . --transport http

# 检查端口可用性
lsof -i :8080

# 使用自动端口选择
swift-mcp-server --port-min 8080 --port-max 8090

# 从日志中检查选择的端口

路径问题

项目路径未被识别

# 验证路径是否存在且可访问
ls -la /path/to/your/swift/project

# 检查是否存在Package.swift
find /path/to/project -name "Package.swift" -type f

# 使用绝对路径
swift-mcp-server --workspace "$(pwd)/path/to/project"

# 检查工作区权限
chmod -R 755 /path/to/your/project

SourceKit-LSP路径问题

# 验证SourceKit-LSP安装
which sourcekit-lsp

# 预期结果: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/sourcekit-lsp

# 如果未找到，安装Xcode命令行工具
xcode-select --install

# 设置正确的Xcode路径
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

依赖问题

Swift包依赖

# 解决包依赖
swift package resolve

# 更新依赖
swift package update

# 清理并重新构建
swift package clean && swift build

VS Code MCP扩展依赖

# 安装VS Code MCP扩展
code --install-extension your-mcp-extension

# 检查VS Code配置
cat ~/.vscode/settings.json | grep mcp

# 配置更改后重启VS Code

Serena集成依赖

# 安装UV包管理器（Serena所需）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装Serena MCP
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

# 验证Serena安装
serena --version

常见配置修复

修复VS Code配置

{
  "mcp.servers": {
    "swift-mcp-server": {
      "command": "/absolute/path/to/swift-mcp-server/.build/release/swift-mcp-server",
      "args": [
        "--transport", "stdio",
        "--workspace", "${workspaceFolder}",
        "--log-level", "info"
      ],
      "env": {
        "PATH": "/usr/bin:/bin:/usr/sbin:/sbin:/Applications/Xcode.app/Contents/Developer/usr/bin"
      },
      "cwd": "${workspaceFolder}"
    }
  }
}

修复环境变量

# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="/Applications/Xcode.app/Contents/Developer/usr/bin:$PATH"
export SOURCEKIT_LSP_PATH="/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/sourcekit-lsp"

# 重新加载shell
source ~/.zshrc

调试配置

# 以最大详细程度进行测试
swift-mcp-server \
  --transport stdio \
  --workspace "$(pwd)" \
  --log-level trace \
  --dev \
  --json-logs

# 检查服务器功能
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "initialize", "params": {"protocolVersion": "2024-11-05"}}'

健康检查与快速修复

我们提供自动化脚本，帮助进行设置和故障排除：

健康检查

运行全面的健康检查：

./swift-mcp.sh health

此脚本将自动验证：

• Swift安装和版本
• SourceKit-LSP可用性
• Xcode路径配置
• 服务器二进制文件存在性
• 包依赖
• 传输模式功能

快速修复脚本

自动解决问题：

# 一体化管理脚本
./swift-mcp.sh              # 设置所有内容（默认）

# 特定功能  
./swift-mcp.sh build        # 仅构建服务器
./swift-mcp.sh vscode       # 设置VS Code配置
./swift-mcp.sh test         # 测试功能  
./swift-mcp.sh stdio        # 运行持久化STDIO模式
./swift-mcp.sh health       # 健康检查

swift-mcp.sh 脚本将自动：

• 构建服务器
• 配置VS Code MCP集成
• 测试所有功能
• 提供持久化STDIO模式
• 运行全面的健康检查

📄 许可证

本项目采用MIT许可证，详细信息请参阅 LICENSE 文件。

🙏 致谢

• Swift社区：基于Swift 6和现代并发模式构建
• SourceKit-LSP：集成SourceKit-LSP进行准确的Swift分析
• MCP生态系统：与VS Code MCP扩展和Serena编码代理兼容
• 开源社区：站在Swift生态系统巨人的肩膀上

准备好为你的Swift开发工作流加速了吗？

从 ./quick-start.sh 开始，在30秒内体验企业级Swift项目分析！ 🚀