Swift-Selena by BlueEventHorizon - MCP Server

Swift Selena

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
SwiftUI Support: Automatically detects Property Wrappers (@State, @Binding, etc.)
Fast Search: Filesystem-based search for fast performance even on large projects
Project Memory: Persists analysis results and notes across sessions
Multi-Client Support: Use with Claude Code and Claude Desktop simultaneously

Provided Tools

Project Management

initialize_project - Initialize a project (must be called first)

File Search

find_files - Search files by wildcard pattern (e.g., *ViewModel.swift)
search_code - Search code content using regex

SwiftSyntax Analysis

list_symbols - List all symbols (Class, Struct, Function, etc.)
find_symbol_definition - Find symbol definitions across the project
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)
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 test cases and test methods
find_type_usages - Find where a type is used (variable declarations, function parameters, return types)

Efficient Reading

read_function_body - Extract only a specific function implementation
read_lines - Read specific line ranges from a file

Project Notes

add_note - Save design decisions and important notes
search_notes - Search saved notes
get_project_stats - Display project statistics and cache information

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)
swift build -c release -Xswiftc -Osize

# Grant execute permission to setup scripts
chmod +x register-mcp-to-claude-desktop.sh
chmod +x register-selena-to-claude-code.sh

# Verify executable path
pwd
# Example output: /Users/yourname/Swift-Selena

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

Setup

Easy Setup (Recommended)

Run the following scripts from the project root for automatic setup:

For Claude Desktop

./register-mcp-to-claude-desktop.sh

This script automatically:

Verifies executable existence
Backs up existing configuration
Adds settings to claude_desktop_config.json
Preserves existing settings (if jq is installed)

For Claude Code (Connect to Specific Project)

To connect Swift-Selena to a specific project:

# From Swift-Selena directory
./register-selena-to-claude-code.sh /path/to/your/project

This script automatically:

Verifies executable existence
Moves to target project directory
Registers with claude mcp add (local to that project)

Alternative: Using makefile (if your project has one)

Add to your project's makefile:

connect_swift-selena:
	@if [ -n "$$SWIFT_SELENA_PATH" ]; then \
		claude mcp add swift-selena -- $$SWIFT_SELENA_PATH/.build/release/Swift-Selena; \
	else \
		echo "Set SWIFT_SELENA_PATH first"; \
	fi

Then:

export SWIFT_SELENA_PATH=/path/to/Swift-Selena
make connect_swift-selena

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

Save notes

"Note that this ViewController is for the login screen"
→ add_note saves it

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 results and notes are 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

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