# Simple-Index MCP Server

A Python Model Context Protocol (MCP) server for indexing projects, files, and folders using embeddings. Provides semantic search capabilities to help AI agents understand and navigate your codebase.

## Features

- **Semantic Indexing**: Uses embeddings (via Ollama) to create a searchable index of your project files
- **Single Index File**: All indexes are stored in `projectIndex.si` (in project root or global location)
- **Incremental Updates**: Only re-indexes files that have changed (based on content hash)
- **Extensible Provider System**: Easy to add new embedding providers beyond Ollama
- **MCP Tools**: Exposes powerful tools for indexing, searching, and retrieving context

## Installation

### Prerequisites

- Python 3.10 or higher
- [Ollama](https://ollama.ai/) installed and running locally
- `nomic-embed-text` model pulled in Ollama: `ollama pull nomic-embed-text`

### Setup

1. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```bash
pip install "mcp>=1.2.0" aiohttp
```

3. Place `simple_index_server.py` in your project directory

## Configuration

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "simple-index": {
      "command": "python",
      "args": [
        "/path/to/simple_index_server.py",
        "/path/to/your/project"
      ],
      "env": {
        "OLLAMA_MODEL": "nomic-embed-text",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}
```

      }
    }
  }
}
```

### Global Index Mode (Optional)

If you prefer to store the index file in a central location (instead of the project root), set the `SIMPLE_INDEX_ROOT` environment variable.

```json
{
  "mcpServers": {
    "simple-index": {
      "command": "python",
      "args": ["/path/to/simple_index_server.py"],
      "env": {
        "SIMPLE_INDEX_ROOT": "/path/to/central/indexes",
        "OLLAMA_MODEL": "nomic-embed-text"
      }
    }
  }
}
```

### Alternative Configuration Options

You can also specify the Ollama model and URL as command-line arguments:

```json
{
  "mcpServers": {
    "simple-index": {
      "command": "python",
      "args": [
        "/path/to/simple_index_server.py",
        "/path/to/your/project",
        "nomic-embed-text",
        "http://localhost:11434"
      ]
    }
  }
}
```

## Available Tools

### 1. `index_file`
Index a single file with embeddings.

**Parameters:**
- `file_path` (string, required): Path to the file to index
- `force` (boolean, optional): Force reindexing even if file hasn't changed

**Example:**
```
Claude, please index the file /path/to/my/script.py
```

### 2. `index_directory`
Index all matching files in a directory recursively.

**Parameters:**
- `directory` (string, required): Path to directory to index
- `patterns` (array of strings, optional): File patterns to match (default: `["*.py", "*.js", "*.ts", "*.md", "*.txt"]`)
- `exclude_patterns` (array of strings, optional): Patterns to exclude (default: `["*/node_modules/*", "*/.git/*", "*/venv/*"]`)

**Example:**
```
Claude, index all Python and JavaScript files in my project, excluding the tests directory
```

### 3. `search`
Search for files similar to a query using semantic search.

**Parameters:**
- `query` (string, required): Search query describing what you're looking for
- `top_k` (integer, optional): Number of results to return (default: 10)

**Example:**
```
Claude, search for files related to "database connection logic"
```

### 4. `get_context`
Get full file contents for the most relevant files to a query.

**Parameters:**
- `query` (string, required): Query describing what context you need
- `top_k` (integer, optional): Number of files to include in context (default: 5)

**Example:**
```
Claude, get context for "authentication implementation"
```

### 5. `list_indexed_files`
List all files currently in the index.

**Example:**
```
Claude, show me all indexed files
```

### 6. `get_index_stats`
Get statistics about the current index.

**Example:**
```
Claude, what are the index statistics?
```

### 7. `remove_file`
Remove a file from the index.

**Parameters:**
- `file_path` (string, required): Path to file to remove from index

**Example:**
```
Claude, remove the file /path/to/old/file.py from the index
```

## Index File Format

The `projectIndex.si` file is stored in JSON format with the following structure:

```json
{
  "version": "1.0",
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T12:30:00Z",
  "project_root": "/path/to/project",
  "metadata": {
    "total_files": 42,
    "total_size": 150000,
    "embedding_model": "ollama:nomic-embed-text"
  },
  "files": {
    "src/main.py": {
      "path": "src/main.py",
      "absolute_path": "/path/to/project/src/main.py",
      "hash": "abc123...",
      "embedding": [0.1, 0.2, ...],
      "indexed_at": "2026-01-31T12:30:00Z",
      "size": 1024,
      "metadata": {
        "extension": ".py",
        "name": "main.py"
      }
    }
  }
}
```

### Index Management

- **Atomic Writes**: The index is written atomically using a temporary file to prevent corruption
- **Change Detection**: Files are only re-indexed if their content hash changes
- **Incremental Updates**: You can index new files without affecting existing entries

## Usage Examples

### Initial Project Indexing

```
You: Claude, index my entire project directory at /Users/me/myproject

Claude: [Uses index_directory tool]
I've indexed your project. Found 45 files, indexed 42, skipped 3 binary files.
```

### Searching for Relevant Files

```
You: Find files related to user authentication

Claude: [Uses search tool]
I found these relevant files:
1. src/auth/login.py (similarity: 0.89)
2. src/middleware/auth_check.py (similarity: 0.85)
3. tests/test_auth.py (similarity: 0.78)
```

### Getting Context for Development

```
You: I need to modify the payment processing logic. Show me the relevant code.

Claude: [Uses get_context tool]
Here's the relevant code from 3 files:

## File 1: src/payments/processor.py (similarity: 0.92)
[Full file contents...]

## File 2: src/payments/validators.py (similarity: 0.87)
[Full file contents...]
```

### Checking Index Status

```
You: What's the status of the index?

Claude: [Uses get_index_stats tool]
Index Statistics:
- Total files: 42
- Total size: 150 KB
- Last updated: 2026-01-31T12:30:00Z
- Embedding model: ollama:nomic-embed-text
```

## Architecture

### Components

1. **EmbeddingProvider**: Abstract base class for embedding providers
   - `OllamaProvider`: Implementation using Ollama API
   - Easy to extend with OpenAI, Cohere, etc.

2. **ProjectIndex**: Manages the `projectIndex.si` file
   - Loading and saving with atomic writes
   - Adding, removing, and querying files
   - Computing statistics

3. **SimpleIndexServer**: Main MCP server implementation
   - File reading and hashing
   - Orchestrating indexing operations
   - Semantic search functionality

4. **MCP Integration**: Standard Model Context Protocol server
   - Tool registration and handling
   - STDIO transport for communication

### Adding New Embedding Providers

To add a new provider (e.g., OpenAI):

```python
class OpenAIProvider(EmbeddingProvider):
    def __init__(self, api_key: str, model: str = "text-embedding-3-small"):
        self.api_key = api_key
        self.model = model
    
    async def embed(self, text: str) -> List[float]:
        # Implementation using OpenAI API
        pass
```

Then modify the `main()` function to support the new provider.

## Best Practices

1. **Index Regularly**: Run indexing after significant code changes
2. **Use Exclude Patterns**: Exclude `node_modules`, `venv`, build artifacts
3. **Semantic Queries**: Use descriptive queries like "error handling for API requests" rather than just "error"
4. **Monitor Index Size**: Large projects may need chunking strategies for very large files

## Troubleshooting

### Ollama Connection Issues

```bash
# Check if Ollama is running
curl http://localhost:11434/api/version

# Pull the embedding model if not available
ollama pull nomic-embed-text
```

### Index Corruption

If `projectIndex.si` becomes corrupted, simply delete it and re-index:

```bash
rm projectIndex.si
# Then ask Claude to re-index the directory
```

### Logging

The server uses Python's `logging` module and writes to stderr (MCP requirement). Check your MCP client's logs for debugging information.

## Performance Considerations

- **Embedding Generation**: ~100-500ms per file depending on size
- **Index Size**: ~4KB per file (768-dim embeddings + metadata)
- **Search Speed**: <100ms for typical project sizes (hundreds of files)

## License

MIT License - Feel free to use and modify as needed.

## Contributing

This is a reference implementation. Feel free to fork and extend with:
- Additional embedding providers
- Chunking strategies for large files
- Multi-language support
- Custom metadata extraction
- Integration with other tools

## Credits

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Ollama](https://ollama.ai/)
- [nomic-embed-text](https://huggingface.co/nomic-ai/nomic-embed-text-v1)