BlueEventHorizon/Swift-Selena

Swift Selena - Swift Analyzer MCP Server with respect to Serena

Swift Selena is an MCP (Model Context Protocol) server that provides Swift code analysis capabilities to Claude AI. It works even with build errors and strongly supports SwiftUI app development.

Key Features

• Build-Free: Works even with build errors through SwiftSyntax-based static analysis
• LSP Integration: Advanced features with SourceKit-LSP when project is buildable (v0.5.1+)
• Meta Tool Mode: Reduces context window usage with dynamic tool loading (v0.6.2+)
• Swift Testing Support: Detects both XCTest and Swift Testing (@Test, @Suite) test cases
• SwiftUI Support: Automatically detects Property Wrappers (@State, @Binding, etc.)
• Fast Search: Filesystem-based search for fast performance even on large projects
• Smart Caching: Caches analysis results for fast repeated queries
• Multi-Client Support: Use with Claude Code and Claude Desktop simultaneously

Provided Tools

Meta Tool Mode (v0.6.2+)

Swift-Selena uses a Meta Tool Mode that exposes only 4 tools to Claude, reducing context window usage. The actual analysis tools are loaded dynamically on demand.

Exposed Tools:

• initialize_project - Initialize a project (must be called first)
• list_available_tools - List all available analysis tools with descriptions
• get_tool_schema - Get the JSON schema for a specific tool
• execute_tool - Execute any analysis tool by name

Available Analysis Tools (via execute_tool)

File Search

• find_files - Search files by wildcard pattern (e.g., *ViewModel.swift)
• search_code - Search code content using regex
• search_files_without_pattern - Search files WITHOUT a pattern (grep -L equivalent)

Symbol Analysis

• list_symbols - List all symbols (Class, Struct, Function, etc.)
• find_symbol_definition - Find symbol definitions across the project

SwiftUI Analysis

• list_property_wrappers - Detect SwiftUI Property Wrappers (@State, @Binding, etc.)
• list_protocol_conformances - Analyze protocol conformances and inheritance (UITableViewDelegate, ObservableObject, etc.)
• list_extensions - Analyze extensions (extended type, protocol conformance, members)

Code Analysis

• analyze_imports - Analyze import dependencies across the project (module usage statistics, cached)
• get_type_hierarchy - Get type inheritance hierarchy (superclass, subclasses, conforming types, cached)
• find_test_cases - Detect XCTest and Swift Testing (@Test, @Suite) test cases

Installation

Requirements

• macOS 13.0 or later
• Swift 5.9 or later
• Claude Desktop or Claude Code

Build Steps

# 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

The build artifact is generated at .build/release/Swift-Selena.

Available Make Commands

make help  # Show all available commands

For release version registration, use scripts directly:

./register-selena-to-claude-code.sh /path/to/project
./unregister-selena-from-claude-code.sh [/path/to/project]

Debugging & Logging

Log File Monitoring (v0.5.3+)

Swift-Selena outputs logs to a file for debugging and troubleshooting:

Log file location:

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

Monitor logs in real-time:

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

What you can see:

• Server startup messages
• Tool execution logs
• LSP connection status (success/failure)
• Error messages and diagnostics

Example log output:

[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

Tip: Keep tail -f running in a separate terminal while using Swift-Selena for real-time debugging.

Setup

Easy Setup (Recommended)

Use make commands from the Swift-Selena project root:

For Claude Desktop

make register-desktop

For Claude Code

# For production use (register to target project)
make register-release TARGET=/path/to/your/project

# Example:
make register-release TARGET=~/apps/CCMonitor

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

Unregister

# Unregister from Claude Desktop
make unregister-desktop

# Unregister from target project
make unregister-release TARGET=/path/to/your/project

# Unregister debug version from this project
make unregister-debug

Manual Setup

If you prefer manual configuration:

Claude Desktop Setup

1. Open the config file (create if it doesn't exist):

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

2. Add the following content:

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

Important: Replace /path/to/Swift-Selena with the actual path.

3. Restart Claude Desktop

Claude Code Manual Setup

In your target project directory:

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

This creates a local configuration for that project only.

To use globally (all projects):

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

Refer to Claude Code documentation for more MCP server configuration options.

Usage

Basic Workflow

1. Initialize project

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

2. Search and analyze code

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

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

3. Analyze code structure

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

Practical Examples

Check SwiftUI Property Wrappers

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)

Find a specific function

You: Find where the fetchData function is defined

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

Check protocol conformance

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

Search for error handling across the project

You: Find all do-catch blocks

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

Data Storage

Analysis cache is stored in the following directory:

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

• Projects are identified by SHA256 hash of project path
• Different projects are automatically separated
• Claude Code (default) and Claude Desktop (claude-desktop) data is automatically separated by MCP_CLIENT_ID

Note: When the same MCP_CLIENT_ID (e.g., multiple Claude Code windows) opens the same project simultaneously, memory file write conflicts may occur. If working on the same project in multiple windows, set different MCP_CLIENT_ID values.

Troubleshooting

MCP server won't start

# Verify build
swift build

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

Tools not found

1. Restart Claude Desktop/Code
2. Verify config file paths are correct
3. Check logs:

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

Clear old cache

rm -rf ~/.swift-selena/

Will be rebuilt on next initialize_project execution.

Architecture

Core Components

• FileSearcher: Fast filesystem-based search
• SwiftSyntaxAnalyzer: Symbol extraction via AST analysis
• ProjectMemory: Persists analysis results and manages cache

Technology Stack

• MCP Swift SDK (0.10.2) - MCP protocol implementation
• SwiftSyntax (602.0.0) - Syntax parsing
• CryptoKit - Project path hashing
• swift-log - Logging

Documentation

For Users

• - This file
• - 日本語版

For Developers

• - Project overview and commands for Claude Code
• - Architecture and design principles
• - MCP server implementation guide
• - Best practices and common pitfalls

Contributing

Issues and Pull Requests are welcome!

For detailed developer information, see .

License

MIT License - See file for details

Acknowledgments

• Model Context Protocol - MCP protocol specification
• SwiftSyntax - Swift syntax parsing library
• Anthropic - Claude AI