# Enhanced Everything MCP Server
A comprehensive Model Context Protocol (MCP) server that transforms [voidtools Everything](https://www.voidtools.com/) search engine into an intelligent development research platform. Integrates with AI assistants like Cursor, [Kiro IDE](https://github.com/kirodotdev/Kiro), [SpecStory](https://github.com/specstoryai/docs), and Claude to provide lightning-fast file search, GitHub integration, intent-based code research, and spec-driven development tools.
## šÆ Kiro IDE Integration Workflow
*Complete spec-driven development workflow from requirements to implementation*
## š Features
### Core Search Capabilities
- **Lightning Fast Search**: Leverages Everything's instant search capabilities
- **Advanced Filtering**: Filter by file types, size, date, and more
- **Multiple Sort Options**: Sort by name, size, date, or path
- **Regex Support**: Use regular expressions for complex searches
- **Service Health Checks**: Verify Everything service status
### Enhanced Research Features
- **š§ Intent-Based Code Research**: Analyzes specifications and finds matching implementations across GitHub
- **š GitHub MCP Integration**: Seamless local/remote search with repository metadata
- **š SQLite Knowledge Base**: Builds searchable library of code patterns over time
- **š CSV Export Integration**: Structured data export using ES tools
- **šÆ Implementation Suggestions**: AI-powered recommendations based on research findings
### Spec-Driven Development
- **š Specification Awareness**: Understands requirements, design, and task documents
- **š Traceability Analysis**: Cross-references between specs and implementation
- **š Progress Tracking**: Monitors specification coverage and task completion
- **š„ļø Terminal UI (TUI)**: Rich terminal interface for interactive project management
### Integration & Automation
- **ā” One-Click Kiro Installation**: Automated setup and configuration
- **š§ Comprehensive Logging**: Full trace logging with structured debugging
- **š Easy Integration**: Simple setup with Cursor, Kiro, SpecStory, and other MCP clients
## š Prerequisites
- **Windows OS**: Everything only runs on Windows
- **Python 3.8+**: Required for virtual environment management
- **Python Virtual Environment**: All operations must run in an activated venv
- **Everything Installed**: Download from [voidtools.com](https://www.voidtools.com/)
- **Node.js 18+**: Required for MCP server
- **es.exe Available**: Command-line interface must be accessible
### Environment Setup
1. **Create and activate Python virtual environment:**
```bash
python -m venv everything-mcp-env
everything-mcp-env\Scripts\activate
```
2. **Install Everything from [voidtools.com](https://www.voidtools.com/)**
3. **Ensure the Everything service is running**
4. **Verify `es.exe` exists at: `C:\Program Files\Everything\es.exe`**
5. **Test with: `"C:\Program Files\Everything\es.exe" test`**
**ā ļø Important**: All commands must be run within the activated virtual environment.
## š ļø Installation
### Option 1: One-Click Kiro Installation *(Coming Soon)*
```bash
# Ensure virtual environment is activated
python -m venv everything-mcp-env
everything-mcp-env\Scripts\activate
# One command installs and configures everything for Kiro
npm install -g everything-mcp-kiro
kiro-everything --setup
```
### Option 2: From Source (Recommended)
```bash
# Create and activate virtual environment
python -m venv everything-mcp-env
everything-mcp-env\Scripts\activate
# Clone the repository
git clone https://github.com/SoMaCoSF/mcp-everything.git
cd mcp-everything
# Install dependencies
npm install
# Build the server
npm run build
# Test the installation (includes venv validation)
npm run test:kiro
```
### Option 3: Manual Configuration
```bash
# Ensure virtual environment is activated
python -m venv everything-mcp-env
everything-mcp-env\Scripts\activate
npm install -g everything-mcp-server
```
## š§ Usage with AI Assistants
### Cursor IDE
Add to your Cursor `settings.json`:
```json
{
"mcp": {
"servers": {
"everything-search": {
"command": "node",
"args": ["path/to/everything-mcp/dist/index.js"],
"env": {
"EVERYTHING_PATH": "C:\\Program Files\\Everything\\es.exe",
"TRACE_DIRECTORY": "D:\\outputs\\traces"
}
}
}
}
}
```
### Kiro IDE
[Kiro](https://github.com/kirodotdev/Kiro) is an agentic IDE that supports MCP servers for external tool integration. To add Everything search to Kiro:
1. **Open Kiro IDE** and navigate to your project
2. **Create or edit your MCP configuration** following Kiro's MCP documentation
3. **Add the Everything MCP server** to your Kiro configuration:
```json
{
"mcpServers": {
"everything-search": {
"command": "node",
"args": ["path/to/everything-mcp/dist/index.js"],
"env": {
"EVERYTHING_PATH": "C:\\Program Files\\Everything\\es.exe",
"TRACE_DIRECTORY": "D:\\outputs\\traces"
},
"description": "Everything search integration for fast file/folder search"
}
}
}
```
4. **Restart Kiro** to load the new MCP server
5. **Use Everything search** through Kiro's agentic chat interface
**Kiro-specific features:**
- **Specs Integration**: Use Everything search to find files when planning features with Kiro's spec-driven development
- **Hooks Automation**: Set up automated file searches triggered by development events
- **Natural Language**: Ask Kiro to "find all TypeScript files modified today" and it will use Everything search
- **Project Context**: Kiro understands your project structure and can combine Everything search with its codebase knowledge
### SpecStory
[SpecStory](https://github.com/specstoryai/docs) is a documentation and specification platform designed for LLM integration. To add Everything search to SpecStory workflows:
1. **Set up MCP integration** in your SpecStory environment
2. **Add the Everything MCP server** to your SpecStory MCP configuration:
```json
{
"mcpServers": {
"everything-search": {
"command": "node",
"args": ["path/to/everything-mcp/dist/index.js"],
"env": {
"EVERYTHING_PATH": "C:\\Program Files\\Everything\\es.exe",
"TRACE_DIRECTORY": "D:\\outputs\\traces"
},
"description": "Everything search for finding specification files and documentation"
}
}
}
```
3. **Restart SpecStory** to load the new MCP server
4. **Use Everything search** to find relevant specification files, documentation, and project artifacts
**SpecStory-specific features:**
- **Specification Search**: Quickly find spec files, requirements documents, and related artifacts
- **Documentation Discovery**: Search across all project documentation and markdown files
- **Cross-Reference Lookup**: Find files referenced in specifications using Everything's fast indexing
- **Version Control Integration**: Search for spec files across different versions and branches
- **Context-Aware Documentation**: Combine Everything search with SpecStory's LLM context for comprehensive documentation workflows
**Example SpecStory workflows:**
```json
{
"query": "user authentication",
"docTypes": ["md", "mdx", "txt"],
"sortBy": "relevance",
"includeArchived": false
}
```
**Use the specialized documentation search:**
```json
{
"tool": "everything_search_docs",
"query": "API specification",
"docTypes": ["md", "yaml", "json"],
"sortBy": "relevance"
}
```
## š Available Tools
### 1. `everything_search`
Basic file and folder search with Everything syntax support.
**Parameters:**
- `query` (required): Search query using Everything syntax
- `maxResults` (optional): Maximum results to return (default: 50)
- `fileOnly` (optional): Search files only (default: false)
- `folderOnly` (optional): Search folders only (default: false)
### 2. `everything_search_advanced`
Advanced search with comprehensive filtering and sorting options.
**Parameters:**
- `query` (required): Search query
- `maxResults` (optional): Maximum results (default: 50)
- `sortBy` (optional): Sort by 'name', 'size', 'date', or 'path'
- `fileTypes` (optional): Array of file extensions to filter
- `includeHidden` (optional): Include hidden files/folders
- `regex` (optional): Use regex search
- `caseSensitive` (optional): Case sensitive search
### 3. `everything_check_service`
Verify Everything service is running and accessible.
### 4. `everything_search_docs`
Specialized documentation and specification search optimized for SpecStory workflows.
**Parameters:**
- `query` (required): Search query for documentation files
- `maxResults` (optional): Maximum results (default: 50)
- `docTypes` (optional): Documentation file types to search ['md', 'mdx', 'txt', 'rst', 'adoc']
- `includeArchived` (optional): Include archived/old documentation (default: false)
- `sortBy` (optional): Sort by 'relevance', 'date', 'name', or 'size'
**Features:**
- **Smart categorization**: Automatically categorizes docs as specs, requirements, designs, APIs, etc.
- **Priority ranking**: Relevance-based sorting puts most important docs first
- **Archive filtering**: Excludes deprecated/old documentation by default
- **SpecStory optimization**: Designed for specification and documentation workflows
### 5. `everything_deep_research` *(Coming Soon)*
Intent-based code research across public GitHub repositories.
**Parameters:**
- `specification` (required): Path to specification document or text content
- `searchDepth` (optional): 'shallow', 'medium', or 'deep' research depth
- `languages` (optional): Preferred programming languages
- `maxRepositories` (optional): Maximum repositories to analyze
**Features:**
- **Intent Analysis**: Parses specifications to understand implementation goals
- **Pattern Discovery**: Finds code patterns that match specification requirements
- **Quality Assessment**: Evaluates code quality, license compatibility, and maintenance status
- **Knowledge Base**: Stores findings in SQLite database for future reference
### 6. `everything_github_search` *(Coming Soon)*
Combined local and GitHub repository search.
**Parameters:**
- `query` (required): Search query
- `includeLocal` (optional): Include local file search (default: true)
- `includeGitHub` (optional): Include GitHub repository search (default: true)
- `repositories` (optional): Specific repositories to search
### 7. `everything_tui_launch` *(Coming Soon)*
Launch Terminal User Interface for interactive project management.
**Features:**
- **Project Dashboard**: Overview of specifications, tasks, and progress
- **Interactive Search**: Real-time search with filtering and sorting
- **Research Interface**: Monitor deep research progress and results
- **Implementation Suggestions**: Browse AI-generated recommendations
## š¤ Everything Search Syntax
The server supports full Everything search syntax:
- **Wildcards**: `*.txt`, `project*`
- **Extensions**: `ext:js`, `ext:pdf`
- **Size filters**: `size:>1mb`, `size:<100kb`
- **Date filters**: `dm:today`, `dm:thisweek`
- **Path filters**: `path:documents`, `path:"c:\projects"`
- **Boolean operators**: `AND`, `OR`, `NOT`
- **Exact phrases**: `"exact phrase"`
## š Examples
### Basic Search
```json
{
"query": "*.py",
"maxResults": 100
}
```
### Advanced Search
```json
{
"query": "dm:lastweek",
"fileTypes": ["mp4", "mkv", "avi"],
"sortBy": "size"
}
```
### Development Files
```json
{
"query": "component",
"fileTypes": ["jsx", "tsx"],
"caseSensitive": false
}
```
## š§ Troubleshooting
### Common Issues
1. **"es.exe not found"**
- Verify Everything is installed
- Check path: `C:\Program Files\Everything\es.exe`
- Try running Everything as administrator
2. **"No results returned"**
- Ensure Everything database is indexed
- Check if Everything service is running
- Use `everything_check_service` tool
3. **"Permission denied"**
- Run Everything as administrator
- Check Windows permissions
- Verify Everything service is started
### Debug Mode
The server logs all operations to the trace directory:
- Default Location: `D:\outputs\traces\everything-mcp-{timestamp}`
- Files: Operation logs, development diary, error traces
- Use for debugging search queries and server issues
## šļø Architecture
The Enhanced Everything MCP Server transforms simple file search into an intelligent development research platform:
### Current Architecture (v1.0)
1. **MCP Client** (Cursor/Kiro/SpecStory/Claude) sends search requests
2. **MCP Server** validates and processes requests
3. **es.exe** executes the actual search
4. **Results** are parsed and returned as structured JSON
5. **Trace System** logs all operations for debugging
### Enhanced Architecture (v2.0 - In Development)
*Intent-based code research with GitHub discovery and pattern analysis*
### Terminal User Interface Preview
*Interactive terminal dashboard for project management and search*
### Key Components
- **Research Engine**: Intent-based code discovery and pattern analysis
- **Knowledge Base**: SQLite database for accumulated research findings
- **GitHub Integration**: Seamless local/remote search capabilities
- **TUI Controller**: Rich terminal interface for interactive development
- **Spec Awareness**: Understanding of requirements, design, and task documents
## ļæ½ļø eRoadmap
### ā
Phase 1: Core Search (v1.0 - Current)
- [x] Basic Everything search integration
- [x] Advanced filtering and sorting
- [x] Documentation search optimization
- [x] MCP protocol implementation
- [x] Comprehensive logging and tracing
### š§ Phase 2: Enhanced Research (v2.0 - In Development)
- [ ] GitHub MCP integration
- [ ] Intent-based code research
- [ ] SQLite knowledge base
- [ ] CSV export capabilities
- [ ] Pattern recognition and analysis
### š® Phase 3: Intelligence & Automation (v3.0 - Planned)
- [ ] Terminal User Interface (TUI)
- [ ] AI-powered implementation suggestions
- [ ] Automated specification analysis
- [ ] One-click Kiro installation
- [ ] Advanced voidtools integration
### š Current Status
The enhanced features are currently in **specification phase**. See `.kiro/specs/enhanced-everything-mcp/` for detailed requirements, design, and implementation plans.
## š Development
```bash
# Run current version in development mode
npm run dev
# Build for production
npm run build
# Start built server
npm start
# View enhancement specifications
# Open .kiro/specs/enhanced-everything-mcp/ in Kiro IDE
```
### File Structure
```
everything-mcp/
āāā src/
ā āāā index.ts # Main server implementation
āāā .kiro/specs/ # Enhancement specifications
ā āāā enhanced-everything-mcp/
ā āāā requirements.md # Detailed requirements
ā āāā design.md # Architecture design
ā āāā tasks.md # Implementation plan
āāā dist/ # Built files (generated)
āāā package.json # Dependencies and scripts
āāā tsconfig.json # TypeScript configuration
āāā architecture.svg # Architecture diagram
āāā README.md # This file
```
## š License
MIT License - See [LICENSE](LICENSE) file for details.
## š¤ Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request
## š Acknowledgments
- [voidtools](https://www.voidtools.com/) for the amazing Everything search engine
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- The Cursor team for MCP integration
- [Kiro IDE](https://github.com/kirodotdev/Kiro) for agentic development with MCP support
- [SpecStory](https://github.com/specstoryai/docs) for specification and documentation workflows
---
**Made with ā¤ļø for the Everything and AI community**
