使用说明

Swift MCP服务器

A. 模型上下文协议提供AI代理和编辑器的服务器语义访问Swift代码。它暴露了苹果官方语言服务器SourceKit LSP stdio 或者HTTP，因此客户端可以使用编译器自己的理解而不是文本启发式方法来导航、检查、重构和诊断Swift。

概述

AI编码代理以搜索框的方式读取代码库：作为文本。对于散文来说，这很好，但源代码是文本无法看到的声明、引用、类型和一致性的图形。一名特工在 grep 无法可靠地分辨 save() 从另一个重载中，区分阴影局部和它隐藏的属性，知道哪些类型符合协议，或者在文件中找到符号的每一个实际用途。

问题

当代理从文本中猜测结构时，错误是安静的，但代价高昂：

破碎的重构器 --查找和替换重命名会错过其他文件中的调用站点，或者重写注释和字符串中的匹配文本。
导航错误 --“转到定义”落在无关文件中的同名符号上。
错过的关系 --如果不阅读整个项目并仍在猜测，代理就无法回答“谁调用这个？”或“什么实现了这个协议？”。

这解决了什么

服务器将每个请求路由到SourceKit LSP并返回 编译器的 答案，不是文本匹配：

安全、工作区范围的重命名 更新每一个真实的参考，而不是其他。
精确导航 --类型检查器解析的确切定义、实现和引用。
结构理解 --调用和类型层次结构，因此代理可以在不读取每个文件的情况下掌握大型代码库是如何组合在一起的。
编译器诊断并修复其 --读取实际错误，然后应用编译器建议的修复。

简而言之，它将“从文本猜测”转化为“查询编译器”

服务器故意设计得很小：它只包装真正需要语言服务器的操作。LLM从源文本中已经做得很好的任何事情——摘要、解释、代码生成——都有意留给客户端，这使每个工具都以真正的编译器语义为基础。

需求

macOS与Xcode工具链
Swift 5.9或更高版本
sourcekit-lsp 可通过Xcode或 PATH （与工具链捆绑在一起）

每个工具都依赖于SourceKit LSP。核心导航工具适用于任何最新的工具链；指数支持的工具(search_workspace_symbols, rename_symbol, call_hierarchy, type_hierarchy, get_implementations)以及 code_actions 修复它最好使用当前的工具链（Xcode 16/Swift 6或更高版本），它提供了它们所依赖的后台索引。

安装

swift build --configuration release

二进制文件是在 .build/release/swift-mcp-server.

用法

运行STDIO（用于编辑器和AI客户端）：

.build/release/swift-mcp-server --transport stdio --workspace /path/to/project

通过HTTP运行（用于本地API的使用和测试）：

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

工作空间可以通过以下方式传递 --workspace <path> 或者作为一种立场论证。还提供了一个辅助脚本：

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

客户端配置

指向任何说话的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"]
      }
    }
  }
}

这适用于任何本地MCP客户端，包括Claude Code/Claude Desktop和Cursor/VS Code风格的设置。一个现成的例子生活在 vscode-mcp-config.json.

工具

所有工具都由SourceKit LSP支持。行和字符参数为 基于0.

导航和搜索

工具	目的	论点
`find_symbols`	列出文件中声明的符号，按名称筛选	`file_path`, `name_pattern`
`search_workspace_symbols`	在整个工作空间中按名称查找符号	`query`
`find_references`	在某个位置找到对符号的每个引用	`file_path`, `line`, `character`
`get_definition`	解析某个位置的符号定义	`file_path`, `line`, `character`
`get_implementations`	查找协议要求或方法的具体实现	`file_path`, `line`, `character`

检查

工具	目的	论点
`get_hover_info`	某位置符号的类型和文件	`file_path`, `line`, `character`
`get_diagnostics`	文件的编译器错误和警告	`file_path`

结构

工具	目的	论点
`call_hierarchy`	来电者(`incoming`)或被叫(`outgoing`)功能	`file_path`, `line`, `character`, `direction`
`type_hierarchy`	`supertypes` 或 `subtypes`/一种类型的构象	`file_path`, `line`, `character`, `direction`

编辑（写入磁盘）

工具	目的	论点
`format_document`	格式化文件并返回编辑结果	`file_path`
`rename_symbol`	在整个工作区重命名符号并应用编辑	`file_path`, `line`, `character`, `new_name`
`code_actions`	列表编译器在一行上修复其/重构，或 `apply` 一个按标题	`file_path`, `line`, `apply`

服务器还实现 initialize, tools/list, tools/call, resources/list，以及 resources/read，并暴露出 swift://workspace 描述活动工作区的资源。

索引支持的工具依赖于SourceKit LSP的全局索引。启动后，索引可能仍在构建中，因此这些工具在返回之前会等待有限的时间。服务器在启动时也会在后台预热索引，因此第一次调用不会受到惩罚。 rename_symbol 和一个应用 code_actions 修改磁盘上的文件。

语言

每个工具都适用于Swift，包括SwiftUI（SwiftUI代码是普通的Swift）。

还支持Objective-C、C和C++。服务器选择LSP languageId 从文件扩展名(.m → 目标-c， .mm → 客观cpp， .h → 目标-c， .c → c, .cpp/.cc/… → cpp），因此SourceKit LSP将这些文件路由到 clangd.C系列文件还需要 compile_commands.json 在工作空间中 clangd 可以解析编译器参数——纯SwiftPM包不会发出参数，因此对于混合的Swift/Objective-C项目，可以从您的构建中生成它（例如Xcode或CMake导出）。

运作原理

服务器将单个SourceKit LSP会话绑定到工作区，并将每个MCP工具调用转换为匹配的LSP请求：

工具	LSP请求
`find_symbols`	`textDocument/documentSymbol` （按名称筛选）
`search_workspace_symbols`	`workspace/symbol`
`find_references`	`textDocument/references`
`get_definition`	`textDocument/definition`
`get_implementations`	`textDocument/implementation`
`get_hover_info`	`textDocument/hover`
`get_diagnostics`	`textDocument/publishDiagnostics`
`call_hierarchy`	`textDocument/prepareCallHierarchy` + `callHierarchy/incomingCalls`
`type_hierarchy`	`textDocument/prepareTypeHierarchy` + `typeHierarchy/supertypes`
`format_document`	`textDocument/formatting`
`rename_symbol`	`textDocument/rename` （编辑应用于磁盘）
`code_actions`	`textDocument/codeAction` （应用的操作将其编辑写入磁盘）

因为结果来自编译器自己的索引，所以它们反映了真实的语言语义，而不是文本匹配。

建筑学

Sources/
├── SwiftMCPServer/      CLI entry point and transport bootstrapping
├── SwiftMCPCore/        MCP protocol, transports, and configuration
└── SourceKitLSP/        standalone SourceKit-LSP client and language types

Tests/
└── SwiftMCPServerTests/ protocol and SourceKit-LSP integration tests

SourceKitLSP 是一个自包含的库（仅依赖于Foundation和swift日志），它公开 SwiftLanguageServer 以及LSP值类型。它不了解MCP，因此可以作为可重用的SourceKit LSP客户端依赖它自己。 SwiftMCPCore 对MCP协议进行分层，并在其上进行传输——依赖关系严格来说是单向的。

发展

swift test

测试涵盖JSON-RPC/MCP请求和响应形状、公开的工具表面以及SourceKit LSP支持的端到端操作。当SourceKit LSP不可用时，需要它的测试会自动跳过。

备注

日志被写入 stderr 因此STDIO MCP输出保持干净。
HTTP模式支持通过以下方式自动选择端口 --port-min / --port-max.
集 SOURCEKIT_LSP_PATH 使用特定 sourcekit-lsp 二进制（例如自定义工具链）；否则，会探测常见的安装位置。

许可证

看许可证.

使用说明

Swift MCP服务器

概述

问题

这解决了什么

需求

安装

用法

客户端配置

工具

语言

运作原理

建筑学

发展

备注

许可证

相关 MCP

代码索引分析工具

Xcode项目操作服务器

Token节约MCP服务

语言服务协议MCP

语言服务器工具

目录树可视化工具