Ultra MCP

Instructions

Implementation Reference

• src/handlers/vector.ts:36-84 (handler)

  Main handler function for the 'index-vectors' tool. Sets up configuration, embedding provider, checks for existing vectors, calls indexProject helper, and formats the response.
  export async function handleIndexVectors(args: IndexVectorsInput): Promise<string> { const configManager = new ConfigManager(); const config = await configManager.getConfig(); logger.log('Starting vector indexing...'); try { // Get embedding provider let provider: EmbeddingProvider; if (args.provider) { provider = new EmbeddingProvider({ provider: args.provider }, configManager); } else { provider = await getDefaultEmbeddingProvider(configManager); } // Get current vector count const currentCount = await getVectorCount(args.path); if (currentCount > 0 && !args.force) { return `Found ${currentCount} existing vectors. Use force=true to re-index.`; } // Index the project const messages: string[] = []; const result = await indexProject({ projectPath: args.path, provider, config: config.vectorConfig || VectorConfigSchema.parse({}), force: args.force, onProgress: (message) => { messages.push(message); logger.log(message); }, }); const totalCount = await getVectorCount(args.path); return `Indexing complete! Files indexed: ${result.filesIndexed} Chunks created: ${result.chunksCreated} Time: ${(result.timeMs / 1000).toFixed(1)}s Total vectors: ${totalCount} Progress: ${messages.join('\n')}`; } catch (error) { logger.error('Vector indexing failed:', error); throw new Error(`Indexing failed: ${error instanceof Error ? error.message : String(error)}`); } }
• src/handlers/vector.ts:10-15 (schema)

  Zod input schema defining parameters for the index-vectors tool: path, provider, and force flag.
  // Input schema for index-vectors tool export const IndexVectorsSchema = z.object({ path: z.string().default(process.cwd()), provider: z.enum(['openai', 'azure', 'gemini']).optional(), force: z.boolean().default(false), });
• src/server.ts:445-465 (registration)

  Tool registration in the MCP server, specifying title, description, schema, and handler wrapper that imports and calls handleIndexVectors.
  // Register vector indexing tools server.registerTool("index-vectors", { title: "Index Vectors", description: "Index project files for semantic search using vector embeddings", inputSchema: IndexVectorsSchema.shape, }, async (args) => { const { handleIndexVectors } = await import("./handlers/vector"); const result = await handleIndexVectors({ path: args.path || process.cwd(), provider: args.provider, force: args.force || false, }); return { content: [ { type: "text", text: result } ] }; });
• src/vector/indexer.ts:27-203 (helper)

  Core helper function implementing the vector indexing logic: scans files, splits into chunks, generates embeddings using the provider, and stores in vector database with deduplication and batching.
  export async function indexProject(options: IndexingOptions): Promise<IndexingResult> { const startTime = Date.now(); const { projectPath, provider, config, force = false, onProgress } = options; onProgress?.('Initializing vector database...'); const { db, client } = await getVectorDB(projectPath); // Update .gitignore if needed await updateGitignore(projectPath); // Get files to index onProgress?.('Scanning project files...'); const files = await getFilesToIndex(projectPath, config.filePatterns); if (files.length === 0) { logger.warn('No files found to index'); return { filesIndexed: 0, chunksCreated: 0, timeMs: Date.now() - startTime }; } onProgress?.(`Found ${files.length} files to process`); // Create text splitter const splitter = new RecursiveCharacterTextSplitter({ chunkSize: config.chunkSize, chunkOverlap: config.chunkOverlap, }); let filesIndexed = 0; let chunksCreated = 0; // Process files in batches for (let i = 0; i < files.length; i += config.batchSize) { const batch = files.slice(i, i + config.batchSize); const batchChunks: Array<{ id: string; relpath: string; chunk: string; hash: string; mtimeMs: number; embedding?: number[]; }> = []; // Process batch for (const filePath of batch) { try { const relPath = relative(projectPath, filePath); const stats = await stat(filePath); const content = await readFile(filePath, 'utf-8'); // Skip empty files if (!content.trim()) continue; // Split into chunks const chunks = await splitter.splitText(content); for (let idx = 0; idx < chunks.length; idx++) { const chunk = chunks[idx]; const id = `${relPath}#${idx}`; const hash = createHash('sha256').update(chunk).digest('hex'); // Check if chunk already exists with same hash if (!force) { const result = await client.execute({ sql: `SELECT hash, mtime_ms FROM vector_chunks WHERE id = ?`, args: [id] }); if (result.rows.length > 0) { const row = result.rows[0]; const existing = { hash: row[0] as string, mtime_ms: row[1] as number }; if (existing.hash === hash && existing.mtime_ms === stats.mtimeMs) { continue; // Skip unchanged chunk } } } batchChunks.push({ id, relpath: relPath, chunk, hash, mtimeMs: stats.mtimeMs, }); } filesIndexed++; } catch (error) { logger.error(`Error processing file ${filePath}:`, error); } } // Generate embeddings for batch if (batchChunks.length > 0) { onProgress?.(`Generating embeddings for batch ${Math.floor(i / config.batchSize) + 1}...`); try { const texts = batchChunks.map(c => c.chunk); const embeddings = await provider.getEmbeddings(texts); // Store chunks with embeddings (dual-table approach) for (let j = 0; j < batchChunks.length; j++) { const chunk = batchChunks[j]; const embedding = embeddings[j]; // Validate embedding dimensions if (embedding.length !== 1536) { logger.warn(`Embedding dimension mismatch for ${chunk.id}: expected 1536, got ${embedding.length}`); continue; } try { // 1. Insert/update metadata in main table const result = await client.execute({ sql: `INSERT OR REPLACE INTO vector_chunks (id, relpath, chunk, hash, mtime_ms) VALUES (?, ?, ?, ?, ?)`, args: [ chunk.id, chunk.relpath, chunk.chunk, chunk.hash, chunk.mtimeMs, ] }); // 2. Get the rowid for linking const rowidResult = await client.execute({ sql: `SELECT rowid FROM vector_chunks WHERE id = ?`, args: [chunk.id] }); if (rowidResult.rows.length > 0) { const rowid = rowidResult.rows[0][0] as number; // 3. Try to insert into VSS virtual table try { // VSS requires DELETE before INSERT for updates await client.execute({ sql: `DELETE FROM vss_vectors WHERE rowid = ?`, args: [rowid] }); await client.execute({ sql: `INSERT INTO vss_vectors (rowid, embedding) VALUES (?, ?)`, args: [rowid, new Float32Array(embedding).buffer] }); } catch (vssError) { // VSS not available, fallback to adding embedding to main table await client.execute({ sql: `UPDATE vector_chunks SET embedding = ? WHERE id = ?`, args: [float32ArrayToBuffer(embedding), chunk.id] }); } chunksCreated++; } } catch (error) { logger.error(`Error storing chunk ${chunk.id}:`, error); } } } catch (error) { logger.error('Error generating embeddings:', error); throw error; } } onProgress?.(`Processed ${Math.min(i + config.batchSize, files.length)} / ${files.length} files`); } const timeMs = Date.now() - startTime; onProgress?.(`Indexing complete: ${filesIndexed} files, ${chunksCreated} chunks in ${(timeMs / 1000).toFixed(1)}s`); return { filesIndexed, chunksCreated, timeMs }; }