swiftlens 0.2.14

SwiftLens is a Model Context Protocol (MCP) server that provides deep, semantic-level analysis of Swift codebases to any AI models. By integrating directly with Apple's SourceKit-LSP, SwiftLens enables AI models to understand Swift code with compiler-grade accuracy.

SwiftLens: MCP Server for Swift Code Semantic Analysis

SwiftLens is a Model Context Protocol (MCP) server that provides deep, semantic-level analysis of Swift codebases to AI agents. By integrating directly with Apple's SourceKit-LSP, SwiftLens enables AI models to understand Swift code with compiler-grade accuracy.

Features

SwiftLens bridges AI models and Swift development through:

AI Agent (Claude/GPT) → MCP Protocol → SwiftLens → SourceKit-LSP → Swift Code

Core Capabilities

• LSP-Powered Semantic Analysis: Leverages SourceKit-LSP for Xcode-grade accuracy
• Token-Optimized Output: Minimizes token usage for AI interactions
• Real-time Code Understanding: Analyzes Swift files with full language feature support
• Cross-file Navigation: Symbol references, definitions, and project-wide analysis
• Code Modification Tools: Safe, atomic file operations for AI-driven refactoring
• Zero Configuration: Works out-of-the-box with standard Swift projects

Supported Swift Features

• Modern Swift syntax (actors, async/await, property wrappers, result builders)
• Generic types and protocols
• Swift Package Manager and Xcode projects
• Unicode identifiers and symbols
• Complex nested types and extensions

Installation

Prerequisites

• macOS (required for SourceKit-LSP)
• Python 3.10+
• Xcode (full installation from App Store, not just Command Line Tools)

Quick Start

Configure for Claude Code / Gemini CLI

Add to your json configuration file mcpServers section:

{
  "mcpServers": {
    "swiftlens": {
      "command": "uvx",
      "args": ["swiftlens"]
    }
  }
}

SourceKit LSP Index

SwiftLens will need proper sourcekit-lsp index in order to work properly you can either

Ask AI to build your index

"hey claude, run swift_build_index tool"

Building Your Project Index Manually

SwiftLens requires an index store for cross-file analysis. Build it with:

# Navigate to your Swift project
cd /path/to/your/swift/project

# Build with index store
swift build -Xswiftc -index-store-path -Xswiftc .build/index/store

Important: Rebuilding of the index is required when you:

• Add new Swift files
• Change public interfaces
• Notice missing symbol references

Available Tools

SwiftLens provides 15 tools for Swift code analysis:

Single-File Analysis (No Index Required)

• swift_analyze_file - Analyze structure and symbols in a Swift file
• swift_analyze_multiple_files - Batch analyze multiple files
• swift_summarize_file - Get symbol counts and file summary
• swift_get_symbols_overview - Extract top-level type declarations
• swift_get_declaration_context - Get fully-qualified symbol paths
• swift_get_file_imports - Extract import statements
• swift_validate_file - Validate syntax and types with swiftc
• swift_check_environment - Verify Swift development setup
• swift_build_index - Build index store db of current project for sourcekit-lsp

Cross-File Analysis (Requires Index)

• swift_find_symbol_references - Find all references to a symbol
• swift_get_symbol_definition - Jump to symbol definition
• swift_get_hover_info - Get type info and documentation

Code Modification

• swift_replace_symbol_body - Replace function/type body

Utilities

• swift_search_pattern - Search with regex patterns
• get_tool_help - Get help for any tool

Example Usage

Ask your AI agent:

"Analyze the UserManager.swift file and find all references to the login() method"

The AI will use SwiftLens tools to:

1. Analyze the file structure
2. Locate the login method
3. Find all project-wide references
4. Provide insights based on the analysis

Real-time Dashboard (CURRENT NOT WORKING, REWORK IMPLEMENTATION PLANNED)

SwiftLens includes a web dashboard for monitoring AI interactions:

• URL: http://localhost:53729 (when server is running)
• Features: Live tool execution logs, usage analytics, session tracking
• Security: Localhost-only access, no external connections

Troubleshooting

"Symbol not found" or "No references found"

Rebuild your index:

swift build -Xswiftc -index-store-path -Xswiftc .build/index/store

New files not recognized

New files need to be indexed:

swift build -Xswiftc -index-store-path -Xswiftc .build/index/store

SourceKit-LSP not found

Ensure Xcode is properly installed:

xcode-select -p  # Should show Xcode path
xcrun sourcekit-lsp --help  # Should show help text

LSP Limitations

Known SourceKit-LSP Limitations

The Swift Context MCP Server accurately reflects SourceKit-LSP's capabilities. The following are known limitations of SourceKit-LSP itself, not bugs in this tool:

Hover Information

• Limited support for local variables: Hover info may not be available for local variables within function bodies
• Property access issues: Expressions like object.property often don't provide hover information when inside functions
• Method call limitations: Hover on method calls with parameters may return incorrect or no information
• Success rate: Hover typically works well for type declarations, method signatures, and top-level symbols, but has approximately 44% success rate for expressions within function bodies

These limitations exist because SourceKit-LSP:

• Does not perform background indexing
• May skip function body analysis in certain configurations
• Is still in early development with acknowledged "rough edges"

For the most up-to-date status, see the SourceKit-LSP repository.

Development

Running Tests

# All tests
make test

# Unit tests only (fast, no LSP required)
make test-unit

# LSP integration tests
make test-lsp

# Check environment
make check-env

Code Quality

# Format code
./format.sh

# Check formatting
./format.sh check

License - FULLY AVAILABLE TO YOU FOR FREE (PERSONAL USE ONLY UNDER ELASTIC 2.0 LICENSE)

SwiftLens is licensed under the Elastic License 2.0:

• ✅ Free for personal use and evaluation
• ⚠️ Commercial use requires a license

See LICENSE.md for details.

Contributing

We welcome contributions! Areas where you can help:

• 🐛 Bug reports and fixes
• 📝 Documentation improvements
• 🧪 Test coverage expansion
• 🔧 New analysis capabilities

Support

• Issues: GitHub Issues

---

SwiftLens - Bringing compiler-grade Swift understanding to AI development