MCP Dual-Cycle Reasoner

Instructions

Implementation Reference

• src/server.ts:541-586 (handler)

  The execute handler for the 'retrieve_similar_cases' tool. It validates input using the schema, retrieves the session's DualCycleEngine, calls getSimilarCases on it with filters, simplifies the result by removing internal fields, and returns JSON.
  execute: async (args, { log, reportProgress, session }) => { try { const sessionEngine = this.getSessionEngine(session); const sessionId = this.sessionIds.get(session); const validatedArgs = RetrieveSimilarCasesInputSchema.parse(args); log.info('Retrieving similar cases', { problemDescription: validatedArgs.problem_description, maxResults: validatedArgs.max_results, sessionId, }); await reportProgress({ progress: 0, total: 2 }); const filters = { context_filter: validatedArgs.context_filter, difficulty_filter: validatedArgs.difficulty_filter, outcome_filter: validatedArgs.outcome_filter, min_similarity: validatedArgs.min_similarity, }; const result = await sessionEngine.getSimilarCases( validatedArgs.problem_description, validatedArgs.max_results, filters ); await reportProgress({ progress: 2, total: 2 }); log.info('Similar cases retrieved', { casesFound: result.length, maxResults: validatedArgs.max_results, }); const simplifiedResult = result.map((caseItem: any) => { const { semantic_features, similarity_metrics, ...rest } = caseItem; return rest; }); return JSON.stringify(simplifiedResult, null, 2); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log.error('Failed to retrieve similar cases', { error: errorMessage }); throw new UserError(`Failed to retrieve similar cases: {errorMessage}`); } },
• src/server.ts:527-588 (registration)

  The registration of the 'retrieve_similar_cases' tool using FastMCP's addTool method within addRetrieveSimilarCasesTool().
  this.server.addTool({ name: 'retrieve_similar_cases', description: 'Retrieve similar cases from the case base', parameters: z.object({ problem_description: z.string().describe(DESCRIPTIONS.PROBLEM_DESCRIPTION), max_results: z.number().optional().default(5).describe(DESCRIPTIONS.MAX_RESULTS), }), annotations: { title: 'Retrieve Similar Cases', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, execute: async (args, { log, reportProgress, session }) => { try { const sessionEngine = this.getSessionEngine(session); const sessionId = this.sessionIds.get(session); const validatedArgs = RetrieveSimilarCasesInputSchema.parse(args); log.info('Retrieving similar cases', { problemDescription: validatedArgs.problem_description, maxResults: validatedArgs.max_results, sessionId, }); await reportProgress({ progress: 0, total: 2 }); const filters = { context_filter: validatedArgs.context_filter, difficulty_filter: validatedArgs.difficulty_filter, outcome_filter: validatedArgs.outcome_filter, min_similarity: validatedArgs.min_similarity, }; const result = await sessionEngine.getSimilarCases( validatedArgs.problem_description, validatedArgs.max_results, filters ); await reportProgress({ progress: 2, total: 2 }); log.info('Similar cases retrieved', { casesFound: result.length, maxResults: validatedArgs.max_results, }); const simplifiedResult = result.map((caseItem: any) => { const { semantic_features, similarity_metrics, ...rest } = caseItem; return rest; }); return JSON.stringify(simplifiedResult, null, 2); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log.error('Failed to retrieve similar cases', { error: errorMessage }); throw new UserError(`Failed to retrieve similar cases: {errorMessage}`); } }, }); }
• src/types.ts:160-170 (schema)

  Zod schema for validating input parameters to the retrieve_similar_cases tool.
  export const RetrieveSimilarCasesInputSchema = z.object({ problem_description: z.string().describe(DESCRIPTIONS.PROBLEM_DESCRIPTION), max_results: z.number().default(5).describe(DESCRIPTIONS.MAX_RESULTS), context_filter: z.string().optional().describe('Filter cases by context'), difficulty_filter: z .enum(['low', 'medium', 'high']) .optional() .describe('Filter cases by difficulty level'), outcome_filter: z.boolean().optional().describe('Filter cases by outcome (success/failure)'), min_similarity: z.number().min(0).max(1).optional().describe('Minimum similarity threshold'), });
• src/dual-cycle-engine.ts:234-250 (helper)

  Wrapper method in DualCycleEngine that delegates to Adjudicator's retrieveSimilarCases.
  async getSimilarCases( problemDescription: string, maxResults: number = 5, filters: { context_filter?: string; difficulty_filter?: 'low' | 'medium' | 'high'; outcome_filter?: boolean; min_similarity?: number; } = {} ): Promise<Case[]> { return await this.adjudicator.retrieveSimilarCases( problemDescription, maxResults, filters, this.sessionId ); }
• src/adjudicator.ts:122-239 (helper)

  Core implementation in Adjudicator class performing semantic feature extraction, filtering, enhanced similarity calculation (semantic + traditional NLP), sorting, and fallback retrieval.
  async retrieveSimilarCases( problemDescription: string, maxResults: number = 5, filters: { context_filter?: string; difficulty_filter?: 'low' | 'medium' | 'high'; outcome_filter?: boolean; min_similarity?: number; } = {}, sessionId?: string ): Promise<Case[]> { if (!this.isInitialized) { await this.initialize(); } try { // Check if semantic analyzer is available if (!semanticAnalyzer.isReady()) { throw new Error('SemanticAnalyzer is not ready'); } // Extract semantic features from the query const queryFeatures = await semanticAnalyzer.extractSemanticFeatures( problemDescription, this.semanticIntents ); // Filter cases based on provided filters let filteredCases = this.caseBase; if (filters.context_filter) { filteredCases = filteredCases.filter( (case_) => case_.context?.includes(filters.context_filter!) || case_.problem_description.includes(filters.context_filter!) ); } if (filters.difficulty_filter) { filteredCases = filteredCases.filter( (case_) => case_.difficulty_level === filters.difficulty_filter ); } if (filters.outcome_filter !== undefined) { filteredCases = filteredCases.filter((case_) => case_.outcome === filters.outcome_filter); } // Calculate enhanced similarity scores const scoredCases = await Promise.all( filteredCases.map(async (case_) => { const rawSimilarity = await this.calculateEnhancedSimilarity( problemDescription, case_.problem_description, queryFeatures, case_.semantic_features, sessionId ); return { case: case_, similarity: rawSimilarity, rawSimilarity: rawSimilarity, }; }) ); // Filter by minimum similarity threshold (more restrictive due to inflated semantic scores) const minSimilarity = filters.min_similarity || 0.6; const validCases = scoredCases.filter((item) => item.similarity >= minSimilarity); // Sort by similarity and success rate const sortedCases = validCases.sort((a, b) => { // Primary sort by similarity if (Math.abs(a.similarity - b.similarity) > 0.05) { return b.similarity - a.similarity; } // Secondary sort by success rate for similar cases const aSuccessRate = a.case.success_rate || (a.case.outcome ? 1 : 0); const bSuccessRate = b.case.success_rate || (b.case.outcome ? 1 : 0); return bSuccessRate - aSuccessRate; }); // Update usage statistics and calculate dynamic confidence/validation scores const results = sortedCases.slice(0, maxResults); results.forEach((item) => { item.case.usage_count = (item.case.usage_count || 0) + 1; // Calculate dynamic confidence score based on similarity to query // Higher similarity = higher confidence in the match const similarityConfidence = Math.min(1.0, item.rawSimilarity * 1.2); // Boost good similarities const usageBonus = Math.min(0.1, (item.case.usage_count || 0) * 0.02); const outcomeBonus = item.case.outcome ? 0.1 : 0; // Dynamic confidence score reflecting match quality item.case.confidence_score = Math.max( 0, Math.min(1, similarityConfidence + usageBonus + outcomeBonus) ); // Add similarity metrics to the case for reference item.case.similarity_metrics = { ...item.case.similarity_metrics, raw_similarity: item.rawSimilarity, combined_similarity: item.rawSimilarity, }; }); return results.map((item) => item.case); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error( 'Error retrieving similar cases, falling back to simple matching:', errorMessage ); // Fallback to simple similarity matching return this.fallbackRetrieveSimilarCases(problemDescription, maxResults); } }