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項目分析！ 🚀