Think MCP

Instructions

Implementation Reference

• src/services/thinking.service.ts:186-371 (handler)

  The core handler function processThought in ThinkingService that executes the logic for the 'think' tool. Handles validation, branching, stagnation detection, coaching nudges, quick extensions, dead-end warnings, and returns progress information.
  processThought(input: ThoughtInput): ThinkingResult { // Smart auto-reset: if thoughtNumber=1 and history not empty, start fresh session // SYNCHRONOUS reset to avoid race conditions if (input.thoughtNumber === 1 && this.thoughtHistory.length > 0 && !input.isRevision) { console.error('🔄 New session detected (thought #1), clearing previous state...'); this.reset(); // Synchronous clear // Clear persistence file asynchronously (non-blocking) this.clearSession().catch((err) => console.error('Failed to clear session:', err)); } // Generate new sessionId for first thought of session (v2.11.0) if (input.thoughtNumber === 1 && !input.isRevision) { this.currentSessionId = new Date().toISOString(); console.error(`🆔 New session ID: ${this.currentSessionId}`); } // Auto-adjust totalThoughts if exceeded if (input.thoughtNumber > input.totalThoughts) { input.totalThoughts = input.thoughtNumber; } // EMPTY THOUGHT VALIDATION - reject meaningless input if (!input.thought || !input.thought.trim()) { return { thoughtNumber: input.thoughtNumber, totalThoughts: input.totalThoughts, nextThoughtNeeded: true, branches: Array.from(this.branches.keys()), thoughtHistoryLength: this.thoughtHistory.length, contextSummary: this.generateContextSummary(), thoughtTree: this.generateAsciiTree(), isError: true, errorMessage: '🚫 REJECTED: Empty thought. Provide meaningful content.', warning: '🚫 REJECTED: Empty thought. Provide meaningful content.', }; } // SESSION GOAL (v2.10.0) - Save goal from first thought if (input.goal && input.thoughtNumber === 1) { this.sessionGoal = input.goal; console.error(`🎯 Session goal set: ${input.goal.substring(0, 50)}...`); } // HARD DUPLICATE REJECTION - reject before adding to history const duplicateError = this.checkDuplicateStrict(input); if (duplicateError) { return { thoughtNumber: input.thoughtNumber, totalThoughts: input.totalThoughts, nextThoughtNeeded: true, branches: Array.from(this.branches.keys()), thoughtHistoryLength: this.thoughtHistory.length, contextSummary: this.generateContextSummary(), thoughtTree: this.generateAsciiTree(), isError: true, errorMessage: duplicateError, warning: duplicateError, }; } // BRANCH VALIDATION - reject if branchFromThought references non-existent thought const branchError = this.validateBranchSource(input); if (branchError) { return { thoughtNumber: input.thoughtNumber, totalThoughts: input.totalThoughts, nextThoughtNeeded: true, branches: Array.from(this.branches.keys()), thoughtHistoryLength: this.thoughtHistory.length, contextSummary: this.generateContextSummary(), thoughtTree: this.generateAsciiTree(), isError: true, errorMessage: branchError, warning: branchError, }; } // Validate sequence (includes shallow/circular revision check) const validation = this.validateSequence(input); // HARD REJECTION for invalid revisions (shallow, circular, non-existent target) if (!validation.valid && input.isRevision) { return { thoughtNumber: input.thoughtNumber, totalThoughts: input.totalThoughts, nextThoughtNeeded: true, branches: Array.from(this.branches.keys()), thoughtHistoryLength: this.thoughtHistory.length, contextSummary: this.generateContextSummary(), thoughtTree: this.generateAsciiTree(), isError: true, errorMessage: validation.warning, warning: validation.warning, }; } // Check for stagnation before adding new thought const stagnationWarning = this.detectStagnation(input.thought); // Create record with timestamp and sessionId (v2.11.0) const record: ThoughtRecord = { ...input, timestamp: Date.now(), sessionId: this.currentSessionId, }; this.thoughtHistory.push(record); this.lastThoughtNumber = input.thoughtNumber; // Invalidate Fuse index for recall_thought (v3.4.0) this.invalidateFuseIndex(); // Handle branching if (input.branchFromThought && input.branchId) { const branchHistory = this.branches.get(input.branchId) ?? []; branchHistory.push(record); this.branches.set(input.branchId, branchHistory); } // Log to stderr for debugging const prefix = input.isRevision ? '🔄 Revision' : input.branchFromThought ? '🌿 Branch' : '💭 Thought'; const confidenceStr = input.confidence ? ` [conf: ${input.confidence}/10]` : ''; console.error( `${prefix} ${input.thoughtNumber}/${input.totalThoughts}${confidenceStr}: ${input.thought.substring(0, 80)}...` ); // Save session asynchronously (fire and forget) this.saveSession().catch((err) => console.error('Failed to save session:', err)); // Combine warnings const warning = [validation.warning, stagnationWarning].filter(Boolean).join('\n'); // QUICK EXTENSION (v3.1.0) - Process inline extension if provided if (input.quickExtension) { this.processQuickExtension(input.thoughtNumber, input.quickExtension); } // LATERAL THINKING TRIGGER - check for overly linear thinking // v5.0.1: Pass isFinishing flag to show subSteps check only at end let systemAdvice = this.checkLateralThinking(!input.nextThoughtNeeded); // DEAD ENDS CHECK (v3.3.0) - Warn if heading towards rejected path const deadEndWarning = this.checkDeadEnds(input.thoughtNumber); if (deadEndWarning) { systemAdvice = systemAdvice ? `${systemAdvice}\n${deadEndWarning}` : deadEndWarning; } // PROACTIVE COACH v3.1.0 - Enhanced nudges for thought quality const coachNudges = this.generateProactiveNudges(input); if (coachNudges) { systemAdvice = systemAdvice ? `${systemAdvice}\n${coachNudges}` : coachNudges; } // PRE-CONSOLIDATION AUDIT (v2.9.2) - Quality gate before finishing if (!input.nextThoughtNeeded) { const auditAdvice = this.performPreConsolidationAudit(); if (auditAdvice) { systemAdvice = systemAdvice ? `${systemAdvice}\n${auditAdvice}` : auditAdvice; } } // v4.6.0: Generate nudge only if no other warnings/advice (avoid noise) const shouldSkipNudge = !!(warning || systemAdvice); const nudge = this.nudgeService.generateNudge(input, this.getCurrentSessionThoughts(), shouldSkipNudge); return { thoughtNumber: input.thoughtNumber, totalThoughts: input.totalThoughts, nextThoughtNeeded: input.nextThoughtNeeded, branches: Array.from(this.branches.keys()), thoughtHistoryLength: this.thoughtHistory.length, contextSummary: this.generateContextSummary(), thoughtTree: this.generateAsciiTree(), // v4.2.0: Lazy Mermaid - removed from hot path, use export_session for diagrams thoughtTreeMermaid: undefined, warning: warning || undefined, averageConfidence: this.calculateAverageConfidence(), systemAdvice, sessionGoal: this.sessionGoal, nudge, }; }
• src/index.ts:68-127 (registration)

  Registration of the 'think' tool using McpServer.registerTool, including title, description, inputSchema, and the handler callback.
  server.registerTool('think', { title: 'Think', description: THINK_DESCRIPTION, inputSchema: thinkSchema }, async (args) => { try { const result = thinkingService.processThought({ thought: args.thought as string, nextThoughtNeeded: args.nextThoughtNeeded as boolean, thoughtNumber: args.thoughtNumber as number, totalThoughts: args.totalThoughts as number, isRevision: args.isRevision as boolean | undefined, revisesThought: args.revisesThought as number | undefined, branchFromThought: args.branchFromThought as number | undefined, branchId: args.branchId as string | undefined, confidence: args.confidence as number | undefined, subSteps: args.subSteps as string[] | undefined, alternatives: args.alternatives as string[] | undefined, goal: args.goal as string | undefined, quickExtension: args.quickExtension as QuickExtension | undefined, }); if (result.isError) { return { content: [{ type: 'text' as const, text: `Error: ${result.errorMessage}` }], isError: true }; } // Progress bar const current = result.thoughtNumber; const total = result.totalThoughts; const filled = Math.round((current / total) * 10); const progressBar = '█'.repeat(filled) + '░'.repeat(10 - filled); // Status detection const hasBlocker = result.warning?.includes('BLOCKER') || result.warning?.includes('STAGNATION'); const status = hasBlocker ? 'BLOCKED' : result.warning ? 'WARNING' : 'OK'; const nearEnd = current >= total - 1; const nextAction = hasBlocker ? 'revise' : nearEnd ? 'think_done' : 'continue'; // Conditional tree - ONLY when explicitly requested const showTree = args.showTree === true; // v5.0.1: Show systemAdvice ONLY when there are real issues const conf = result.averageConfidence ?? 10; const hasRealIssue = status !== 'OK' || conf < 7; const showAdvice = hasRealIssue && result.systemAdvice; const text = [ result.sessionGoal ? `🎯 ${result.sessionGoal}\n` : '', `[${progressBar}] ${current}/${total}`, result.averageConfidence ? ` | conf: ${result.averageConfidence}/10` : '', result.warning ? `\n⚠️ ${result.warning}` : '', showTree ? `\n\n${result.thoughtTree}` : '', showAdvice ? `\n${result.systemAdvice}` : '', result.nudge ? `\n💡 ${result.nudge}` : '', `\n[${status}|next:${nextAction}]`, ].filter(Boolean).join(''); return { content: [{ type: 'text' as const, text }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error: ${error instanceof Error ? error.message : 'Unknown'}` }], isError: true }; } } );
• src/index.ts:47-66 (schema)

  Zod input schema definition for the 'think' tool parameters.
  const thinkSchema = { thought: z.string().describe('Your thinking step'), nextThoughtNeeded: z.boolean().describe('More thinking needed?'), thoughtNumber: z.number().int().min(1).describe('Current number'), totalThoughts: z.number().int().min(1).describe('Estimated total'), confidence: z.number().min(1).max(10).optional().describe('Confidence 1-10'), subSteps: z.array(z.string()).max(5).optional().describe('Micro-actions (max 5)'), alternatives: z.array(z.string()).max(5).optional().describe('Options to compare'), goal: z.string().optional().describe('Session goal (set on first thought)'), quickExtension: z.object({ type: z.enum(['critique', 'elaboration', 'correction', 'alternative_scenario', 'assumption_testing', 'innovation', 'optimization', 'polish']), content: z.string(), impact: z.enum(['low', 'medium', 'high', 'blocker']).optional(), }).optional().describe('Inline extension (replaces extend_thought)'), isRevision: z.boolean().optional().describe('Revising previous thought?'), revisesThought: z.number().int().min(1).optional().describe('Which thought to revise'), branchFromThought: z.number().int().min(1).optional().describe('Branch point'), branchId: z.string().optional().describe('Branch identifier'), showTree: z.boolean().optional().describe('Show ASCII tree'), };