Merge pull request #20 from heroku/http_simple

Adding transport - Stateless Streamable HTTP

Author: hillarysanders

.github/workflows/test.yml

@@ -0,0 +1,79 @@
+name: MCP Tests
+
+on:
+  push:
+    branches:
+  pull_request:
+
+jobs:
+  ###########################################################################
+  # 1 - Local integration tests (always run)
+  ###########################################################################
+  local:
+    runs-on: ubuntu-latest
+
+    # Dummy key lets the clients authenticate against the local servers.
+    env:
+      API_KEY: ci-test-key
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Optional: cache wheels to speed up numpy / scipy installs
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
+
+      - name: Run pytest (local transports)
+        run: pytest -q
+
+
+  ###########################################################################
+  # 2 - Remote smoke-test (only when secrets are set)
+  #
+  #    • Put MCP_SERVER_URL  → “https://<app>.herokuapp.com”
+  #    • Put API_KEY         → same key you set as Heroku config var
+  #
+  #    The fixture auto-skips the remote case if these are missing, so
+  #    the job is conditionally *created* only when both secrets exist.
+  ###########################################################################
+  remote:
+    if: ${{ secrets.MCP_SERVER_URL != '' && secrets.API_KEY != '' }}
+    runs-on: ubuntu-latest
+
+    env:
+      MCP_SERVER_URL: ${{ secrets.MCP_SERVER_URL }}
+      API_KEY:       ${{ secrets.API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      # We reuse the *same* test-suite; the fixture detects MCP_SERVER_URL
+      # and adds the “remote” parameter automatically.
+      - name: Run pytest (remote smoke)
+        run: pytest -q

Procfile

@@ -1,2 +1,2 @@
-web: uvicorn src.sse_server:app --host=0.0.0.0 --port=${PORT:-8000} --workers=${WEB_CONCURRENCY:-1}
+web: uvicorn src.${REMOTE_SERVER_TRANSPORT_MODULE:-streamable_http_server}:app --host=0.0.0.0 --port=${PORT:-8000} --workers=${WEB_CONCURRENCY:-1}
 mcp-python: python -m src.stdio_server

README.md

@@ -6,13 +6,13 @@
   - [Manual Deployment](#manual-deployment)
     - [**Set Required Environment Variables from Heroku CLI**](#set-required-environment-variables-from-heroku-cli)
   - [Local Testing](#local-testing)
-    - [Local SSE](#local-sse)
-      - [Local SSE - Example Requests](#local-sse---example-requests)
+    - [Local Streamable HTTP, SSE](#local-streamable-http-sse)
+      - [Local Streamable HTTP, SSE - Example Requests](#local-streamable-http-sse---example-requests)
     - [Local STDIO](#local-stdio)
       - [1. Local STDIO - Example Python STDIO Client](#1-local-stdio---example-python-stdio-client)
       - [2. Local STDIO - Direct Calls](#2-local-stdio---direct-calls)
   - [Remote Testing](#remote-testing)
-    - [Remote SSE](#remote-sse)
+    - [Remote Streamable HTTP, SSE](#remote-streamable-http-sse)
     - [Remote STDIO](#remote-stdio)
       - [1. Remote STDIO - Example Python STDIO Client, Running On-Server](#1-remote-stdio---example-python-stdio-client-running-on-server)
       - [2. Remote STDIO - Direct Calls to One-Off Dyno](#2-remote-stdio---direct-calls-to-one-off-dyno)
@@ -35,6 +35,8 @@ heroku buildpacks:set heroku/python -a $APP_NAME
 # set a private API key that you create, for example:
 heroku config:set API_KEY=$(openssl rand -hex 32) -a $APP_NAME
 heroku config:set STDIO_MODE_ONLY=<true/false> -a $APP_NAME
+# set the remote server type (module) that your web process will use (only relevant for web deployments)
+heroku config:set REMOTE_SERVER_TRANSPORT_MODULE=<streamable_http_server/sse_server>
 ```
 *Note: we recommend setting `STDIO_MODE_ONLY` to `true` for security and code execution isolation security in non-dev environments.*
 
@@ -67,38 +69,41 @@ heroku logs --tail -a $APP_NAME
 ```
 
 ## Local Testing
-### Local SSE
 One-time packages installation:
 ```bash
 virtualenv venv
 source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-If you're testing SSE, in one terminal pane you'll need to start the server:
-```
+### Local Streamable HTTP, SSE
+If you're testing (stateless) Streamable HTTP OR SSE, in one terminal pane you'll need to start the server:
+```bash
 source venv/bin/activate
 export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
-uvicorn src.sse_server:app --reload
+# Either run src.streamable_http_server or src.sse_server, here:
+uvicorn src.streamable_http_server:app --reload
 ```
-*Running with --reload is optional, but great for local development*
+*Running with `--reload` is optional, but great for local development*
 
 Next, in a new pane, you can try running some queries against your server:
-#### Local SSE - Example Requests
+#### Local Streamable HTTP, SSE - Example Requests
 First run:
 ```bash
 export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
 ```
 
+In the following commands, use either `example_clients/streamable_http_client.py` if you ran the streamable HTTP server above, or `example_clients/sse_client.py` if you're running the SSE server.
+
 List tools:
 ```bash
-python example_clients/test_sse.py mcp list_tools | jq
+python example_clients/streamable_http_client.py mcp list_tools | jq
 ```
 
 Example tool call request:
 *NOTE: this will intentionally NOT work if you have set `STDIO_MODE_ONLY` to `true`.*
 ```bash
-python example_clients/test_sse.py mcp call_tool --args '{
+python example_clients/streamable_http_client.py mcp call_tool --args '{
   "name": "code_exec_python",
   "arguments": {
     "code": "import numpy as np; print(np.random.rand(50).tolist())",
@@ -113,12 +118,12 @@ There are two ways to easily test out your MCP server in STDIO mode:
 #### 1. Local STDIO - Example Python STDIO Client
 List tools:
 ```bash
-python example_clients/test_stdio.py mcp list_tools | jq
+python example_clients/stdio_client.py mcp list_tools | jq
 ```
 
 Example tool call request:
 ```bash
-python example_clients/test_stdio.py mcp call_tool --args '{
+python example_clients/stdio_client.py mcp call_tool --args '{
   "name": "code_exec_python",
   "arguments": {
     "code": "import numpy as np; print(np.random.rand(50).tolist())",
@@ -143,34 +148,40 @@ EOF
 
 ## Remote Testing
 
-### Remote SSE
-To test your remote `SSE` server, you'll need to make sure a web process is actually spun up. To save on costs, by default this repository doesn't spin up web dynos on creation, as many folks only want to use `STDIO` mode (local and one-off dyno) requests:
-```
+### Remote Streamable HTTP, SSE
+To test your remote `Streamble HTTP` or `SSE` server, you'll need to make sure a web process is actually spun up. To save on costs, by default this repository doesn't spin up web dynos on creation, as many folks only want to use `STDIO` mode (local and one-off dyno) requests:
+```bash
 heroku ps:scale web=1 -a $APP_NAME
 ```
 You only need to do this once, unless you spin back down to 0 web dynos to save on costs (`heroku ps:scale web=0 -a $APP_NAME`). To confirm currently running dynos, use `heroku ps -a $APP_NAME`.
 
+By default, this app deploys a Streamable HTTP MCP server - if you want to deploy an SSE server, run:
+```bash
+heroku config:set REMOTE_SERVER_TRANSPORT_MODULE=sse_server
+```
+Which will affect which server is run in the Procfile.
+
 Next, run:
 
 ```bash
 export API_KEY=$(heroku config:get API_KEY -a $APP_NAME)
 export MCP_SERVER_URL=$(heroku info -s -a $APP_NAME | grep web_url | cut -d= -f2)
 ```
 
-Next, you can run the same queries as shown in the [Local SSE - Example Requests](#local-sse---example-requests) testing section - because you've set `MCP_SERVER_URL`, the client will call out to your deployed server.
+Next, you can run the same queries as shown in the [Local SSE - Example Requests](#local-streamable-http-sse---example-requests) testing section - because you've set `MCP_SERVER_URL`, the client will call out to your deployed server.
 
 ### Remote STDIO
 There are two ways to test out your remote MCP server in STDIO mode:
 
 #### 1. Remote STDIO - Example Python STDIO Client, Running On-Server
 To run against your deployed code, you can run the example client code on your deployed server inside a one-off dyno:
 ```bash
-heroku run --app $APP_NAME -- bash -c 'python -m example_clients.test_stdio mcp list_tools | jq'
+heroku run --app $APP_NAME -- bash -c 'python -m example_clients.stdio_client mcp list_tools | jq'
 ```
 or:
 ```bash
 heroku run --app $APP_NAME -- bash -c '
-python -m example_clients.test_stdio mcp call_tool --args '\''{
+python -m example_clients.stdio_client mcp call_tool --args '\''{
   "name": "code_exec_python",
   "arguments": {
     "code": "import numpy as np; print(np.random.rand(50).tolist())",

app.json

@@ -16,6 +16,10 @@
             "description": "Only allow tool requests via STDIO mode?",
             "value": "false"
         },
+        "REMOTE_SERVER_TRANSPORT_MODULE": {
+            "description": "Tranport module name used for deployed web app (applicable when web formation size is >0). `streamable_http_server` or `sse_server`.",
+            "value": "streamable_http_server"
+        },
         "USE_TEMP_DIR": {
            "description": "Run Python code in a temporary virtualenv (not a sandbox, but does isolate packages).",
             "value": "false"

example_clients/test_sse.py renamed to example_clients/sse_client.py

@@ -0,0 +1,35 @@
+"""Spins up a test client to interact with MCP server in SSE-mode."""
+import os
+import asyncio
+import json
+import sys
+from mando import command, main
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+API_KEY=os.environ.get('API_KEY')
+MCP_SERVER_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8000").rstrip("/") + '/mcp/'
+
+async def run(method_name: str, raw_args: str = None):
+    """Generalized runner for MCP client methods."""
+    try:
+        args = json.loads(raw_args) if raw_args else {}
+    except json.JSONDecodeError:
+        raise ValueError(f"Could not parse JSON args: {raw_args}")
+
+    headers = {"Authorization": f"Bearer {API_KEY}"}
+
+    async with streamablehttp_client(MCP_SERVER_URL, headers=headers) as (read_stream, write_stream, get_session_id):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            method = getattr(session, method_name)
+            return await method(**args)
+
+
+@command
+def mcp(method_name, args=None):
+    result = asyncio.run(run(method_name, args))
+    print(json.dumps(result.model_dump(), indent=2))
+
+if __name__ == "__main__" and not hasattr(sys, "ps1"):
+    main()

example_clients/test_stdio.py renamed to example_clients/stdio_client.py

@@ -0,0 +1,4 @@
+[pytest]
+addopts = -ra
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function

example_clients/streamable_http_client.py

@@ -1,5 +1,8 @@
-mcp==1.7.1
+mcp[client,server]==1.9.2
 fastapi==0.115.12
 uvicorn==0.34.3
 python-dotenv==1.1.0
 mando==0.8.2
+# --- dev / CI only -------------------------------------------------
+pytest>=8.0
+pytest-asyncio>=0.23

pytest.ini

@@ -0,0 +1,24 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+# local:
+from src import config
+
+API_KEY = config.get_env_variable("API_KEY")
+
+# MCP is still working on ironing out SSE authentication protocols, so for now we'll build our own middleware layer:
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        auth_header = request.headers.get("authorization")
+        api_key_header = request.headers.get("x-api-key")
+        token = None
+
+        if auth_header and auth_header.lower().startswith("bearer "):
+            token = auth_header[7:]
+        elif api_key_header:
+            token = api_key_header
+
+        if token != API_KEY:
+            return JSONResponse({"error": "Unauthorized"}, status_code=401)
+
+        return await call_next(request)