[Bug/RFC] Robustness Issues in Docker Deployment: SSE Stability, Pathing Inconsistency, and Missing STDIO Support

[eouzoe]

1. Description
   While deploying the PromptX MCP Server via Docker/Podman, I encountered several critical issues that hinder its usability in containerized environments. Specifically, the current implementation makes it difficult to use via the standard STDIO transport, and the SSE mode exhibits significant instability.

2. Identified Issues
   SSE Instability (500 Internal Server Errors): When connecting via MCP Inspector or other frontends using HTTP/SSE, the server frequently returns 500 Internal Server Error, leading to connection drops. This might be due to session management or buffering issues within the container network stack.

Pathing Mismatch: The image structure places the server deep within global node modules: /usr/local/lib/node_modules/@promptx/mcp-server/dist/index.js. Standard documentation implies a more accessible path like /app/dist/index.js, making manual execution or custom STDIO configurations unintuitive.

STDIO Transport Non-Responsive: Running the server via node index.js and piping JSON-RPC commands (e.g., tools/list) results in a hang with no output. It appears the server is locked into a Web/Hono lifecycle and does not correctly initialize or listen to stdin.

Missing Auto-Initialization: Mounting an empty volume to /root/.promptx does not trigger a default configuration setup (e.g., experts.json), resulting in an empty tool list without clear log warnings.

3. Technical Analysis
   Transport Logic: The entry point seems heavily coupled with the SSE/Web framework. Without an explicit branch for StdioServerTransport, the server fails to function as a local process.

Image Packaging: The lack of a defined WORKDIR, ENTRYPOINT, or symbolic links makes the container feel like a "black box" rather than a modular tool.

4. Proposed Suggestions
   Standardize Directory Structure: Add RUN ln -s /usr/local/lib/node_modules/@promptx/mcp-server /app in the Dockerfile for better accessibility.

Implement Dual-Transport Support: Add a conditional check for an environment variable (e.g., MCP_TRANSPORT=stdio) to toggle between SSEServerTransport and StdioServerTransport.

Configuration Guard: Check for the existence of .promptx/experts.json at startup and auto-populate it with defaults if missing.

Documentation: Provide a clear docker run example for STDIO mode, as this is the preferred method for tools like Claude Desktop and OpenCode.