BioMCP

Instructions

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