diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5c0e038..63c0c5e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,92 +3,219 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+  id-token: write  # Required for trusted publishing to crates.io
 
 env:
   CARGO_TERM_COLOR: always
+  CARGO_INCREMENTAL: 0
+  CARGO_NET_RETRY: 10
+  RUSTUP_MAX_RETRIES: 10
 
 jobs:
-  build:
-    name: Build ${{ matrix.target }}
+  create-release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    outputs:
+      upload_url: ${{ steps.create_release.outputs.upload_url }}
+      version: ${{ steps.get_version.outputs.version }}
+    steps:
+      - name: Get version from tag
+        id: get_version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Create Release
+        id: create_release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref }}
+          name: Release v${{ steps.get_version.outputs.version }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-crate:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Optional: use environment for additional protection
+    # environment: release
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "publish"
+
+      # Trusted Publishing: get short-lived token via OIDC
+      - name: Authenticate with crates.io
+        uses: rust-lang/crates-io-auth-action@v1
+
+      - name: Publish mcpls-core
+        run: cargo publish --package mcpls-core
+
+      - name: Wait for mcpls-core to be available on crates.io
+        run: sleep 60
+
+      - name: Verify mcpls-core is indexed
+        run: |
+          for i in {1..10}; do
+            if cargo search mcpls-core | grep -q "mcpls-core"; then
+              echo "mcpls-core is indexed"
+              exit 0
+            fi
+            echo "Waiting for mcpls-core to be indexed (attempt $i/10)..."
+            sleep 30
+          done
+          echo "mcpls-core not indexed after 5 minutes, proceeding anyway"
+
+      - name: Publish mcpls
+        run: cargo publish --package mcpls
+
+  build-release:
+    name: Build Release Binary (${{ matrix.name }})
+    needs: create-release
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-latest
-            target: x86_64-unknown-linux-gnu
-            artifact: mcpls-linux-x86_64
-          - os: ubuntu-latest
-            target: x86_64-unknown-linux-musl
-            artifact: mcpls-linux-x86_64-musl
-          - os: macos-latest
-            target: x86_64-apple-darwin
-            artifact: mcpls-macos-x86_64
-          - os: macos-latest
-            target: aarch64-apple-darwin
-            artifact: mcpls-macos-aarch64
-          - os: windows-latest
-            target: x86_64-pc-windows-msvc
-            artifact: mcpls-windows-x86_64.exe
+          # Linux x86_64 (GNU)
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            name: linux-x86_64
+            archive_ext: tar.gz
+
+          # Linux x86_64 (musl - static binary)
+          - target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+            name: linux-x86_64-musl
+            archive_ext: tar.gz
+
+          # macOS x86_64 (Intel)
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            name: macos-x86_64
+            archive_ext: tar.gz
+
+          # macOS aarch64 (Apple Silicon)
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            name: macos-aarch64
+            archive_ext: tar.gz
+
+          # Windows x86_64
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            name: windows-x86_64
+            archive_ext: zip
 
     steps:
       - uses: actions/checkout@v6
 
-      - uses: dtolnay/rust-toolchain@stable
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
         with:
           targets: ${{ matrix.target }}
 
-      - uses: Swatinem/rust-cache@v2
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@v0.0.4
 
-      - name: Install musl-tools
+      - name: Configure sccache
+        shell: bash
+        run: |
+          echo "RUSTC_WRAPPER=sccache" >> $GITHUB_ENV
+          echo "SCCACHE_GHA_ENABLED=true" >> $GITHUB_ENV
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "release-${{ matrix.target }}"
+
+      - name: Install musl-tools (Linux musl)
         if: matrix.target == 'x86_64-unknown-linux-musl'
         run: sudo apt-get update && sudo apt-get install -y musl-tools
 
-      - name: Build
-        run: cargo build --release --target ${{ matrix.target }}
+      - name: Build release binary
+        run: cargo build --release --target ${{ matrix.target }} --package mcpls
 
-      - name: Rename binary (Unix)
+      - name: Strip binary (Unix)
         if: runner.os != 'Windows'
-        run: mv target/${{ matrix.target }}/release/mcpls ${{ matrix.artifact }}
+        run: strip target/${{ matrix.target }}/release/mcpls
 
-      - name: Rename binary (Windows)
-        if: runner.os == 'Windows'
-        run: mv target/${{ matrix.target }}/release/mcpls.exe ${{ matrix.artifact }}
+      - name: Get binary name
+        id: get_binary
+        shell: bash
+        run: |
+          if [[ "${{ runner.os }}" == "Windows" ]]; then
+            echo "binary=mcpls.exe" >> $GITHUB_OUTPUT
+          else
+            echo "binary=mcpls" >> $GITHUB_OUTPUT
+          fi
 
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ matrix.artifact }}
-          path: ${{ matrix.artifact }}
+      - name: Check binary size
+        shell: bash
+        run: |
+          ls -lh target/${{ matrix.target }}/release/${{ steps.get_binary.outputs.binary }}
+          du -sh target/${{ matrix.target }}/release/${{ steps.get_binary.outputs.binary }}
 
-  release:
-    name: Create Release
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
+      - name: Create archive (Unix)
+        if: matrix.archive_ext == 'tar.gz'
+        run: |
+          cd target/${{ matrix.target }}/release
+          tar czf mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.tar.gz mcpls
+          mv mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.tar.gz ../../..
+
+      - name: Create archive (Windows)
+        if: matrix.archive_ext == 'zip'
+        shell: bash
+        run: |
+          cd target/${{ matrix.target }}/release
+          7z a mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.zip mcpls.exe
+          mv mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.zip ../../../
 
-      - name: Download artifacts
-        uses: actions/download-artifact@v4
+      - name: Upload artifact to workflow
+        uses: actions/upload-artifact@v4
         with:
-          path: artifacts
+          name: mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}
+          path: mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.${{ matrix.archive_ext }}
+          retention-days: 7
 
-      - name: Create release
+      - name: Upload to GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          draft: true
-          generate_release_notes: true
-          files: artifacts/**/*
+          tag_name: ${{ github.ref }}
+          files: mcpls-${{ needs.create-release.outputs.version }}-${{ matrix.name }}.${{ matrix.archive_ext }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  publish:
-    name: Publish to crates.io
-    needs: release
+      - name: sccache stats
+        run: sccache --show-stats
+
+  # All release jobs passed
+  release-success:
+    name: Release Success
+    needs: [create-release, publish-crate, build-release]
     runs-on: ubuntu-latest
+    if: always()
     steps:
-      - uses: actions/checkout@v6
-      - uses: dtolnay/rust-toolchain@stable
-      - run: cargo publish -p mcpls-core --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
-      - run: cargo publish -p mcpls --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
+      - name: Check all jobs
+        run: |
+          if [[ "${{ needs.create-release.result }}" != "success" ]] || \
+             [[ "${{ needs.publish-crate.result }}" != "success" ]] || \
+             [[ "${{ needs.build-release.result }}" != "success" ]]; then
+            echo "One or more release jobs failed"
+            exit 1
+          fi
+          echo "All release jobs passed successfully!"
+          echo "Version ${{ needs.create-release.outputs.version }} released!"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b9b6a7..af937d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,45 +7,240 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - 2024-12-24
+
+Initial release of mcpls - Universal MCP to LSP bridge enabling AI agents to access semantic code intelligence.
+
 ### Added
 
-- Initial project structure with workspace layout
-- Core library (`mcpls-core`) with protocol translation foundation
-- CLI application (`mcpls`) with argument parsing and logging
-- LSP client module structure
-- MCP tool definitions for 8 core tools:
-  - `get_hover` - Get type information and documentation
-  - `get_definition` - Jump to symbol definition
-  - `get_references` - Find all references
-  - `get_diagnostics` - Get compiler diagnostics
-  - `get_completions` - Get code completions
-  - `rename_symbol` - Rename symbols
-  - `get_document_symbols` - List document symbols
-  - `format_document` - Format document
-- Document state tracking for LSP synchronization
-- Position encoding conversion (MCP 1-based to LSP 0-based)
-- TOML configuration support
-- Built-in rust-analyzer default configuration
-- Dual MIT/Apache-2.0 licensing
+**Core Features**:
+- Universal MCP to LSP bridge exposing semantic code intelligence to AI agents
+- 8 MCP tools for code intelligence:
+  - `get_hover` - Type information and documentation at cursor position
+  - `get_definition` - Symbol definition location (go-to-definition)
+  - `get_references` - Find all references to a symbol across workspace
+  - `get_diagnostics` - Compiler errors, warnings, and hints
+  - `rename_symbol` - Workspace-wide symbol renaming with preview
+  - `get_completions` - Code completion suggestions with documentation
+  - `get_document_symbols` - List all symbols in a document (outline view)
+  - `format_document` - Code formatting according to language server rules
+- LSP client implementation with JSON-RPC 2.0 transport over stdio
+- Support for multiple concurrent language servers (one per language)
+- Intelligent LSP server lifecycle management (spawn, initialize, shutdown)
+- Position encoding conversion (MCP 1-based to LSP 0-based, UTF-8/UTF-16/UTF-32)
+- Document state tracking with lazy loading and synchronization
+- Path validation and workspace boundary security
+- TOML configuration support with multiple discovery locations
+
+**Language Support**:
+- Built-in rust-analyzer support (zero-config for Rust projects)
+- Configurable support for any LSP-compliant language server:
+  - Python (pyright, pylsp)
+  - TypeScript/JavaScript (typescript-language-server)
+  - Go (gopls)
+  - C/C++ (clangd)
+  - Java (jdtls)
+  - And any other LSP 3.17 compliant server
+
+**CLI & Configuration**:
+- `mcpls` binary with stdio transport for MCP protocol
+- Configuration file support (`mcpls.toml`) with auto-discovery:
+  - `--config` flag
+  - `$MCPLS_CONFIG` environment variable
+  - `./mcpls.toml` (current directory)
+  - `~/.config/mcpls/mcpls.toml` (user config)
+- Structured logging (JSON and human-readable formats)
+- Log level control via `--log-level` and `$MCPLS_LOG`
+- Environment variable support for all settings
+- Workspace root auto-detection from current directory
+
+**Testing Infrastructure**:
+- 72+ unit and integration tests (100% pass rate)
+- Mock LSP server for isolated unit testing
+- Integration tests with real rust-analyzer
+- End-to-end MCP protocol tests
+- Test fixtures (Rust workspace, configuration files)
+- cargo-nextest configuration for parallel test execution
+- 51.32% code coverage baseline
+
+**Documentation**:
+- Comprehensive README with quick start guide
+- User documentation:
+  - Getting started guide with Claude Code integration
+  - Configuration reference with examples
+  - Tools reference (all 8 MCP tools documented)
+  - Troubleshooting guide with common issues
+- API documentation (rustdoc) for all public APIs
+- Architecture Decision Records (7 ADRs):
+  - ADR-001: Workspace structure
+  - ADR-002: Error handling strategy
+  - ADR-003: Async runtime selection
+  - ADR-004: Position encoding conversion
+  - ADR-005: Document state management
+  - ADR-006: Configuration format
+  - ADR-007: rmcp integration
+- Example configurations for multiple languages
+
+**Quality & CI/CD**:
+- Comprehensive CI/CD pipeline with GitHub Actions
+- Multi-platform testing (Linux, macOS, Windows)
+- Security audit with cargo-deny (advisories, licenses, bans)
+- Clippy linting (pedantic + nursery level warnings)
+- rustfmt code formatting enforcement
+- Documentation completeness checks
+- Code coverage reporting with codecov
+- MSRV enforcement (Rust 1.85, Edition 2024)
+- Automated release workflow:
+  - Binary builds for 5 platforms (Linux x86_64, Linux musl, macOS x86_64, macOS aarch64, Windows x86_64)
+  - Automatic publishing to crates.io (mcpls-core first, then mcpls)
+  - GitHub Releases with binary artifacts
+  - Changelog integration
+
+**Performance & Optimization**:
+- Optimized release profile with LTO and code generation settings
+- Binary size optimization (strip symbols, single codegen unit)
+- Async-first design for concurrent LSP server management
+- Efficient document synchronization (incremental updates)
+- Lazy initialization of LSP servers
+- Resource limits and timeouts
+
+**Security**:
+- Path validation for all file operations (workspace boundary checks)
+- No `unsafe` code allowed (enforced by lints)
+- Regular dependency audits (cargo-deny)
+- License compliance verification (MIT OR Apache-2.0)
+- Secure LSP server process spawning
+- Input validation for all MCP tool parameters
+
+**Developer Experience**:
+- Workspace-based Cargo project (mcpls-core library, mcpls CLI)
+- Comprehensive error messages with context
+- Tracing-based logging with structured output
+- Mock infrastructure for testing
+- Clear contribution guidelines
+- Issue and PR templates
 
 ### Changed
 
-- N/A
+- N/A (initial release)
 
 ### Deprecated
 
-- N/A
+- N/A (initial release)
 
 ### Removed
 
-- N/A
+- N/A (initial release)
 
 ### Fixed
 
-- N/A
+- N/A (initial release)
 
 ### Security
 
-- N/A
+- Path validation prevents access outside workspace boundaries
+- All LSP file operations validated against workspace roots
+- Resource limits enforced for document tracking
+- No unsafe code (enforced via workspace lints)
+- Regular security audits via cargo-deny in CI
+- Dependency vulnerability scanning on every commit
+
+## Technical Details
+
+**Architecture**:
+```
+AI Agent (Claude)
+    ↓ MCP Protocol (JSON-RPC 2.0)
+mcpls Server (rmcp)
+    ↓ Translation Layer
+LSP Client Manager
+    ↓ LSP Protocol (JSON-RPC 2.0)
+Language Servers (rust-analyzer, pyright, etc.)
+```
+
+**Dependencies**:
+- rmcp 0.12 - Official MCP Rust SDK
+- lsp-types 0.97 - LSP type definitions
+- tokio 1.48 - Async runtime
+- serde/serde_json 1.0 - Serialization
+- clap 4.5 - CLI argument parsing
+- tracing 0.1 - Structured logging
+
+**Supported Platforms**:
+- Linux x86_64 (glibc and musl)
+- macOS x86_64 (Intel)
+- macOS aarch64 (Apple Silicon)
+- Windows x86_64
+
+**Rust Version**:
+- MSRV: 1.85
+- Edition: 2024
+- Stable Rust required
+
+**Installation Methods**:
+1. From crates.io: `cargo install mcpls`
+2. From source: `cargo install --path crates/mcpls-cli`
+3. Pre-built binaries from GitHub Releases
+
+**Configuration Example**:
+```toml
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+```
+
+**Usage with Claude Code**:
+Add to `~/.claude/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "mcpls": {
+      "command": "mcpls",
+      "args": []
+    }
+  }
+}
+```
+
+## Known Limitations
+
+- LSP servers must be installed separately (not bundled)
+- Language server initialization can take 1-5 seconds on first use
+- Limited to LSP 3.17 protocol features
+- No support for LSP extensions (server-specific features)
+- Document synchronization is full-text (not incremental at protocol level)
+
+## Future Roadmap
+
+**Phase 7** (Enhanced Features):
+- Workspace symbol search across files
+- Code actions (quick fixes, refactorings)
+- Semantic tokens (syntax highlighting)
+- Call hierarchy (incoming/outgoing calls)
+- Type hierarchy
+- Inlay hints
+
+**Phase 8** (Performance & Scale):
+- LSP server connection pooling
+- Response caching
+- Incremental document sync at protocol level
+- Batch request optimization
+- Memory usage optimization
+
+**Phase 9** (Developer Experience):
+- Configuration schema with validation
+- Better error messages with recovery suggestions
+- Progress reporting for long operations
+- Workspace auto-discovery
+- LSP server auto-detection and installation
 
 [Unreleased]: https://github.com/bug-ops/mcpls/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bug-ops/mcpls/releases/tag/v0.1.0
diff --git a/Cargo.lock b/Cargo.lock
index ed206d7..e7f1f60 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -626,6 +626,7 @@ dependencies = [
 name = "mcpls-core"
 version = "0.1.0"
 dependencies = [
+ "anyhow",
  "async-trait",
  "dirs",
  "futures",
@@ -1607,6 +1608,6 @@ checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
 
 [[package]]
 name = "zmij"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e404bcd8afdaf006e529269d3e85a743f9480c3cef60034d77860d02964f3ba"
+checksum = "f1dccf46b25b205e4bebe1d5258a991df1cc17801017a845cb5b3fe0269781aa"
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..06db59c
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,42 @@
+# Multi-stage build for mcpls
+# Build stage uses rust:1.85-slim, runtime uses debian:bookworm-slim
+
+# Build stage
+FROM rust:1.85-slim as builder
+
+WORKDIR /app
+
+# Copy workspace files
+COPY Cargo.toml Cargo.lock ./
+COPY crates/ ./crates/
+
+# Build release binary
+RUN cargo build --release --package mcpls
+
+# Runtime stage
+FROM debian:bookworm-slim
+
+# Install runtime dependencies (CA certificates for HTTPS)
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy only the binary from builder stage
+COPY --from=builder /app/target/release/mcpls /usr/local/bin/mcpls
+
+# Create config directory
+RUN mkdir -p /etc/mcpls
+
+# Set default environment variables
+ENV MCPLS_CONFIG=/etc/mcpls/mcpls.toml
+ENV MCPLS_LOG=info
+
+# Run as non-root user for security
+RUN useradd -m -u 1000 mcpls && \
+    chown -R mcpls:mcpls /etc/mcpls
+
+USER mcpls
+WORKDIR /home/mcpls
+
+ENTRYPOINT ["mcpls"]
+CMD []
diff --git a/crates/mcpls-core/Cargo.toml b/crates/mcpls-core/Cargo.toml
index 7859929..459882d 100644
--- a/crates/mcpls-core/Cargo.toml
+++ b/crates/mcpls-core/Cargo.toml
@@ -28,6 +28,7 @@ dirs.workspace = true
 rstest.workspace = true
 tempfile.workspace = true
 tokio = { workspace = true, features = ["test-util"] }
+anyhow.workspace = true
 
 [lints]
 workspace = true
diff --git a/crates/mcpls-core/src/bridge/mod.rs b/crates/mcpls-core/src/bridge/mod.rs
index 9dfa6dd..b84f9ca 100644
--- a/crates/mcpls-core/src/bridge/mod.rs
+++ b/crates/mcpls-core/src/bridge/mod.rs
@@ -9,4 +9,8 @@ mod translator;
 
 pub use encoding::{PositionEncoding, lsp_to_mcp_position, mcp_to_lsp_position};
 pub use state::{DocumentState, DocumentTracker};
-pub use translator::Translator;
+pub use translator::{
+    Completion, CompletionsResult, DefinitionResult, Diagnostic, DiagnosticSeverity,
+    DiagnosticsResult, DocumentChanges, DocumentSymbolsResult, FormatDocumentResult, HoverResult,
+    Location, Position2D, Range, ReferencesResult, RenameResult, Symbol, TextEdit, Translator,
+};
diff --git a/crates/mcpls-core/src/bridge/translator.rs b/crates/mcpls-core/src/bridge/translator.rs
index 40e569e..c1ae7dc 100644
--- a/crates/mcpls-core/src/bridge/translator.rs
+++ b/crates/mcpls-core/src/bridge/translator.rs
@@ -128,9 +128,13 @@ pub struct ReferencesResult {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum DiagnosticSeverity {
+    /// Error diagnostic.
     Error,
+    /// Warning diagnostic.
     Warning,
+    /// Informational diagnostic.
     Information,
+    /// Hint diagnostic.
     Hint,
 }
 
diff --git a/crates/mcpls-core/tests/e2e/mcp_client.rs b/crates/mcpls-core/tests/e2e/mcp_client.rs
new file mode 100644
index 0000000..65e21e1
--- /dev/null
+++ b/crates/mcpls-core/tests/e2e/mcp_client.rs
@@ -0,0 +1,276 @@
+//! MCP client simulator for end-to-end testing.
+//!
+//! This module provides a synchronous MCP client that spawns the mcpls binary
+//! and communicates via stdio using the JSON-RPC 2.0 protocol.
+
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
+
+use anyhow::{Context, Result};
+use serde_json::{Value, json};
+
+/// Simulates an MCP client (like Claude Code) for E2E testing.
+///
+/// This client spawns the mcpls binary as a child process and communicates
+/// with it via stdio using JSON-RPC 2.0 protocol.
+///
+/// # Examples
+///
+/// ```no_run
+/// use mcpls_core::tests::e2e::mcp_client::McpClient;
+///
+/// let mut client = McpClient::spawn()?;
+/// let response = client.initialize()?;
+/// assert!(response.get("result").is_some());
+/// # Ok::<(), anyhow::Error>(())
+/// ```
+pub struct McpClient {
+    process: Child,
+    stdin: ChildStdin,
+    stdout: BufReader<ChildStdout>,
+    request_id: i64,
+}
+
+impl McpClient {
+    /// Spawn mcpls process and connect via stdio.
+    ///
+    /// Uses an empty configuration file for testing the MCP protocol layer only.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The mcpls binary cannot be found or spawned
+    /// - stdin or stdout cannot be captured
+    pub fn spawn() -> Result<Self> {
+        // Use empty config to avoid LSP server initialization timeouts
+        let config_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("tests/fixtures/empty_config.toml");
+
+        Self::spawn_with_args(&[
+            "--config",
+            config_path
+                .to_str()
+                .ok_or_else(|| anyhow::anyhow!("Invalid config path"))?,
+        ])
+    }
+
+    /// Spawn mcpls process with custom arguments.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The mcpls binary cannot be found or spawned
+    /// - stdin or stdout cannot be captured
+    pub fn spawn_with_args(args: &[&str]) -> Result<Self> {
+        // Get binary path from cargo test environment
+        // CARGO_BIN_EXE_mcpls is only set for tests in the mcpls-cli crate.
+        // For tests in mcpls-core, compute workspace root from CARGO_MANIFEST_DIR.
+        let binary_path = std::env::var("CARGO_BIN_EXE_mcpls")
+            .ok()
+            .or_else(|| {
+                let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+                manifest_dir
+                    .ancestors()
+                    .nth(2) // mcpls-core -> crates -> workspace
+                    .map(|root| {
+                        root.join("target/debug/mcpls")
+                            .to_string_lossy()
+                            .into_owned()
+                    })
+            })
+            .unwrap_or_else(|| "target/debug/mcpls".to_string());
+
+        let mut process = Command::new(binary_path)
+            .args(args)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .spawn()
+            .context("failed to spawn mcpls binary")?;
+
+        let stdin = process
+            .stdin
+            .take()
+            .context("failed to capture stdin of mcpls process")?;
+
+        let stdout = process
+            .stdout
+            .take()
+            .context("failed to capture stdout of mcpls process")?;
+
+        Ok(Self {
+            process,
+            stdin,
+            stdout: BufReader::new(stdout),
+            request_id: 0,
+        })
+    }
+
+    /// Send MCP initialize request.
+    ///
+    /// This establishes the MCP connection and negotiates protocol version.
+    /// After receiving the initialize response, sends the initialized notification
+    /// as required by the MCP protocol.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The request cannot be sent
+    /// - The response cannot be read or parsed
+    /// - The server returns an error response
+    pub fn initialize(&mut self) -> Result<Value> {
+        let request = json!({
+            "jsonrpc": "2.0",
+            "id": self.next_id(),
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {
+                    "name": "mcpls-e2e-test",
+                    "version": "0.1.0"
+                }
+            }
+        });
+
+        let response = self.send_request(&request)?;
+
+        // Send initialized notification as required by MCP protocol
+        self.send_notification("notifications/initialized", &json!({}))?;
+
+        Ok(response)
+    }
+
+    /// List available MCP tools.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The request cannot be sent
+    /// - The response cannot be read or parsed
+    /// - The server returns an error response
+    pub fn list_tools(&mut self) -> Result<Value> {
+        let request = json!({
+            "jsonrpc": "2.0",
+            "id": self.next_id(),
+            "method": "tools/list",
+            "params": {}
+        });
+
+        self.send_request(&request)
+    }
+
+    /// Call a tool by name with parameters.
+    ///
+    /// # Parameters
+    ///
+    /// - `name`: The name of the tool to call
+    /// - `arguments`: JSON object with tool-specific parameters
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The request cannot be sent
+    /// - The response cannot be read or parsed
+    /// - The server returns an error response
+    /// - The tool does not exist
+    /// - The parameters are invalid
+    pub fn call_tool(&mut self, name: &str, arguments: &Value) -> Result<Value> {
+        let request = json!({
+            "jsonrpc": "2.0",
+            "id": self.next_id(),
+            "method": "tools/call",
+            "params": {
+                "name": name,
+                "arguments": arguments
+            }
+        });
+
+        self.send_request(&request)
+    }
+
+    /// Send a raw JSON-RPC request and return the response.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The request cannot be serialized or sent
+    /// - The response cannot be read or parsed
+    /// - The server returns an error response
+    fn send_request(&mut self, request: &Value) -> Result<Value> {
+        let request_str = serde_json::to_string(request)?;
+        writeln!(self.stdin, "{request_str}")?;
+        self.stdin.flush()?;
+
+        let mut line = String::new();
+        self.stdout
+            .read_line(&mut line)
+            .context("failed to read response from mcpls")?;
+
+        let response: Value =
+            serde_json::from_str(&line).context("failed to parse JSON-RPC response")?;
+
+        if let Some(error) = response.get("error") {
+            anyhow::bail!("MCP error: {error:?}");
+        }
+
+        Ok(response)
+    }
+
+    /// Send a notification (request without expecting a response).
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The notification cannot be serialized or sent
+    fn send_notification(&mut self, method: &str, params: &Value) -> Result<()> {
+        let notification = json!({
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params
+        });
+
+        let notification_str = serde_json::to_string(&notification)?;
+        writeln!(self.stdin, "{notification_str}")?;
+        self.stdin.flush()?;
+
+        Ok(())
+    }
+
+    /// Get the next request ID and increment the counter.
+    // False positive: clippy suggests const fn, but const fn cannot mutate self
+    #[allow(clippy::missing_const_for_fn)]
+    fn next_id(&mut self) -> i64 {
+        self.request_id += 1;
+        self.request_id
+    }
+}
+
+impl Drop for McpClient {
+    fn drop(&mut self) {
+        let _ = self.process.kill();
+        let _ = self.process.wait();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[ignore = "Requires mcpls binary built"]
+    fn test_mcp_client_spawn() {
+        let client = McpClient::spawn();
+        assert!(client.is_ok(), "Should successfully spawn mcpls binary");
+    }
+
+    #[test]
+    #[ignore = "Requires mcpls binary built"]
+    fn test_request_id_increment() -> Result<()> {
+        let mut client = McpClient::spawn()?;
+        assert_eq!(client.next_id(), 1);
+        assert_eq!(client.next_id(), 2);
+        assert_eq!(client.next_id(), 3);
+        Ok(())
+    }
+}
diff --git a/crates/mcpls-core/tests/e2e/mod.rs b/crates/mcpls-core/tests/e2e/mod.rs
new file mode 100644
index 0000000..02bb83d
--- /dev/null
+++ b/crates/mcpls-core/tests/e2e/mod.rs
@@ -0,0 +1,4 @@
+//! End-to-end tests for MCP protocol.
+
+pub mod mcp_client;
+pub mod protocol_tests;
diff --git a/crates/mcpls-core/tests/e2e/protocol_tests.rs b/crates/mcpls-core/tests/e2e/protocol_tests.rs
new file mode 100644
index 0000000..b2a22b8
--- /dev/null
+++ b/crates/mcpls-core/tests/e2e/protocol_tests.rs
@@ -0,0 +1,343 @@
+//! End-to-end tests for MCP protocol implementation.
+//!
+//! These tests validate the complete MCP protocol flow by spawning the mcpls
+//! binary and communicating with it as a real MCP client would.
+
+use anyhow::Result;
+use serde_json::json;
+
+use super::mcp_client::McpClient;
+
+/// Test the MCP initialize handshake.
+///
+/// Validates that the server:
+/// - Accepts the initialize request
+/// - Returns the correct protocol version
+/// - Exposes tool capabilities
+/// - Provides server information
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_initialize_handshake() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+
+    let response = client.initialize()?;
+
+    assert!(
+        response.get("result").is_some(),
+        "Response should have 'result' field"
+    );
+
+    let result = &response["result"];
+
+    assert_eq!(
+        result["protocolVersion"], "2024-11-05",
+        "Protocol version should match"
+    );
+
+    assert!(
+        result["capabilities"]["tools"].is_object(),
+        "Should expose tools capability"
+    );
+
+    assert_eq!(
+        result["serverInfo"]["name"], "mcpls",
+        "Server name should be 'mcpls'"
+    );
+
+    Ok(())
+}
+
+/// Test listing all available MCP tools.
+///
+/// Validates that:
+/// - tools/list returns an array of 8 tools
+/// - All expected tool names are present
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_list_tools() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let response = client.list_tools()?;
+
+    let tools = response["result"]["tools"]
+        .as_array()
+        .unwrap_or_else(|| panic!("tools should be an array"));
+
+    assert_eq!(tools.len(), 8, "Should have exactly 8 tools");
+
+    let tool_names: Vec<&str> = tools.iter().filter_map(|t| t["name"].as_str()).collect();
+
+    assert!(
+        tool_names.contains(&"get_hover"),
+        "Should have get_hover tool"
+    );
+    assert!(
+        tool_names.contains(&"get_definition"),
+        "Should have get_definition tool"
+    );
+    assert!(
+        tool_names.contains(&"get_references"),
+        "Should have get_references tool"
+    );
+    assert!(
+        tool_names.contains(&"get_diagnostics"),
+        "Should have get_diagnostics tool"
+    );
+    assert!(
+        tool_names.contains(&"rename_symbol"),
+        "Should have rename_symbol tool"
+    );
+    assert!(
+        tool_names.contains(&"get_completions"),
+        "Should have get_completions tool"
+    );
+    assert!(
+        tool_names.contains(&"get_document_symbols"),
+        "Should have get_document_symbols tool"
+    );
+    assert!(
+        tool_names.contains(&"format_document"),
+        "Should have format_document tool"
+    );
+
+    Ok(())
+}
+
+/// Test that all tools have valid JSON schemas.
+///
+/// Validates that each tool has:
+/// - A name (string)
+/// - A description (string)
+/// - An input schema (object)
+/// - Schema with "object" type
+/// - Schema with properties
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_tool_schemas() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let response = client.list_tools()?;
+    let tools = response["result"]["tools"]
+        .as_array()
+        .unwrap_or_else(|| panic!("tools should be an array"));
+
+    for tool in tools {
+        let tool_name = tool["name"]
+            .as_str()
+            .unwrap_or_else(|| panic!("Tool should have name field"));
+
+        assert!(
+            tool["name"].is_string(),
+            "Tool '{tool_name}' should have name as string"
+        );
+
+        assert!(
+            tool["description"].is_string(),
+            "Tool '{tool_name}' should have description as string"
+        );
+
+        assert!(
+            tool["inputSchema"].is_object(),
+            "Tool '{tool_name}' should have inputSchema as object"
+        );
+
+        let schema = &tool["inputSchema"];
+
+        assert_eq!(
+            schema["type"], "object",
+            "Tool '{tool_name}' schema type should be 'object'"
+        );
+
+        assert!(
+            schema["properties"].is_object(),
+            "Tool '{tool_name}' schema should have properties object"
+        );
+    }
+
+    Ok(())
+}
+
+/// Test calling a non-existent tool.
+///
+/// Validates that the server properly rejects invalid tool calls
+/// with an appropriate error response.
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_invalid_tool_call() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let result = client.call_tool("non_existent_tool", &json!({}));
+
+    assert!(result.is_err(), "Should return error for non-existent tool");
+
+    if let Err(err) = result {
+        let error_msg = format!("{err:?}");
+        assert!(
+            error_msg.contains("error") || error_msg.contains("Error"),
+            "Error message should indicate failure"
+        );
+    }
+
+    Ok(())
+}
+
+/// Test calling a tool with missing required parameters.
+///
+/// Validates that the server properly validates tool parameters
+/// and rejects calls with missing required fields.
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_tool_call_missing_params() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let result = client.call_tool("get_hover", &json!({}));
+
+    assert!(
+        result.is_err(),
+        "Should return error for missing required parameters"
+    );
+
+    if let Err(err) = result {
+        let error_msg = format!("{err:?}");
+        assert!(
+            error_msg.contains("error") || error_msg.contains("Error"),
+            "Error message should indicate parameter validation failure"
+        );
+    }
+
+    Ok(())
+}
+
+/// Test calling `get_hover` with invalid file path.
+///
+/// Validates that the server properly handles file path validation
+/// and returns appropriate errors for non-existent files.
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_tool_call_invalid_file() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let result = client.call_tool(
+        "get_hover",
+        &json!({
+            "file_path": "/nonexistent/path/to/file.rs",
+            "line": 1,
+            "character": 1
+        }),
+    );
+
+    assert!(result.is_err(), "Should return error for non-existent file");
+
+    Ok(())
+}
+
+/// Test calling `get_definition` with out-of-bounds position.
+///
+/// Validates that the server handles position validation correctly.
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_tool_call_invalid_position() -> Result<()> {
+    use std::fs;
+
+    use tempfile::TempDir;
+
+    let mut client = McpClient::spawn()?;
+    client.initialize()?;
+
+    let temp_dir = TempDir::new()?;
+    let test_file = temp_dir.path().join("test.rs");
+    fs::write(&test_file, "fn main() {}\n")?;
+
+    let result = client.call_tool(
+        "get_definition",
+        &json!({
+            "file_path": test_file.to_string_lossy(),
+            "line": 9999,
+            "character": 9999
+        }),
+    );
+
+    // Server should either return error or empty result for out-of-bounds position
+    // Both are acceptable behaviors
+    if let Ok(response) = result {
+        // If successful, result should indicate no definition found
+        let result_field = &response["result"];
+        // Accept both null/empty results as valid responses
+        assert!(
+            result_field.is_null() || result_field.is_array() || result_field.is_object(),
+            "Should return null or empty result for invalid position"
+        );
+    }
+    // Error response is also acceptable
+
+    Ok(())
+}
+
+/// Test the complete workflow: initialize → list → call tool.
+///
+/// This test validates the typical usage pattern of an MCP client.
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_complete_workflow() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+
+    // Step 1: Initialize
+    let init_response = client.initialize()?;
+    assert!(init_response.get("result").is_some());
+
+    // Step 2: List tools
+    let list_response = client.list_tools()?;
+    let tools = list_response["result"]["tools"]
+        .as_array()
+        .unwrap_or_else(|| panic!("tools should be an array"));
+    assert!(!tools.is_empty(), "Should have tools available");
+
+    // Step 3: Verify we can attempt to call a tool (even if it fails due to no LSP)
+    // This validates the protocol flow works end-to-end
+    let _result = client.call_tool("get_diagnostics", &json!({"file_path": "test.rs"}));
+    // We don't assert success here because LSP servers may not be configured
+    // The important part is that the protocol flow works
+
+    Ok(())
+}
+
+/// Test multiple sequential requests on the same connection.
+///
+/// Validates that:
+/// - The connection remains stable across multiple requests
+/// - Request IDs increment correctly
+/// - The server handles concurrent operations properly
+#[test]
+#[ignore = "Requires mcpls binary built"]
+fn test_e2e_multiple_requests() -> Result<()> {
+    let mut client = McpClient::spawn()?;
+
+    // Multiple initialize calls should work (idempotent)
+    let response1 = client.initialize()?;
+    assert!(response1.get("result").is_some());
+
+    let response2 = client.list_tools()?;
+    assert!(response2.get("result").is_some());
+
+    let response3 = client.list_tools()?;
+    assert!(response3.get("result").is_some());
+
+    // Responses should have different IDs
+    assert_ne!(
+        response1.get("id"),
+        response2.get("id"),
+        "Different requests should have different IDs"
+    );
+    assert_ne!(
+        response2.get("id"),
+        response3.get("id"),
+        "Different requests should have different IDs"
+    );
+
+    Ok(())
+}
diff --git a/crates/mcpls-core/tests/fixtures/empty_config.toml b/crates/mcpls-core/tests/fixtures/empty_config.toml
new file mode 100644
index 0000000..4c2075e
--- /dev/null
+++ b/crates/mcpls-core/tests/fixtures/empty_config.toml
@@ -0,0 +1,7 @@
+# Empty configuration for E2E testing
+# No LSP servers configured - tests protocol only
+
+[workspace]
+roots = []
+
+# No LSP servers - we're only testing the MCP protocol layer
diff --git a/crates/mcpls-core/tests/integration/mod.rs b/crates/mcpls-core/tests/integration/mod.rs
index ddf7753..46d9ba0 100644
--- a/crates/mcpls-core/tests/integration/mod.rs
+++ b/crates/mcpls-core/tests/integration/mod.rs
@@ -1 +1,2 @@
 mod basic_tests;
+mod rust_analyzer_tests;
diff --git a/crates/mcpls-core/tests/integration/rust_analyzer_tests.rs b/crates/mcpls-core/tests/integration/rust_analyzer_tests.rs
new file mode 100644
index 0000000..8393b6c
--- /dev/null
+++ b/crates/mcpls-core/tests/integration/rust_analyzer_tests.rs
@@ -0,0 +1,679 @@
+//! Integration tests with real rust-analyzer LSP server.
+//!
+//! These tests require rust-analyzer to be installed and available in PATH.
+//! Run with: cargo nextest run -- --ignored
+
+#![allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::uninlined_format_args,
+    clippy::unnecessary_unwrap
+)]
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use mcpls_core::bridge::Translator;
+use mcpls_core::config::LspServerConfig;
+use mcpls_core::lsp::{LspServer, ServerInitConfig};
+use tokio::sync::Mutex;
+use tokio::time::timeout;
+
+use crate::common::test_utils::{rust_analyzer_available, rust_workspace_path};
+
+/// Setup helper to spawn rust-analyzer and create a translator.
+///
+/// This function:
+/// 1. Spawns rust-analyzer process
+/// 2. Initializes the LSP server
+/// 3. Creates and configures a Translator
+/// 4. Returns the translator wrapped in Arc<Mutex>
+async fn setup_rust_analyzer() -> Arc<Mutex<Translator>> {
+    let workspace_path = rust_workspace_path();
+
+    let lsp_config = LspServerConfig {
+        language_id: "rust".to_string(),
+        command: "rust-analyzer".to_string(),
+        args: vec![],
+        env: std::collections::HashMap::new(),
+        file_patterns: vec!["**/*.rs".to_string()],
+        initialization_options: None,
+        timeout_seconds: 30,
+    };
+
+    let server_init_config = ServerInitConfig {
+        server_config: lsp_config,
+        workspace_roots: vec![workspace_path.clone()],
+        initialization_options: None,
+    };
+
+    let server = LspServer::spawn(server_init_config)
+        .await
+        .expect("Failed to spawn rust-analyzer");
+
+    let client = server.client().clone();
+
+    let mut translator = Translator::new();
+    translator.set_workspace_roots(vec![workspace_path]);
+    translator.register_client("rust".to_string(), client);
+
+    Arc::new(Mutex::new(translator))
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_hover_on_std_vec() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let file_path = workspace_path.join("src/lib.rs");
+
+    // Give rust-analyzer time to index the workspace
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Hover over "String" in User struct (line 20)
+    // The line is: `pub name: String,`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_hover(
+            file_path.to_string_lossy().to_string(),
+            20,
+            19, // Position on "String"
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let hover_result = result.unwrap();
+    assert!(
+        hover_result.is_ok(),
+        "Should successfully get hover: {:?}",
+        hover_result.err()
+    );
+
+    let hover_json = hover_result.unwrap();
+    let hover_str = serde_json::to_string(&hover_json).unwrap();
+
+    // Verify hover contains String type information
+    assert!(
+        hover_str.contains("String") || hover_str.contains("string"),
+        "Hover should contain String type information, got: {}",
+        hover_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_hover_on_u64_type() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let file_path = workspace_path.join("src/lib.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Hover over "u64" in User struct (line 19)
+    // The line is: `pub id: u64,`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_hover(
+            file_path.to_string_lossy().to_string(),
+            19,
+            17, // Position on "u64"
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let hover_result = result.unwrap();
+    assert!(hover_result.is_ok(), "Should successfully get hover");
+
+    let hover_json = hover_result.unwrap();
+    let hover_str = serde_json::to_string(&hover_json).unwrap();
+
+    // Verify hover contains u64 type information
+    assert!(
+        hover_str.contains("u64") || hover_str.contains("unsigned"),
+        "Hover should contain u64 type information, got: {}",
+        hover_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_definition_user_struct() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let types_file = workspace_path.join("src/types.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Go to definition of User in types.rs (line 9, owner: User)
+    // The line is: `pub owner: User,`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_definition(
+            types_file.to_string_lossy().to_string(),
+            9,
+            20, // Position on "User"
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let def_result = result.unwrap();
+    assert!(
+        def_result.is_ok(),
+        "Should successfully get definition: {:?}",
+        def_result.err()
+    );
+
+    let def_json = def_result.unwrap();
+    let def_str = serde_json::to_string(&def_json).unwrap();
+
+    // Verify definition points to lib.rs where User is defined
+    assert!(
+        def_str.contains("lib.rs") && def_str.contains("User"),
+        "Definition should reference User struct in lib.rs, got: {}",
+        def_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_definition_across_files() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let functions_file = workspace_path.join("src/functions.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Go to definition of Repository in functions.rs (line 3, use statement)
+    // The line is: `use crate::types::Repository;`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_definition(
+            functions_file.to_string_lossy().to_string(),
+            3,
+            24, // Position on "Repository"
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let def_result = result.unwrap();
+    assert!(def_result.is_ok(), "Should successfully get definition");
+
+    let def_json = def_result.unwrap();
+    let def_str = serde_json::to_string(&def_json).unwrap();
+
+    // Verify definition points to types.rs
+    assert!(
+        def_str.contains("types.rs") || def_str.contains("Repository"),
+        "Definition should reference Repository in types.rs, got: {}",
+        def_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_references_create_repo_function() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let functions_file = workspace_path.join("src/functions.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Find references to create_repo function (line 7, function name)
+    // The line is: `pub fn create_repo(name: &str) -> Repository {`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_references(
+            functions_file.to_string_lossy().to_string(),
+            7,
+            12,   // Position on "create_repo"
+            true, // Include declaration
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let refs_result = result.unwrap();
+    assert!(
+        refs_result.is_ok(),
+        "Should successfully get references: {:?}",
+        refs_result.err()
+    );
+
+    let refs_json = refs_result.unwrap();
+
+    // Should find at least the definition itself
+    assert!(
+        !refs_json.locations.is_empty(),
+        "Should find at least one reference (the definition)"
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_references_user_struct() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Find references to User struct (line 18, struct name)
+    // The line is: `pub struct User {`
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_references(
+            lib_file.to_string_lossy().to_string(),
+            18,
+            15, // Position on "User"
+            true,
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let refs_result = result.unwrap();
+    assert!(refs_result.is_ok(), "Should successfully get references");
+
+    let refs_json = refs_result.unwrap();
+
+    // User is referenced in types.rs and functions.rs, plus the definition
+    assert!(
+        refs_json.locations.len() >= 2,
+        "Should find multiple references to User struct, got: {}",
+        refs_json.locations.len()
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_diagnostics_with_error() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    // Give rust-analyzer extra time to analyze and generate diagnostics
+    tokio::time::sleep(Duration::from_secs(5)).await;
+
+    // Get diagnostics from lib.rs (has intentional error on line 37)
+    let result = timeout(
+        Duration::from_secs(10),
+        translator
+            .lock()
+            .await
+            .handle_diagnostics(lib_file.to_string_lossy().to_string()),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let diag_result = result.unwrap();
+    assert!(
+        diag_result.is_ok(),
+        "Should successfully get diagnostics: {:?}",
+        diag_result.err()
+    );
+
+    let diag_json = diag_result.unwrap();
+    let diag_str = serde_json::to_string(&diag_json).unwrap();
+
+    // Should contain the error about undefined_variable
+    assert!(
+        diag_str.contains("undefined_variable") || diag_str.contains("cannot find"),
+        "Diagnostics should report the intentional error, got: {}",
+        diag_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_diagnostics_no_errors() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let types_file = workspace_path.join("src/types.rs");
+
+    tokio::time::sleep(Duration::from_secs(5)).await;
+
+    // Get diagnostics from types.rs (should have no errors)
+    let result = timeout(
+        Duration::from_secs(10),
+        translator
+            .lock()
+            .await
+            .handle_diagnostics(types_file.to_string_lossy().to_string()),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let diag_result = result.unwrap();
+    assert!(diag_result.is_ok(), "Should successfully get diagnostics");
+
+    let diag_json = diag_result.unwrap();
+
+    // types.rs should have no errors or warnings
+    // (it's a clean file without issues)
+    let errors: Vec<_> = diag_json
+        .diagnostics
+        .iter()
+        .filter(|d| matches!(d.severity, mcpls_core::bridge::DiagnosticSeverity::Error))
+        .collect();
+
+    assert!(
+        errors.is_empty(),
+        "types.rs should have no errors, got: {:?}",
+        errors
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_document_symbols() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Get document symbols from lib.rs
+    let result = timeout(
+        Duration::from_secs(10),
+        translator
+            .lock()
+            .await
+            .handle_document_symbols(lib_file.to_string_lossy().to_string()),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let symbols_result = result.unwrap();
+    assert!(
+        symbols_result.is_ok(),
+        "Should successfully get symbols: {:?}",
+        symbols_result.err()
+    );
+
+    let symbols_json = symbols_result.unwrap();
+    let symbols_str = serde_json::to_string(&symbols_json).unwrap();
+
+    // Should contain User struct
+    assert!(
+        symbols_str.contains("User"),
+        "Should find User struct, got: {}",
+        symbols_str
+    );
+
+    // Should contain has_error function
+    assert!(
+        symbols_str.contains("has_error"),
+        "Should find has_error function, got: {}",
+        symbols_str
+    );
+
+    // Should contain has_warning function
+    assert!(
+        symbols_str.contains("has_warning"),
+        "Should find has_warning function, got: {}",
+        symbols_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_document_symbols_types_file() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let types_file = workspace_path.join("src/types.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Get document symbols from types.rs
+    let result = timeout(
+        Duration::from_secs(10),
+        translator
+            .lock()
+            .await
+            .handle_document_symbols(types_file.to_string_lossy().to_string()),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let symbols_result = result.unwrap();
+    assert!(symbols_result.is_ok(), "Should successfully get symbols");
+
+    let symbols_json = symbols_result.unwrap();
+    let symbols_str = serde_json::to_string(&symbols_json).unwrap();
+
+    // Should contain Repository struct
+    assert!(
+        symbols_str.contains("Repository"),
+        "Should find Repository struct, got: {}",
+        symbols_str
+    );
+
+    // Should contain methods
+    assert!(
+        symbols_str.contains("new") || symbols_str.contains("get_owner"),
+        "Should find struct methods, got: {}",
+        symbols_str
+    );
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_completions_basic() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let functions_file = workspace_path.join("src/functions.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Get completions in functions.rs
+    // Position after "repo." on line 23 (repo.get_owner().name)
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_completions(
+            functions_file.to_string_lossy().to_string(),
+            23,
+            10, // Position after "repo."
+            None,
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let completions_result = result.unwrap();
+
+    // Completions might not always be available depending on timing
+    if completions_result.is_ok() {
+        let completions_json = completions_result.unwrap();
+        let completions_str = serde_json::to_string(&completions_json).unwrap();
+
+        // If we got completions, they should include Repository fields/methods
+        // This is a soft check since completion can be timing-sensitive
+        println!("Completions: {}", completions_str);
+    }
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_format_document() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Request document formatting
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_format_document(
+            lib_file.to_string_lossy().to_string(),
+            4,    // tab_size
+            true, // insert_spaces
+        ),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should not timeout");
+    let format_result = result.unwrap();
+
+    // rust-analyzer may or may not support formatting directly
+    // (often defers to rustfmt which needs to be configured separately)
+    // So we just check that the call doesn't error out catastrophically
+    match format_result {
+        Ok(format_json) => {
+            // Format succeeded, verify it returns edits
+            println!("Format response: {:?}", format_json);
+        }
+        Err(e) => {
+            // Format might not be supported, which is ok for this test
+            println!("Format not supported or failed (expected): {:?}", e);
+        }
+    }
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_timeout_handling() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    // Very short timeout to test timeout behavior
+    let result = timeout(
+        Duration::from_millis(1), // 1ms - should timeout
+        translator
+            .lock()
+            .await
+            .handle_hover(lib_file.to_string_lossy().to_string(), 20, 19),
+    )
+    .await;
+
+    // Should timeout
+    assert!(result.is_err(), "Should timeout with 1ms timeout");
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_invalid_file_path() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+
+    tokio::time::sleep(Duration::from_secs(2)).await;
+
+    // Try to get hover on non-existent file
+    let result = translator
+        .lock()
+        .await
+        .handle_hover("/nonexistent/file.rs".to_string(), 1, 1)
+        .await;
+
+    // Should return an error (file not found or not in workspace)
+    assert!(result.is_err(), "Should fail for non-existent file");
+}
+
+#[tokio::test]
+#[ignore = "Requires rust-analyzer installed"]
+async fn test_out_of_bounds_position() {
+    if !rust_analyzer_available() {
+        eprintln!("Skipping: rust-analyzer not available");
+        return;
+    }
+
+    let translator = setup_rust_analyzer().await;
+    let workspace_path = rust_workspace_path();
+    let lib_file = workspace_path.join("src/lib.rs");
+
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    // Try to get hover at an extremely large line number
+    let result = timeout(
+        Duration::from_secs(10),
+        translator.lock().await.handle_hover(
+            lib_file.to_string_lossy().to_string(),
+            99999, // Way beyond file bounds
+            1,
+        ),
+    )
+    .await;
+
+    // LSP server should handle this gracefully (might return empty or error)
+    assert!(
+        result.is_ok(),
+        "Should not timeout even with out-of-bounds position"
+    );
+
+    // The actual result might be Ok(empty) or Err, both are acceptable
+    // We just want to ensure it doesn't hang or crash
+}
diff --git a/crates/mcpls-core/tests/integration_tests.rs b/crates/mcpls-core/tests/integration_tests.rs
index 77a9552..3c73e22 100644
--- a/crates/mcpls-core/tests/integration_tests.rs
+++ b/crates/mcpls-core/tests/integration_tests.rs
@@ -1,6 +1,7 @@
 //! Integration tests for mcpls-core.
 
 mod common;
+mod e2e;
 mod integration;
 
 // Re-export the macro for tests
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
new file mode 100644
index 0000000..fa78dc9
--- /dev/null
+++ b/docs/user-guide/configuration.md
@@ -0,0 +1,443 @@
+# Configuration Reference
+
+Complete reference for configuring mcpls.
+
+## Configuration File
+
+mcpls uses TOML format for configuration. The file can be placed in several locations (searched in order):
+
+1. Path specified by `--config` flag
+2. `$MCPLS_CONFIG` environment variable
+3. `./mcpls.toml` (current directory)
+4. `~/.config/mcpls/mcpls.toml` (user config directory)
+
+## Configuration Structure
+
+```toml
+# Workspace configuration
+[workspace]
+roots = ["/path/to/project1", "/path/to/project2"]
+position_encodings = ["utf-8", "utf-16"]
+
+# LSP server definitions (can have multiple)
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+timeout_seconds = 30
+
+# Optional: LSP server initialization options
+[lsp_servers.initialization_options]
+cargo.features = "all"
+```
+
+## Workspace Section
+
+### `workspace.roots`
+
+**Type**: Array of strings
+**Default**: `[]` (auto-detect from current directory)
+
+Workspace root directories for LSP servers.
+
+```toml
+[workspace]
+# Single workspace
+roots = ["/Users/username/projects/myproject"]
+
+# Multiple workspaces
+roots = [
+    "/Users/username/projects/frontend",
+    "/Users/username/projects/backend"
+]
+
+# Auto-detect (empty array)
+roots = []
+```
+
+### `workspace.position_encodings`
+
+**Type**: Array of strings
+**Default**: `["utf-8", "utf-16"]`
+**Options**: `"utf-8"`, `"utf-16"`, `"utf-32"`
+
+Preferred position encodings for LSP communication.
+
+```toml
+[workspace]
+position_encodings = ["utf-8", "utf-16", "utf-32"]
+```
+
+Most language servers use UTF-16 encoding. mcpls automatically converts between MCP (UTF-8) and LSP encodings.
+
+## LSP Server Configuration
+
+Each `[[lsp_servers]]` section defines a language server.
+
+### `language_id`
+
+**Type**: String
+**Required**: Yes
+
+Language identifier for this server.
+
+```toml
+[[lsp_servers]]
+language_id = "rust"  # Standard: rust, python, typescript, javascript, go, etc.
+```
+
+### `command`
+
+**Type**: String
+**Required**: Yes
+
+Command to execute the language server.
+
+```toml
+[[lsp_servers]]
+command = "rust-analyzer"  # Must be in PATH or absolute path
+```
+
+For absolute paths:
+```toml
+[[lsp_servers]]
+command = "/usr/local/bin/rust-analyzer"
+```
+
+### `args`
+
+**Type**: Array of strings
+**Default**: `[]`
+
+Command-line arguments for the language server.
+
+```toml
+[[lsp_servers]]
+command = "pyright-langserver"
+args = ["--stdio"]  # Many servers require --stdio flag
+```
+
+### `file_patterns`
+
+**Type**: Array of strings (glob patterns)
+**Required**: No (defaults to empty array)
+
+File patterns to associate with this language server.
+
+```toml
+[[lsp_servers]]
+file_patterns = ["**/*.rs"]  # Rust files
+
+[[lsp_servers]]
+file_patterns = ["**/*.py", "**/*.pyi"]  # Python files
+
+[[lsp_servers]]
+file_patterns = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]  # TS/JS files
+```
+
+Glob pattern syntax:
+- `**` - Match any number of directories
+- `*` - Match any characters except `/`
+- `?` - Match single character
+- `[abc]` - Match any character in brackets
+
+### `timeout_seconds`
+
+**Type**: Integer
+**Default**: `30`
+
+Timeout in seconds for LSP server operations.
+
+```toml
+[[lsp_servers]]
+timeout_seconds = 60  # Increase for slow servers or large projects
+```
+
+### `initialization_options`
+
+**Type**: Table (key-value pairs)
+**Default**: `{}`
+
+Server-specific initialization options passed during LSP initialization.
+
+```toml
+[lsp_servers.initialization_options]
+# rust-analyzer specific options
+cargo.features = "all"
+checkOnSave.command = "clippy"
+
+# pyright specific options
+python.analysis.typeCheckingMode = "strict"
+```
+
+See your language server documentation for available options.
+
+### `env`
+
+**Type**: Table (key-value pairs)
+**Default**: `{}`
+
+Environment variables to set for the LSP server process.
+
+```toml
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+
+[lsp_servers.env]
+PYTHONPATH = "/custom/path"
+VIRTUAL_ENV = "/path/to/venv"
+```
+
+## Environment Variables
+
+### `MCPLS_CONFIG`
+
+Path to configuration file.
+
+```bash
+export MCPLS_CONFIG=/custom/path/to/mcpls.toml
+mcpls
+```
+
+### `MCPLS_LOG`
+
+Log level for mcpls output.
+
+**Values**: `trace`, `debug`, `info`, `warn`, `error`
+**Default**: `info`
+
+```bash
+export MCPLS_LOG=debug
+mcpls
+```
+
+### `MCPLS_LOG_JSON`
+
+Output logs in JSON format.
+
+**Values**: `true`, `false`
+**Default**: `false`
+
+```bash
+export MCPLS_LOG_JSON=true
+mcpls
+```
+
+## Complete Examples
+
+### Rust Project (Zero Config)
+
+mcpls works without configuration for Rust:
+
+```bash
+# No configuration needed!
+mcpls
+```
+
+### Python Project
+
+```toml
+[workspace]
+roots = ["/Users/username/projects/myapp"]
+
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+timeout_seconds = 45
+
+[lsp_servers.initialization_options]
+python.analysis.typeCheckingMode = "basic"
+python.analysis.autoSearchPaths = true
+```
+
+### TypeScript/JavaScript Project
+
+```toml
+[workspace]
+roots = ["/Users/username/projects/webapp"]
+
+[[lsp_servers]]
+language_id = "typescript"
+command = "typescript-language-server"
+args = ["--stdio"]
+file_patterns = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+
+[lsp_servers.initialization_options]
+preferences.quotePreference = "single"
+preferences.importModuleSpecifierPreference = "relative"
+```
+
+### Go Project
+
+```toml
+[workspace]
+roots = ["/Users/username/go/src/myproject"]
+
+[[lsp_servers]]
+language_id = "go"
+command = "gopls"
+args = []
+file_patterns = ["**/*.go"]
+
+[lsp_servers.initialization_options]
+analyses.unusedparams = true
+staticcheck = true
+```
+
+### Multi-Language Monorepo
+
+```toml
+[workspace]
+roots = [
+    "/Users/username/projects/monorepo/frontend",
+    "/Users/username/projects/monorepo/backend",
+    "/Users/username/projects/monorepo/cli"
+]
+
+# Rust backend
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/backend/**/*.rs", "**/cli/**/*.rs"]
+
+# TypeScript frontend
+[[lsp_servers]]
+language_id = "typescript"
+command = "typescript-language-server"
+args = ["--stdio"]
+file_patterns = ["**/frontend/**/*.ts", "**/frontend/**/*.tsx"]
+
+# Python scripts
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/scripts/**/*.py"]
+```
+
+### C/C++ Project
+
+```toml
+[workspace]
+roots = ["/Users/username/projects/cppproject"]
+
+[[lsp_servers]]
+language_id = "cpp"
+command = "clangd"
+args = ["--background-index", "--clang-tidy"]
+file_patterns = ["**/*.cpp", "**/*.cc", "**/*.cxx", "**/*.h", "**/*.hpp"]
+
+[lsp_servers.initialization_options]
+compilationDatabasePath = "build"
+```
+
+## Command-Line Flags
+
+mcpls supports configuration via command-line flags:
+
+```bash
+# Specify config file
+mcpls --config /path/to/mcpls.toml
+
+# Set log level
+mcpls --log-level debug
+
+# Enable JSON logging
+mcpls --log-json
+
+# Show version
+mcpls --version
+
+# Show help
+mcpls --help
+```
+
+## Configuration Validation
+
+Test your configuration:
+
+```bash
+# mcpls will validate config on startup
+mcpls --log-level debug
+
+# Check for errors in logs
+# Valid config will show: "Configuration loaded successfully"
+```
+
+Common validation errors:
+- Missing required fields (`language_id`, `command`, `file_patterns`)
+- Invalid TOML syntax
+- Command not found in PATH
+- Invalid glob patterns
+
+## Performance Tuning
+
+### Large Projects
+
+For large codebases, increase timeouts:
+
+```toml
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+timeout_seconds = 120  # 2 minutes for initial indexing
+```
+
+### Multiple Workspaces
+
+Limit workspace roots to active projects:
+
+```toml
+[workspace]
+# Don't include entire home directory!
+roots = [
+    "/Users/username/active-project",
+    "/Users/username/dependency-project"
+]
+```
+
+### Server-Specific Optimizations
+
+#### rust-analyzer
+
+```toml
+[lsp_servers.initialization_options]
+cargo.features = "all"
+checkOnSave.enable = true
+checkOnSave.command = "clippy"
+files.excludeDirs = ["target", ".git"]  # Skip build artifacts
+```
+
+#### pyright
+
+```toml
+[lsp_servers.initialization_options]
+python.analysis.typeCheckingMode = "basic"  # "strict" is slower
+python.analysis.diagnosticMode = "openFilesOnly"  # Faster
+```
+
+#### typescript-language-server
+
+```toml
+[lsp_servers.initialization_options]
+diagnostics.ignoredCodes = [6133, 6192]  # Disable some slow checks
+```
+
+## Troubleshooting Configuration
+
+See [Troubleshooting Guide](troubleshooting.md) for common configuration issues.
+
+## Next Steps
+
+- [Getting Started](getting-started.md) - Quick start guide
+- [Tools Reference](tools-reference.md) - Available MCP tools
+- [Troubleshooting](troubleshooting.md) - Common issues
diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md
new file mode 100644
index 0000000..0e2cadf
--- /dev/null
+++ b/docs/user-guide/getting-started.md
@@ -0,0 +1,222 @@
+# Getting Started with mcpls
+
+This guide will help you get up and running with mcpls in 5 minutes.
+
+## What is mcpls?
+
+mcpls is a universal bridge that exposes Language Server Protocol (LSP) capabilities as Model Context Protocol (MCP) tools, enabling AI assistants like Claude Code to access semantic code intelligence.
+
+Instead of treating code as plain text, AI agents can now:
+- Get type information and documentation
+- Navigate to symbol definitions
+- Find all references across the codebase
+- Access compiler diagnostics
+- Perform workspace-wide refactoring
+- Get code completion suggestions
+
+## Installation
+
+### From crates.io
+
+```bash
+cargo install mcpls
+```
+
+### From source
+
+```bash
+git clone https://github.com/bug-ops/mcpls
+cd mcpls
+cargo install --path crates/mcpls-cli
+```
+
+### Verify installation
+
+```bash
+mcpls --version
+# Should output: mcpls 0.1.0
+```
+
+## Quick Start with Claude Code
+
+### 1. Configure Claude Code
+
+Add mcpls to your Claude Code MCP configuration file:
+
+**macOS/Linux**: `~/.claude/mcp.json`
+**Windows**: `%APPDATA%\Claude\mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "mcpls": {
+      "command": "mcpls",
+      "args": []
+    }
+  }
+}
+```
+
+### 2. Restart Claude Code
+
+After adding the configuration, restart Claude Code to load mcpls.
+
+### 3. Verify Tools
+
+Ask Claude: "What tools are available?"
+
+You should see 8 mcpls tools:
+- get_hover
+- get_definition
+- get_references
+- get_diagnostics
+- rename_symbol
+- get_completions
+- get_document_symbols
+- format_document
+
+### 4. Try It Out
+
+Open a Rust project and ask Claude:
+
+> "What type is this variable on line 42?"
+
+Claude will use the `get_hover` tool to retrieve type information from rust-analyzer.
+
+## Configuration (Optional)
+
+mcpls works zero-config for Rust projects (uses rust-analyzer by default). For other languages, create a configuration file.
+
+### Configuration File Location
+
+mcpls searches for configuration in:
+1. Path specified by `--config` flag
+2. `$MCPLS_CONFIG` environment variable
+3. `./mcpls.toml` (current directory)
+4. `~/.config/mcpls/mcpls.toml`
+
+### Example Configuration
+
+Create `~/.config/mcpls/mcpls.toml`:
+
+```toml
+[workspace]
+roots = []  # Auto-detect from current directory
+
+# Rust - rust-analyzer (built-in)
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+
+# Python - pyright
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+
+# TypeScript - typescript-language-server
+[[lsp_servers]]
+language_id = "typescript"
+command = "typescript-language-server"
+args = ["--stdio"]
+file_patterns = ["**/*.ts", "**/*.tsx"]
+```
+
+## Example Usage
+
+### Get Type Information
+
+```
+User: What's the type of the user variable on line 15 in src/main.rs?
+Claude: [Uses get_hover] The variable `user` has type `User`, which is a struct
+        defined in this module with fields: id (u64), name (String), email (String).
+```
+
+### Find References
+
+```
+User: Where is the calculate_total function used?
+Claude: [Uses get_references] The function `calculate_total` is referenced in 5 locations:
+        1. src/billing.rs:42
+        2. src/invoice.rs:18
+        3. src/report.rs:67
+        4. tests/billing_tests.rs:25
+        5. tests/integration_tests.rs:103
+```
+
+### Get Diagnostics
+
+```
+User: Are there any errors in this file?
+Claude: [Uses get_diagnostics] Found 2 errors:
+        1. Line 23: cannot find value `undefined_variable` in this scope
+        2. Line 45: mismatched types: expected `i32`, found `String`
+```
+
+### Rename Symbol
+
+```
+User: Rename the process_data function to handle_data everywhere
+Claude: [Uses rename_symbol] Successfully prepared rename across 12 files
+        with 28 edits. Would you like me to apply these changes?
+```
+
+## Installing Language Servers
+
+mcpls requires language servers to be installed separately:
+
+### Rust (rust-analyzer)
+```bash
+rustup component add rust-analyzer
+```
+
+### Python (pyright)
+```bash
+npm install -g pyright
+```
+
+### TypeScript (typescript-language-server)
+```bash
+npm install -g typescript-language-server
+```
+
+### Go (gopls)
+```bash
+go install golang.org/x/tools/gopls@latest
+```
+
+### C/C++ (clangd)
+```bash
+# Ubuntu/Debian
+sudo apt install clangd
+
+# macOS
+brew install llvm
+```
+
+## Next Steps
+
+- [Configuration Guide](configuration.md) - Detailed configuration options
+- [Tools Reference](tools-reference.md) - Documentation for each MCP tool
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+
+## Common Questions
+
+### Do I need to configure mcpls for Rust?
+
+No! mcpls has built-in support for rust-analyzer and works zero-config for Rust projects.
+
+### Can I use multiple language servers?
+
+Yes! Configure as many language servers as needed in `mcpls.toml`. mcpls will route requests to the appropriate server based on file patterns.
+
+### Does mcpls modify my code?
+
+Only when you explicitly ask for changes (like rename_symbol or format_document). All other tools are read-only and provide information without modifying files.
+
+### Can I use mcpls with other MCP clients?
+
+Yes! mcpls implements the standard MCP protocol and works with any MCP-compliant client, not just Claude Code.
diff --git a/docs/user-guide/installation.md b/docs/user-guide/installation.md
new file mode 100644
index 0000000..184f2c7
--- /dev/null
+++ b/docs/user-guide/installation.md
@@ -0,0 +1,532 @@
+# Installation Guide
+
+Complete installation guide for mcpls - the universal MCP to LSP bridge.
+
+## Prerequisites
+
+- Rust 1.85 or later (for building from source)
+- At least one Language Server installed (see [Language Server Setup](#language-server-setup))
+
+## Installation Methods
+
+### Method 1: Cargo Install from crates.io (Recommended)
+
+The easiest way to install mcpls is via cargo:
+
+```bash
+cargo install mcpls
+```
+
+Verify installation:
+
+```bash
+mcpls --version
+# Should output: mcpls 0.1.0
+```
+
+### Method 2: Pre-Built Binaries from GitHub Releases
+
+Download pre-built binaries for your platform from [GitHub Releases](https://github.com/bug-ops/mcpls/releases).
+
+#### Linux (x86_64)
+
+```bash
+# Download latest release
+curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-v0.1.0-linux-x86_64.tar.gz
+
+# Extract archive
+tar xzf mcpls-v0.1.0-linux-x86_64.tar.gz
+
+# Move to system path
+sudo mv mcpls /usr/local/bin/
+
+# Verify installation
+mcpls --version
+```
+
+#### macOS (x86_64 Intel)
+
+```bash
+# Download latest release
+curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-v0.1.0-macos-x86_64.tar.gz
+
+# Extract archive
+tar xzf mcpls-v0.1.0-macos-x86_64.tar.gz
+
+# Move to system path
+sudo mv mcpls /usr/local/bin/
+
+# Verify installation
+mcpls --version
+```
+
+#### macOS (Apple Silicon / M1/M2/M3)
+
+```bash
+# Download latest release
+curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-v0.1.0-macos-aarch64.tar.gz
+
+# Extract archive
+tar xzf mcpls-v0.1.0-macos-aarch64.tar.gz
+
+# Move to system path
+sudo mv mcpls /usr/local/bin/
+
+# Verify installation
+mcpls --version
+```
+
+#### Windows (x86_64)
+
+1. Download `mcpls-v0.1.0-windows-x86_64.zip` from [GitHub Releases](https://github.com/bug-ops/mcpls/releases)
+2. Extract the archive to a directory
+3. Add the directory to your PATH environment variable
+4. Open a new terminal and verify:
+
+```powershell
+mcpls --version
+```
+
+### Method 3: Building from Source
+
+For the latest development version or custom builds:
+
+```bash
+# Clone repository
+git clone https://github.com/bug-ops/mcpls
+cd mcpls
+
+# Build and install
+cargo install --path crates/mcpls
+
+# Verify installation
+mcpls --version
+```
+
+### Method 4: Docker
+
+Run mcpls in a Docker container:
+
+```bash
+# Pull image from GitHub Container Registry
+docker pull ghcr.io/bug-ops/mcpls:latest
+
+# Run mcpls (stdio mode)
+docker run -i ghcr.io/bug-ops/mcpls:latest
+```
+
+For production use with configuration:
+
+```bash
+# Create config file
+cat > mcpls.toml <<EOF
+[workspace]
+roots = ["/workspace"]
+
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+EOF
+
+# Run with volume mount
+docker run -i \
+  -v $(pwd)/mcpls.toml:/etc/mcpls/mcpls.toml:ro \
+  -v $(pwd):/workspace:ro \
+  ghcr.io/bug-ops/mcpls:latest
+```
+
+## Language Server Setup
+
+mcpls requires language servers to be installed separately. Install the language servers for the languages you work with.
+
+### Rust - rust-analyzer
+
+**Installation:**
+
+```bash
+# Install via rustup (recommended)
+rustup component add rust-analyzer
+
+# Verify installation
+rust-analyzer --version
+```
+
+**Configuration:** Zero-config for Rust projects. rust-analyzer is the default LSP server.
+
+### Python - pyright
+
+**Installation:**
+
+```bash
+# Install via npm
+npm install -g pyright
+
+# Verify installation
+pyright --version
+```
+
+**Configuration:**
+
+Create `~/.config/mcpls/mcpls.toml`:
+
+```toml
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+```
+
+### TypeScript/JavaScript - typescript-language-server
+
+**Installation:**
+
+```bash
+# Install typescript and language server
+npm install -g typescript typescript-language-server
+
+# Verify installation
+typescript-language-server --version
+```
+
+**Configuration:**
+
+```toml
+[[lsp_servers]]
+language_id = "typescript"
+command = "typescript-language-server"
+args = ["--stdio"]
+file_patterns = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+```
+
+### Go - gopls
+
+**Installation:**
+
+```bash
+# Install via go
+go install golang.org/x/tools/gopls@latest
+
+# Verify installation (ensure $GOPATH/bin is in PATH)
+gopls version
+```
+
+**Configuration:**
+
+```toml
+[[lsp_servers]]
+language_id = "go"
+command = "gopls"
+args = []
+file_patterns = ["**/*.go"]
+```
+
+### C/C++ - clangd
+
+**Installation:**
+
+```bash
+# Ubuntu/Debian
+sudo apt install clangd
+
+# Fedora/RHEL
+sudo dnf install clangd
+
+# macOS (via Homebrew)
+brew install llvm
+
+# Verify installation
+clangd --version
+```
+
+**Configuration:**
+
+```toml
+[[lsp_servers]]
+language_id = "cpp"
+command = "clangd"
+args = []
+file_patterns = ["**/*.c", "**/*.cpp", "**/*.h", "**/*.hpp"]
+```
+
+### Java - jdtls (Eclipse JDT Language Server)
+
+**Installation:**
+
+1. Download from [Eclipse JDT LS releases](https://download.eclipse.org/jdtls/milestones/)
+2. Extract to a directory (e.g., `~/jdtls`)
+
+**Configuration:**
+
+```toml
+[[lsp_servers]]
+language_id = "java"
+command = "/path/to/jdtls/bin/jdtls"
+args = []
+file_patterns = ["**/*.java"]
+```
+
+### Bash - bash-language-server
+
+**Installation:**
+
+```bash
+npm install -g bash-language-server
+
+# Verify installation
+bash-language-server --version
+```
+
+**Configuration:**
+
+```toml
+[[lsp_servers]]
+language_id = "bash"
+command = "bash-language-server"
+args = ["start"]
+file_patterns = ["**/*.sh", "**/*.bash"]
+```
+
+## Configuration
+
+mcpls searches for configuration files in the following order:
+
+1. Path specified by `--config` flag
+2. `$MCPLS_CONFIG` environment variable
+3. `./mcpls.toml` (current directory)
+4. `~/.config/mcpls/mcpls.toml` (user config directory)
+
+### Minimal Configuration
+
+For Rust projects only (uses built-in defaults):
+
+```toml
+[workspace]
+roots = []  # Auto-detect from current directory
+```
+
+### Multi-Language Configuration
+
+Example configuration for a polyglot project:
+
+```toml
+[workspace]
+roots = [
+    "/home/user/projects/myapp"
+]
+
+# Rust
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+
+# Python
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+
+# TypeScript/JavaScript
+[[lsp_servers]]
+language_id = "typescript"
+command = "typescript-language-server"
+args = ["--stdio"]
+file_patterns = ["**/*.ts", "**/*.tsx", "**/*.js"]
+
+# Go
+[[lsp_servers]]
+language_id = "go"
+command = "gopls"
+args = []
+file_patterns = ["**/*.go"]
+```
+
+## PATH Configuration
+
+After installation, ensure the installation directory is in your PATH.
+
+### Linux/macOS
+
+If `mcpls --version` doesn't work, add to your shell profile:
+
+```bash
+# For Bash (~/.bashrc or ~/.bash_profile)
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# For Zsh (~/.zshrc)
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# Reload shell configuration
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### Windows
+
+1. Open System Properties > Advanced > Environment Variables
+2. Edit the `Path` variable for your user
+3. Add the directory containing `mcpls.exe` (e.g., `C:\Users\YourName\.cargo\bin`)
+4. Click OK and restart your terminal
+
+## Upgrading
+
+### Cargo Install
+
+```bash
+cargo install mcpls --force
+```
+
+### Pre-Built Binaries
+
+Download the latest release and replace the existing binary:
+
+```bash
+# Backup current version
+sudo mv /usr/local/bin/mcpls /usr/local/bin/mcpls.backup
+
+# Download and install new version
+curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-v0.2.0-linux-x86_64.tar.gz
+tar xzf mcpls-v0.2.0-linux-x86_64.tar.gz
+sudo mv mcpls /usr/local/bin/
+
+# Verify upgrade
+mcpls --version
+```
+
+### Docker
+
+```bash
+docker pull ghcr.io/bug-ops/mcpls:latest
+```
+
+## Uninstalling
+
+### Cargo Install
+
+```bash
+cargo uninstall mcpls
+```
+
+### Manual Installation
+
+```bash
+# Remove binary
+sudo rm /usr/local/bin/mcpls
+
+# Remove configuration (optional)
+rm -rf ~/.config/mcpls
+```
+
+### Docker
+
+```bash
+docker rmi ghcr.io/bug-ops/mcpls:latest
+```
+
+## Verifying Installation
+
+After installation, verify mcpls is working correctly:
+
+```bash
+# Check version
+mcpls --version
+
+# Check help
+mcpls --help
+
+# Test with initialize request (manual test)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | mcpls
+```
+
+Expected output should be a JSON response with `"method":"initialize"` result.
+
+## Troubleshooting
+
+### "command not found: mcpls"
+
+**Problem:** mcpls binary not in PATH
+
+**Solution:**
+1. Check installation directory: `which mcpls` or `where mcpls` (Windows)
+2. Add to PATH (see [PATH Configuration](#path-configuration))
+3. Try absolute path: `~/.cargo/bin/mcpls --version`
+
+### "failed to compile mcpls"
+
+**Problem:** Rust version too old
+
+**Solution:**
+```bash
+# Update Rust to 1.85+
+rustup update stable
+rustup default stable
+
+# Verify version
+rustc --version
+```
+
+### macOS: "cannot be opened because the developer cannot be verified"
+
+**Problem:** Security restriction on unsigned binaries
+
+**Solution:**
+```bash
+# Remove quarantine attribute
+xattr -d com.apple.quarantine /usr/local/bin/mcpls
+
+# Or right-click > Open in Finder
+```
+
+### Windows: "mcpls.exe is not recognized"
+
+**Problem:** Binary not in PATH
+
+**Solution:**
+1. Find installation directory: `where mcpls.exe`
+2. Add to PATH via System Properties
+3. Restart terminal
+
+## Next Steps
+
+After installation:
+
+- [Getting Started Guide](getting-started.md) - Quick start with Claude Code
+- [Configuration Reference](configuration.md) - Detailed configuration options
+- [Tools Reference](tools-reference.md) - Documentation for all MCP tools
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+
+## Platform-Specific Notes
+
+### Linux
+
+- Ensure `~/.cargo/bin` is in PATH
+- May need `build-essential` for compiling from source
+- Some LSP servers require additional dependencies
+
+### macOS
+
+- Both Intel and Apple Silicon binaries available
+- May need to allow binary execution in Security & Privacy settings
+- Homebrew recommended for installing LSP servers
+
+### Windows
+
+- Use PowerShell or Command Prompt
+- May need Visual Studio Build Tools for compiling from source
+- WSL2 recommended for best LSP server compatibility
+
+## Support
+
+For installation issues:
+
+1. Check [Troubleshooting Guide](troubleshooting.md)
+2. Search [GitHub Issues](https://github.com/bug-ops/mcpls/issues)
+3. Open a new issue with:
+   - Operating system and version
+   - Installation method used
+   - Complete error message
+   - Output of `mcpls --version` (if partially working)
diff --git a/docs/user-guide/tools-reference.md b/docs/user-guide/tools-reference.md
new file mode 100644
index 0000000..e2d0b13
--- /dev/null
+++ b/docs/user-guide/tools-reference.md
@@ -0,0 +1,687 @@
+# MCP Tools Reference
+
+Complete reference for all 8 MCP tools provided by mcpls.
+
+## Overview
+
+mcpls exposes semantic code intelligence from Language Server Protocol (LSP) servers as MCP tools. Each tool corresponds to one or more LSP methods and provides rich code information to AI agents.
+
+## Tool Index
+
+| Tool | LSP Method | Description |
+|------|------------|-------------|
+| [get_hover](#get_hover) | `textDocument/hover` | Type information and documentation |
+| [get_definition](#get_definition) | `textDocument/definition` | Symbol definition location |
+| [get_references](#get_references) | `textDocument/references` | All references to a symbol |
+| [get_diagnostics](#get_diagnostics) | `textDocument/publishDiagnostics` | Compiler errors and warnings |
+| [rename_symbol](#rename_symbol) | `textDocument/rename` | Workspace-wide symbol renaming |
+| [get_completions](#get_completions) | `textDocument/completion` | Code completion suggestions |
+| [get_document_symbols](#get_document_symbols) | `textDocument/documentSymbol` | Document symbol outline |
+| [format_document](#format_document) | `textDocument/formatting` | Document formatting |
+
+---
+
+## get_hover
+
+Get type information and documentation for a symbol at a specific position.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "line": 10,
+  "character": 5
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `line` | integer | Yes | Line number (1-based) |
+| `character` | integer | Yes | Character position (1-based, UTF-8) |
+
+### Returns
+
+JSON object with hover information:
+
+```json
+{
+  "contents": "```rust\nstruct User {\n    id: u64,\n    name: String,\n}\n```\n\nUser information structure.",
+  "range": {
+    "start": { "line": 10, "character": 5 },
+    "end": { "line": 10, "character": 9 }
+  }
+}
+```
+
+### Example Use Cases
+
+**Claude interaction:**
+```
+User: What type is the variable user on line 42?
+Claude: [Uses get_hover] The variable user has type User, a struct with fields
+        id (u64), name (String), and email (String).
+```
+
+**Python type checking:**
+```
+User: What's the return type of calculate_total()?
+Claude: [Uses get_hover] The function returns Optional[Decimal], which means
+        it can return either a Decimal value or None.
+```
+
+### Notes
+
+- Returns `null` if no hover information available
+- Includes markdown-formatted documentation when available
+- Works best with strongly-typed languages (Rust, TypeScript, Go)
+
+---
+
+## get_definition
+
+Jump to the definition of a symbol at a specific position.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "line": 10,
+  "character": 5
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `line` | integer | Yes | Line number (1-based) |
+| `character` | integer | Yes | Character position (1-based, UTF-8) |
+
+### Returns
+
+Array of definition locations:
+
+```json
+[
+  {
+    "uri": "file:///absolute/path/to/definition.rs",
+    "range": {
+      "start": { "line": 5, "character": 0 },
+      "end": { "line": 5, "character": 14 }
+    }
+  }
+]
+```
+
+### Example Use Cases
+
+**Find function definition:**
+```
+User: Where is the process_payment function defined?
+Claude: [Uses get_definition] The function is defined in src/billing.rs at line 23.
+```
+
+**Navigate to struct:**
+```
+User: Show me the User struct definition
+Claude: [Uses get_definition] The User struct is defined in src/models/user.rs:
+        [shows code snippet]
+```
+
+### Notes
+
+- May return multiple locations for symbols with multiple definitions
+- Returns empty array if no definition found
+- Works across file boundaries
+
+---
+
+## get_references
+
+Find all references to a symbol in the workspace.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "line": 10,
+  "character": 5,
+  "include_declaration": false
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `line` | integer | Yes | Line number (1-based) |
+| `character` | integer | Yes | Character position (1-based, UTF-8) |
+| `include_declaration` | boolean | No | Include the declaration site (default: false) |
+
+### Returns
+
+Array of reference locations:
+
+```json
+[
+  {
+    "uri": "file:///path/to/file1.rs",
+    "range": {
+      "start": { "line": 15, "character": 4 },
+      "end": { "line": 15, "character": 8 }
+    }
+  },
+  {
+    "uri": "file:///path/to/file2.rs",
+    "range": {
+      "start": { "line": 42, "character": 10 },
+      "end": { "line": 42, "character": 14 }
+    }
+  }
+]
+```
+
+### Example Use Cases
+
+**Find all usages:**
+```
+User: Where is the calculate_total function used?
+Claude: [Uses get_references] Found 7 references:
+        1. src/billing.rs:45 - function call
+        2. src/invoice.rs:23 - function call
+        3. tests/billing_tests.rs:15 - test case
+        [...]
+```
+
+**Impact analysis:**
+```
+User: If I change the User struct, what will be affected?
+Claude: [Uses get_references] The User struct is referenced in 23 locations
+        across 8 files, including models, services, and tests.
+```
+
+### Notes
+
+- Searches entire workspace
+- May be slow for frequently-used symbols
+- `include_declaration: true` includes the definition site in results
+
+---
+
+## get_diagnostics
+
+Get compiler errors, warnings, and hints for a file.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+
+### Returns
+
+Array of diagnostic messages:
+
+```json
+[
+  {
+    "range": {
+      "start": { "line": 10, "character": 8 },
+      "end": { "line": 10, "character": 24 }
+    },
+    "severity": 1,
+    "message": "cannot find value `undefined_variable` in this scope",
+    "source": "rustc"
+  },
+  {
+    "range": {
+      "start": { "line": 15, "character": 0 },
+      "end": { "line": 15, "character": 40 }
+    },
+    "severity": 2,
+    "message": "unused variable: `x`",
+    "source": "rustc"
+  }
+]
+```
+
+Severity levels:
+- `1` - Error
+- `2` - Warning
+- `3` - Information
+- `4` - Hint
+
+### Example Use Cases
+
+**Check for errors:**
+```
+User: Are there any errors in this file?
+Claude: [Uses get_diagnostics] Found 2 errors:
+        Line 10: cannot find value `undefined_variable` in this scope
+        Line 23: mismatched types: expected `i32`, found `String`
+```
+
+**Pre-commit validation:**
+```
+User: Is this code ready to commit?
+Claude: [Uses get_diagnostics] Found 1 warning:
+        Line 15: unused variable `x` - consider removing or prefixing with `_`
+        Otherwise the code compiles successfully.
+```
+
+### Notes
+
+- Diagnostics are updated automatically by the LSP server
+- May include linter warnings (clippy for Rust, pylint for Python)
+- Empty array if no issues found
+
+---
+
+## rename_symbol
+
+Rename a symbol across the entire workspace.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "line": 10,
+  "character": 5,
+  "new_name": "new_identifier_name"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `line` | integer | Yes | Line number (1-based) |
+| `character` | integer | Yes | Character position (1-based, UTF-8) |
+| `new_name` | string | Yes | New name for the symbol |
+
+### Returns
+
+Workspace edit with all changes:
+
+```json
+{
+  "changes": {
+    "file:///path/to/file1.rs": [
+      {
+        "range": {
+          "start": { "line": 10, "character": 4 },
+          "end": { "line": 10, "character": 16 }
+        },
+        "newText": "new_identifier_name"
+      }
+    ],
+    "file:///path/to/file2.rs": [
+      {
+        "range": {
+          "start": { "line": 5, "character": 8 },
+          "end": { "line": 5, "character": 20 }
+        },
+        "newText": "new_identifier_name"
+      }
+    ]
+  }
+}
+```
+
+### Example Use Cases
+
+**Rename function:**
+```
+User: Rename the process_data function to handle_data
+Claude: [Uses rename_symbol] Prepared rename with 15 edits across 6 files:
+        - src/data.rs: 3 edits
+        - src/processor.rs: 8 edits
+        - tests/data_tests.rs: 4 edits
+        Would you like me to apply these changes?
+```
+
+**Refactor variable:**
+```
+User: Rename the user variable to customer throughout the codebase
+Claude: [Uses rename_symbol] Found 47 occurrences across 12 files. This is
+        a large refactoring. Shall I proceed?
+```
+
+### Notes
+
+- Validates that the new name is a valid identifier
+- Respects language-specific naming rules
+- Does not apply changes automatically - returns edit plan
+- Some LSP servers may reject invalid renames
+
+---
+
+## get_completions
+
+Get code completion suggestions at a specific position.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "line": 10,
+  "character": 5,
+  "trigger": null
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `line` | integer | Yes | Line number (1-based) |
+| `character` | integer | Yes | Character position (1-based, UTF-8) |
+| `trigger` | string | No | Trigger character (e.g., ".", ":", "->") |
+
+### Returns
+
+Array of completion items:
+
+```json
+[
+  {
+    "label": "to_string",
+    "kind": 2,
+    "detail": "fn(&self) -> String",
+    "documentation": "Converts the value to a String.",
+    "insertText": "to_string()"
+  },
+  {
+    "label": "len",
+    "kind": 2,
+    "detail": "fn(&self) -> usize",
+    "documentation": "Returns the length of the string.",
+    "insertText": "len()"
+  }
+]
+```
+
+Completion kinds:
+- `1` - Text
+- `2` - Method
+- `3` - Function
+- `5` - Field
+- `6` - Variable
+- `7` - Class
+- `9` - Module
+
+### Example Use Cases
+
+**Method suggestions:**
+```
+User: What methods are available on this Vec?
+Claude: [Uses get_completions] Available methods include:
+        - push(value) - Add element to end
+        - pop() - Remove and return last element
+        - len() - Get number of elements
+        - is_empty() - Check if empty
+        [...]
+```
+
+**Import suggestions:**
+```
+User: How do I import HashMap?
+Claude: [Uses get_completions] You can use:
+        use std::collections::HashMap;
+```
+
+### Notes
+
+- Completions are context-aware
+- May be slow for large codebases
+- Quality depends on LSP server capabilities
+
+---
+
+## get_document_symbols
+
+Get an outline of all symbols in a document.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+
+### Returns
+
+Hierarchical array of symbols:
+
+```json
+[
+  {
+    "name": "User",
+    "kind": 5,
+    "range": {
+      "start": { "line": 5, "character": 0 },
+      "end": { "line": 10, "character": 1 }
+    },
+    "children": [
+      {
+        "name": "id",
+        "kind": 8,
+        "range": {
+          "start": { "line": 6, "character": 4 },
+          "end": { "line": 6, "character": 14 }
+        }
+      }
+    ]
+  },
+  {
+    "name": "create_user",
+    "kind": 12,
+    "range": {
+      "start": { "line": 12, "character": 0 },
+      "end": { "line": 20, "character": 1 }
+    }
+  }
+]
+```
+
+Symbol kinds:
+- `5` - Class/Struct
+- `6` - Method
+- `8` - Field
+- `11` - Interface/Trait
+- `12` - Function
+- `13` - Variable
+
+### Example Use Cases
+
+**File overview:**
+```
+User: What's in this file?
+Claude: [Uses get_document_symbols] The file contains:
+        Structs:
+        - User (lines 5-10) with fields: id, name, email
+        - Config (lines 15-20)
+
+        Functions:
+        - create_user (line 25)
+        - validate_email (line 40)
+```
+
+**Find specific symbol:**
+```
+User: What functions are exported from this module?
+Claude: [Uses get_document_symbols] Public functions:
+        - pub fn initialize() - line 10
+        - pub fn process() - line 25
+        - pub fn cleanup() - line 50
+```
+
+### Notes
+
+- Returns hierarchical structure (children of classes, modules, etc.)
+- Symbol visibility depends on LSP server
+- Useful for navigation and code understanding
+
+---
+
+## format_document
+
+Format a document according to language server rules.
+
+### Parameters
+
+```json
+{
+  "file_path": "/absolute/path/to/file.rs",
+  "tab_size": 4,
+  "insert_spaces": true
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path to the file |
+| `tab_size` | integer | No | Tab size for formatting (default: 4) |
+| `insert_spaces` | boolean | No | Use spaces instead of tabs (default: true) |
+
+### Returns
+
+Array of text edits to apply formatting:
+
+```json
+[
+  {
+    "range": {
+      "start": { "line": 5, "character": 0 },
+      "end": { "line": 5, "character": 45 }
+    },
+    "newText": "fn main() {\n    println!(\"Hello, world!\");\n}"
+  }
+]
+```
+
+### Example Use Cases
+
+**Auto-format:**
+```
+User: Format this Rust file
+Claude: [Uses format_document] Formatted according to rustfmt rules.
+        Applied 12 formatting changes.
+```
+
+**Check formatting:**
+```
+User: Is this file properly formatted?
+Claude: [Uses format_document] The file needs formatting changes:
+        - Line 15: inconsistent indentation
+        - Line 23: line too long (should wrap)
+```
+
+### Notes
+
+- Uses language-specific formatter (rustfmt, black, prettier, etc.)
+- Does not apply changes automatically - returns edit plan
+- May fail if formatter is not available
+- Respects `.editorconfig` and formatter configuration files
+
+---
+
+## Common Parameters
+
+### file_path
+
+**Type**: String
+**Format**: Absolute path
+**Validation**: Must exist within workspace roots
+
+```json
+{
+  "file_path": "/Users/username/project/src/main.rs"  // Absolute
+}
+```
+
+### line
+
+**Type**: Integer
+**Indexing**: 1-based (first line is 1)
+
+```json
+{
+  "line": 10  // 10th line in the file
+}
+```
+
+### character
+
+**Type**: Integer
+**Indexing**: 1-based (first character is 1)
+**Encoding**: UTF-8 (converted to UTF-16 for LSP)
+
+```json
+{
+  "character": 5  // 5th character (UTF-8 code points)
+}
+```
+
+## Error Handling
+
+All tools return errors in standard MCP error format:
+
+```json
+{
+  "error": {
+    "code": -32603,
+    "message": "LSP server not available for file type 'rs'"
+  }
+}
+```
+
+Common error scenarios:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| LSP server not available | No server configured for file type | Add LSP server to config |
+| File not found | File doesn't exist | Check file path |
+| Position out of bounds | Invalid line/character | Verify position is valid |
+| Timeout | LSP server too slow | Increase timeout in config |
+| No hover information | Not hoverable | Try different position |
+
+## Performance Considerations
+
+### Slow Operations
+
+- `get_references` - Searches entire workspace
+- `rename_symbol` - Analyzes all files
+- `get_completions` - May trigger indexing
+
+### Fast Operations
+
+- `get_hover` - Single file lookup
+- `get_diagnostics` - Cached by LSP server
+- `get_definition` - Direct index lookup
+
+### Optimization Tips
+
+1. Limit workspace roots to active projects
+2. Increase timeouts for large codebases
+3. Use file patterns to exclude build artifacts
+4. Close unnecessary language servers
+
+## Next Steps
+
+- [Getting Started](getting-started.md) - Quick start guide
+- [Configuration](configuration.md) - Configure language servers
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/troubleshooting.md
new file mode 100644
index 0000000..eabe6a0
--- /dev/null
+++ b/docs/user-guide/troubleshooting.md
@@ -0,0 +1,754 @@
+# Troubleshooting Guide
+
+Common issues and solutions when using mcpls.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Claude Code Integration](#claude-code-integration)
+- [LSP Server Issues](#lsp-server-issues)
+- [Configuration Issues](#configuration-issues)
+- [Performance Issues](#performance-issues)
+- [Common Error Messages](#common-error-messages)
+- [Getting Help](#getting-help)
+
+---
+
+## Installation Issues
+
+### "command not found: mcpls"
+
+**Problem**: mcpls binary not in PATH after `cargo install`
+
+**Solution**:
+```bash
+# Add Cargo bin directory to PATH
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# For permanent fix, add to ~/.bashrc or ~/.zshrc
+echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Verify**:
+```bash
+which mcpls
+# Should output: /Users/username/.cargo/bin/mcpls
+```
+
+### "failed to compile mcpls"
+
+**Problem**: Rust version too old
+
+**Solution**:
+```bash
+# Update to Rust 1.85 or later
+rustup update stable
+rustc --version
+# Should output: rustc 1.85.0 or higher
+```
+
+**Problem**: Missing build dependencies
+
+**Solution** (Linux):
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install build-essential pkg-config libssl-dev
+
+# Fedora/RHEL
+sudo dnf install gcc pkg-config openssl-devel
+```
+
+### "error: could not find Cargo.toml"
+
+**Problem**: Not in the project directory
+
+**Solution**:
+```bash
+# Clone the repository first
+git clone https://github.com/bug-ops/mcpls
+cd mcpls
+
+# Then install
+cargo install --path crates/mcpls-cli
+```
+
+---
+
+## Claude Code Integration
+
+### mcpls not showing up in Claude Code
+
+**Checklist**:
+1. Verify mcpls is installed: `mcpls --version`
+2. Check MCP configuration file exists
+   - macOS/Linux: `~/.claude/mcp.json`
+   - Windows: `%APPDATA%\Claude\mcp.json`
+3. Verify JSON syntax is valid (no trailing commas)
+4. Restart Claude Code completely (quit and reopen)
+5. Check Claude Code logs for errors
+
+**Example valid configuration**:
+```json
+{
+  "mcpServers": {
+    "mcpls": {
+      "command": "mcpls",
+      "args": []
+    }
+  }
+}
+```
+
+**Invalid configurations**:
+```json
+{
+  "mcpServers": {
+    "mcpls": {
+      "command": "mcpls",
+      "args": [],  // ❌ Trailing comma!
+    },  // ❌ Trailing comma!
+  }
+}
+```
+
+### "Failed to start MCP server"
+
+**Problem**: mcpls binary not found or not executable
+
+**Solution**:
+```bash
+# Find the mcpls binary
+which mcpls
+
+# If found, use absolute path in config
+{
+  "mcpServers": {
+    "mcpls": {
+      "command": "/Users/username/.cargo/bin/mcpls",
+      "args": []
+    }
+  }
+}
+```
+
+**Test manually**:
+```bash
+# Test mcpls stdio communication
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | mcpls
+```
+
+Expected output should include:
+```json
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
+```
+
+### Tools available but not working
+
+**Problem**: LSP server not configured or not installed
+
+**Symptoms**:
+- Claude sees tools in the list
+- Tool calls return "LSP server not available for file type"
+
+**Solution**:
+
+1. Install required language server:
+```bash
+# For Rust
+rustup component add rust-analyzer
+
+# For Python
+npm install -g pyright
+
+# For TypeScript
+npm install -g typescript-language-server
+```
+
+2. Verify language server works:
+```bash
+rust-analyzer --version
+pyright --version
+typescript-language-server --version
+```
+
+3. Configure in `~/.config/mcpls/mcpls.toml` if needed (Rust works zero-config)
+
+---
+
+## LSP Server Issues
+
+### "LSP server not available for file type"
+
+**Problem**: No LSP server configured for the file extension
+
+**Solution**:
+
+Create `~/.config/mcpls/mcpls.toml`:
+```toml
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+file_patterns = ["**/*.py"]
+```
+
+**Verify configuration**:
+```bash
+mcpls --log-level debug
+# Check logs for "Registered LSP server for language: python"
+```
+
+### "LSP server timeout"
+
+**Problem**: Language server taking too long to respond
+
+**Symptoms**:
+- First requests are slow
+- Large projects time out
+- Tools return timeout errors
+
+**Solution 1**: Increase timeout in configuration:
+```toml
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+timeout_seconds = 120  # Increase from default 30
+```
+
+**Solution 2**: Wait for initial indexing to complete:
+```bash
+# rust-analyzer needs time to index on first run
+# Monitor with debug logging
+mcpls --log-level debug
+```
+
+**Solution 3**: Reduce workspace size:
+```toml
+[workspace]
+# Limit to active project only
+roots = ["/Users/username/current-project"]
+```
+
+### "rust-analyzer indexing takes forever"
+
+**Problem**: Large codebase with many dependencies
+
+**Symptoms**:
+- High CPU usage on first run
+- Slow response times
+- Timeout errors
+
+**Solutions**:
+
+1. **Wait for initial indexing** (one-time cost):
+```bash
+# Tail logs to monitor progress
+mcpls --log-level info 2>&1 | grep "rust-analyzer"
+```
+
+2. **Exclude build artifacts**:
+```toml
+[lsp_servers.initialization_options]
+files.excludeDirs = ["target", ".git", "node_modules"]
+```
+
+3. **Disable on-save checking temporarily**:
+```toml
+[lsp_servers.initialization_options]
+checkOnSave.enable = false
+```
+
+4. **Close unnecessary workspaces**:
+```toml
+[workspace]
+# Don't include entire home directory!
+roots = ["/Users/username/active-project"]
+```
+
+### "LSP server crashed"
+
+**Problem**: Language server process died unexpectedly
+
+**Symptoms**:
+- Tools suddenly stop working
+- "Server connection closed" errors
+- Need to restart mcpls
+
+**Debug steps**:
+
+1. Check server logs:
+```bash
+mcpls --log-level debug 2>&1 | tee mcpls-debug.log
+```
+
+2. Test server manually:
+```bash
+# For rust-analyzer
+rust-analyzer --help
+
+# For pyright
+pyright-langserver --help
+```
+
+3. Update language server:
+```bash
+# rust-analyzer
+rustup update
+rustup component add rust-analyzer
+
+# pyright
+npm update -g pyright
+```
+
+4. Report bug to language server maintainers if reproducible
+
+---
+
+## Configuration Issues
+
+### "Configuration file not found"
+
+**Problem**: mcpls not finding `mcpls.toml`
+
+**Debug**:
+```bash
+# Check searched locations
+mcpls --log-level debug 2>&1 | grep "config"
+```
+
+**Solution 1**: Specify config explicitly:
+```bash
+mcpls --config /path/to/mcpls.toml
+```
+
+**Solution 2**: Set environment variable:
+```bash
+export MCPLS_CONFIG=/path/to/mcpls.toml
+mcpls
+```
+
+**Solution 3**: Place in default location:
+```bash
+mkdir -p ~/.config/mcpls
+cp mcpls.toml ~/.config/mcpls/
+```
+
+### "Invalid configuration: missing field"
+
+**Problem**: TOML syntax error or missing required field
+
+**Common mistakes**:
+```toml
+# ❌ Missing required fields
+[[lsp_servers]]
+command = "rust-analyzer"
+# Missing: language_id, file_patterns
+
+# ✅ Correct
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+```
+
+**Solution**: Validate TOML syntax:
+```bash
+# Use online TOML validator
+# Or check with mcpls debug mode
+mcpls --config mcpls.toml --log-level debug
+```
+
+### "Command not found: rust-analyzer"
+
+**Problem**: Language server not in PATH
+
+**Solution 1**: Install language server:
+```bash
+rustup component add rust-analyzer
+```
+
+**Solution 2**: Use absolute path:
+```toml
+[[lsp_servers]]
+command = "/Users/username/.rustup/toolchains/stable-x86_64-apple-darwin/bin/rust-analyzer"
+```
+
+**Solution 3**: Add to PATH:
+```bash
+export PATH="$HOME/.rustup/toolchains/stable-x86_64-apple-darwin/bin:$PATH"
+```
+
+---
+
+## Performance Issues
+
+### mcpls using too much memory
+
+**Problem**: Multiple LSP servers or large workspace
+
+**Symptoms**:
+- High memory usage (>500MB)
+- System slowdown
+- Out of memory errors
+
+**Solutions**:
+
+1. **Configure only needed language servers**:
+```toml
+# Don't configure servers you don't use
+[[lsp_servers]]
+language_id = "rust"  # Only if working with Rust
+# ...
+```
+
+2. **Limit workspace roots**:
+```toml
+[workspace]
+# Only active projects
+roots = ["/Users/username/current-project"]
+```
+
+3. **Restart mcpls periodically**:
+```bash
+# If using with Claude, restart Claude Code
+# Or restart mcpls if running standalone
+```
+
+4. **Exclude large directories**:
+```toml
+[lsp_servers.initialization_options]
+files.excludeDirs = ["target", "node_modules", ".git", "dist"]
+```
+
+### Slow response times
+
+**Problem**: Cold start or large files
+
+**Symptoms**:
+- First request takes >5 seconds
+- Subsequent requests fast
+- Tools time out
+
+**Solutions**:
+
+1. **Increase timeout**:
+```toml
+[[lsp_servers]]
+timeout_seconds = 60
+```
+
+2. **Pre-warm LSP server**:
+```bash
+# Keep mcpls running between requests
+# Don't restart for every interaction
+```
+
+3. **Enable debug logging** to identify bottleneck:
+```bash
+mcpls --log-level debug 2>&1 | grep "duration\|took\|elapsed"
+```
+
+4. **Check system resources**:
+```bash
+# Monitor CPU and memory
+top -pid $(pgrep mcpls)
+```
+
+### High CPU usage
+
+**Problem**: Language server indexing or checking
+
+**Temporary solutions**:
+```toml
+[lsp_servers.initialization_options]
+# For rust-analyzer
+checkOnSave.enable = false  # Disable cargo check on save
+
+# For pyright
+python.analysis.diagnosticMode = "openFilesOnly"
+```
+
+**Long-term solution**: Wait for indexing to complete (one-time)
+
+---
+
+## Common Error Messages
+
+### "Document not found"
+
+**Cause**: File path not in workspace or doesn't exist
+
+**Fix**:
+1. Ensure file exists: `ls -la /path/to/file`
+2. Verify file is in workspace roots
+3. Use absolute path, not relative path
+
+### "No client available for language"
+
+**Cause**: No LSP server configured for file extension
+
+**Fix**: Add LSP server configuration for that language
+
+**Example**:
+```toml
+[[lsp_servers]]
+language_id = "go"
+command = "gopls"
+args = []
+file_patterns = ["**/*.go"]
+```
+
+### "Position out of bounds"
+
+**Cause**: Line/character position exceeds file content
+
+**Fix**:
+1. Verify line number is valid (1-based indexing)
+2. Verify character is within line length
+3. Remember: character is UTF-8 code points, not bytes
+
+**Example**:
+```rust
+// File with 10 lines
+get_hover(file, line: 15, ...)  // ❌ Line 15 doesn't exist
+get_hover(file, line: 5, ...)   // ✅ Valid
+```
+
+### "Internal error: failed to parse LSP response"
+
+**Cause**: LSP server returned invalid JSON or unexpected format
+
+**Debug**:
+```bash
+# Enable trace logging
+mcpls --log-level trace 2>&1 | tee mcpls-trace.log
+# Look for malformed JSON in logs
+```
+
+**Solutions**:
+1. Update language server to latest version
+2. Check for server bugs or incompatibilities
+3. Report issue to mcpls maintainers with trace logs
+
+### "Failed to initialize LSP server"
+
+**Cause**: Server startup failed or initialization timeout
+
+**Debug**:
+```bash
+# Test server manually
+rust-analyzer --help  # Should show help message
+
+# Check initialization options
+mcpls --log-level debug 2>&1 | grep "initialization"
+```
+
+**Solutions**:
+1. Verify server is installed and executable
+2. Check initialization_options in config
+3. Increase timeout
+4. Remove invalid initialization options
+
+---
+
+## Getting Help
+
+### Before asking for help
+
+1. **Enable debug logging**:
+```bash
+mcpls --log-level debug 2>&1 | tee mcpls-debug.log
+```
+
+2. **Collect system information**:
+```bash
+mcpls --version
+rust-analyzer --version  # or other LSP server
+rustc --version
+uname -a  # OS info
+```
+
+3. **Verify configuration**:
+```bash
+cat ~/.config/mcpls/mcpls.toml
+```
+
+4. **Test minimal example**:
+```bash
+# Create minimal config
+cat > test-mcpls.toml <<EOF
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+EOF
+
+mcpls --config test-mcpls.toml --log-level debug
+```
+
+### Where to get help
+
+1. **GitHub Issues**: https://github.com/bug-ops/mcpls/issues
+   - Search existing issues first
+   - Include debug logs and configuration
+   - Provide minimal reproduction steps
+
+2. **GitHub Discussions**: https://github.com/bug-ops/mcpls/discussions
+   - For questions and general help
+   - Community support
+
+3. **Documentation**:
+   - [Getting Started](getting-started.md)
+   - [Configuration Reference](configuration.md)
+   - [Tools Reference](tools-reference.md)
+
+### Reporting bugs
+
+When reporting bugs, include:
+
+```bash
+# System information
+mcpls --version
+rust-analyzer --version  # or other LSP server
+rustc --version
+uname -a
+
+# Configuration
+cat ~/.config/mcpls/mcpls.toml
+
+# Debug logs (run command that fails)
+mcpls --log-level trace 2>&1 | tee bug-report.log
+
+# Minimal reproduction steps
+echo "1. Create file test.rs with content: ..."
+echo "2. Run: mcpls ..."
+echo "3. Expected: ..."
+echo "4. Actual: ..."
+```
+
+### Feature requests
+
+For feature requests, include:
+- **Use case**: What problem are you trying to solve?
+- **Proposed solution**: How should it work?
+- **Alternatives**: What workarounds exist?
+- **Examples**: Show example configuration or usage
+
+---
+
+## Advanced Debugging
+
+### Enable trace logging
+
+Maximum verbosity for debugging:
+```bash
+export MCPLS_LOG=trace
+mcpls 2>&1 | tee trace.log
+```
+
+### Test LSP server directly
+
+Bypass mcpls to test LSP server:
+```bash
+# Start rust-analyzer
+rust-analyzer
+
+# Send initialize request (JSON-RPC)
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"processId":null,"rootUri":"file:///path/to/project","capabilities":{}}}
+```
+
+### Test MCP protocol
+
+Test mcpls MCP implementation:
+```bash
+# Send MCP initialize
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | mcpls
+
+# List tools
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | mcpls
+```
+
+### Monitor file changes
+
+Watch configuration file:
+```bash
+# macOS
+fswatch ~/.config/mcpls/mcpls.toml | xargs -n1 echo "Config changed:"
+
+# Linux
+inotifywait -m ~/.config/mcpls/mcpls.toml
+```
+
+### Network debugging
+
+If using TCP transport (future feature):
+```bash
+# Monitor network traffic
+tcpdump -i lo0 -A port 8080
+
+# Test with netcat
+nc localhost 8080
+```
+
+---
+
+## Quick Reference
+
+### Restart everything
+
+```bash
+# 1. Kill any running mcpls processes
+pkill mcpls
+
+# 2. Clear any cached state (if applicable)
+rm -rf ~/.cache/mcpls  # Future feature
+
+# 3. Restart Claude Code
+# Quit and reopen Claude Code application
+
+# 4. Verify clean start
+mcpls --version
+```
+
+### Reset configuration
+
+```bash
+# Backup existing config
+cp ~/.config/mcpls/mcpls.toml ~/.config/mcpls/mcpls.toml.backup
+
+# Start with minimal config
+cat > ~/.config/mcpls/mcpls.toml <<EOF
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+args = []
+file_patterns = ["**/*.rs"]
+EOF
+```
+
+### Check logs
+
+```bash
+# Recent errors
+mcpls --log-level error 2>&1 | tail -20
+
+# All debug output
+mcpls --log-level debug 2>&1 | less
+
+# JSON logs for parsing
+mcpls --log-json 2>&1 | jq
+```
+
+---
+
+## Next Steps
+
+- [Getting Started](getting-started.md) - Quick start guide
+- [Configuration](configuration.md) - Detailed configuration
+- [Tools Reference](tools-reference.md) - MCP tools documentation