feat: enable bind to unix domain socket

Related: openai/openai-agents-python#437
Related: modelcontextprotocol/python-sdk#430
Related: johnandersen777/scitt-api-emulator@73bbb92
Signed-off-by: John Andersen <johnandersenpdx@gmail.com>

Author: pdxjohnny

README.md

@@ -111,6 +111,7 @@ Arguments
 | `command_or_url`     | Yes                        | The command to spawn the MCP stdio server                        | uvx mcp-server-fetch  |
 | `--sse-port`         | No, random available       | The SSE server port to listen on                                 | 8080                  |
 | `--sse-host`         | No, `127.0.0.1` by default | The host IP address that the SSE server will listen on           | 0.0.0.0               |
+| `--sse-uds`          | No                         | The UNIX Domain Socket that the SSE server will listen on        | /tmp/mcp.sock         |
 | `--env`              | No                         | Additional environment variables to pass to the MCP stdio server | FOO=BAR               |
 | `--pass-environment` | No                         | Pass through all environment variables when spawning the server  | --no-pass-environment |
 | `--allow-origin`     | No                         | Pass through all environment variables when spawning the server  | --allow-cors "\*"     |
@@ -129,6 +130,9 @@ mcp-proxy --sse-port=8080 uvx mcp-server-fetch
 # Start the MCP server behind the proxy with a custom host and port
 mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch
 
+# Start the MCP server behind the proxy bound to a UNIX Domain Socket
+mcp-proxy --sse-uds /tmp/mcp.sock uvx mcp-server-fetch
+
 # Start the MCP server behind the proxy with a custom user agent
 # Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments
 mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

src/mcp_proxy/__main__.py

@@ -38,6 +38,7 @@ def main() -> None:
             "  mcp-proxy --sse-port 8080 -- your-command --arg1 value1 --arg2 value2\n"
             "  mcp-proxy your-command --sse-port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE\n"
             "  mcp-proxy your-command --sse-port 8080 --allow-origin='*'\n"
+            "  mcp-proxy your-command --sse-uds /tmp/mcp.sock\n"
         ),
         formatter_class=argparse.RawTextHelpFormatter,
     )
@@ -97,6 +98,11 @@ def main() -> None:
         default="127.0.0.1",
         help="Host to expose an SSE server on. Default is 127.0.0.1",
     )
+    sse_server_group.add_argument(
+        "--sse-uds",
+        default=None,
+        help="UNIX Domain Socket to expose an SSE server on. Default is None",
+    )
     sse_server_group.add_argument(
         "--allow-origin",
         nargs="+",
@@ -142,6 +148,7 @@ def main() -> None:
     sse_settings = SseServerSettings(
         bind_host=args.sse_host,
         port=args.sse_port,
+        uds=args.sse_uds,
         allow_origins=args.allow_origin if len(args.allow_origin) > 0 else None,
     )
     asyncio.run(run_sse_server(stdio_params, sse_settings))

src/mcp_proxy/sse_server.py

@@ -23,6 +23,7 @@ class SseServerSettings:
 
     bind_host: str
     port: int
+    uds: str | None = None
     allow_origins: list[str] | None = None
     log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
 
@@ -90,12 +91,19 @@ async def run_sse_server(
             debug=(sse_settings.log_level == "DEBUG"),
         )
 
+        config_kwargs = {}
+
+        if sse_settings.uds:
+            config_kwargs["uds"] = sse_settings.uds
+        else:
+            config_kwargs["host"] = sse_settings.bind_host
+            config_kwargs["port"] = sse_settings.port
+
         # Configure HTTP server
         config = uvicorn.Config(
             starlette_app,
-            host=sse_settings.bind_host,
-            port=sse_settings.port,
             log_level=sse_settings.log_level.lower(),
+            **config_kwargs,
         )
         http_server = uvicorn.Server(config)
         await http_server.serve()