ai-debug-local-mcp
Version:
🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh
202 lines • 8.93 kB
JavaScript
import { BaseToolHandler } from '../base-handler.js';
import { LocalDebugEngine } from '../../local-debug-engine.js';
import { AIExtractionUtils } from './ai-utils.js';
export class AIVectorHandler extends BaseToolHandler {
tools = [
{
name: 'monitor_vector_search',
description: 'Monitor vector database searches and similarity queries',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Debug session ID' },
database: { type: 'string', description: 'Filter by database (e.g., Pinecone, pgvector)' }
},
required: ['sessionId']
}
},
{
name: 'monitor_retrieval_quality',
description: 'Analyze the quality and relevance of retrieved documents in vector search results',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Debug session ID' },
scoreThreshold: { type: 'number', description: 'Quality threshold (0-1)', default: 0.8 }
},
required: ['sessionId']
}
}
];
async handle(toolName, args, sessions) {
const session = sessions.get(args.sessionId);
if (!session) {
return {
content: [{ type: 'text', text: `Session not found: ${args.sessionId}` }]
};
}
try {
switch (toolName) {
case 'monitor_vector_search':
return await this.monitorVectorSearch(args, session);
case 'monitor_retrieval_quality':
return await this.monitorRetrievalQuality(args, session);
default:
throw new Error(`Unknown tool: ${toolName}`);
}
}
catch (error) {
return {
content: [{
type: 'text',
text: `Error in ${toolName}: ${error instanceof Error ? error.message : String(error)}`
}]
};
}
}
async monitorVectorSearch(args, session) {
const engine = session.engine || new LocalDebugEngine();
const networkRequests = engine.getNetworkRequests();
const vectorSearches = AIExtractionUtils.extractVectorSearches(networkRequests);
const filteredSearches = args.database
? vectorSearches.filter(search => search.database === args.database)
: vectorSearches;
if (filteredSearches.length === 0) {
return {
content: [{
type: 'text',
text: '## Vector Search Monitoring\n\nNo vector searches detected.'
}]
};
}
let report = '## Vector Search Monitoring\n\n';
// Summary
report += '### Summary\n';
report += `- **Total Searches:** ${filteredSearches.length}\n`;
const avgDuration = filteredSearches.reduce((sum, s) => sum + (s.duration || 0), 0) / filteredSearches.length;
report += `- **Average Duration:** ${avgDuration.toFixed(0)}ms\n\n`;
// Individual searches
report += '### Search Details\n\n';
for (const [index, search] of filteredSearches.entries()) {
report += `#### Search ${index + 1}\n`;
report += `- **Database:** ${search.database}\n`;
report += `- **Operation:** ${search.operation}\n`;
if (search.metadata?.index) {
report += `- **Index:** ${search.metadata.index}\n`;
}
if (search.metadata?.topK) {
report += `- **Top K:** ${search.metadata.topK}\n`;
}
if (search.metadata?.resultCount !== undefined) {
report += `- **Results Returned:** ${search.metadata.resultCount}\n`;
}
if (search.metadata?.bestScore !== undefined) {
report += `- **Best Score:** ${search.metadata.bestScore}\n`;
}
if (search.duration) {
report += `- **Duration:** ${search.duration}ms\n`;
}
report += '\n';
}
return {
content: [{ type: 'text', text: report }]
};
}
async monitorRetrievalQuality(args, session) {
const engine = session.engine || new LocalDebugEngine();
const networkRequests = engine.getNetworkRequests();
const scoreThreshold = args.scoreThreshold || 0.8;
// Extract vector search results from various databases
const retrievalResults = AIExtractionUtils.extractRetrievalResults(networkRequests);
if (retrievalResults.length === 0) {
return {
content: [{
type: 'text',
text: '## Retrieval Quality Analysis\n\nNo vector search results found to analyze.'
}]
};
}
let report = '## Retrieval Quality Analysis\n\n';
// Overall statistics
let totalDocs = 0;
let totalScore = 0;
let highQualityDocs = 0;
let lowQualityDocs = 0;
retrievalResults.forEach(query => {
query.results.forEach(result => {
totalDocs++;
totalScore += result.score;
if (result.score >= scoreThreshold) {
highQualityDocs++;
}
else if (result.score < 0.5) {
lowQualityDocs++;
}
});
});
const avgScore = totalDocs > 0 ? totalScore / totalDocs : 0;
report += `### Summary\n`;
report += `- **Total Queries:** ${retrievalResults.length}\n`;
report += `- **Total Documents Retrieved:** ${totalDocs}\n`;
report += `- **High Quality (>${scoreThreshold}):** ${highQualityDocs}\n`;
report += `- **Low Quality (<0.5):** ${lowQualityDocs}\n`;
report += `- **Average Score:** ${avgScore.toFixed(3)}\n\n`;
// Quality warnings
if (avgScore < scoreThreshold) {
report += `⚠️ **Quality Warning**: Average relevance score (${avgScore.toFixed(3)}) is below threshold (${scoreThreshold})\n\n`;
}
if (lowQualityDocs > totalDocs * 0.3) {
report += `⚠️ **Poor Matches**: ${Math.round(lowQualityDocs / totalDocs * 100)}% of results have low relevance\n\n`;
}
// Distribution analysis
report += `### Quality Distribution\n\n`;
const distribution = {
excellent: 0,
good: 0,
fair: 0,
poor: 0
};
retrievalResults.forEach(query => {
query.results.forEach(result => {
if (result.score >= 0.9)
distribution.excellent++;
else if (result.score >= 0.7)
distribution.good++;
else if (result.score >= 0.5)
distribution.fair++;
else
distribution.poor++;
});
});
report += `- **Excellent (≥0.9):** ${distribution.excellent}\n`;
report += `- **Good (0.7-0.9):** ${distribution.good}\n`;
report += `- **Fair (0.5-0.7):** ${distribution.fair}\n`;
report += `- **Poor (<0.5):** ${distribution.poor}\n\n`;
// Individual query analysis
retrievalResults.forEach((query, index) => {
report += `### Query ${index + 1}\n`;
report += `- **Database:** ${query.database}\n`;
report += `- **Retrieved:** ${query.results.length} documents\n`;
const queryAvg = query.results.reduce((sum, r) => sum + r.score, 0) / query.results.length;
report += `- **Average Score:** ${queryAvg.toFixed(3)}\n`;
if (query.metadata?.topK && query.results.length < query.metadata.topK) {
report += `- ⚠️ **Warning:** Retrieved ${query.results.length} docs but requested ${query.metadata.topK}\n`;
}
report += '\n';
});
// Recommendations
report += `### Recommendations\n\n`;
if (avgScore < scoreThreshold) {
report += `1. **Improve Embeddings**: Consider using better embedding models\n`;
report += `2. **Refine Queries**: Optimize query vectors for better matches\n`;
}
if (lowQualityDocs > 0) {
report += `3. **Filter Results**: Add post-retrieval filtering for low scores\n`;
report += `4. **Expand Index**: Your index might be missing relevant documents\n`;
}
return {
content: [{ type: 'text', text: report.trim() }]
};
}
}
//# sourceMappingURL=ai-vector-handler.js.map