MCP Server Dispatch

Relevant source files

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

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

The MCP Server Dispatch system manages the communication between the Model Context Protocol (MCP) client and the internal reasoning logic of the sequential-thinking-mcp-v2 project. It translates JSON-RPC requests from the client into specific tool executions that manage sessions, thoughts, and memories.

The system uses a layered architecture to separate protocol transport, tool registration, and business logic. The main.py file serves as the entry point, utilizing the mcp library to establish a standard I/O (stdio) server that listens for tool calls.

Sources: main.py:1-15, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:27-30, README.md:143-145

Request Lifecycle and Architecture

The dispatch process follows a 5-layer path from the external client to the internal domain models. Communication begins when an MCP client sends a JSON-RPC request over stdio. The main.py entry point acts as the dispatcher, routing these requests to the MCPToolsHandler in mcp_tools.py.

The main.py file defines the call_tool function, which uses hasattr and getattr to dynamically route requests based on the tool name provided in the arguments. If the tool exists, the MCPToolsHandler executes the logic and returns a TextContent object containing a JSON-encoded result.

Sources: main.py:192-208, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:27-30, 48-52

Component Roles

The dispatch system relies on three primary components to handle incoming requests:

Component	File	Primary Responsibility
Server Instance	main.py	Defines the MCP server name and manages the initialization options.
Tools Handler	mcp_tools.py	Acts as an adapter that translates raw tool arguments into calls for the session manager.
Session Manager	session_manager.py	Orchestrates the business logic and handles Markdown file persistence.

Sources: main.py:11-14, mcp_tools.py:14-18, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:27-30

Tool Registration and Dispatch

The server exposes 12 distinct tools to the MCP client. Each tool is registered with a name, description, and an inputSchema that defines expected JSON properties and required fields.

Dispatch Sequence

When the server receives a call_tool request:

1. main.py receives the name and arguments dictionary.
2. It verifies the existence of a corresponding method in MCPToolsHandler.
3. It calls the method, unpacking the arguments dictionary as keyword arguments (**arguments).
4. MCPToolsHandler catches potential exceptions and returns them as a JSON error object to prevent the transport layer from crashing.

Error Handling during Dispatch

The dispatch layer implements a "fail-safe" error handling strategy. Instead of allowing exceptions to propagate to the stdio transport level, main.py wraps the tool execution in a try/except block. Any caught exception is converted into a standard JSON response with an "error" key.

Inside the tools handler, specific errors such as NoActiveSessionError or ValidationError are frequently caught and returned as string messages within the result dictionary. This ensures that the MCP client receives a valid protocol response even when internal logic fails.

Sources: main.py:204-211, mcp_tools.py:177-184, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:52-55

Core Tool Definitions

The following table summarizes key tools registered by the dispatch server:

Tool Name	Purpose	Required Input
start_session	Initializes a new reasoning context.	problem, success_criteria
add_thought	Appends reasoning steps to the active session.	content
store_memory	Persists a specific insight or code snippet.	content
query_memories	Searches existing memories using tags or regex.	None (Optional tags, content_contains)
record_decision	Documents an architectural choice.	decision_title, context, chosen_option

Sources: main.py:22-189, mcp_tools.py:20-165

Summary

The MCP Server Dispatch system provides a robust interface between the Model Context Protocol and the Sequential Thinking business logic. By utilizing a dynamic routing mechanism and protective error handling, the system maintains stable communication while enabling complex reasoning operations through its 12-tool surface. All operations ultimately flow through the UnifiedSessionManager for persistence in the project's Markdown-based memory bank.