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

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

## 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](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 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](./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
