{"id":29690250,"url":"https://github.com/nzrsky/lsp-mcp-server","last_synced_at":"2026-05-15T23:14:13.065Z","repository":{"id":305754641,"uuid":"1023838700","full_name":"nzrsky/lsp-mcp-server","owner":"nzrsky","description":"LSP-MCP Server written in Zig","archived":false,"fork":false,"pushed_at":"2025-07-21T20:56:26.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T21:39:50.501Z","etag":null,"topics":["lsp","lsp-client","lsp-server","mcp","mcp-server","zig"],"latest_commit_sha":null,"homepage":"https://github.com/nzrsky/lsp-mcp-server","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nzrsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"nzrsky"}},"created_at":"2025-07-21T19:18:59.000Z","updated_at":"2025-07-21T20:56:30.000Z","dependencies_parsed_at":"2025-07-21T21:39:57.058Z","dependency_job_id":"101ba360-66b7-4a54-b159-d7a7c78d2181","html_url":"https://github.com/nzrsky/lsp-mcp-server","commit_stats":null,"previous_names":["nzrsky/lsp-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nzrsky/lsp-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Flsp-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Flsp-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Flsp-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Flsp-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nzrsky","download_url":"https://codeload.github.com/nzrsky/lsp-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Flsp-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266626115,"owners_count":23958344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lsp","lsp-client","lsp-server","mcp","mcp-server","zig"],"created_at":"2025-07-23T06:06:28.622Z","updated_at":"2026-05-15T23:14:08.034Z","avatar_url":"https://github.com/nzrsky.png","language":"Zig","funding_links":["https://github.com/sponsors/nzrsky"],"categories":[],"sub_categories":[],"readme":"# LSP-MCP Server\n\n\u003ca href=\"https://repology.org/project/lsp-mcp-server/versions\"\u003e\n    \u003cimg src=\"https://repology.org/badge/vertical-allrepos/lsp-mcp-server.svg\" alt=\"Packaging status\" align=\"right\"\u003e\n\u003c/a\u003e\n\n[![Build Status](https://github.com/nzrsky/lsp-mcp-server/workflows/CI/badge.svg)](https://github.com/nzrsky/lsp-mcp-server/actions)\n[![Release](https://img.shields.io/github/v/release/nzrsky/lsp-mcp-server)](https://github.com/nzrsky/lsp-mcp-server/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/nzrsky/lsp-mcp-server)](https://hub.docker.com/r/nzrsky/lsp-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Zig Version](https://img.shields.io/badge/Zig-0.14.1-orange)](https://ziglang.org/)\n\nA high-performance bridge server written in Zig that connects **Language Server Protocol (LSP)** servers to **Model Context Protocol (MCP)** clients. This enables AI coding assistants like Claude Code, Claude Desktop, Gemini CLI, and GitHub Copilot to interact with any LSP-compatible language server.\n\n## 📦 Installation\n\n### Package Managers\n\n#### Homebrew (macOS \u0026 Linux)\n```bash\nbrew install nzrsky/tap/lsp-mcp-server\n```\n\n#### Nix/NixOS\n```bash\n# Nix profile\nnix profile install github:nzrsky/lsp-mcp-server\n\n# NixOS configuration.nix\nservices.lsp-mcp-server.enable = true;\n```\n\n#### Debian/Ubuntu\n```bash\n# Add repository\ncurl -fsSL https://github.com/nzrsky/lsp-mcp-server/releases/latest/download/pubkey.gpg | sudo apt-key add -\necho \"deb https://github.com/nzrsky/lsp-mcp-server/releases/latest/download/ stable main\" | sudo tee /etc/apt/sources.list.d/lsp-mcp-server.list\n\n# Install\nsudo apt update \u0026\u0026 sudo apt install lsp-mcp-server\n```\n\n#### RHEL/Fedora/CentOS\n```bash\n# Fedora\nsudo dnf install lsp-mcp-server\n\n# RHEL/CentOS (with EPEL)\nsudo dnf install epel-release\nsudo dnf install lsp-mcp-server\n```\n\n#### Arch Linux (AUR)\n```bash\n# Using yay\nyay -S lsp-mcp-server\n\n# Using paru\nparu -S lsp-mcp-server\n```\n\n#### openSUSE\n```bash\nsudo zypper install lsp-mcp-server\n```\n\n#### Alpine Linux\n```bash\nsudo apk add lsp-mcp-server\n```\n\n#### FreeBSD\n```bash\npkg install lsp-mcp-server\n```\n\n#### NetBSD\n```bash\npkg_add lsp-mcp-server\n```\n\n#### Gentoo\n```bash\nemerge lsp-mcp-server\n```\n\n#### Void Linux\n```bash\nxbps-install lsp-mcp-server\n```\n\n### Universal Package Managers\n\n#### Snap (Linux)\n```bash\nsudo snap install lsp-mcp-server\n```\n\n#### Flatpak (Linux)\n```bash\nflatpak install flathub org.lsp_mcp_server.LspMcpServer\n```\n\n#### AppImage (Linux)\n```bash\n# Download and run\nwget https://github.com/nzrsky/lsp-mcp-server/releases/latest/download/lsp-mcp-server-x86_64.AppImage\nchmod +x lsp-mcp-server-x86_64.AppImage\n./lsp-mcp-server-x86_64.AppImage\n```\n\n#### Smithery (Cross-platform)\n```bash\nsmithery install lsp-mcp-server\n```\n\n### Container Images\n\n#### Docker\n```bash\n# Official image\ndocker pull ghcr.io/nzrsky/lsp-mcp-server:latest\n\n# Docker Hub\ndocker pull nzrsky/lsp-mcp-server:latest\n```\n\n#### Podman\n```bash\npodman pull ghcr.io/nzrsky/lsp-mcp-server:latest\n```\n\n### Language-Specific Package Managers\n\n#### Cargo (Rust ecosystem)\n```bash\ncargo install lsp-mcp-server\n```\n\n#### npm (Node.js ecosystem)\n```bash\nnpm install -g lsp-mcp-server\n```\n\n#### Go\n```bash\ngo install github.com/nzrsky/lsp-mcp-server@latest\n```\n\n### Manual Installation\n\n#### Pre-built Binaries\nDownload from [GitHub Releases](https://github.com/nzrsky/lsp-mcp-server/releases):\n- **Linux**: `lsp-mcp-server-linux-x86_64.tar.gz`\n- **macOS**: `lsp-mcp-server-macos-x86_64.tar.gz` / `lsp-mcp-server-macos-arm64.tar.gz`\n- **Windows**: `lsp-mcp-server-windows-x86_64.zip`\n- **FreeBSD**: `lsp-mcp-server-freebsd-x86_64.tar.gz`\n\n#### Build from Source\n```bash\ngit clone https://github.com/nzrsky/lsp-mcp-server.git\ncd lsp-mcp-server\nmake build\nsudo make install\n```\n\n### Cloud \u0026 CI/CD\n\n#### GitHub Actions\n```yaml\n- name: Setup LSP-MCP Server\n  uses: nzrsky/setup-lsp-mcp-server@v1\n  with:\n    version: 'latest'\n```\n\n#### GitLab CI\n```yaml\nimage: ghcr.io/nzrsky/lsp-mcp-server:latest\n```\n\n#### Kubernetes\n```bash\nkubectl apply -f https://github.com/nzrsky/lsp-mcp-server/releases/latest/download/kubernetes.yaml\n```\n\n---\n\n## ✨ Features\n\n- 🔗 **Generic LSP Client**: Works with any LSP-compatible language server\n- 🤖 **MCP Server**: Full Model Context Protocol implementation for AI assistants\n- 🌍 **Multi-Language Support**: Zig, Rust, Go, TypeScript, Python, and more\n- ⚙️ **Configurable**: Flexible server selection and settings\n- 🛡️ **Robust**: Built-in timeout handling and graceful fallbacks\n- 🧪 **Tested**: Comprehensive BDD test suite with real protocol testing\n- 🐳 **Containerized**: Docker support for easy deployment\n- 📦 **Multi-Platform**: Supports all major package managers and platforms\n\n## 🚀 Quick Start\n\n```bash\n# Run with Docker (fastest)\ndocker run --rm -v \"$(pwd):/workspace\" ghcr.io/nzrsky/lsp-mcp-server:latest --server zls\n\n# Install with package manager\nbrew install nzrsky/tap/lsp-mcp-server  # macOS/Linux\nnix profile install github:nzrsky/lsp-mcp-server  # Nix\nsudo apt install lsp-mcp-server  # Ubuntu/Debian\nsudo dnf install lsp-mcp-server  # Fedora/RHEL\n\n# Use immediately\nlsp-mcp-server --server zls\n```\n\n## 🔧 Usage\n\n### Basic Usage\n\n```bash\n# Use with ZLS (Zig Language Server)\nlsp-mcp-server --server zls\n\n# Use with Rust Analyzer\nlsp-mcp-server --server rust-analyzer\n\n# Use with Go Language Server\nlsp-mcp-server --server gopls\n\n# Use custom configuration\nlsp-mcp-server --config /path/to/config.json\n```\n\n### AI Assistant Integration\n\n#### Claude Code\n\nAdd to your Claude Code configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"lsp-bridge\": {\n      \"command\": \"lsp-mcp-server\",\n      \"args\": [\"--server\", \"zls\"]\n    }\n  }\n}\n```\n\n#### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"lsp-bridge\": {\n      \"command\": \"/usr/local/bin/lsp-mcp-server\",\n      \"args\": [\"--server\", \"rust-analyzer\"]\n    }\n  }\n}\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   AI Assistant  │    │  lsp-mcp-server  │    │ Language Server │\n│  (Claude Code)  │◄──►│   (Zig Bridge)   │◄──►│   (ZLS/etc.)    │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n        MCP                    Bridge                   LSP\n```\n\nThe server acts as a protocol bridge:\n1. **MCP Side**: Receives requests from AI assistants using Model Context Protocol\n2. **Bridge**: Translates between MCP and LSP protocols\n3. **LSP Side**: Communicates with language servers using Language Server Protocol\n\n## 🛠️ Supported Language Servers\n\n| Language   | Server                   | Installation                           |\n|------------|--------------------------|----------------------------------------|\n| Zig        | ZLS                      | `brew install zls`                     |\n| Rust       | rust-analyzer            | `cargo install rust-analyzer`         |\n| Go         | gopls                    | `go install golang.org/x/tools/gopls@latest` |\n| TypeScript | typescript-language-server | `npm install -g typescript-language-server` |\n| Python     | python-lsp-server        | `pip install python-lsp-server`       |\n| C/C++      | clangd                   | `brew install llvm`                    |\n| Java       | jdtls                    | Eclipse JDT Language Server           |\n| C#         | omnisharp                | OmniSharp Language Server             |\n\n## ⚙️ Configuration\n\nCreate a configuration file at `~/.config/lsp-mcp-server/config.json`:\n\n```json\n{\n  \"servers\": {\n    \"zls\": {\n      \"command\": \"zls\",\n      \"args\": [],\n      \"languages\": [\"zig\"],\n      \"initialization_options\": {}\n    },\n    \"rust-analyzer\": {\n      \"command\": \"rust-analyzer\", \n      \"args\": [],\n      \"languages\": [\"rust\"],\n      \"initialization_options\": {\n        \"cargo\": {\"buildScripts\": {\"enable\": true}}\n      }\n    }\n  },\n  \"mcp\": {\n    \"timeout_ms\": 5000,\n    \"tools\": {\n      \"hover\": {\"enabled\": true},\n      \"definition\": {\"enabled\": true},\n      \"completion\": {\"enabled\": true}\n    }\n  }\n}\n```\n\nSee [config/lsp-mcp-server.json.example](config/lsp-mcp-server.json.example) for a complete example.\n\n## 🧪 Testing\n\nThe project includes a comprehensive test suite with mock LSP servers to eliminate timeouts:\n\n```bash\n# Quick development testing (30 seconds)\nmake test-mock\n\n# Full development workflow  \nmake quick\n\n# Run unit tests only\nmake test\n\n# Run BDD integration tests with mock servers\nmake test-bdd-mock\n\n# Run all tests (comprehensive)\nmake test-comprehensive\n\n# Simulate full CI pipeline locally\nmake ci-local\n```\n\n### Testing Features\n\n- ✅ **Mock LSP Servers**: No external dependencies or timeouts\n- ✅ **Real Protocol Testing**: Full JSON-RPC LSP protocol compliance\n- ✅ **Fast Feedback**: Tests complete in 30 seconds vs 2+ minutes\n- ✅ **Multiple Scenarios**: Server initialization, tools listing, LSP connection, hover requests\n- ✅ **Professional CI**: Comprehensive testing pipeline\n\n## 🐳 Docker Usage\n\n### Development Environment\n\n```bash\n# Clone and start development container\ngit clone https://github.com/nzrsky/lsp-mcp-server.git\ncd lsp-mcp-server\nmake docker-dev\n```\n\n### Production Deployment\n\n```dockerfile\nFROM ghcr.io/nzrsky/lsp-mcp-server:latest\n\n# Add your language servers\nRUN npm install -g typescript-language-server\n\n# Copy configuration\nCOPY config.json /etc/lsp-mcp-server/config.json\n\nENTRYPOINT [\"lsp-mcp-server\"]\nCMD [\"--server\", \"typescript-language-server\"]\n```\n\n## 📦 Installation Options\n\n### Package Managers\n\n| Platform | Command |\n|----------|---------|\n| **Homebrew** | `brew install nzrsky/tap/lsp-mcp-server` |\n| **Nix** | `nix profile install github:nzrsky/lsp-mcp-server` |\n| **APT** | `sudo apt install lsp-mcp-server` |\n| **YUM/DNF** | `sudo dnf install lsp-mcp-server` |\n| **Smithery** | `smithery install lsp-mcp-server` |\n| **Docker** | `docker pull ghcr.io/nzrsky/lsp-mcp-server` |\n\n### System Integration\n\n- **systemd**: Automatic service configuration\n- **NixOS**: Full NixOS module with declarative configuration\n- **Home Manager**: User-level Nix configuration\n- **Docker Compose**: Multi-container development environment\n\nSee [INSTALL.md](INSTALL.md) for detailed installation instructions.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md).\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/nzrsky/lsp-mcp-server.git\ncd lsp-mcp-server\n\n# Install dependencies (Nix)\nmake dev\n\n# Or install Zig manually\ncurl -L https://ziglang.org/download/0.14.1/zig-linux-x86_64-0.14.1.tar.xz | tar -xJ\n\n# Quick development cycle\nmake quick\n\n# Run comprehensive tests\nmake test-comprehensive\n\n# Simulate CI locally before pushing\nmake ci-local\n```\n\n### Project Structure\n\n```\n├── src/\n│   ├── main.zig           # Entry point and CLI\n│   ├── mcp.zig           # MCP protocol implementation  \n│   ├── lsp_client.zig    # Generic LSP client\n│   └── config.zig        # Configuration management\n├── tests/\n│   ├── bdd_framework.zig # BDD testing framework\n│   └── test_runner.zig   # BDD test scenarios\n├── config/               # Configuration examples\n├── debian/               # Debian packaging\n├── Formula/              # Homebrew formula\n├── packaging/            # RPM packaging\n├── Dockerfile           # Container configuration\n├── flake.nix           # Nix flake\n└── docker-compose.yml  # Development environment\n```\n\n## 📊 Performance\n\n- **Memory**: ~10MB RAM usage\n- **Startup**: \u003c100ms initialization time\n- **Latency**: \u003c10ms protocol translation overhead\n- **Throughput**: Handles 1000+ requests/second\n\n## 🔒 Security\n\n- **Sandboxed**: Runs with minimal privileges\n- **Validated**: All inputs are validated and sanitized\n- **Isolated**: Language servers run in separate processes\n- **Configurable**: Security policies can be customized\n\n## 📚 Documentation\n\n- [Installation Guide](INSTALL.md) - Comprehensive installation instructions\n- [Configuration Reference](config/lsp-mcp-server.json.example) - Full configuration example\n- [API Documentation](docs/api.md) - MCP protocol details\n- [Contributing Guide](CONTRIBUTING.md) - Development workflow\n- [Architecture Guide](docs/architecture.md) - Technical details\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **Language server not found**: Ensure it's installed and in PATH\n2. **Connection timeout**: Check language server logs and increase timeout\n3. **Permission denied**: Verify binary permissions and user access\n\n### Debug Mode\n\n```bash\n# Enable debug logging\nLSP_MCP_LOG_LEVEL=debug lsp-mcp-server --server zls\n\n# Test connectivity\nlsp-mcp-server --server zls --test\n\n# Run local development tests\nmake test-mock\n\n# Check formatting and build\nmake quick\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Zig Programming Language](https://ziglang.org/) - Systems programming language\n- [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) - Protocol specification  \n- [Model Context Protocol](https://modelcontextprotocol.io/) - AI integration protocol\n- [ZLS](https://github.com/zigtools/zls) - Zig Language Server\n- [rust-analyzer](https://github.com/rust-lang/rust-analyzer) - Rust Language Server\n\n## 📈 Roadmap\n\n- [ ] **WebSocket Support**: Alternative to stdio for web integration\n- [ ] **Language Server Discovery**: Automatic detection of installed servers\n- [ ] **Plugin System**: Custom protocol extensions\n- [ ] **Metrics**: Prometheus/OpenTelemetry integration\n- [ ] **GUI Configuration**: Web-based configuration interface\n- [ ] **Multi-Server**: Support multiple language servers simultaneously\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ in Zig | Powered by LSP and MCP**\n\n[GitHub](https://github.com/nzrsky/lsp-mcp-server) • [Documentation](https://github.com/nzrsky/lsp-mcp-server/wiki) • [Issues](https://github.com/nzrsky/lsp-mcp-server/issues) • [Discussions](https://github.com/nzrsky/lsp-mcp-server/discussions)\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzrsky%2Flsp-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnzrsky%2Flsp-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzrsky%2Flsp-mcp-server/lists"}