MCP Tool Interface

Relevant source files

The following files were used as context for generating this wiki page:

• mcp_tools.py
• main.py
• session_manager.py
• README.md
• tests/test_mcp_tools.py
• memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md

The MCP Tool Interface provides a structured gateway for AI agents to interact with the reasoning and memory systems of the Sequential Thinking server. It translates Model Context Protocol (MCP) requests into internal business logic for managing thoughts, memories, and session persistence.

This interface consists of 12 distinct tools that manage the lifecycle of a structured thinking process. The MCPToolsHandler class acts as the primary adapter between the transport layer and the UnifiedSessionManager.

Sources: main.py:15-187, mcp_tools.py:11-14, README.md:144-150

Architecture Overview

The system employs a 5-layer architecture to process tool calls. Communication begins at the stdio_server transport and terminates at the markdown storage layer.

This diagram illustrates the flow of data from an external agent request through the system layers to final disk persistence.

Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:32-35, main.py:190-209

Component Responsibilities

• main.py: Defines the JSON-RPC tool schemas and dispatches incoming call_tool requests using Python's hasattr and getattr functions.
• mcp_tools.py: Wraps session manager methods to provide consistent JSON responses and top-level error catching.
• session_manager.py: Executes core logic, manages the active session state, and performs file I/O operations in the memory-bank/ directory.

Sources: main.py:190-209, mcp_tools.py:11-14, README.md:144-150

Tool Definitions and Schemas

The interface exposes 12 tools organized by their primary function: session control, reasoning management, and knowledge persistence.

Tool Name	Description	Key Inputs
start_session	Initializes a new reasoning thread.	problem, success_criteria, session_type
add_thought	Records a discrete step in the reasoning chain.	content, confidence, branch_id
create_branch	Forks reasoning into an alternative path.	name, from_thought, purpose
merge_branch	Joins a reasoning branch back to the main thread.	branch_id, target_thought
store_memory	Persists durable knowledge or code snippets.	content, code_snippet, tags
query_memories	Searches stored memories with filtering.	tags, content_contains
record_decision	Documents an architecture decision (ADR).	decision_title, chosen_option, rationale
explore_packages	Identifies relevant libraries for a task.	task_description, language
export_session	Generates Markdown or JSON summary files.	filename, format, export_type
list_sessions	Returns a list of all existing sessions.	N/A
load_session	Restores a session from the registry.	session_id
analyze_session	Provides metrics on session completeness.	N/A

Sources: main.py:17-187, mcp_tools.py:15-144

Request Execution Flow

When a tool is called, the server follows a strict execution path to ensure data integrity and proper response formatting.

The sequence diagram shows how internal persistence is triggered before the result returns to the calling agent.

Sources: main.py:190-209, mcp_tools.py:15-144, session_manager.py:53-125

Input Validation

The interface validates inputs at multiple levels:

1. JSON Schema: main.py enforces required fields (e.g., problem for start_session).
2. Logic Validation: mcp_tools.py checks for specific values like format in export_session.
3. State Validation: UnifiedSessionManager raises NoActiveSessionError if a tool requiring a session is called without one.

Sources: main.py:17-187, mcp_tools.py:118-128, session_manager.py:133-134

Error Handling

The interface implements a robust error hierarchy to prevent server crashes and provide actionable feedback to agents.

• Catch-all Wrapper: main.py wraps tool calls in a try/except block and returns errors as JSON strings.
• Typed Exceptions: The system uses specific exceptions such as ValidationError, SessionNotFoundError, and BranchError.
• Graceful Degradation: If package exploration fails during thought addition, the system logs a warning but continues with the reasoning step.

Sources: main.py:190-209, mcp_tools.py:11-14, session_manager.py:149-152, tests/test_mcp_tools.py:44-55

Implementation Example: add_thought

The add_thought implementation demonstrates the coordination between input handling, logic, and package discovery.

# mcp_tools.py:38-54
def add_thought(self, content, branch_id="", confidence=0.8, dependencies="", explore_packages=False):
    try:
        thought_id = self.session_manager.add_thought(
            content, branch_id, confidence, dependencies, explore_packages
        )
        return {
            "thought_id": thought_id,
            "content": content,
            "confidence": confidence,
            "branch_id": branch_id,
            "explore_packages": explore_packages,
        }
    except Exception as e:
        return {"error": str(e)}

Sources: mcp_tools.py:38-54

Summary

The MCP Tool Interface acts as the primary interaction layer for the Sequential Thinking server. It translates complex reasoning tasks into a set of 12 standard tools that manage sessions, logic branches, and memory storage. By utilizing a layered architecture and markdown-based persistence, it ensures that every reasoning step performed by an agent is validated and durably stored.