MCP Qdrant Codebase Embeddings

MCP Qdrant Codebase Embeddings

This MCP (Model Context Protocol) server uses Qdrant vector database to provide semantic understanding of your codebase. It enables AI assistants to understand relationships between files, find similar code patterns, and provide architectural insights.

Features

• Semantic File Search: Find files based on their purpose or functionality
• Relationship Discovery: Understand how files relate to each other (imports, exports, tests, etc.)
• Architecture Analysis: Get insights into code structure, dependencies, and potential issues
• Refactoring Suggestions: Find candidates for refactoring based on various criteria
• Code Pattern Recognition: Identify similar code patterns across the codebase

Setup

Prerequisites

1. Qdrant: You need a running Qdrant instance
   # Using Docker docker run -p 6333:6333 qdrant/qdrant # Or use the docker-compose.yml in the parent directory docker-compose -f ../docker-compose.qdrant.yml up -d
2. Node.js: Version 18 or higher

Installation

1. Install dependencies:
   cd mcp-server npm install
2. Configure environment:
   cp .env.example .env # Edit .env with your configuration
3. Index your codebase:
   npm run index # Or index a specific directory npm run index /path/to/codebase

Running the Server

MCP Tools Available

1. find_related_files

Find files that are semantically related to a given file.

Parameters:

• filePath: Path to the file to find relationships for
• limit: Maximum number of related files to return (default: 10)

Example:

2. search_by_purpose

Search for files that match a specific purpose or functionality.

Parameters:

• purpose: Description of the purpose or functionality
• limit: Maximum number of files to return (default: 10)

Example:

3. analyze_architecture

Analyze the codebase architecture and identify patterns, issues, and insights.

Parameters:

• rootPath: Root path to analyze (optional, defaults to current directory)

Example:

4. find_refactoring_candidates

Find files that match criteria for refactoring.

Parameters:

• criteria: Description of what needs refactoring
• limit: Maximum number of files to return (default: 20)

Example:

5. explain_file_relationship

Explain the relationship between two files.

Parameters:

• sourceFile: Path to the source file
• targetFile: Path to the target file

Example:

How It Works

1. Indexing: The system analyzes each file in your codebase and generates embeddings that capture:
   • File structure and patterns
   • Imports and exports
   • Classes, functions, and interfaces
   • Code complexity and style
2. Vector Storage: These embeddings are stored in Qdrant, enabling fast similarity searches
3. Relationship Analysis: The system can identify various types of relationships:
   • Imports: Direct dependency relationships
   • Exports: Provider-consumer relationships
   • Similar: Files with similar structure or purpose
   • Complementary: Files that work together
   • Test: Test files and their implementations
   • Implementation: Interface/type implementations
4. Semantic Search: When you search by purpose, the system:
   • Generates an embedding for your query
   • Finds files with similar embeddings
   • Returns the most relevant matches

Configuration

Using OpenAI Embeddings (Recommended)

For best results, provide an OpenAI API key in your .env file. This uses OpenAI's text-embedding-ada-002 model.

Using Local Embeddings

If no OpenAI API key is provided, the system falls back to local embeddings based on code patterns. While less sophisticated, this still provides useful results without external dependencies.

Development

Building

Testing

Adding New Tools

To add new MCP tools:

1. Add the tool definition in src/index.ts in the ListToolsRequestSchema handler
2. Add the handler in the CallToolRequestSchema switch statement
3. Implement the logic in the appropriate service

Troubleshooting

Qdrant Connection Issues

• Ensure Qdrant is running on the configured URL (default: http://localhost:6333)
• Check if the port is not blocked by firewall
• Verify QDRANT_URL in your .env file

Indexing Issues

• Check file permissions for the codebase directory
• Ensure sufficient memory for large codebases
• Monitor Qdrant logs for storage issues

Embedding Generation Issues

• If using OpenAI, verify your API key is valid
• Check rate limits if indexing large codebases
• Consider using local embeddings for development

Integration with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol. Configure your AI assistant to connect to this server to enable codebase-aware responses.

Claude Desktop Configuration

Add to your Claude desktop configuration:

License

This tool is part of the FamilyManager project and follows the same license terms.