SCS-MCP - Smart Code Search for Claude Desktop
An intelligent code search and analysis system with voice interaction capabilities
Features • Installation • Usage • API • Voice Assistant • Contributing
🌟 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
- 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
# 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):
{
"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):
{
"mcpServers": {
"scs-mcp": {
"command": "python3",
"args": ["-m", "src.server"],
"cwd": "/path/to/scs-mcp"
}
}
}
For detailed installation instructions, see docs/INSTALLATION.md.
🎙️ Voice Assistant
The integrated voice assistant provides a hands-free coding experience with natural language commands.
Setup
# 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
VS Code Extension
Install the companion VS Code extension for enhanced editor integration:
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]
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.
For detailed feature descriptions, see 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.
🔧 Configuration
Create a .env file in the project root:
# 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
- 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:
# 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 for guidelines.
Development Setup
# 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 file for details.
🙏 Acknowledgments
See CREDITS.md for detailed attribution of all dependencies and third-party code.
📮 Support
🚦 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 for full release notes.
Built with ❤️ for Claude Code and AI assisted developement
⬆ Back to top