mcp_troubleshooting - thesavant42/retrorecon GitHub Wiki
This document provides guidance on troubleshooting Model Context Protocol (MCP) server issues within the RetroRecon application. The default setup uses the fetch-mcp
Node module as an SSE service for web content retrieval.
RetroRecon integrates an MCP server directly within its Flask application via the RetroReconMCPServer
class in retrorecon/mcp/server.py
. Earlier versions attempted to mount additional FastMCP servers, but this feature has been removed. The built-in server still handles SQL queries and a simple time function.
Key observations from the codebase:
-
RetroReconMCPServer
: This class (inretrorecon/mcp/server.py
) acts as RetroRecon's internal MCP server. It includes tools for_query_sqlite
,_get_current_datetime
, and_fetch_url_content
. -
MCPConfig
: Defined inretrorecon/mcp/config.py
, this dataclass holds configuration for the MCP server, includingapi_base
,model
,temperature
,row_limit
,api_key
,timeout
, andalt_api_bases
. -
External Server Configuration: Additional FastMCP servers are defined in
mcp_servers.json
(or the file specified byRETRORECON_MCP_SERVERS_FILE
).
RetroRecon relies on the fetch-mcp
package to retrieve web content. The service exposes an SSE endpoint (by default http://localhost:3000/sse
). Add an entry like the following to mcp_servers.json
and ensure the Node server is running:
[
{
"name": "fetch",
"transport": "sse",
"url": "http://localhost:3000/sse"
}
]
To the programming agent, the following recommendations are provided to address the MCP server integration issues and facilitate the addition of new servers:
Problem: The current implementation makes it difficult to ascertain why memory
and sequential-thinking
servers are not working, as there's limited visibility into their connection status or errors during tool invocation.
Recommendation: Implement robust MCP server discovery and status reporting mechanisms. This involves:
-
Active Health Checks: Periodically attempt to connect to the
api_base
of each configured MCP server and log its availability. This could be a simple HTTP GET request to the server's root or a dedicated health endpoint if the MCP server provides one. For STDIO servers, this would involve attempting to launch the process and verifying it runs without immediate errors. -
Detailed Error Logging: When an MCP server connection fails or a tool invocation returns an error, log comprehensive details, including the server's
name
,transport
type,api_base
(if applicable) orcommand
(if applicable), the specific error message, and any relevant stack traces. This will greatly aid in diagnosing issues like network accessibility, firewall blocks, incorrect server configurations, or issues with launching STDIO processes. - User Interface for Server Status: (Optional but highly recommended) Develop a simple UI within RetroRecon that displays the status of configured MCP servers (e.g., online/offline, last successful connection, last error). This would provide immediate feedback to the user about server availability.
Problem: The mcp_servers
list is hardcoded in retrorecon/mcp/config.py
and currently only supports api_base
, making it unsuitable for STDIO modules.
Recommendation: Allow for more flexible MCP server configuration that explicitly defines the transport
type and associated parameters (e.g., api_base
for HTTP/SSE, command
for STDIO). This involves:
-
Update
MCPServersConfig
: Modify theMCPServersConfig
dataclass inretrorecon/mcp/config.py
to include atransport
field (e.g.,Literal["http", "stdio", "sse"]
, defaulting tohttp
) and acommand
field (e.g.,Optional[List[str]] = None
) for STDIO servers. Theapi_base
field would then become optional and only used for HTTP/SSE transports. -
External Configuration File: Implement logic to load MCP server configurations from an external file (e.g.,
mcp_servers.json
ormcp_servers.yaml
). This file could be located in the user's data directory or a configurable path, allowing users to add or remove servers without modifying the core application code. -
Dynamic Server Registration: Allow RetroRecon to dynamically register and unregister MCP servers based on the loaded configuration and their specified
transport
type.
Problem: While RetroReconMCPServer
is a good start, integrating new external MCP servers might require repetitive code if not generalized.
Recommendation: Develop a more generic mechanism for integrating external MCP servers, capable of handling different transport types. This could involve:
-
MCP Client Abstraction: Create a clear abstraction layer for interacting with MCP clients that can dynamically select the appropriate
FastMCP.Client
transport (e.g.,HttpClient
,StdioClient
,SSEClient
) based on thetransport
field in the configuration. - Tool Discovery and Invocation: Implement a robust system for discovering tools exposed by external MCP servers and invoking them. This would involve parsing the MCP server's capabilities (e.g., via its OpenAPI schema for HTTP/SSE, or through introspection for STDIO) and dynamically creating callable functions or methods within RetroRecon.
Problem: Without clear testing procedures, it's hard to confirm if MCP servers are correctly integrated and functioning.
Recommendation: Establish clear testing and validation procedures for MCP server integration:
- Unit Tests for MCP Integration: Write unit tests that simulate connections to MCP servers (both HTTP/SSE and STDIO) and verify tool invocation. This will catch regressions and ensure that changes to the MCP integration logic do not break existing functionality.
- Integration Tests with Mock Servers: Create integration tests that use mock MCP servers to simulate various scenarios (e.g., successful tool invocation, server errors, network timeouts, process exit for STDIO). This will help ensure the robustness of the MCP integration.
-
User-Friendly Testing Tools: Provide simple, user-friendly tools or commands within RetroRecon that allow users to test the connectivity and functionality of their configured MCP servers. For example, a CLI command like
retrorecon mcp test <server_name>
could attempt to connect to a specified server and list its available tools, providing specific feedback based on the transport type.
By addressing the fundamental difference in communication mechanisms for STDIO versus HTTP/SSE MCP servers, and by implementing a more flexible and robust framework for integrating new MCP servers, RetroRecon can significantly enhance its capabilities and provide a more seamless experience for users. These improvements allow the application to interact with a wider range of data sources and services.
To help diagnose the memory
and sequential-thinking
server issues, please run the following commands in your Windows 11 Command Prompt or PowerShell and provide the output:
where basic-memory
First, you will need to modify the RetroRecon logging configuration to DEBUG
level. This typically involves finding the logging.basicConfig
call in retrorecon/__init__.py
or a similar central configuration file and changing level=logging.INFO
to level=logging.DEBUG
.
After modifying the logging level, run RetroRecon as usual and capture the console output:
.\launch_app.bat > retrorecon_debug_log.txt 2>&1
Then, please provide the retrorecon_debug_log.txt
file.