mcp-sequentialthinking-tools

Instructions

Implementation Reference

• src/index.ts:173-257 (handler)

  The processThought method in ToolAwareSequentialThinkingServer class implements the core execution logic for the sequentialthinking_tools: processes and validates input, manages thought history and branches, formats output with JSON status including recommendations.

  public async processThought(input: v.InferInput<typeof SequentialThinkingSchema>) {
  	try {
  		// Input is already validated by tmcp with Valibot
  		const validatedInput = input as ThoughtData;
  
  		if (
  			validatedInput.thought_number > validatedInput.total_thoughts
  		) {
  			validatedInput.total_thoughts = validatedInput.thought_number;
  		}
  
  		// Store the current step in thought history
  		if (validatedInput.current_step) {
  			if (!validatedInput.previous_steps) {
  				validatedInput.previous_steps = [];
  			}
  			validatedInput.previous_steps.push(validatedInput.current_step);
  		}
  
  		this.thought_history.push(validatedInput);
  	
  	// Prevent memory leaks by limiting history size
  	if (this.thought_history.length > this.maxHistorySize) {
  		this.thought_history = this.thought_history.slice(-this.maxHistorySize);
  		console.error(`History trimmed to ${this.maxHistorySize} items`);
  	}
  
  		if (
  			validatedInput.branch_from_thought &&
  			validatedInput.branch_id
  		) {
  			if (!this.branches[validatedInput.branch_id]) {
  				this.branches[validatedInput.branch_id] = [];
  			}
  			this.branches[validatedInput.branch_id].push(validatedInput);
  		}
  
  		const formattedThought = this.formatThought(validatedInput);
  		console.error(formattedThought);
  
  		return {
  			content: [
  				{
  					type: 'text' as const,
  					text: JSON.stringify(
  						{
  							thought_number: validatedInput.thought_number,
  							total_thoughts: validatedInput.total_thoughts,
  							next_thought_needed:
  								validatedInput.next_thought_needed,
  							branches: Object.keys(this.branches),
  							thought_history_length: this.thought_history.length,
  							available_mcp_tools: validatedInput.available_mcp_tools,
  							current_step: validatedInput.current_step,
  							previous_steps: validatedInput.previous_steps,
  							remaining_steps: validatedInput.remaining_steps,
  						},
  						null,
  						2,
  					),
  				},
  			],
  		};
  	} catch (error) {
  		return {
  			content: [
  				{
  					type: 'text' as const,
  					text: JSON.stringify(
  						{
  							error:
  								error instanceof Error
  									? error.message
  									: String(error),
  							status: 'failed',
  						},
  						null,
  						2,
  					),
  				},
  			],
  			isError: true,
  		};
  	}
  }

• src/schema.ts:125-182 (schema)

  Valibot schema defining the input structure for the sequentialthinking_tools, including fields for thoughts, steps, tool recommendations, branches, etc.

  export const SequentialThinkingSchema = v.object({
  	available_mcp_tools: v.pipe(
  		v.array(v.string()),
  		v.description('Array of MCP tool names available for use (e.g., ["mcp-omnisearch", "mcp-turso-cloud"])')
  	),
  	thought: v.pipe(
  		v.string(),
  		v.description('Your current thinking step')
  	),
  	next_thought_needed: v.pipe(
  		v.boolean(),
  		v.description('Whether another thought step is needed')
  	),
  	thought_number: v.pipe(
  		v.number(),
  		v.minValue(1),
  		v.description('Current thought number')
  	),
  	total_thoughts: v.pipe(
  		v.number(),
  		v.minValue(1),
  		v.description('Estimated total thoughts needed')
  	),
  	is_revision: v.optional(v.pipe(
  		v.boolean(),
  		v.description('Whether this revises previous thinking')
  	)),
  	revises_thought: v.optional(v.pipe(
  		v.number(),
  		v.minValue(1),
  		v.description('Which thought is being reconsidered')
  	)),
  	branch_from_thought: v.optional(v.pipe(
  		v.number(),
  		v.minValue(1),
  		v.description('Branching point thought number')
  	)),
  	branch_id: v.optional(v.pipe(
  		v.string(),
  		v.description('Branch identifier')
  	)),
  	needs_more_thoughts: v.optional(v.pipe(
  		v.boolean(),
  		v.description('If more thoughts are needed')
  	)),
  	current_step: v.optional(v.pipe(
  		StepRecommendationSchema,
  		v.description('Current step recommendation')
  	)),
  	previous_steps: v.optional(v.pipe(
  		v.array(StepRecommendationSchema),
  		v.description('Steps already recommended')
  	)),
  	remaining_steps: v.optional(v.pipe(
  		v.array(v.string()),
  		v.description('High-level descriptions of upcoming steps')
  	))
  });

• src/index.ts:272-281 (registration)

  MCP server.tool registration for 'sequentialthinking_tools', providing name, description from schema export, input schema, and handler delegating to processThought.

  server.tool(
  	{
  		name: 'sequentialthinking_tools',
  		description: SEQUENTIAL_THINKING_TOOL.description,
  		schema: SequentialThinkingSchema,
  	},
  	async (input) => {
  		return thinkingServer.processThought(input);
  	},
  );

• src/schema.ts:184-188 (schema)

  Constant definition and export of the tool metadata (name, description) used in registration.

  export const SEQUENTIAL_THINKING_TOOL: Tool = {
  	name: 'sequentialthinking_tools',
  	description: TOOL_DESCRIPTION,
  	inputSchema: {} // This will be handled by tmcp with the schema above
  };

• src/index.ts:127-171 (helper)

  formatThought helper formats individual thoughts with colored prefixes, borders, and includes step recommendations for console output.

  	private formatThought(thoughtData: ThoughtData): string {
  		const {
  			thought_number,
  			total_thoughts,
  			thought,
  			is_revision,
  			revises_thought,
  			branch_from_thought,
  			branch_id,
  			current_step,
  		} = thoughtData;
  
  		let prefix = '';
  		let context = '';
  
  		if (is_revision) {
  			prefix = chalk.yellow('🔄 Revision');
  			context = ` (revising thought ${revises_thought})`;
  		} else if (branch_from_thought) {
  			prefix = chalk.green('🌿 Branch');
  			context = ` (from thought ${branch_from_thought}, ID: ${branch_id})`;
  		} else {
  			prefix = chalk.blue('💭 Thought');
  			context = '';
  		}
  
  		const header = `${prefix} ${thought_number}/${total_thoughts}${context}`;
  		let content = thought;
  
  		// Add recommendation information if present
  		if (current_step) {
  			content = `${thought}\n\nRecommendation:\n${this.formatRecommendation(current_step)}`;
  		}
  
  		const border = '─'.repeat(
  			Math.max(header.length, content.length) + 4,
  		);
  
  		return `
  ┌${border}┐
  │ ${header} │
  ├${border}┤
  │ ${content.padEnd(border.length - 2)} │
  └${border}┘`;
  	}