A Model Context Protocol (MCP) tool that automatically fixes common JSON-RPC validation errors in MCP containers by adding message filtering to prevent log messages from being processed as JSON-RPC requests.
To use this tool with MCP, you'll need to add it to your MCP configuration:
{
"tools": {
"json-rpc-fixer": {
"command": "node",
"args": ["/absolute/path/to/fixjson-rpc-tool.js"],
"transport": "stdio",
"env": {}
}
}
}IMPORTANT: You must use an absolute path to the tool's JS file in the args array, not in the command itself. The ENOENT error (spawn node /path/to/fixjson-rpc-tool.js ENOENT) occurs when the path is incorrectly specified as part of the command.
MCP Tool Identifier: json-rpc-fixer@1.0.0
MCP containers often encounter validation errors when log messages (with timestamp, level, and message fields) are mistakenly processed as JSON-RPC messages. This results in errors like:
Error: Invalid JSON-RPC message: message doesn't have required field 'jsonrpc'
This tool implements three key fixes:
- Transport Layer Modification: Adds message filtering logic to prevent non-JSON-RPC messages from being processed
- Dockerfile Modification: Redirects stderr to log files to prevent logging output from interfering with JSON-RPC communication
- Logger Configuration: Updates Winston logger (if used) to output to stderr for better log handling
- Automatic Detection: Analyzes your code to find the right insertion points
- Safe Execution: Creates backups of all files before modification
- Comprehensive Fixes: Handles transport layer, Dockerfile, and logger configuration
- Detailed Reporting: Provides clear success/failure messages for each component
npm installIf you want to use this tool in a Docker container, add it to your Dockerfile:
# Install the JSON-RPC Validation Error Fixer tool
COPY --from=mcp-tool-fixjson-rpc2.0 /app /usr/local/lib/mcp-tool-fixjson-rpc2.0
RUN cd /usr/local/lib/mcp-tool-fixjson-rpc2.0 && npm install
# Add to your MCP configuration or config file
# Example using a config file approach:
COPY mcp-config.json /etc/mcp/config.json
ENV MCP_CONFIG_PATH=/etc/mcp/config.json
# Inside mcp-config.json:
# {
# "tools": {
# "json-rpc-fixer": {
# "command": "node",
# "args": ["/usr/local/lib/mcp-tool-fixjson-rpc2.0/fixjson-rpc-tool.js"],
# "transport": "stdio"
# }
# }
# }This tool is designed to be used via the Model Context Protocol. You can invoke it like this:
const result = await client.callTool({
name: "fix_json_rpc_validation",
arguments: {
project_path: "/path/to/your/project",
transport_file_path: "src/utils/transport.ts", // Required
dockerfile_path: "Dockerfile", // Optional
logger_file_path: "src/utils/logger.ts" // Optional
}
});project_path: Absolute path to your MCP project roottransport_file_path: Relative path to your transport file (required)dockerfile_path: Relative path to your Dockerfile (optional)logger_file_path: Relative path to your logger configuration file (optional)
The tool adds an isJsonRpcMessage() function that performs two checks:
- Filters out objects that look like log messages (have level, message, timestamp fields)
- Verifies the message has the required JSON-RPC 2.0 structure
function isJsonRpcMessage(msg: any): boolean {
// Filter out log messages
if (msg && typeof msg === 'object' &&
('level' in msg && 'message' in msg && 'timestamp' in msg)) {
return false;
}
// Basic JSON-RPC structure check
return msg && typeof msg === 'object' &&
'jsonrpc' in msg && msg.jsonrpc === '2.0';
}The tool modifies your Dockerfile to:
- Create a logs directory:
RUN mkdir -p /app/logs - Redirect stderr to a log file:
CMD ["sh", "-c", "node dist/index.js 2>/app/logs/error.log"]
If you're using Winston, the tool updates your logger configuration to use stderr:
new winston.transports.Console({
stderr: true, // Added by the tool
format: winston.format.simple()
})The repository includes test files to verify functionality:
# Test listing the available tools
node test.js
# Test calling the fix tool on a sample project
node test-call.jsTo modify or extend this tool:
- Update the fix strategies in the helper functions
- Add new validation or fix methods as needed
- Run tests to ensure everything works as expected
If you encounter an error like: spawn node /path/to/fixjson-rpc-tool.js ENOENT
This typically happens when the command and arguments are not properly separated in the configuration. The correct format is:
{
"tools": {
"json-rpc-fixer": {
"command": "node", // Just the executable
"args": ["/absolute/path/to/fixjson-rpc-tool.js"], // Path as an argument
"transport": "stdio"
}
}
}Common mistakes to avoid:
- Don't include the path in the command string
- Always use absolute paths, not relative paths
- Make sure the file exists at the specified location and has proper permissions
- Verify that the Node.js executable is in the PATH of the environment where MCP runs
This tool was created to address a common pain point in MCP container development: log messages being misinterpreted as JSON-RPC messages.
When building MCP tools that use JSON-RPC over stdio, logging messages can inadvertently be picked up by the JSON-RPC parser. This happens because:
- Both log messages and JSON-RPC messages share the same stdio channel
- Log messages often have a valid JSON structure (with fields like timestamp, level, message)
- The JSON-RPC parser attempts to process these log messages, leading to validation errors
This tool provides an elegant solution by:
- Automatically detecting log message patterns
- Adding filtering logic at the correct points in your code
- Separating log output to stderr and redirecting it to files
By implementing this tool, we've made MCP container development more robust and less error-prone.
MIT