swiftlens

[](https://mseep.ai/app/swiftlens-swiftlens) # SwiftLens: First MCP Server that provides Semantic-Lelvel Analysis for iOS/Swift Development **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: ```json { "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 ```bash "hey claude, run swift_build_index tool" ``` ### Building Your Project Index Manually SwiftLens requires an index store for cross-file analysis. Build it with: ```bash # 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: ```bash swift build -Xswiftc -index-store-path -Xswiftc .build/index/store ``` ### New files not recognized New files need to be indexed: ```bash swift build -Xswiftc -index-store-path -Xswiftc .build/index/store ``` ### SourceKit-LSP not found Ensure Xcode is properly installed: ```bash xcode-select -p # Should show Xcode path xcrun sourcekit-lsp --help # Should show help text ``` ## SourceKit-LSP Limitations ### Known SourceKit-LSP Limitations The SwiftLens 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](https://github.com/swiftlang/sourcekit-lsp). ## Development ### Running Tests ```bash # 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 ```bash # Format code ./format.sh # Check formatting ./format.sh check ``` ## License - FULLY AVAILABLE TO YOU FOR FREE (PERSONAL USE ONLY UNDER LICENSE) - ✅ Free for personal use and evaluation - ⚠️ Commercial use requires a license See [LICENSE.md](./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](https://github.com/swiftlens/swiftlens/issues) --- SwiftLens - Bringing compiler-grade Swift understanding to AI development