MCP Server: Software Project Indexing & Semantic Search

This project provides a Model Context Protocol (MCP) server designed to index software project files and offer semantic search capabilities over the indexed content. It monitors project directories for changes and maintains an up-to-date index.

For detailed design and architectural decisions, please refer to ARCHITECTURE.md.

Usage (End Users)

This server is designed to be run easily by pointing it to the software project you want to index.

1. Run the Server

Navigate to a convenient location in your terminal. The server is started using the python -m command, specifying the module and the path to the project you wish to index.

python -m vector_index_mcp.main_mcp <path_to_your_project>

For example, to index a project located at ~/dev/my_cool_project, you would run:

python -m vector_index_mcp.main_mcp ~/dev/my_cool_project

Or, to index the current directory:

python -m vector_index_mcp.main_mcp .

The server will start, begin watching the specified project path for changes, and create/use a LanceDB database within that project's directory (by default).

2. Configuration

• PROJECT_PATH (Required, via Command Line):

  • This is now passed as a direct command-line argument to the server, as shown above. It specifies the root directory of the software project you want to index.

• Environment Variables (Optional, via .env file):

  • Other settings can be configured using an .env file placed in the directory from where you run the python -m ... command. The server uses pydantic-settings and will automatically load this .env file.

  • The following variables are supported:

    • LANCEDB_URI: Path where the LanceDB vector database will be stored.
      • Default: ./.lancedb (relative to the indexed project's path, meaning it's stored within the project itself).
    • EMBEDDING_MODEL_NAME: The Hugging Face Sentence Transformer model used for generating embeddings.
      • Default: all-MiniLM-L6-v2.
    • IGNORE_PATTERNS: Comma-separated list of glob patterns specifying files/directories to exclude from indexing (e.g., __pycache__/*,.git/*,*.db). These patterns are relative to the PROJECT_PATH.
      • Default: .*,*.db,*.sqlite,*.log,node_modules/*,venv/*,.git/*
    • LOG_LEVEL: Logging level for the application.
      • Default: INFO.

  • Example .env file (place this where you run the server command):

    # --- Optional (Defaults Provided) ---
    # URI for the LanceDB database. Default is './.lancedb' (inside the indexed project).
    # LANCEDB_URI=./my_project_index_data/.lancedb
    
    # Name of the Sentence Transformer model. Default is 'all-MiniLM-L6-v2'.
    # EMBEDDING_MODEL_NAME=sentence-transformers/paraphrase-multilingual-mpnet-base-v2
    
    # Comma-separated list of glob patterns to ignore.
    # Default: .*,*.db,*.sqlite,*.log,node_modules/*,venv/*,.git/*
    # IGNORE_PATTERNS=*.log,*.tmp,node_modules/*,dist/*,build/*
    
    # Logging level. Default is INFO
    # LOG_LEVEL=DEBUG
    

3. Accessing the Server

Once running, the server provides its functionality via the Model Context Protocol (MCP). You can interact with it using MCP-compatible clients, such as:

• Claude Desktop (if configured to connect to this server)
• mcp inspect CLI tool for exploring available tools and resources.

The server will announce its availability over MCP.

4. Editor/IDE Integration (e.g., for Roo)

To connect this MCP server to a compatible editor like Roo, you can configure it in the editor's settings. For Roo, you would create or update the .roo/mcp.json file in your project's root with the following configuration. This tells the editor how to launch and communicate with the server.

.roo/mcp.json:

{
  "mcpServers": {
    "vector-index-mcp": {
      "command": "pipx",
      "args": ["run", "vector-index-mcp", "./"],
      "timeout": 60,
      "env": {}
    }
  }
}

Development Setup

If you want to contribute to or modify the server itself:

1. Clone the repository:

   git clone https://github.com/synonymouse/vector-index-mcp.git
   cd vector-index-mcp
   

2. Set up the development environment: This command creates a virtual environment (.venv) if it doesn't exist, and installs the project in editable mode (-e) along with all runtime and development dependencies specified in pyproject.toml (.[dev]).

   make install-dev
   

3. Activate the virtual environment:

   source .venv/bin/activate
   

   (On Windows using Git Bash or WSL, the command is the same. For Command Prompt/PowerShell, use .venv\Scripts\activate)

4. (Optional) Create a .env file in the vector-index-mcp project root for development-specific settings if needed. For example, to specify a test project path when running directly:

   # In vector-index-mcp/.env (for development)
   # No PROJECT_PATH here, as it's passed as an argument
   LANCEDB_URI=./.dev_lancedb
   EMBEDDING_MODEL_NAME=all-MiniLM-L6-v2
   LOG_LEVEL=DEBUG
   IGNORE_PATTERNS=__pycache__/*,.git/*,*.tmp
   

   Then run the server pointing to a test project:

   python vector_index_mcp/main_mcp.py ../path/to/your/test_project
   

Development Commands

Ensure your virtual environment is activated (source .venv/bin/activate) before running these make commands from the vector-index-mcp project root:

• make test: Run the test suite using pytest.
• make lint: Check code style and format using ruff.
• make run-dev: Runs the development server, indexing the current directory.
• make clean: Remove temporary files (__pycache__, build artifacts, etc.).
• make help: Display a list of available commands.

MCP Interface (MCP Tools)

The server provides its functionality through the Model Context Protocol (MCP). Interaction with these tools occurs via an MCP-compatible client.

Available MCP Tools

The following tools are exposed by the server (defined in vector_index_mcp/main_mcp.py):

1. trigger_index

   • Description: Triggers the indexing process for the specified project path.
   • Arguments:
     • force_reindex: bool (optional, default: False): If true, forces a re-index, clearing any existing index data for the project first.
   • Note: The project_path itself is implicitly handled by the server instance, as it's configured at startup. The tool acts on this pre-configured path.

2. get_status

   • Description: Gets the current status of the indexer (e.g., idle, indexing, last_indexed_time).
   • Arguments: None.

3. search_index

   • Description: Searches the vector index for a given query.
   • Arguments:
     • query: str (required): The search query string.
     • top_k: int (optional, default: 5): The number of top results to return.

Interacting with MCP Tools

Use an MCP client (like mcp inspect or a programmatic client) to discover and call these tools. The client will handle the communication with the server.

Project Structure

graph TD
    MainMCP["vector_index_mcp/main_mcp.py (FastMCP Server)"]
    MCPServerClass["vector_index_mcp/mcp_server.py (MCPServer Class)"]
    Indexer["vector_index_mcp/indexer.py"]
    FileWatcher["vector_index_mcp/file_watcher.py"]
    ContentExtractor["vector_index_mcp/content_extractor.py"]
    Config["vector_index_mcp/config.py (Settings)"]
    Models["vector_index_mcp/models.py (Data Models)"]
    PyProject["pyproject.toml"]
    README["README.md"]
    REFACTORING_PLAN["REFACTORING_PLAN.md"]
    Tests["tests/"]

    MainMCP --> MCPServerClass
    MainMCP --> Config
    MCPServerClass --> Indexer
    MCPServerClass --> FileWatcher
    MCPServerClass --> Config
    Indexer --> ContentExtractor
    Indexer --> Models
    Indexer --> Config
    FileWatcher --> Indexer
    FileWatcher --> Models
    FileWatcher --> Config

    PyProject -. Used for build and dependencies .-> MainMCP
    PyProject -. Used for build and dependencies .-> MCPServerClass
    PyProject -. Used for build and dependencies .-> Indexer
    PyProject -. Used for build and dependencies .-> FileWatcher
    PyProject -. Used for build and dependencies .-> ContentExtractor
    PyProject -. Used for build and dependencies .-> Config
    PyProject -. Used for build and dependencies .-> Models