BioMCP

Instructions

🚨 IMPORTANT: You MUST use this tool BEFORE any search or fetch operations when:
- Researching ANY biomedical topic (genes, diseases, variants, trials)
- Planning to use multiple BioMCP tools
- Answering questions that require analysis or synthesis
- Comparing information from different sources
- Making recommendations or drawing conclusions

⚠️ FAILURE TO USE THIS TOOL FIRST will result in:
- Incomplete or poorly structured analysis
- Missing important connections between data
- Suboptimal search strategies
- Overlooked critical information

Sequential thinking ensures you:
1. Fully understand the research question
2. Plan an optimal search strategy
3. Identify all relevant data sources
4. Structure your analysis properly
5. Deliver comprehensive, well-reasoned results

## Usage Pattern:
1. Start with thoughtNumber=1 to initiate analysis
2. Progress through numbered thoughts sequentially
3. Adjust totalThoughts estimate as understanding develops
4. Set nextThoughtNeeded=False only when analysis is complete

## Example:
```python
# Initial analysis
await think(
    thought="Breaking down the relationship between BRAF mutations and melanoma treatment resistance...",
    thoughtNumber=1,
    totalThoughts=5,
    nextThoughtNeeded=True
)

# Continue analysis
await think(
    thought="Examining specific BRAF V600E mutation mechanisms...",
    thoughtNumber=2,
    totalThoughts=5,
    nextThoughtNeeded=True
)

# Final thought
await think(
    thought="Synthesizing findings and proposing research directions...",
    thoughtNumber=5,
    totalThoughts=5,
    nextThoughtNeeded=False
)
```

## Important Notes:
- Each thought builds on previous ones within a session
- State is maintained throughout the MCP session
- Use thoughtful, detailed analysis in each step
- Revisions and branching are supported through the underlying implementation

Implementation Reference

• src/biomcp/thinking_tool.py:17-122 (handler)

  The primary handler for the 'think' MCP tool. Defined with @mcp_app.tool() decorator, includes input schema via Annotated Fields with Pydantic Field descriptions, and implements the tool by calling mark_thinking_used() and _sequential_thinking().

  @mcp_app.tool()
  @track_performance("biomcp.think")
  async def think(
      thought: Annotated[
          str,
          Field(description="Current thinking step for analysis"),
      ],
      thoughtNumber: Annotated[
          int,
          Field(
              description="Current thought number, starting at 1",
              ge=1,
          ),
      ],
      totalThoughts: Annotated[
          int,
          Field(
              description="Estimated total thoughts needed for complete analysis",
              ge=1,
          ),
      ],
      nextThoughtNeeded: Annotated[
          bool,
          Field(
              description="Whether more thinking steps are needed after this one",
          ),
      ] = True,
  ) -> dict:
      """REQUIRED FIRST STEP: Perform structured sequential thinking for ANY biomedical research task.
  
      🚨 IMPORTANT: You MUST use this tool BEFORE any search or fetch operations when:
      - Researching ANY biomedical topic (genes, diseases, variants, trials)
      - Planning to use multiple BioMCP tools
      - Answering questions that require analysis or synthesis
      - Comparing information from different sources
      - Making recommendations or drawing conclusions
  
      ⚠️ FAILURE TO USE THIS TOOL FIRST will result in:
      - Incomplete or poorly structured analysis
      - Missing important connections between data
      - Suboptimal search strategies
      - Overlooked critical information
  
      Sequential thinking ensures you:
      1. Fully understand the research question
      2. Plan an optimal search strategy
      3. Identify all relevant data sources
      4. Structure your analysis properly
      5. Deliver comprehensive, well-reasoned results
  
      ## Usage Pattern:
      1. Start with thoughtNumber=1 to initiate analysis
      2. Progress through numbered thoughts sequentially
      3. Adjust totalThoughts estimate as understanding develops
      4. Set nextThoughtNeeded=False only when analysis is complete
  
      ## Example:
      ```python
      # Initial analysis
      await think(
          thought="Breaking down the relationship between BRAF mutations and melanoma treatment resistance...",
          thoughtNumber=1,
          totalThoughts=5,
          nextThoughtNeeded=True
      )
  
      # Continue analysis
      await think(
          thought="Examining specific BRAF V600E mutation mechanisms...",
          thoughtNumber=2,
          totalThoughts=5,
          nextThoughtNeeded=True
      )
  
      # Final thought
      await think(
          thought="Synthesizing findings and proposing research directions...",
          thoughtNumber=5,
          totalThoughts=5,
          nextThoughtNeeded=False
      )
      ```
  
      ## Important Notes:
      - Each thought builds on previous ones within a session
      - State is maintained throughout the MCP session
      - Use thoughtful, detailed analysis in each step
      - Revisions and branching are supported through the underlying implementation
      """
      # Mark that thinking has been used
      mark_thinking_used()
  
      result = await _sequential_thinking(
          thought=thought,
          thoughtNumber=thoughtNumber,
          totalThoughts=totalThoughts,
          nextThoughtNeeded=nextThoughtNeeded,
      )
  
      return {
          "domain": "thinking",
          "result": result,
          "thoughtNumber": thoughtNumber,
          "nextThoughtNeeded": nextThoughtNeeded,
      }

• src/biomcp/thinking/sequential.py:15-107 (helper)

  Core helper function _sequential_thinking() called by the think handler, handles validation, session management via _session_manager, creates ThoughtEntry, and returns progress status.

  async def _sequential_thinking(
      thought: Annotated[
          str, "Current thinking step - be detailed and thorough"
      ],
      nextThoughtNeeded: Annotated[
          bool, "True if more thinking needed, False only when completely done"
      ],
      thoughtNumber: Annotated[int, "Current thought number (start at 1)"],
      totalThoughts: Annotated[
          int, "Best estimate of total thoughts (adjust as needed)"
      ],
      isRevision: Annotated[
          bool, "True when correcting/improving a previous thought"
      ] = False,
      revisesThought: Annotated[
          int | None, "The thought number being revised"
      ] = None,
      branchFromThought: Annotated[
          int | None, "Create alternative path from this thought number"
      ] = None,
      needsMoreThoughts: Annotated[
          bool | None,
          "True when problem is significantly larger than initially estimated",
      ] = None,
  ) -> str:
      """
      ALWAYS use this tool for complex reasoning, analysis, or problem-solving. This facilitates a detailed, step-by-step thinking process that helps break down problems systematically.
  
      Use this tool when:
      - Analyzing complex problems or questions
      - Planning multi-step solutions
      - Breaking down tasks into components
      - Reasoning through uncertainties
      - Exploring alternative approaches
  
      Start with thoughtNumber=1 and totalThoughts as your best estimate. Set nextThoughtNeeded=true to continue thinking, or false when done. You can revise earlier thoughts or branch into alternative paths as needed.
  
      This is your primary reasoning tool - USE IT LIBERALLY for any non-trivial thinking task.
      """
  
      # Validate inputs
      if thoughtNumber < 1:
          return "Error: thoughtNumber must be >= 1"
  
      if totalThoughts < 1:
          return "Error: totalThoughts must be >= 1"
  
      if isRevision and not revisesThought:
          return "Error: revisesThought must be specified when isRevision=True"
  
      # Get or create session
      session = _session_manager.get_or_create_session()
  
      # Create thought entry
      branch_id = f"branch_{branchFromThought}" if branchFromThought else None
  
      entry = ThoughtEntry(
          thought=thought,
          thought_number=thoughtNumber,
          total_thoughts=totalThoughts,
          next_thought_needed=nextThoughtNeeded,
          is_revision=isRevision,
          revises_thought=revisesThought,
          branch_from_thought=branchFromThought,
          branch_id=branch_id,
          metadata={"needsMoreThoughts": needsMoreThoughts}
          if needsMoreThoughts
          else {},
      )
  
      # Add thought to session
      session.add_thought(entry)
  
      # Generate status message
      if branchFromThought:
          status_msg = f"Added thought {thoughtNumber} to branch '{branch_id}'"
      elif isRevision and revisesThought:
          status_msg = (
              f"Revised thought {revisesThought} (now thought {thoughtNumber})"
          )
      else:
          status_msg = f"Added thought {thoughtNumber} to main sequence"
  
      # Generate progress information
      progress_msg = f"Progress: {thoughtNumber}/{totalThoughts} thoughts"
      next_msg = (
          "Next thought needed"
          if nextThoughtNeeded
          else "Thinking sequence complete"
      )
  
      return f"{status_msg}. {progress_msg}. {next_msg}."

• src/biomcp/thinking_tracker.py:14-16 (helper)

  Helper function mark_thinking_used() called at the start of think handler to track thinking tool usage in the current context.

  def mark_thinking_used() -> None:
      """Mark that the thinking tool has been used."""
      thinking_used.set(True)

• src/biomcp/__init__.py:14-14 (registration)

  Import of the thinking_tool module, which triggers registration of the 'think' tool via its @mcp_app.tool() decorator.

  from . import thinking_tool