Branch Thinking MCP Server

Instructions

Implementation Reference

• src/index.ts:137-225 (registration)

  Tool object definition registering 'branch-thinking' with detailed description and comprehensive input schema supporting thoughts, commands, insights, and cross-references.

  const BRANCHING_THOUGHT_TOOL: Tool = {
    name: "branch-thinking",
    description: `A tool for managing multiple branches of thought with insights and cross-references.
    
  Each thought can:
  - Belong to a specific branch
  - Generate insights
  - Create cross-references to other branches
  - Include confidence scores and key points
  
  The system tracks:
  - Branch priorities and states
  - Relationships between thoughts
  - Accumulated insights
  - Cross-branch connections
  
  Commands:
  - list: Show all branches and their status
  - focus [branchId]: Switch focus to a specific branch
  - history [branchId?]: Show the history of thoughts in a branch (uses active branch if none specified)`,
    inputSchema: {
      type: "object",
      properties: {
        content: {
          type: "string",
          description: "The thought content"
        },
        branchId: {
          type: "string",
          description: "Optional: ID of the branch (generated if not provided)"
        },
        parentBranchId: {
          type: "string",
          description: "Optional: ID of the parent branch"
        },
        type: {
          type: "string",
          description: "Type of thought (e.g., 'analysis', 'hypothesis', 'observation')"
        },
        confidence: {
          type: "number",
          description: "Optional: Confidence score (0-1)"
        },
        keyPoints: {
          type: "array",
          items: { type: "string" },
          description: "Optional: Key points identified in the thought"
        },
        relatedInsights: {
          type: "array",
          items: { type: "string" },
          description: "Optional: IDs of related insights"
        },
        crossRefs: {
          type: "array",
          items: {
            type: "object",
            properties: {
              toBranch: { type: "string" },
              type: { type: "string" },
              reason: { type: "string" },
              strength: { type: "number" }
            }
          },
          description: "Optional: Cross-references to other branches"
        },
        command: {
          type: "object",
          description: "Optional: Navigation command",
          properties: {
            type: {
              type: "string",
              enum: ["list", "focus", "history"],
              description: "Command type"
            },
            branchId: {
              type: "string",
              description: "Branch ID for commands that require it"
            }
          },
          required: ["type"]
        }
      },
      anyOf: [
        { required: ["content", "type"] },
        { required: ["command"] }
      ]
    }
  };

• src/index.ts:17-61 (handler)

  Core handler function processThought that processes tool inputs: handles commands or adds new thoughts to branches, generates status response, and manages errors.

  processThought(input: unknown): { content: Array<{ type: string; text: string }>; isError?: boolean } {
    try {
      const inputData = input as any;
      
      // Handle commands if present
      if (inputData.command) {
        return this.handleCommand(inputData.command);
      }
  
      // Handle regular thought input
      const thoughtInput = input as BranchingThoughtInput;
      const thought = this.branchManager.addThought(thoughtInput);
      const branch = this.branchManager.getBranch(thought.branchId)!;
      
      // Format the response with the branch status
      const formattedStatus = this.branchManager.formatBranchStatus(branch);
      console.error(formattedStatus); // Display in the console
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            thoughtId: thought.id,
            branchId: thought.branchId,
            branchState: branch.state,
            branchPriority: branch.priority,
            numInsights: branch.insights.length,
            numCrossRefs: branch.crossRefs.length,
            activeBranch: this.branchManager.getActiveBranch()?.id
          }, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            status: 'failed'
          }, null, 2)
        }],
        isError: true
      };
    }
  }

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

  MCP CallTool request handler that routes 'branch-thinking' tool calls to the processThought implementation.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === "branch-thinking") {
      return thinkingServer.processThought(request.params.arguments);
    }
  
    return {
      content: [{
        type: "text",
        text: `Unknown tool: ${request.params.name}`
      }],
      isError: true
    };
  });

• src/index.ts:241-243 (registration)

  Registers the 'branch-thinking' tool for listing in MCP ListTools requests.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [BRANCHING_THOUGHT_TOOL],
  }));

• src/branchManager.ts:71-121 (helper)

  Key helper method implementing branch creation, thought addition, insight generation, cross-reference management, and metric updates.

  addThought(input: BranchingThoughtInput): ThoughtData {
    // Use active branch if no branchId provided
    const branchId = input.branchId || this.activeBranchId || this.generateId('branch');
    let branch = this.branches.get(branchId);
  
    if (!branch) {
      branch = this.createBranch(branchId, input.parentBranchId);
    }
  
    const thought: ThoughtData = {
      id: `thought-${++this.thoughtCounter}`,
      content: input.content,
      branchId: branch.id,
      timestamp: new Date(),
      metadata: {
        type: input.type,
        confidence: input.confidence || 1.0,
        keyPoints: input.keyPoints || []
      }
    };
  
    branch.thoughts.push(thought);
  
    // Create insights if key points are provided
    if (input.keyPoints) {
      const insight = this.createInsight(
        'observation',
        `Identified key points: ${input.keyPoints.join(', ')}`,
        [input.type],
        input.relatedInsights
      );
      branch.insights.push(insight);
    }
  
    // Create cross references if specified
    if (input.crossRefs) {
      input.crossRefs.forEach(ref => {
        const crossRef = this.createCrossReference(
          branch!.id,
          ref.toBranch,
          ref.type,
          ref.reason,
          ref.strength
        );
        branch!.crossRefs.push(crossRef);
      });
    }
  
    this.updateBranchMetrics(branch);
    return thought;
  }