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: 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

Command	Description
`make build`	Build debug version
`make build-release`	Build release version
`make clean`	Clean build artifacts
`make register-debug`	Build & register DEBUG version to this project
`make register-desktop`	Register to Claude Desktop
`make unregister-debug`	Unregister DEBUG version from this project
`make unregister-desktop`	Unregister from Claude Desktop

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

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

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

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.

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

README (English) - This file
README (Japanese) - 日本語版

For Developers

CLAUDE.md - Project overview and commands for Claude Code
System Architecture - Architecture and design principles
MCP Implementation Guide - MCP server implementation guide
MCP Best Practices - Best practices and common pitfalls

Contributing

Issues and Pull Requests are welcome!

For detailed developer information, see CLAUDE.md.

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 113 Commits
.claude		.claude
.github		.github
.serena		.serena
.swiftpm/xcode/xcshareddata/xcschemes		.swiftpm/xcode/xcshareddata/xcschemes
Sources		Sources
Tests		Tests
Tools		Tools
docs		docs
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Package.resolved		Package.resolved
Package.swift		Package.swift
README.ja.md		README.ja.md
README.md		README.md
makefile		makefile
register-selena-to-claude-code.sh		register-selena-to-claude-code.sh
selena.png		selena.png
unregister-selena-from-claude-code.sh		unregister-selena-from-claude-code.sh

BlueEventHorizon/Swift-Selena

Folders and files

Latest commit

History

Repository files navigation