papers/hanzo-mcp-server/sections/04-implementation.tex

\section{Implementation}


\subsection{Transport Layer}

The server supports three transport mechanisms:

\paragraph{Stdio.} Default for local execution. Messages are JSON lines on stdin/stdout.

\paragraph{HTTP/SSE.} For remote deployments. Requests via HTTP POST, responses via Server-Sent Events for streaming.

\paragraph{WebSocket.} For persistent connections with bidirectional streaming.

\begin{lstlisting}[language=TypeScript]
// Stdio (default)
const transport = new StdioServerTransport();
await server.connect(transport);

// HTTP/SSE
const httpServer = createHTTPServer(server);
httpServer.listen(3000);

// WebSocket
const wsServer = createWebSocketServer(server);
wsServer.listen(3001);
\end{lstlisting}

\subsection{Error Handling}

Tool errors are propagated as structured responses:

\begin{lstlisting}[language=JSON]
{
  "content": [{
    "type": "text",
    "text": "Error: ENOENT: no such file"
  }],
  "isError": true
}
\end{lstlisting}

The \texttt{isError} flag allows clients to distinguish tool failures from successful results returning error messages.

\subsection{Security Considerations}

\paragraph{Path Validation.} All file operations validate paths against an allowlist, rejecting paths containing \texttt{..} or absolute paths outside the project root.

\paragraph{Command Injection.} Shell commands are executed via \texttt{child\_process.spawn} with arguments passed as arrays, preventing shell injection.

\paragraph{Resource Limits.} Configurable limits on file sizes, command output, and execution time prevent resource exhaustion.