JustinL.MCP.CodeVectorsMCP 1.0.8

CodeVectorsMCP

CodeVectorsMCP is an MCP (Model Context Protocol) server that provides context awareness for large software projects through text embeddings and vector search. It uses OpenAI embeddings and Qdrant vector database to enable semantic search across codebases.

Features

• Semantic Code Search: Search your codebase using natural language queries
• MCP Protocol Support: Integrates with AI assistants that support the Model Context Protocol
• Real-time Updates: Watch for file changes and automatically update embeddings
• Multi-language Support: Process various programming languages and documentation formats
• Efficient Chunking: Smart file chunking that respects code boundaries
• Batch Processing: Efficient batch embedding generation

Installation

Install as .NET Tool (Recommended)

Once published to NuGet, you can install CodeVectors globally:

dotnet tool install -g CodeVectorsMCP

Then use it anywhere with:

codevectors --help

Build from Source

Alternatively, you can build and run from source as described below.

Quick Start

Prerequisites

• .NET 8.0 SDK
• Docker (for Qdrant)
• OpenAI API key

Setup

1. If building from source, clone the repository

   git clone https://github.com/JustinL/CodeVectorsMCP.git
   cd CodeVectorsMCP
   

2. Initialize configuration

   # If installed as tool:
   codevectors init
   
   # If running from source:
   dotnet run --project src/JustinL.MCP.CodeVectors -- init
   

   This creates a configuration file at ./.codevectors/config.json

3. Set up Qdrant

   cd docker
   ./setup-qdrant.sh
   

4. Configure OpenAI API key

   export OPENAI_API_KEY=your-api-key-here
   

5. Build the project

   dotnet build
   

Usage

Generate embeddings for a project

# Generate embeddings for all files (both code and docs)
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject

# Generate embeddings for specific directories (include both code and docs from those directories)
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject --include src/ docs/

# Generate embeddings for specific file types across all directories
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject --include "*.cs" "*.md"

# Generate only for documentation files
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject --docs-only

# Generate for documentation directories specifically
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject --docs-dir docs/ documentation/

# Combine code and docs from different directories
dotnet run --project src/JustinL.MCP.CodeVectors -- generate /path/to/your/project --project myproject --include src/ --docs-dir docs/ wiki/

Watch for changes

dotnet run --project src/JustinL.MCP.CodeVectors -- watch /path/to/your/project --project myproject

Query the vector store

dotnet run --project src/JustinL.MCP.CodeVectors -- query "How does authentication work?"

Chunk files or directories into the vector store

# Chunk a single file
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/file.cs --project myproject

# Chunk a directory (processes all supported file types)
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/directory --project myproject

# Chunk specific directories (includes all file types from those directories)
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/directory --project myproject --include src/ docs/

# Chunk with custom file extensions across all directories
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/directory --project myproject --include "*.cs" "*.md"

# Chunk only documentation files
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/directory --project myproject --docs-only

# Force re-processing of existing files
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/directory --project myproject --force

# Process multiple directories with mixed content
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/project --project myproject --include src/ lib/ docs/ examples/

Run as MCP server (STDIO mode)

dotnet run --project src/JustinL.MCP.CodeVectors -- --stdio

Note: In STDIO mode, all logging is written to logs/codevectors.log to avoid interfering with the MCP protocol communication.

Run as MCP server (STDIO mode)

dotnet run --project src/JustinL.MCP.CodeVectors -- --stdio

Note: In STDIO mode, all logging is written to logs/codevectors.log to avoid interfering with the MCP protocol communication.

Run the REST API Server with Test UI

# Default port 5000
dotnet run --project src/JustinL.MCP.CodeVectors.Server

# Custom port
ASPNETCORE_URLS="http://localhost:8080" dotnet run --project src/JustinL.MCP.CodeVectors.Server

The REST API server provides:

• Test UI: http://localhost:5000/test.html - Interactive web interface for testing queries
• API endpoints:
  • POST /api/test/search - Search the vector store
  • GET /api/test/history - Get search history
  • DELETE /api/test/history - Clear search history
• Health check: GET /health - Server health status

Using the Test UI

The Test UI provides an easy way to test vector search without using an AI agent:

1. Open http://localhost:5000/test.html in your browser
2. Select which collection to search: All Collections, Code Only, or Documentation Only
3. Enter a search query (e.g., "How does authentication work?")
4. Click Search or press Enter
5. View the results with file paths, scores, code snippets, and type indicators (CODE/DOCS)

See docs/TEST_UI.md for detailed documentation.

MCP Protocol Example

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "1.0",
      "capabilities": {},
      "clientInfo": {
        "name": "debug-client",
        "version": "1.0.0"
      }
    }
  }'

Configuration

CodeVectorsMCP uses a configuration file located at ./.codevectors/config.json by default. You can specify a different location using the --config option.

Initialize Configuration

# Create default configuration
dotnet run --project src/JustinL.MCP.CodeVectors -- init

# Create configuration at custom location
dotnet run --project src/JustinL.MCP.CodeVectors -- init --config /path/to/config.json

Using Custom Configuration

# Use custom config file for any command
dotnet run --project src/JustinL.MCP.CodeVectors -- chunk /path/to/code --config /path/to/config.json

Key Settings

• Mode: Operation mode - "local" (default) or "remote"
• Embeddings:Model: OpenAI model to use (default: text-embedding-3-small)
• Embeddings:ApiKey: OpenAI API key (supports ${OPENAI_API_KEY} environment variable)
• Embeddings:ChunkSize: Size of text chunks (default: 1000)
• VectorStore:ConnectionString: Qdrant connection URL (default: http://localhost:6334 for gRPC)
• VectorStore:CodeCollectionName: Name of the code vector collection (default: code-vectors)
• VectorStore:DocumentationCollectionName: Name of the documentation vector collection (default: documentation-vectors)
• FileWatcher:IncludePatterns: File patterns to include when watching
• FileWatcher:ExcludePatterns: File patterns to exclude when watching
• RemoteServices: Configuration for remote mode (API URLs and settings)

Environment Variables

Configuration values can reference environment variables using the ${VARIABLE_NAME} syntax. For example:

{
  "Embeddings": {
    "ApiKey": "${OPENAI_API_KEY}"
  }
}

Architecture

The solution consists of several projects:

• JustinL.MCP.CodeVectors: Main CLI and MCP server
• JustinL.MCP.CodeVectors.Core: Core interfaces and models
• JustinL.MCP.CodeVectors.Server: REST API server for remote operations
• JustinL.MCP.CodeVectors.VectorStore: Qdrant integration

Documentation

Generate API Documentation for Vector Store

To generate YAML documentation files for vector store ingestion:

# Option 1: Build solution with API docs
dotnet build -p:GenerateApiDocs=true

# Option 2: Use MSBuild target directly
dotnet msbuild -t:GenerateApiDocs

# Option 3: Use the make target
make docs

The API documentation will be generated in docs/api/ as YAML files containing:

• Complete XML documentation comments
• Public API signatures
• Type information and inheritance
• Source file references

These YAML files are perfect for:

• Vector store ingestion
• RAG-based code generation
• API discovery and search
• Documentation processing

Building HTML Documentation

The project includes comprehensive XML documentation comments that can be built into HTML documentation.

Prerequisites

Tools are automatically installed when running the build scripts.

Build Documentation

# Windows PowerShell
./scripts/generate-docs.ps1

# Linux/Mac
./scripts/generate-docs.sh

# Or using make
make docs

The documentation will be generated in:

• docs/api/ - YAML metadata files (for vector stores)
• docs/_site/ - HTML website (when using full DocFX build)

MCP Integration

CodeVectorsMCP implements the Model Context Protocol and exposes a search_codebase tool that AI assistants can use to search through your indexed code.

Tool Schema

{
  "name": "search_codebase",
  "description": "Search for code snippets and documentation in the indexed codebase",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query"
      },
      "projectFilter": {
        "type": "string",
        "description": "Optional: Filter results to a specific project"
      },
      "namespaceFilter": {
        "type": "string",
        "description": "Optional: Filter results to a specific namespace"
      },
      "topK": {
        "type": "integer",
        "description": "Number of results to return (default: 10)"
      }
    }
  }
}

License

MIT License