迅捷-MCP-服务器
项目介绍
Swift MCP Server
适用于Swift项目的生产就绪模型上下文协议（MCP）服务器。企业级双传输架构，具备全面的分析能力。
🎯 目标
Swift代码质量、架构指导和性能优化的终极工具。
专为需要可靠、快速且智能项目分析的专业Swift开发者设计，这些分析可以无缝集成到他们的工作流程中。
✅ 当前功能
🏗️ 坚实的基础
- 🔄 双传输：HTTP服务器 + STDIO用于VS Code/Serena集成
- 🛠️ 15+分析工具：符号搜索、引用查找、架构分析
- 🏢 企业就绪：JSON配置、结构化日志、优雅关闭
- ⚡ 兼容Swift 6：现代并发和生产就绪架构
- 📊 实时分析：实时编译反馈和性能指标
- 🎯 VS Code集成：直接支持MCP扩展的STDIO
🚀 开发者体验
- 一键设置：
./swift-mcp.sh- 构建、配置、测试在30秒内完成 - 自动IDE配置：VS Code开箱即用
- 全面测试：所有功能自动验证
- 自动修复常见问题：
./swift-mcp.sh解决90%的问题 - 零退出码64错误：强大的参数解析，支持位置参数
🔧 生产特性
- 跨平台：支持macOS和Linux
- 专业CLI：ArgumentParser具有全面选项
- 错误恢复：优雅处理边缘情况
- 性能优化：中型项目次秒级分析
- 内存高效：最小资源使用并清理
🚀 下一步计划
第二阶段：智能引擎（2025年第一季度）
// Swift 6合规性分析器
✅ 自动检测并发问题
✅ 建议actor隔离模式
✅ 自动修复常见的async/await错误
✅ 防止数据竞争发生
// 架构模式分析
✅ 识别MVVM、VIPER、TCA模式
✅ 检测庞大的视图控制器
✅ 建议关注点分离
✅ 推荐依赖注入
// 性能优化
✅ 查找主线程阻塞操作
✅ 建议高效的算法
✅ 识别潜在的内存泄漏
✅ 推荐缓存策略
快速开始
一键设置
# 一站式脚本 - 构建、配置、测试一切
./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
🎛️ 传输模式
VS Code集成（推荐）
# 自动VS Code配置
./swift-mcp.sh vscode # 自动设置VS Code配置
# 手动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
📊 可用分析工具
核心分析
list_symbols- 查找所有函数、类、协议和变量find_references- 定位符号在整个代码库中的使用位置analyze_architecture- 检测模式、依赖关系和代码组织generate_documentation- 自动生成全面文档analyze_project- 全面项目健康和结构分析
高级功能
- iOS框架分析 - 检测UIKit、SwiftUI、Core Data使用模式
- 依赖映射 - 可视化模块关系和耦合
- 性能分析 - 识别优化机会
- 现代并发 - 分析async/await和actor使用
- 内存安全 - 检测潜在的保留循环和内存问题
🔧 配置
项目文件
swift-mcp-server/
├── 📄 README.md # 主要文档（您在这里）
├── CONFIG_GUIDE.md # 高级配置指南
├── 📦 Package.swift # Swift包定义
├── 🛠️ 管理/
│ └── swift-mcp.sh # ⚡ 一站式管理脚本
├── ⚙️ 配置/
│ ├── vscode-mcp-config.json # VS Code MCP扩展设置
│ ├── stdio-config.json # STDIO传输配置
│ └── http-config.json # HTTP服务器配置
└── 💻 Sources/
├── SwiftMCPServer/ # 主应用程序入口点
├── SwiftMCPCore/ # 核心MCP协议实现
└── ModernConcurrency/ # Swift 6并发工具
🚨 故障排除
常见问题
退出码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进行详细故障排除。
📈 项目状态
✅ 第一阶段：基础（100%完成）
- 双传输架构（HTTP + STDIO）
- VS Code和Serena集成
- 15+分析工具正常工作
- 跨平台支持（macOS + Linux）
- 零退出码64错误
- 全面健康检查
- 生产就绪错误处理
🚀 第二阶段：智能引擎（计划2025年第一季度）
- Swift 6合规性分析器
- 架构模式检测
- 性能优化建议
- 高级内存安全性分析
- 智能代码补全
- 自动重构建议
当前状态：具备生产就绪基础的战略增强路线图。
🤝 贡献
参阅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- 架构模式检测
配置
命令行选项
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输出
企业配置
创建config.json用于高级部署：
{
"mcpServer": {
"transport": {
"type": "http",
"host": "0.0.0.0",
"portRange": {"min": 9000, "max": 9010}
}
},
"performance": {
"maxConcurrentTasks": 10,
"taskTimeoutSeconds": 30.0
}
}
API文档
可用MCP工具
核心分析
analyze_project- 完整项目分析带指标find_symbols- 高级符号搜索和过滤find_references- 符号引用跟踪get_definition- 符号定义查找
架构分析
analyze_architecture- 模式检测（MVC、MVVM、VIPER）analyze_pop_usage- 协议导向编程评估generate_documentation- 自动API文档生成
开发工具
format_document- Swift代码格式化get_hover_info- 符号信息和文档
HTTP API示例
# 列出可用工具
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"method": "tools/list", "params": {}}'
# 分析项目结构
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "analyze_project",
"arguments": {"project_path": "/path/to/project"}
}
}'
架构
项目结构
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 # 线程安全工具
传输架构
- HTTP传输：具有智能端口管理的RESTful API服务器
- STDIO传输：直接JSON-RPC通信以集成VS Code
- 统一核心：共享分析引擎服务于两种传输模式
开发
要求
- Swift 5.9+（兼容Swift 6）
- macOS 13.0+或Linux Ubuntu 18.04+
- Xcode 15.0+（包括SourceKit-LSP）
构建
# 调试构建
swift build
# 发布构建并优化
swift build --configuration release
# 运行测试
swift test
🏗️ 技术架构
传输层
// 统一的MCP核心服务多种传输模式
SwiftMCPCore/
├── MCPServer.swift // HTTP JSON-RPC服务器
├── StdioTransport.swift // VS Code STDIO集成
├── MCPProtocolHandler.swift // 协议合规层
└── ServerConfiguration.swift // 企业配置
分析引擎
// 专业Swift项目分析
SwiftMCPCore/
├── SwiftLanguageServer.swift // SourceKit-LSP集成
├── SymbolSearchEngine.swift // 高级符号搜索
├── ProjectAnalyzer.swift // 架构模式检测
├── ArchitectureAnalyzer.swift // MVVM/VIPER/TCA分析
└── iOSFrameworkAnalyzer.swift // UIKit/SwiftUI分析
现代并发
// 兼容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
从日志检查选择了哪个端口
### 路径问题
#### 项目路径未被识别
```bash
# 验证路径存在且可访问
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/sw