Smart Code Search MCP Server

# SCS-MCP - Smart Code Search for Claude Desktop <div align="center">     **An intelligent code search and analysis system with voice interaction capabilities** [Features](#features) • [Installation](#installation) • [Usage](#usage) • [API](#api) • [Voice Assistant](#voice-assistant) • [Contributing](#contributing) </div> --- ## 🌟 Overview SCS-MCP is a powerful Model Context Protocol (MCP) server that brings intelligent semantic code search, analysis, and voice interaction capabilities to Claude Desktop and other MCP-compatible clients. It combines state-of-the-art embedding models with sophisticated code analysis tools to provide deep insights into your codebase. ## Note from author This project is a work in progress and is not yet production-ready. It is intended for developers who want to experiment with advanced code search and analysis features, and contribute to its development. The Indexing and search capabilities are functional, but the voice assistant and orchestration features are still in beta. Please use with caution and report any issues you encounter. ~Steve Jobson ### Key Capabilities - 🔍 **Semantic Search** - Find code by meaning, not just text matching - 🎙️ **Voice Control** - Natural language voice commands for hands-free coding - 📸 **Media History** - Capture and annotate screenshots and recordings - 🧠 **AI-Powered Analysis** - Instant code reviews and quality assessments - 📊 **Code Metrics** - Complexity analysis and technical debt tracking - 🔄 **Git Integration** - Search through commit history and analyze changes - 🚀 **High Performance** - Sub-100ms search with intelligent caching - 🌍 **Multi-Language** - Support for Python, JavaScript, TypeScript, Java, Go, and more ## 🎯 Features ### Core Search Capabilities - **Hybrid Search**: Combines semantic understanding with keyword matching - **Context-Aware**: Understands code relationships and dependencies - **Instant Results**: Optimized for speed with response caching - **Flexible Filtering**: Filter by file type, path, or custom patterns ### Code Intelligence Tools - **Instant Review**: Real-time code quality feedback - **Complexity Analysis**: Identify complex code that needs refactoring - **Test Gap Detection**: Find untested code paths - **Security Scanning**: Basic vulnerability detection - **Dependency Analysis**: Track imports and circular dependencies - **Graph Visualization**: Generate dependency graphs in DOT, Mermaid, or JSON formats ### Voice Assistant Integration - **Natural Commands**: "Find authentication code", "Review this function" - **Context Awareness**: Integrates with VS Code for current file context - **Media Capture**: Voice-triggered screenshots and recordings with annotation tools - **Web UI**: Beautiful interface for voice interaction and media history - **Media Server**: Full-featured screenshot/recording system with gallery and export ### Orchestration Framework - **Technical Debt Analysis**: Comprehensive debt assessment - **Refactoring Assistant**: Guided refactoring suggestions - **Migration Planning**: Coordinate complex code migrations - **Quality Gates**: Automated quality checks ## 🚀 Installation ### Quick Start ```bash # Clone the repository git clone https://github.com/StevenJJobson/scs-mcp.git cd scs-mcp # Run the installer chmod +x scripts/install.sh ./scripts/install.sh # Configure Claude Desktop (see below) ``` ### Claude Desktop Configuration Add to your Claude Desktop config file: **Windows** (`%APPDATA%\Claude\claude_desktop_config.json`): ```json { "mcpServers": { "scs-mcp": { "command": "wsl", "args": ["bash", "-c", "cd /path/to/scs-mcp && python3 -m src.server"] } } } ``` **macOS/Linux** (`~/.config/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "scs-mcp": { "command": "python3", "args": ["-m", "src.server"], "cwd": "/path/to/scs-mcp" } } } ``` For detailed installation instructions, see [docs/INSTALLATION.md](docs/INSTALLATION.md). ## 🎙️ Voice Assistant The integrated voice assistant provides a hands-free coding experience with natural language commands. ### Setup ```bash # Navigate to voice assistant directory cd voice-assistant # Install dependencies npm install # Setup media directories npm run setup # Start the server npm start ``` ### Access the Web UI Open your browser to: [http://localhost:3000/media-ui.html](http://localhost:3000/media-ui.html) ### VS Code Extension Install the companion VS Code extension for enhanced editor integration: ```bash cd voice-assistant/vscode-extension npm install npm run compile # Press F5 in VS Code to launch ``` ### Voice Commands Examples - "Find all authentication functions" - "Review the current code for security issues" - "Show me similar code patterns" - "Take a screenshot of this error" - "Start recording my debugging session" - "What's the complexity of this function?" ## 📚 Usage Examples ### In Claude Desktop Once configured, you can use natural language queries: ``` You: Find all database connection code in the project Claude: I'll search for database connection code using the SCS-MCP tool... [Returns relevant code snippets with context] You: Review the authentication.py file for security issues Claude: Let me analyze the authentication.py file for security concerns... [Provides detailed security review with recommendations] ``` ### Available Tools SCS-MCP provides 30+ specialized tools. Here are some highlights: | Tool | Description | Example Use | |-----------------------------|----------------------------------|---------------------------------| | `search` | Semantic code search | Find authentication logic | | `find_similar` | Find similar code patterns | Locate duplicate code | | `instant_review` | Quick code review | Check code quality | | `analyze_symbol` | Deep symbol analysis | Understand a complex class | | `git_search_history` | Search git history | Find when bug was introduced | | `debt_orchestrator` | Technical debt analysis | Identify refactoring priorities | | `generate_dependency_graph` | Create dependency graphs | Visualize code structure | For complete API documentation, see [docs/API.md](docs/API.md). For detailed feature descriptions, see [docs/FEATURES.md](docs/FEATURES.md). ## 🏗️ Architecture SCS-MCP uses a modular architecture for scalability and extensibility: ``` ┌─────────────────┐ │ Claude Desktop │ └────────┬────────┘ │ MCP Protocol ┌────────▼────────┐ │ MCP Server │ ├─────────────────┤ │ Search Engine │ │ Analysis Tools │ │ Orchestrators │ ├─────────────────┤ │ Database Layer │ │ Git Integration│ │ Cache System │ └─────────────────┘ ``` For detailed architecture information, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## 🔧 Configuration Create a `.env` file in the project root: ```bash # Project Settings PROJECT_ROOT=/path/to/your/code PROJECT_NAME=MyProject # Performance MAX_WORKERS=4 CACHE_TTL=300 # Features ENABLE_VOICE=true ENABLE_GIT_HISTORY=true # Optional: API Keys ELEVENLABS_API_KEY=your_key_here # For text-to-speech OPENAI_API_KEY=your_key_here # For enhanced processing ``` ## 📊 Performance - **Search Speed**: < 100ms for most queries - **Indexing**: ~1000 files/second - **Memory Usage**: < 500MB typical - **Cache Hit Rate**: > 80% for common queries ## 🧪 Testing Run the test suite: ```bash # Python tests python -m pytest tests/ # Voice assistant tests cd voice-assistant && npm test # Integration tests python scripts/integration_test.py ``` ## 🤝 Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ### Development Setup ```bash # Create virtual environment python -m venv venv source venv/bin/activate # or venv\Scripts\activate on Windows # Install in development mode pip install -e . pip install -r requirements-dev.txt # Run tests pytest --cov=src tests/ ``` ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - [Anthropic](https://anthropic.com) for Claude and the MCP specification - [Sentence Transformers](https://www.sbert.net/) for embedding models - [Tree-sitter](https://tree-sitter.github.io/) for code parsing - The open-source community for invaluable contributions See [CREDITS.md](CREDITS.md) for detailed attribution of all dependencies and third-party code. ## 📮 Support - **Documentation**: [/docs](./docs/) - **Issues**: [GitHub Issues](https://github.com/StevenJJobson/scs-mcp/issues) - **Discussions**: [GitHub Discussions](https://github.com/StevenJJobson/scs-mcp/discussions) ## 🚦 Status - ✅ **Core Search**: Production ready - ✅ **Code Analysis**: Production ready - ✅ **Git Integration**: Production ready - ✅ **Voice Assistant**: Beta - 🚧 **Cloud Deployment**: In development ## 🎉 What's New ### Version 1.0.0 - 🎙️ Voice Assistant with web UI - 📸 Media history for screenshots and recordings - 🧠 Model information tools - 📊 Enhanced code metrics - 🔄 Improved orchestration framework - 🚀 Performance optimizations See [CHANGELOG.md](CHANGELOG.md) for full release notes. --- <div align="center"> **Built with ❤️ for Claude Code and AI assisted developement** [⬆ Back to top](#scs-mcp---smart-code-search-for-claude-desktop) </div>