使用说明

Swift Selena-关于Serena的Swift分析器MCP服务器

斯威夫特赛琳娜是一种MCP（Model Context Protocol）服务器，它为Claude（AI）提供Swift项目的代码解析。即使有构建错误的代码也能工作，强力支持SwiftUI应用程序开发。

英文版本

主要特征

无需构建：基于SwiftSyntax的静态分析可在构建错误时运行
LSP统合：在可用的情况下使用SourceKit-LSP强化支持工具，在不可用的情况下使用SwiftSyntax
元工具模式：通过动态工具加载减少上下文窗口使用（v0.6.3+）
Swift Testing対応：检测XCTest和Swift Testing（@Test，@Suite）
SwiftUI対応：Property Wrapper（@State，@Binding等）を自动検出
高速検索：基于文件系统的搜索在大型项目中速度更快
智能高速缓存：缓存分析结果并加快重复查询速度
多客户端支持：Claude CodeとClaude Desktopを同时使用可能

交付工具

元工具模式（v0.6.3+）

Swift-Selena元工具模式中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。这将减少上下文窗口的使用。实际分析工具按需动态加载。

发布工具：

initialize_project -初始化项目（必须首先运行）
list_available_tools -显示可用分析工具列表和说明
get_tool_schema -获取特定工具的JSON架构
execute_tool -以名称运行分析工具

可用分析工具（通过execute_tool）

文件搜索

find_files -以通配符模式搜索文件（例如： *ViewModel.swift）
search_code -查找正则表达式中的代码内容。output_mode、limit、include_patterns、exclude_patterns 对待
search_files_without_pattern -查找不匹配模式的文件（相当于grep-L）。include_patterns、exclude_patterns 对待

符号分析

list_symbols -Class、Struct、Function等符号一览表
find_symbol_definition -在整个项目中查找符号定义。symbol_kinds 和作用域信息

SwiftUI解析

list_property_wrappers - SwiftUI Property Wrapper（@State, @Binding等）を検出
list_protocol_conformances - Protocol准据と继承关系を解析（UITableViewDelegate，ObservableObject等）
list_extensions -扩展分析（扩展类型、协议遵从性和成员列表）

代码分析

analyze_imports -分析整个项目的导入依赖关系（模块使用统计信息、高速缓存使用）
get_type_hierarchy -获取类型的继承层次（超类、子类、协议遵从性、高速缓存使用）
find_test_cases -检测XCTest和Swift Testing（@Test，@Suite）测试用例

当前工具规格的补充

search_code 的，之 output_mode 是 match_detail（既定）、file_list、count_only
search_code 的，之 limit 是1-10000。超过10000的值被截断为内部上限，并通知结果
search_code 和 search_files_without_pattern 是 include_patterns / exclude_patterns 中所述修改相应参数的值。old file_pattern 已故意取消，即使指定也将被忽略
find_symbol_definition 的，之 symbol_kinds 是 struct、class、enum、protocol、actor、function、variable、typealias、extension 可指定
search_code 和 find_symbol_definition 在人类文本输出的末尾 --- structured --- 附加JSON模块
LSP强化是最好的。.xcodeproj 在包含的Xcode项目目录中，当前禁用LSP并回退到SwiftSyntax分析

安装

必要要件

macOS 13.0以上
Swift 5.9以上
克劳德桌面版或克劳德代码

Homebrew（推奨）

点击希望安装（明示URL形式的 brew tap 将存储库本身用作tap。专用 homebrew-* 不需要存储库）：

brew tap blueeventhorizon/swift-selena https://github.com/BlueEventHorizon/Swift-Selena
brew install blueeventhorizon/swift-selena/swift-selena
# tap 後は短縮形も使えます:
# brew install swift-selena

brew install 后、swift-selena 二进制 PATH 上（通常 $(brew --prefix)/bin/swift-selena），模板名称将采用不同的格式。

Swift toolchain 要件: 构建在macOS13.0+上需要Swift5.9+。已在全Xcode15+提供Swift5.9+的环境中确认工作。仅使用Command Line Tools的构建在技术上有望成立本发布时未验证是。在只安装CLT的环境中 brew install 如果失败，请安装Xcode15+作为解决方案。

注册Claude Code

二进制波 PATH 因为在上面，所以不需要绝对路径。请选择作用域：

｜作用域｜命令｜有效范围｜ | --- | --- | --- | | local（默认值）｜ claude mcp add swift-selena -- swift-selena 只有这个项目・只有自己 | project | claude mcp add -s project swift-selena -- swift-selena 此项目.mcp.json 团队共享 | user | claude mcp add -s user swift-selena -- swift-selena 自己的全部项目

# このプロジェクトのみ（local・デフォルト）
claude mcp add swift-selena -- swift-selena

project 作用域注意事项： -s project 是 .mcp.json 提交到存储库并共享团队。注册 command 的 swift-selena（PATH ）所有团队成员 swift-selena 的 PATH 拿在上面（例如，在此Homebrew formula中部署）。未安装的成员不启动。

注册Claude Desktop

因为Claude Desktop是从GUI启动的，所以对话壳的 PATH 中所述修改相应参数的值。brew --prefix 获得绝对路径请使用：

# インストール先 prefix を確認（典型例: Apple Silicon → /opt/homebrew / Intel → /usr/local）
brew --prefix

~/Library/Application Support/Claude/claude_desktop_config.json 编辑，然后单击实际路径粘贴（因为不展开壳，所以不能直接写壳式）：

{
  "mcpServers": {
    "swift-selena": {
      "command": "/opt/homebrew/bin/swift-selena",
      "env": { "MCP_CLIENT_ID": "claude-desktop" }
    }
  }
}

⚠️ 在JSON内 $(brew --prefix) -JSON不会shell展开。brew --prefix 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

编辑后，重新启动Claude Desktop。

构建过程（替代：源构建）

对于无法使用Homebrew的环境（如受限环境），请手动构建注册：

git clone https://github.com/BlueEventHorizon/Swift-Selena.git
cd Swift-Selena
swift build -c release -Xswiftc -Osize
# 成果物: .build/release/Swift-Selena

将构建的二进制文件注册到Claude Code中：

claude mcp add -s user swift-selena -- "$(pwd)/.build/release/Swift-Selena"

所有的 make 命令、本地开发时的注册、发布步骤是 贡献.ja.md 来修改标记元素的显示属性。

调试日志功能

日志文件监视（v0.5.3+）

Swift-Selena输出到日志文件以进行调试和故障排除：

日志文件位置：

~/.swift-selena/logs/server.log

实时监视日志：

tail -f ~/.swift-selena/logs/server.log

可确认的内容：

服务器启动消息
工具运行日志
LSP接続状态（成功/失败）
错误消息和诊断信息

日志输出示例：

[17:29:24] ℹ️ [info] Starting Swift MCP Server...
[17:29:50] ℹ️ [info] Tool called: initialize_project
[17:29:50] ℹ️ [info] Attempting LSP connection...
[17:29:51] ℹ️ [info] ✅ LSP connected successfully

提示： 使用Swift-Selena时，在其他终端tail -f中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

用法

基本工作流

初始化项目

Claudeに「このSwiftプロジェクトを解析して」と依頼
→ initialize_project が自動実行される

查找和分析代码

「ViewModelを探して」
→ find_files で *ViewModel.swift を検索

「@Stateを使っているファイルは？」
→ list_property_wrappers で検出

分析代码结构

「ViewControllerの型階層を表示して」
→ get_type_hierarchy で継承関係を表示

実践例

检查SwiftUI的Property Wrapper

あなた: ContentView.swiftで使われているProperty Wrapperを教えて

Claude: list_property_wrappers を実行
結果:
[@State] counter: Int (line 12)
[@ObservedObject] viewModel: ViewModel (line 13)
[@EnvironmentObject] appState: AppState (line 14)

查找特定函数

あなた: fetchDataという関数がどこにあるか探して

Claude: find_symbol_definition を実行
結果:
[Function] fetchData
  File: /path/to/NetworkManager.swift
  Line: 45

验证协议合规性

あなた: ViewControllerがどのプロトコルに準拠しているか教えて

Claude: list_protocol_conformances を実行
結果:
[Class] ViewController (line 25)
  Inherits from: UIViewController
  Conforms to: UITableViewDelegate, UITableViewDataSource

在整个项目中查找错误处理

あなた: do-catchブロックを全部探して

Claude: search_code を実行（正規表現: do\s*\{）
結果: 15箇所のdo-catchブロックを発見

仅搜索生产代码的转换文件

Claude: search_code を実行
Params:
{
  "pattern": "URLSession\\.shared",
  "output_mode": "file_list",
  "include_patterns": ["Sources/**/*.swift"],
  "exclude_patterns": ["*Tests*"],
  "limit": 100
}

按类型缩小符号定义

Claude: find_symbol_definition を実行
Params:
{
  "symbol_name": "Button",
  "symbol_kinds": ["struct", "class"]
}
結果には Scope 行と structured JSON ブロックが含まれます。

数据位置

分析高速缓存保存在以下目录中：

~/.swift-selena/
└── clients/
    ├── default/              # Claude Code（デフォルト）
    │   └── projects/
    │       └── YourProject-abc12345/
    │           └── memory.json
    └── claude-desktop/       # Claude Desktop
        └── projects/
            └── YourProject-abc12345/
                └── memory.json

在项目路径的SHA256散列中标识同一项目
不同项目自动分离
克劳德代码(default）和Claude Desktop（claude-desktop）表示MCP_CLIENT_ID自动分离数据

注意：相同MCP_CLIENT_ID（例如，多个Claude Code窗口）中同时打开同一项目时，可能会发生内存文件写入冲突。如果要在多个窗口中处理同一项目，请选择不同的MCP_CLIENT_ID中所述修改相应参数的值。

故障排除

MCP服务器未启动

启动二进制文件，确认是否显示开始横幅：

# Homebrew でインストールした場合
swift-selena
# "Starting Swift MCP Server..." が表示されればOK。Ctrl+C で終了

如果从源构建 .build/release/Swift-Selena 执行（贡献.ja.md 参照）。

找不到工具

重新启动Claude Desktop/Code
确认配置文件的路径是否正确
查看日志：

tail -f ~/Library/Logs/Claude/mcp*.log

清除旧缓存

rm -rf ~/.swift-selena/

次回initialize_project在运行时重建。

高级设置

传统模式（所有工具直接发布）

缺省情况下，Swift-Selena是元工具模式（v0.6.3+）。如果不想经由元工具而想直接公开12个工具SWIFT_SELENA_LEGACY=1 请设置环境变量：

克劳德桌面版

{
  "mcpServers": {
    "swift-selena": {
      "command": "/opt/homebrew/bin/swift-selena",
      "env": {
        "MCP_CLIENT_ID": "claude-desktop",
        "SWIFT_SELENA_LEGACY": "1"
      }
    }
  }
}

克劳德代码

claude mcp add swift-selena -e SWIFT_SELENA_LEGACY=1 -- swift-selena

在传统模式下，以下12个工具将直接发布： initialize_project、find_files、search_code、search_files_without_pattern、list_symbols、find_symbol_definition、list_property_wrappers、list_protocol_conformances、list_extensions、analyze_imports、get_type_hierarchy、find_test_cases

体系结构

核心组件

文件搜索器：基于文件系统的快速搜索
SwiftSyntax分析仪：通过AST分析提取符号
项目内存：分析结果的持久化和高速缓存管理

技术栈

MCP Swift SDK （0.12.0）-MCP协议实现
Swift语法 （602.0.0）-构文解析
CryptoKit -散列项目路径
swift日志 （经由MCP Swift SDK）-记录

分发

欢迎Issue、Pull Request！

对于维护者的发行说明（版本更新+Homebrew公式，带图解）贡献.ja.md 来修改标记元素的显示属性。

许可证

IT许可证-了解更多信息许可证浏览文件

参考

模型上下文协议 -MCP协议规格
Swift语法 -转换语法分析库
Anthropic -克劳德·艾