VectorCodeLens

🚀 Modern Semantic Code Analysis Platform

A sophisticated TypeScript application that combines vector embeddings, large language models, and the Model Context Protocol to provide intelligent codebase analysis and natural language querying capabilities.

Features

• Semantic Code Analysis: Understand code structure, patterns, and relationships
• Natural Language Queries: Ask questions about your codebase in plain English
• Vector Embeddings: Semantic search powered by vector similarity
• Progressive Enhancement: Works with or without external AI services
• MCP Integration: Model Context Protocol for AI tool integration

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd VectorCodeLens

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the environment template:

cp .env.example .env

2. Configure your services in .env:

# Required: Qdrant Vector Database
VECTOR_DB_URL=http://127.0.0.1:6333

# Optional: Local LLM for embeddings
LLM_SERVICE_URL=http://localhost:11434

# Optional: Claude API for advanced analysis
CLAUDE_API_KEY=your_api_key_here

Running the Service

# Start external services (optional)
docker run -p 6333:6333 qdrant/qdrant  # Vector database
ollama serve                            # Local LLM

# Start VectorCodeLens
npm start

Usage Examples

Analyze a Codebase

// Using the MCP tool interface
const result = await codeAnalyzer({
  directory: "/path/to/your/project",
  filePatterns: ["*.ts", "*.js"],
  includeSummary: true
});

Query Your Code

// Ask natural language questions
const results = await queryCodebase({
  query: "How are errors handled in this codebase?",
  limit: 5
});

Architecture

VectorCodeLens uses a modular architecture with progressive enhancement:

• Scanner: Discovers and chunks code files intelligently
• Analysis: Uses LLMs to understand code structure and patterns
• Storage: Stores analysis and embeddings in vector database
• Query: Provides semantic search capabilities

Documentation

• Architecture Overview
• API Documentation
• Deployment Guide
• Development Guide

Project Structure

VectorCodeLens/
├── src/                # TypeScript source code
├── specs/              # Technical specifications
├── scripts/            # Build and utility scripts
├── docs/               # Additional documentation
├── test/               # Test files and fixtures
└── logs/              # Runtime logs

Development

Prerequisites

• Node.js 18.x or higher
• TypeScript 5.x
• Optional: Docker for services

Development Workflow

# Install dependencies
npm install

# Watch mode for development
npm run watch

# Run tests
npm test

# Check dependencies
npm run check-deps

Services Integration

Qdrant Vector Database

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

Ollama (Local LLM)

ollama serve
ollama pull rjmalagon/gte-qwen2-1.5b-instruct-embed-f16

Claude API

Set your API key in the .env file for enhanced analysis capabilities.

Technical Highlights

This project demonstrates modern software engineering practices including:

• TypeScript: Fully typed codebase with strict compilation
• Vector Databases: Qdrant integration for semantic search
• AI Integration: LLM-powered code analysis with fallback mechanisms
• Modular Architecture: Clean separation of concerns with dependency injection
• Progressive Enhancement: Graceful degradation when services are unavailable
• MCP Protocol: Standards-compliant Model Context Protocol implementation

Contributing

This is a portfolio/demonstration project showcasing advanced AI-powered code analysis techniques. See Development Guide for detailed technical information.

License

MIT License - see LICENSE file for details.

---

Status

✅ Production Ready - All TypeScript compilation errors resolved
✅ MCP Integration - Fully functional Model Context Protocol server
✅ Vector Storage - Qdrant integration with robust error handling
✅ Progressive Enhancement - Works with or without external AI services

Recent Updates

• Fixed all TypeScript compilation issues
• Updated Qdrant client integration to latest API
• Implemented robust error handling and retry logic
• Added comprehensive test coverage
• ES modules fully operational

Note: This is a portfolio/demo project demonstrating modern approaches to semantic code analysis using vector embeddings and large language models.