MCP Tools Handler

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
• memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md
• tests/test_mcp_tools.py

The MCPToolsHandler acts as the intermediary adapter between the Model Context Protocol (MCP) server interface and the underlying business logic. It translates standardized tool calls into operations for the UnifiedSessionManager and formats the results into a JSON-serializable structure for delivery to the client.

Sources: mcp_tools.py:12-14, main.py:12-14

System Architecture

The handler resides in the middle of a five-layer stack. The main.py entry point receives JSON-RPC requests via the MCP transport and dispatches them to the MCPToolsHandler. The handler then invokes methods on the UnifiedSessionManager to modify or retrieve data stored in the memory-bank/ directory.

Component Relationship

The following diagram illustrates the position of the MCPToolsHandler within the server architecture:

The diagram shows the top-down flow from the client request to the physical storage layer.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:33-40

Tool Registry and Dispatch

The system exposes 12 distinct tools to the MCP client. main.py registers these tools with specific input schemas and routes incoming calls dynamically.

Dispatch Logic

When a tool is called, the server uses hasattr(tools_handler, name) to verify the existence of a corresponding method. It then calls the method using keyword arguments derived from the MCP request.

# From main.py:155-168
@server.call_tool()
async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
    try:
        if hasattr(tools_handler, name):
            result = getattr(tools_handler, name)(**arguments)
            return [
                TextContent(type="text", text=json.dumps(result, indent=2, default=str))
            ]

Sources: main.py:155-168, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:42-49

Core Tools Table

Tool Name	Primary Function	Key Input Parameters
start_session	Initializes a reasoning context	problem, success_criteria, session_type
add_thought	Records a reasoning step	content, confidence, branch_id
create_branch	Branches for alternative logic	name, from_thought, purpose
store_memory	Persists a durable artifact	content, code_snippet, tags
query_memories	Searches existing artifacts	tags, content_contains
record_decision	Logs architectural choices	decision_title, rationale, chosen_option
export_session	Saves session to a specific file	filename, format, export_type

Sources: mcp_tools.py:16-160, main.py:20-152

Data Flow and Error Handling

The MCPToolsHandler implements a uniform error handling pattern. It wraps all calls to the session manager in try...except blocks. If an operation fails, it returns a dictionary containing an "error" key instead of allowing exceptions to propagate to the transport layer.

Sequence of Operations

The sequence diagram shows how the handler intercepts exceptions from the manager to ensure the client receives a valid JSON-RPC response.
Sources: mcp_tools.py:116-125, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:42-49

Session Export and Persistence

The handler provides specialized logic for exporting data into human-readable or machine-parsable formats. The export_session tool supports both markdown and json formats.

1. Validation: The handler validates the filename, format, and export_type before processing.
2. Path Resolution: It resolves the output path relative to the memory_bank_path.
3. Content Generation: It uses internal helper methods _export_session_content or _export_memories_content to format the data.

# From mcp_tools.py:148-154
output_path = self.session_manager.memory_bank_path / filename.strip()

if export_type == "session":
    content = self._export_session_content(format)
else:
    memories = self.session_manager.query_memories(tags, "")
    content = self._export_memories_content(memories, format)

Sources: mcp_tools.py:127-160, tests/test_mcp_tools.py:186-215

Memory Exploration and Analysis

The handler extends simple CRUD operations with analysis and discovery features:

• Package Exploration: explore_packages scans the local environment for libraries relevant to a provided task description.
• Session Analysis: analyze_session provides counts of thoughts, memories, branches, and decisions to assess the completeness of the reasoning process.
• Query Filters: query_memories supports advanced filtering using tags with Boolean operators (& for AND, | for OR) and regex patterns for content.

Sources: mcp_tools.py:116-125, session_manager.py:270-348, tests/test_mcp_tools.py:126-145

Conclusion

The MCPToolsHandler standardizes interaction with the reasoning system. By decoupling protocol dispatch from business logic, it ensures that the UnifiedSessionManager remains focused on state management and persistence while the handler manages client-facing validation, formatting, and error recovery.