Swift Selena

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

斯威夫特赛琳娜 是一个MCP（模型上下文协议）服务器，为Claude AI提供Swift代码分析功能。它甚至可以处理构建错误，并强烈支持SwiftUI应用程序开发。

  

日语版在这里

主要特点

• 免费构建：通过基于SwiftSyntax的静态分析，即使在构建错误的情况下也能工作
• LSP集成：项目可构建时SourceKit LSP的高级功能（v0.5.1+）
• 元工具模式：通过动态工具加载减少上下文窗口的使用（v0.6.2+）
• Swift测试支持：检测XCTest和Swift测试（@Test、@Suite）测试用例
• SwiftUI支持：自动检测属性包装器（@State、@Binding等）
• 快速搜索：基于文件系统的搜索，即使在大型项目上也能实现快速性能
• 智能缓存：缓存快速重复查询的分析结果
• 多客户端支持：同时使用Claude Code和Claude Desktop

提供的工具

元工具模式（v0.6.2+）

Swift Selena使用 元工具模式 这只向Claude公开了4个工具，减少了上下文窗口的使用。实际的分析工具是按需动态加载的。

外露工具：

• initialize_project -初始化项目（必须先调用）
• list_available_tools -列出所有可用的分析工具及其说明
• get_tool_schema -获取特定工具的JSON模式
• execute_tool -按名称执行任何分析工具

可用分析工具（通过execute_tool）

文件搜索

• find_files -按通配符模式搜索文件（例如。， *ViewModel.swift)
• search_code -使用正则表达式搜索代码内容
• search_files_without_pattern -无模式搜索文件（grep-L等效）

符号分析

• list_symbols -列出所有符号（类、结构、函数等）
• find_symbol_definition -在整个项目中查找符号定义

SwiftUI分析

• list_property_wrappers -检测SwiftUI属性包装器（@State、@Binding等）
• list_protocol_conformances -分析协议一致性和继承（UITableViewDelegate、ObservableObject等）
• list_extensions -分析扩展（扩展类型、协议一致性、成员）

代码分析

• analyze_imports -分析整个项目的导入依赖关系（模块使用统计数据，缓存）
• get_type_hierarchy -获取类型继承层次结构（超类、子类、一致类型、缓存）
• find_test_cases -检测XCTest和Swift测试（@Test，@Suite）测试用例

安装

需求

• macOS 13.0或更高版本
• Swift 5.9或更高版本

构建步骤

# Clone the repository
git clone https://github.com/BlueEventHorizon/Swift-Selena.git
cd Swift-Selena

# Build (release mode for production)
make build-release

# Or using swift directly:
# swift build -c release -Xswiftc -Osize

构建工件生成于 .build/release/Swift-Selena.

可用的生成命令

make help  # Show all available commands

构建

注册/注销

调试和记录

日志文件监控（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

提示： 保持 tail -f 在单独的终端中运行，同时使用Swift Selena进行实时调试。

设置

易于设置（推荐）

使用Swift Selena项目根目录中的make命令：

适用于克劳德桌面

make register-desktop

克劳德代码

# For production use (register to target project)
make register-release
# → Prompts: Enter the target project path

# For development/testing (register to Swift-Selena project itself)
make register-debug

注销

# Unregister from Claude Desktop
make unregister-desktop

# Unregister from target project
make unregister-release
# → Prompts: Enter the target project path (leave blank for current directory)

# Unregister debug version from this project
make unregister-debug

手动设置

如果您更喜欢手动配置：

Claude桌面设置

1. 打开配置文件（如果不存在则创建）：

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

1. 添加以下内容：

{
  "mcpServers": {
    "swift-selena": {
      "command": "/path/to/Swift-Selena/.build/release/Swift-Selena",
      "env": {
        "MCP_CLIENT_ID": "claude-desktop"
      }
    }
  },
  "isUsingBuiltInNodeForMcp": true
}

重要：替换 /path/to/Swift-Selena 与实际路径。

1. 重新启动克劳德桌面

Claude代码手动设置

在目标项目目录中：

cd /path/to/your/project
claude mcp add swift-selena -- /path/to/Swift-Selena/.build/release/Swift-Selena

这将仅为该项目创建本地配置。

在全球范围内使用 （所有项目）：

cd ~
claude mcp add -s user swift-selena -- /path/to/Swift-Selena/.build/release/Swift-Selena

参见 Claude代码文档 了解更多MCP服务器配置选项。

用法

基本工作流程

1. 初始化项目

Ask Claude: "Analyze this Swift project"
→ initialize_project is automatically executed

1. 搜索和分析代码

"Find ViewModels"
→ find_files searches for *ViewModel.swift

"Which files use @State?"
→ list_property_wrappers detects them

1. 分析代码结构

"Show me the type hierarchy for ViewController"
→ get_type_hierarchy displays inheritance

实际案例

检查SwiftUI属性包装器

You: Tell me what Property Wrappers are used in ContentView.swift

Claude: Executes list_property_wrappers
Result:
[@State] counter: Int (line 12)
[@ObservedObject] viewModel: ViewModel (line 13)
[@EnvironmentObject] appState: AppState (line 14)

查找特定功能

You: Find where the fetchData function is defined

Claude: Executes find_symbol_definition
Result:
[Function] fetchData
  File: /path/to/NetworkManager.swift
  Line: 45

检查协议一致性

You: Tell me what protocols ViewController conforms to

Claude: Executes list_protocol_conformances
Result:
[Class] ViewController (line 25)
  Inherits from: UIViewController
  Conforms to: UITableViewDelegate, UITableViewDataSource

在整个项目中搜索错误处理

You: Find all do-catch blocks

Claude: Executes search_code (regex: do\s*\{)
Result: Found 15 do-catch blocks

数据存储

分析缓存存储在以下目录中：

~/.swift-selena/
└── clients/
    ├── default/              # Claude Code (default)
    │   └── projects/
    │       └── YourProject-abc12345/
    │           └── memory.json
    └── claude-desktop/       # Claude Desktop
        └── projects/
            └── YourProject-abc12345/
                └── memory.json

• 项目由项目路径的SHA256哈希标识
• 不同的项目会自动分开
• 克劳德代码(default)和克劳德桌面(claude-desktop)数据自动分隔为 MCP_CLIENT_ID

备注：当相同 MCP_CLIENT_ID （例如，多个克劳德代码窗口）同时打开同一个项目，可能会发生内存文件写入冲突。如果在多个窗口中处理同一项目，请设置不同的 MCP_CLIENT_ID 价值观。

故障排除

MCP服务器无法启动

# Verify build
swift build

# Test execution
.build/release/Swift-Selena
# "Starting Swift MCP Server..." should appear
# Press Ctrl+C to exit

未找到工具

1. 重新启动克劳德桌面/代码
2. 验证配置文件路径是否正确
3. 检查日志：

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

清除旧缓存

rm -rf ~/.swift-selena/

将在下一次重建 initialize_project 执行。

高级配置

传统模式（所有工具均已公开）

默认情况下，Swift Selena使用 元工具模式 （v0.6.2+）。如果您希望直接公开所有12个分析工具，而不需要元工具间接，请设置 SWIFT_SELENA_LEGACY=1 环境变量：

克劳德桌面

{
  "mcpServers": {
    "swift-selena": {
      "command": "/path/to/Swift-Selena/.build/release/Swift-Selena",
      "env": {
        "MCP_CLIENT_ID": "claude-desktop",
        "SWIFT_SELENA_LEGACY": "1"
      }
    }
  }
}

克劳德代码

claude mcp add swift-selena -e SWIFT_SELENA_LEGACY=1 -- /path/to/Swift-Selena/.build/release/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.10.2）-MCP协议实现
• Swift语法 （602.0.0）-语法解析
• CryptoKit -项目路径哈希
• swift日志 （通过MCP Swift SDK）-日志记录

贡献

欢迎问题和拉取请求！

许可证

MIT许可证-请参阅 许可证 详细信息文件

致谢

• 模型上下文协议 -MCP协议规范
• Swift语法 -Swift语法解析库
• Anthropic -克劳德·艾