Swift MCP Server

Swift MCP服务器

Swift MCP Server是Swift工作区的模型上下文协议服务器。它公开了导航、诊断、格式化和项目分析工具 stdio 或HTTP。

该项目有意分为两个分析层：

• SourceKit-LSP 用于编辑器级操作，如引用、定义、悬停、格式化和诊断。
• SwiftSyntax 加 Package.swift AST解析用于项目结构、符号索引和保守架构分析。
• AppleSDKCatalog 用于本地Xcode SDK模块发现和iOS框架分析使用的官方Apple文档参考。

状态

今天有效的方法：

• 主控程序 initialize, tools/list, tools/call, resources/list，以及 resources/read
• SourceKit-LSP-支持 find_references, get_definition, get_hover_info, format_document，以及 get_diagnostics
• 语法感知 find_symbols, analyze_project, detect_architecture, analyze_symbol_usage，以及 analyze_pop_usage
• 本地Xcode SDK编目，用于跨导入的Apple模块发现Apple框架/模块，为 FoundationModels 和 ImagePlayground
• 用于编辑器集成的STDIO传输和用于本地API使用的HTTP传输

本项目未声明的内容：

• 它不是一个完整的程序编译器分析框架
• 它不能保证每个项目都可以被分类到一个命名的架构中
• 它不再从文件名或文件夹名推断模式

默认情况下禁用架构检测。如果您想要命名模式检测，请在服务器配置中或根据MCP请求启用它。 如果语义证据较弱， detect_architecture 回报 Custom 而不是猜测。

需求

• Swift 5.9+
• 建议使用带Xcode工具链的macOS
• sourcekit-lsp 可通过Xcode或 PATH 用于导航、诊断和格式化

该项目仍然是一个没有SourceKit LSP的Swift包，但编辑器级工具将受到限制。

快速开始

构建：

swift build --configuration release

在STDIO模式下对当前工作区运行：

./.build/release/swift-mcp-server --transport stdio --workspace .

在HTTP模式下运行：

./.build/release/swift-mcp-server --transport http --workspace . --port 8080

您还可以使用辅助脚本：

./swift-mcp.sh build
./swift-mcp.sh health
./swift-mcp.sh stdio

AI/编辑器集成

支持MCP的AI客户端已经可以使用该服务器 stdio.与当地人握手 initialize 和 tools/list 对构建的二进制文件成功。

适用于MCP客户 stdio，将它们指向已构建的二进制文件：

{
  "mcp": {
    "servers": {
      "swift-mcp-server": {
        "command": "/path/to/swift-mcp-server/.build/release/swift-mcp-server",
        "args": ["--transport", "stdio", "--workspace", "/path/to/project"]
      }
    }
  }
}

还有一个签入示例 vscode-mcp-config.json.

这涵盖了支持MCP的AI/编辑器客户端，而不仅仅是VS Code：

• 克劳德桌面/Claude代码风格MCP设置
• 光标/VS代码风格MCP设置
• 任何可以生成MCP服务器的本地AI客户端 stdio

工具

SourceKit LSP支持的工具：

• find_references
• get_definition
• get_hover_info
• format_document
• get_diagnostics

语法/包分析工具：

• find_symbols
• analyze_project
• detect_architecture
• analyze_symbol_usage
• create_project_memory
• generate_migration_plan
• analyze_pop_usage
• generate_documentation
• analyze_ios_frameworks
• generate_template

analyze_ios_frameworks 现在报告：

• 从本地Xcode SDK目录解析的导入Apple模块
• 每个导入的Apple模块的语义符号点击数
• 进口苹果模块的官方文档链接
• 更丰富的特征级分析 FoundationModels 和 ImagePlayground

项目级架构检测是可选的：

• config:set "analysis": { "enableArchitectureDetection": true }
• 每次请求：通过 "enable_architecture_detection": true 到 analyze_project, detect_architecture, create_project_memory, generate_migration_plan，或 analyze_ios_frameworks

状态/缓存帮助程序：

• intelligent_project_memory

分析工作原理

find_symbols, analyze_project，以及 detect_architecture 不再使用正则表达式扫描原始文本。他们现在从以下内容构建一个解析的项目快照：

• Swift声明和引用提取 SwiftSyntax
• 导入从解析的AST节点中提取的图形和类型关系
• 从中提取目标和依赖关系信息 Package.swift 语法

这意味着项目分析人员可以推理：

• 具体类型声明
• 协议一致性和继承类型
• MVVM风格检测的可观察/视图关系
• 测试目标和包依赖关系
• 在分析过程中，无需向SwiftPM支付费用即可实现封装模块化

这也意味着一些结果是故意保守的：

• find_symbols 具有语法感知能力，但不是跨模块编译器索引
• detect_architecture 仅在代码结构支持模式时报告模式
• analyze_project 报告结构度量，而不是行覆盖率或形式复杂性证明

架构检测

当前架构检测是证据驱动的：

• TCA 当工作区显示时 ComposableArchitecture 嵌套式减速器 State 和 Action，以及存储支持的视图
• MVVM 当视图依赖于可观察的状态类型时
• MVP 当被动视图依赖于演示者类型，并且演示者自己的演示流没有可观察的状态模型时
• VIPER 当视图、演示者、交互者和路由器角色都存在，并且它们之间存在语义连接时
• Coordinator 当导航所有权集中在具有显式路由/导航API的协调器类型中时
• MVC 当控制器直接依赖于模型/域类型而没有可观察层时
• Clean Architecture 当表示依赖于协议抽象并且数据适配器跨模块边界实现这些抽象时
• Features-based 当可执行目标依赖于多个内部特征目标时
• Modular 当包被明确拆分为多个内部目标时
• Custom 当工作区没有为更强的标签提供足够的证据时

这使得误报率低于旧的文件夹名和文件名匹配方法。

发展

运行测试：

swift test

当前测试覆盖范围包括：

• JSON-RPC/MCP请求和响应形状
• SourceKit LSP格式化、诊断、悬停、定义和引用
• MVVM、TCA、VIPER和协调器的语义架构检测
• Package.swift 目标解析与依赖关系分析

项目布局

Sources/
├── SwiftMCPServer/      CLI entrypoint and transport bootstrapping
├── SwiftMCPCore/        MCP protocol, SourceKit-LSP client, syntax analysis
└── ModernConcurrency/   concurrency helpers

Tests/
└── SwiftMCPServerTests/ integration and protocol tests

备注

• 日志被写入 stderr 因此STDIO MCP输出保持干净
• 工作区路径可以通过以下方式传递 `--workspace

` 或者作为CLI接受的位置参数

• analyze_project 否时默认为当前工作区 project_path 被提供

相关文档

• CONFIG_GUIDE.md
• SERENA_INTEGRATION.md
• CONTRIBUTING.md