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.

日本語版はこちら / Japanese version

Key Features

Build-Free: Works even with build errors through SwiftSyntax-based static analysis
LSP Integration: Enhances supported tools with SourceKit-LSP when available; SwiftSyntax remains the fallback
Meta Tool Mode: Reduces context window usage with dynamic tool loading (v0.6.3+)
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.3+)

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; supports output_mode, limit, include_patterns, and exclude_patterns
search_files_without_pattern - Search files WITHOUT a pattern (grep -L equivalent); supports include_patterns and exclude_patterns

Symbol Analysis

list_symbols - List all symbols (Class, Struct, Function, etc.)
find_symbol_definition - Find symbol definitions across the project; supports symbol_kinds and scope information

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

Current Tool Notes

search_code output modes are match_detail (default), file_list, and count_only
search_code accepts limit from 1 to 10,000; values above 10,000 are clamped and reported
search_code and search_files_without_pattern use include_patterns / exclude_patterns; the old file_pattern parameter is intentionally removed and ignored if passed
find_symbol_definition accepts symbol_kinds: struct, class, enum, protocol, actor, function, variable, typealias, extension
search_code and find_symbol_definition append a --- structured --- JSON block after the human-readable text output
LSP enhancement is best-effort. Xcode project directories containing .xcodeproj currently disable LSP, and SwiftSyntax analysis is used instead

Installation

Requirements

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

Homebrew (Recommended)

Tap and install (the explicit-URL brew tap form lets this repository serve as a tap directly — no separate homebrew-* repository is required):

brew tap blueeventhorizon/swift-selena https://github.com/BlueEventHorizon/Swift-Selena
brew install blueeventhorizon/swift-selena/swift-selena
# After tap, the short form also works:
# brew install swift-selena

After brew install, the swift-selena binary is on your PATH (typically $(brew --prefix)/bin/swift-selena).

Swift toolchain requirement: Building requires Swift 5.9+ on macOS 13.0+. Verified with full Xcode 15+ providing Swift 5.9+. The Command Line Tools-only path is plausible but was not verified at the time of this release; if you have only CLT installed and brew install fails, install Xcode 15+ as a workaround.

Register to Claude Code

The binary is on PATH, so no absolute path is required:

claude mcp add -s user swift-selena -- swift-selena

Register to Claude Desktop

Claude Desktop is launched from the GUI and does not always inherit the interactive shell PATH. Use the absolute path returned by brew --prefix:

# Find the install prefix (typical: /opt/homebrew on Apple Silicon, /usr/local on Intel)
brew --prefix

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and paste the actual path (not a shell expression — JSON is not shell-expanded):

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

⚠️ Do not write $(brew --prefix) literally inside the JSON — JSON is not shell-expanded. Run brew --prefix first and paste the resulting absolute path.

Restart Claude Desktop after editing.

Build from source (Alternative)

# 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

Build

Command	Description
`make build`	Build debug version
`make build-release`	Build release version
`make clean`	Clean build artifacts

MCP Helpers

Command	Target	Description
`make connect_gemini`	Claude Code	Connect gemini-cli MCP server
`make disconnect_gemini`	Claude Code	Disconnect gemini-cli MCP server

Register / Unregister

Command	Target	Description
`make register-release`	Claude Code	Register RELEASE version (prompts for project path)
`make unregister-release`	Claude Code	Unregister RELEASE version (prompts for project path)
`make register-debug`	Claude Code	Build & register DEBUG version to Swift-Selena project
`make unregister-debug`	Claude Code	Unregister DEBUG version from Swift-Selena project
`make register-desktop`	Claude Desktop	Register to Claude Desktop
`make unregister-desktop`	Claude Desktop	Unregister from Claude Desktop

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 (for source builds)

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
# → Prompts: Enter the target project path

# 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
# → Prompts: Enter the target project path (leave blank for current directory)

# Unregister debug version from this project
make unregister-debug

Manual Setup

If you prefer manual configuration:

Claude Desktop Setup

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

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

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.

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

Initialize project

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

Search and analyze code

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

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

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

Search only production Swift files

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

Narrow symbol definitions by kind

Claude: Executes find_symbol_definition
Params:
{
  "symbol_name": "Button",
  "symbol_kinds": ["struct", "class"]
}
Result includes Scope lines and a structured JSON block.

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 debug build
swift build

# Or verify release build
swift build -c release -Xswiftc -Osize

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

Tools not found

Restart Claude Desktop/Code
Verify config file paths are correct
Check logs:

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

Clear old cache

rm -rf ~/.swift-selena/

Will be rebuilt on next initialize_project execution.

Advanced Configuration

Legacy Mode (All Tools Exposed)

By default, Swift-Selena uses Meta Tool Mode (v0.6.3+). If you prefer to have 12 tools exposed directly without meta tool indirection, set the SWIFT_SELENA_LEGACY=1 environment variable:

Claude Desktop

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

Claude Code

claude mcp add swift-selena -e SWIFT_SELENA_LEGACY=1 -- /path/to/Swift-Selena/.build/release/Swift-Selena

In legacy mode, the following 12 tools are exposed directly: 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

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.12.0) - MCP protocol implementation
SwiftSyntax (602.0.0) - Syntax parsing
CryptoKit - Project path hashing
swift-log (via MCP Swift SDK) - Logging

Contributing

Issues and Pull Requests are welcome!

License

MIT License - See LICENSE file for details

Acknowledgments

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

Name		Name	Last commit message	Last commit date
Latest commit History 225 Commits
.claude		.claude
.github		.github
.serena		.serena
.swiftpm/xcode/xcshareddata/xcschemes		.swiftpm/xcode/xcshareddata/xcschemes
Formula		Formula
Sources		Sources
Tests		Tests
docs		docs
project		project
scripts		scripts
.doc_structure.yaml		.doc_structure.yaml
.git_information.yaml		.git_information.yaml
.gitignore		.gitignore
.version-config.yaml		.version-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
Package.resolved		Package.resolved
Package.swift		Package.swift
README.ja.md		README.ja.md
README.md		README.md
makefile		makefile
selena.png		selena.png

Folders and files

Latest commit

History

Repository files navigation

Swift Selena - Swift Analyzer MCP Server with respect to Serena

Key Features

Provided Tools

Meta Tool Mode (v0.6.3+)

Available Analysis Tools (via execute_tool)

File Search

Symbol Analysis

SwiftUI Analysis

Code Analysis

Current Tool Notes

Installation

Requirements

Homebrew (Recommended)

Register to Claude Code

Register to Claude Desktop

Build from source (Alternative)

Available Make Commands

Build

MCP Helpers

Register / Unregister

Debugging & Logging

Log File Monitoring (v0.5.3+)

Setup

Easy Setup (for source builds)

For Claude Desktop

For Claude Code

Unregister

Manual Setup

Claude Desktop Setup

Claude Code Manual Setup

Usage

Basic Workflow

Practical Examples

Check SwiftUI Property Wrappers

Find a specific function

Check protocol conformance

Search for error handling across the project

Search only production Swift files

Narrow symbol definitions by kind

Data Storage

Troubleshooting

MCP server won't start

Tools not found

Clear old cache

Advanced Configuration

Legacy Mode (All Tools Exposed)

Claude Desktop

Claude Code

Architecture

Core Components

Technology Stack

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages