mcp-reasoner

Instructions

Implementation Reference

• src/index.ts:49-83 (registration)

  Registers the 'mcp-reasoner' tool for ListTools requests, including name, description, and input schema.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [{
      name: "mcp-reasoner",
      description: "Advanced reasoning tool with multiple strategies including Beam Search and Monte Carlo Tree Search",
      inputSchema: {
        type: "object",
        properties: {
          thought: {
            type: "string",
            description: "Current reasoning step"
          },
          thoughtNumber: {
            type: "integer",
            description: "Current step number",
            minimum: 1
          },
          totalThoughts: {
            type: "integer",
            description: "Total expected steps",
            minimum: 1
          },
          nextThoughtNeeded: {
            type: "boolean",
            description: "Whether another step is needed"
          },
          strategyType: {
            type: "string",
            enum: Object.values(ReasoningStrategy),
            description: "Reasoning strategy to use (beam_search or mcts)"
          }
        },
        required: ["thought", "thoughtNumber", "totalThoughts", "nextThoughtNeeded"]
      }
    }]
  }));

• src/index.ts:86-149 (handler)

  Executes the 'mcp-reasoner' tool: validates input, delegates to Reasoner.processThought, augments response with stats and returns JSON.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== "mcp-reasoner") {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({ error: "Unknown tool", success: false })
        }],
        isError: true
      };
    }
  
    try {
      // Process and validate input
      const step = processInput(request.params.arguments);
  
      // Process thought with selected strategy
      const response = await reasoner.processThought({
        thought: step.thought,
        thoughtNumber: step.thoughtNumber,
        totalThoughts: step.totalThoughts,
        nextThoughtNeeded: step.nextThoughtNeeded,
        strategyType: step.strategyType
      });
  
      // Get reasoning stats
      const stats = await reasoner.getStats();
  
      // Return enhanced response
      const result = {
        thoughtNumber: step.thoughtNumber,
        totalThoughts: step.totalThoughts,
        nextThoughtNeeded: step.nextThoughtNeeded,
        thought: step.thought,
        nodeId: response.nodeId,
        score: response.score,
        strategyUsed: response.strategyUsed,
        stats: {
          totalNodes: stats.totalNodes,
          averageScore: stats.averageScore,
          maxDepth: stats.maxDepth,
          branchingFactor: stats.branchingFactor,
          strategyMetrics: stats.strategyMetrics
        }
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            success: false
          })
        }],
        isError: true
      };
    }
  });

• src/index.ts:25-46 (helper)

  Helper function to validate and type-coerce tool input parameters.

  function processInput(input: any) {
    const result = {
      thought: String(input.thought || ""),
      thoughtNumber: Number(input.thoughtNumber || 0),
      totalThoughts: Number(input.totalThoughts || 0),
      nextThoughtNeeded: Boolean(input.nextThoughtNeeded),
      strategyType: input.strategyType as ReasoningStrategy | undefined
    };
  
    // Validate
    if (!result.thought) {
      throw new Error("thought must be provided");
    }
    if (result.thoughtNumber < 1) {
      throw new Error("thoughtNumber must be >= 1");
    }
    if (result.totalThoughts < 1) {
      throw new Error("totalThoughts must be >= 1");
    }
  
    return result;
  }

• src/reasoner.ts:31-45 (handler)

  Core reasoning handler in Reasoner class: selects strategy and delegates processing, adds strategy info to response.

  public async processThought(request: ReasoningRequest): Promise<ReasoningResponse> {
    // Switch strategy if requested
    if (request.strategyType && this.strategies.has(request.strategyType as ReasoningStrategy)) {
      this.currentStrategy = this.strategies.get(request.strategyType as ReasoningStrategy)!;
    }
  
    // Process thought using current strategy
    const response = await this.currentStrategy.processThought(request);
  
    // Add strategy information to response
    return {
      ...response,
      strategyUsed: this.getCurrentStrategyName()
    };
  }

• src/strategies/factory.ts:11-24 (helper)

  Factory for creating reasoning strategy instances (Beam Search or MCTS) used by the Reasoner.

  export class StrategyFactory {
    static createStrategy(
      type: ReasoningStrategy,
      stateManager: StateManager
    ): BaseStrategy {
      switch (type) {
        case ReasoningStrategy.BEAM_SEARCH:
          return new BeamSearchStrategy(stateManager);
        case ReasoningStrategy.MCTS:
          return new MonteCarloTreeSearchStrategy(stateManager);
        default:
          throw new Error(`Unknown strategy type: ${type}`);
      }
    }