feat: add stateless streamable http mode (#15)

Author: PeterRodenkirchAA

README.md

@@ -34,7 +34,7 @@ To use this server, you must have both Python and [Deno](https://deno.com/) inst
 The server can be run with `deno` installed using `uvx`:
 
 ```bash
-uvx mcp-run-python [-h] [--version] [--port PORT] [--deps DEPS] {stdio,streamable-http,example}
+uvx mcp-run-python [-h] [--version] [--port PORT] [--deps DEPS] {stdio,streamable-http,streamable-http-stateless,example}
 ```
 
 where:
@@ -46,6 +46,8 @@ where:
   [Streamable HTTP MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) -
   suitable for running the server as an HTTP server to connect locally or remotely. This supports stateful requests, but
   does not require the client to hold a stateful connection like SSE
+- `streamable-http-stateless` runs the server with [Streamable HTTP MCP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) in stateless mode and does not
+  support server-to-client notifications
 - `example` will run a minimal Python script using `numpy`, useful for checking that the package is working, for the code
   to run successfully, you'll need to install `numpy` using `uvx mcp-run-python --deps numpy example`
 
@@ -91,7 +93,6 @@ uv add mcp-run-python
 
 With `mcp-run-python` installed, you can also run deno directly with `prepare_deno_env` or `async_prepare_deno_env`
 
-
 ```python
 from pydantic_ai import Agent
 from pydantic_ai.mcp import MCPServerStdio

mcp_run_python/_cli.py

@@ -30,7 +30,7 @@ def cli_logic(args_list: Sequence[str] | None = None) -> int:
     parser.add_argument('--version', action='store_true', help='Show version and exit')
     parser.add_argument(
         'mode',
-        choices=['stdio', 'streamable-http', 'example'],
+        choices=['stdio', 'streamable-http', 'streamable-http-stateless', 'example'],
         nargs='?',
         help='Mode to run the server in.',
     )

mcp_run_python/deno/src/main.ts

@@ -30,7 +30,11 @@ export async function main() {
       return
     } else if (args[0] === 'streamable_http') {
       const port = parseInt(flags.port)
-      runStreamableHttp(port, deps, flags['return-mode'])
+      runStreamableHttp(port, deps, flags['return-mode'], false)
+      return
+    } else if (args[0] === 'streamable_http_stateless') {
+      const port = parseInt(flags.port)
+      runStreamableHttp(port, deps, flags['return-mode'], true)
       return
     } else if (args[0] === 'example') {
       await example(deps)
@@ -44,7 +48,7 @@ export async function main() {
     `\
 Invalid arguments: ${args.join(' ')}
 
-Usage: deno ... deno/main.ts [stdio|streamable_http|install_deps|noop]
+Usage: deno ... deno/main.ts [stdio|streamable_http|streamable_http_stateless|install_deps|noop]
 
 options:
 --port <port>             Port to run the HTTP server on (default: 3001)
@@ -167,12 +171,53 @@ function httpSetJsonResponse(res: http.ServerResponse, status: number, text: str
 /*
  * Run the MCP server using the Streamable HTTP transport
  */
-function runStreamableHttp(port: number, deps: string[], returnMode: string) {
+function runStreamableHttp(port: number, deps: string[], returnMode: string, stateless: boolean): void {
+  const server = (stateless ? createStatelessHttpServer : createStatefulHttpServer)(deps, returnMode)
+  server.listen(port, () => {
+    console.log(`Listening on port ${port}`)
+  })
+}
+
+function createStatelessHttpServer(deps: string[], returnMode: string): http.Server {
+  return http.createServer(async (req, res) => {
+    const url = httpGetUrl(req)
+
+    if (url.pathname !== '/mcp') {
+      httpSetTextResponse(res, 404, 'Page not found')
+      return
+    }
+
+    try {
+      const mcpServer = createServer(deps, returnMode)
+      const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      })
+
+      res.on('close', () => {
+        transport.close()
+        mcpServer.close()
+      })
+
+      await mcpServer.connect(transport)
+
+      const body = req.method === 'POST' ? await httpGetBody(req) : undefined
+      await transport.handleRequest(req, res, body)
+    } catch (error) {
+      console.error('Error handling MCP request:', error)
+      if (!res.headersSent) {
+        httpSetJsonResponse(res, 500, 'Internal server error', -32603)
+      }
+    }
+  })
+}
+
+function createStatefulHttpServer(deps: string[], returnMode: string): http.Server {
+  // Stateful mode with session management
   // https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#with-session-management
   const mcpServer = createServer(deps, returnMode)
   const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {}
 
-  const server = http.createServer(async (req, res) => {
+  return http.createServer(async (req, res) => {
     const url = httpGetUrl(req)
     let pathMatch = false
     function match(method: string, path: string): boolean {
@@ -243,10 +288,6 @@ function runStreamableHttp(port: number, deps: string[], returnMode: string) {
       httpSetTextResponse(res, 404, 'Page not found')
     }
   })
-
-  server.listen(port, () => {
-    console.log(`Listening on port ${port}`)
-  })
 }
 
 /*

mcp_run_python/main.py

@@ -15,7 +15,7 @@
 
 logger = logging.getLogger(__name__)
 LoggingLevel = Literal['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency']
-Mode = Literal['stdio', 'streamable_http', 'example']
+Mode = Literal['stdio', 'streamable_http', 'streamable_http_stateless', 'example']
 LogHandler = Callable[[LoggingLevel, str], None]
 
 
@@ -53,7 +53,7 @@ def run_mcp_server(
         deps_log_handler=deps_log_handler,
         allow_networking=allow_networking,
     ) as env:
-        if mode == 'streamable_http':
+        if mode in ('streamable_http', 'streamable_http_stateless'):
             logger.info('Running mcp-run-python via %s on port %d...', mode, http_port)
         else:
             logger.info('Running mcp-run-python via %s...', mode)
@@ -198,10 +198,10 @@ def _deno_run_args(
     if dependencies is not None:
         args.append(f'--deps={",".join(dependencies)}')
     if http_port is not None:
-        if mode == 'streamable_http':
+        if mode in ('streamable_http', 'streamable_http_stateless'):
             args.append(f'--port={http_port}')
         else:
-            raise ValueError('Port is only supported for `streamable_http` mode')
+            raise ValueError('Port is only supported for `streamable_http` modes')
     return args
 
 

tests/test_mcp_servers.py

@@ -22,7 +22,7 @@
 pytestmark = pytest.mark.anyio
 
 
-@pytest.fixture(name='run_mcp_session', params=['stdio', 'streamable_http'])
+@pytest.fixture(name='run_mcp_session', params=['stdio', 'streamable_http', 'streamable_http_stateless'])
 def fixture_run_mcp_session(
     request: pytest.FixtureRequest,
 ) -> Callable[[list[str]], AbstractAsyncContextManager[ClientSession]]:
@@ -35,9 +35,9 @@ async def run_mcp(deps: list[str]) -> AsyncIterator[ClientSession]:
                     async with ClientSession(read, write) as session:
                         yield session
         else:
-            assert request.param == 'streamable_http', request.param
+            assert request.param in ('streamable_http', 'streamable_http_stateless'), request.param
             port = 3101
-            async with async_prepare_deno_env('streamable_http', http_port=port, dependencies=deps) as env:
+            async with async_prepare_deno_env(request.param, http_port=port, dependencies=deps) as env:
                 p = subprocess.Popen(['deno', *env.args], cwd=env.cwd)
                 try:
                     url = f'http://localhost:{port}/mcp'