cprime-supergateway 3.4.3

package/.github/workflows/docker-publish.yaml

@@ -0,0 +1,79 @@
+name: Publish Docker images
+
+on:
+  workflow_dispatch: {}
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  GHCR_REGISTRY: ghcr.io/supercorp-ai
+  DOCKERHUB_REGISTRY: docker.io/supercorp
+
+jobs:
+  publish:
+    name: Build and push supergateway container
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version
+        id: ver
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Docker meta
+        id: docker_meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.GHCR_REGISTRY }}/supergateway
+            ${{ env.DOCKERHUB_REGISTRY }}/supergateway
+          labels: |
+            org.opencontainers.image.title=Supergateway
+            org.opencontainers.image.version=${{ steps.ver.outputs.VERSION }}
+            org.opencontainers.image.source=${{ github.repository }}
+
+      - name: Build & push (Bake)
+        uses: docker/bake-action@v6
+        env:
+          VERSION: ${{ steps.ver.outputs.VERSION }}
+        with:
+          source: .
+          files: |
+            docker-bake.hcl
+            ${{ steps.docker_meta.outputs.bake-file }}
+          push: true
+          set: |
+            *.args.VERSION=${{ steps.ver.outputs.VERSION }}
+            *.cache-from=type=gha
+            *.cache-to=type=gha,mode=max

package/.husky/pre-commit

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Ensure we're in the project directory
+GIT_ROOT=$(git rev-parse --show-toplevel)
+cd "$GIT_ROOT" || exit 1
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|jsx|ts|tsx|json|css|scss|md|yaml|yml)$' || true)
+
+if [ -n "$STAGED_FILES" ]; then
+  echo "Formatting staged files before commit..."
+  # Use the installed Prettier to format only the staged files
+  ./node_modules/.bin/prettier --write --ignore-unknown $STAGED_FILES
+  # Re-add the formatted files to the staging area
+  git add $STAGED_FILES
+fi

package/.prettierignore

@@ -0,0 +1,8 @@
+dist
+node_modules
+.git
+.github
+package-lock.json
+.DS_Store
+**/.hermit/**
+**/cache/**

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "singleAttributePerLine": true
+}

package/AGENTS.md

@@ -0,0 +1,29 @@
+## Setup
+
+Install Node.js v24 using nvm. After checking out the repository, run:
+
+```bash
+nvm install 24
+nvm use 24
+npm install
+
+# Build
+
+Compile the TypeScript sources before running tests:
+
+npm run build
+```
+
+## Running tests
+
+Run the test suite with Node's test runner and ts-node to enable mocks:
+
+```bash
+npm run test
+```
+
+The `tests/helpers/mock-mcp-server.js` script provides a lightweight local MCP
+server used during tests so everything runs offline. All tests should pass
+without external downloads.
+
+If network-dependent commands (like `npx -y @modelcontextprotocol/server-*`) fail, check network access.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Supercorp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+![Supergateway: Run stdio MCP servers over SSE and WS](https://raw.githubusercontent.com/supercorp-ai/supergateway/main/supergateway.png)
+
+**Supergateway** runs **MCP stdio-based servers** over **SSE (Server-Sent Events)** or **WebSockets (WS)** with one command. This is useful for remote access, debugging, or connecting to clients when your MCP server only supports stdio.
+
+Supported by [Supermachine](https://supermachine.ai) (hosted MCPs), [Superinterface](https://superinterface.ai), and [Supercorp](https://supercorp.ai).
+
+## Installation & Usage
+
+Run Supergateway via `npx`:
+
+```bash
+npx -y supergateway --stdio "uvx mcp-server-git"
+```
+
+- **`--stdio "command"`**: Command that runs an MCP server over stdio
+- **`--sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"`**: SSE URL to connect to (SSE→stdio mode)
+- **`--streamableHttp "https://mcp-server.example.com/mcp"`**: Streamable HTTP URL to connect to (StreamableHttp→stdio mode)
+- **`--outputTransport stdio | sse | ws | streamableHttp`**: Output MCP transport (default: `sse` with `--stdio`, `stdio` with `--sse` or `--streamableHttp`)
+- **`--port 8000`**: Port to listen on (stdio→SSE or stdio→WS mode, default: `8000`)
+- **`--baseUrl "http://localhost:8000"`**: Base URL for SSE or WS clients (stdio→SSE mode; optional)
+- **`--ssePath "/sse"`**: Path for SSE subscriptions (stdio→SSE mode, default: `/sse`)
+- **`--messagePath "/message"`**: Path for messages (stdio→SSE or stdio→WS mode, default: `/message`)
+- **`--streamableHttpPath "/mcp"`**: Path for Streamable HTTP (stdio→Streamable HTTP mode, default: `/mcp`)
+- **`--stateful`**: Run stdio→Streamable HTTP in stateful mode
+- **`--sessionTimeout 60000`**: Session timeout in milliseconds (stateful stdio→Streamable HTTP mode only)
+- **`--header "x-user-id: 123"`**: Add one or more headers (stdio→SSE, SSE→stdio, or Streamable HTTP→stdio mode; can be used multiple times)
+- **`--oauth2Bearer "some-access-token"`**: Adds an `Authorization` header with the provided Bearer token
+- **`--logLevel debug | info | none`**: Controls logging level (default: `info`). Use `debug` for more verbose logs, `none` to suppress all logs.
+- **`--cors`**: Enable CORS (stdio→SSE or stdio→WS mode). Use `--cors` with no values to allow all origins, or supply one or more allowed origins (e.g. `--cors "http://example.com"` or `--cors "/example\\.com$/"` for regex matching).
+- **`--healthEndpoint /healthz`**: Register one or more endpoints (stdio→SSE or stdio→WS mode; can be used multiple times) that respond with `"ok"`
+
+## stdio → SSE
+
+Expose an MCP stdio server as an SSE server:
+
+```bash
+npx -y supergateway \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
+    --port 8000 --baseUrl http://localhost:8000 \
+    --ssePath /sse --messagePath /message
+```
+
+- **Subscribe to events**: `GET http://localhost:8000/sse`
+- **Send messages**: `POST http://localhost:8000/message`
+
+## SSE → stdio
+
+Connect to a remote SSE server and expose locally via stdio:
+
+```bash
+npx -y supergateway --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+```
+
+Useful for integrating remote SSE MCP servers into local command-line environments.
+
+You can also pass headers when sending requests. This is useful for authentication:
+
+```bash
+npx -y supergateway \
+    --sse "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app" \
+    --oauth2Bearer "some-access-token" \
+    --header "X-My-Header: another-header-value"
+```
+
+## Streamable HTTP → stdio
+
+Connect to a remote Streamable HTTP server and expose locally via stdio:
+
+```bash
+npx -y supergateway --streamableHttp "https://mcp-server.example.com/mcp"
+```
+
+This mode is useful for connecting to MCP servers that use the newer Streamable HTTP transport protocol. Like SSE mode, you can also pass headers for authentication:
+
+```bash
+npx -y supergateway \
+    --streamableHttp "https://mcp-server.example.com/mcp" \
+    --oauth2Bearer "some-access-token" \
+    --header "X-My-Header: another-header-value"
+```
+
+## stdio → Streamable HTTP
+
+Expose an MCP stdio server as a Streamable HTTP server.
+
+### Stateless mode
+
+```bash
+npx -y supergateway \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
+    --outputTransport streamableHttp \
+    --port 8000
+```
+
+### Stateful mode
+
+```bash
+npx -y supergateway \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
+    --outputTransport streamableHttp --stateful \
+    --sessionTimeout 60000 --port 8000
+```
+
+The Streamable HTTP endpoint defaults to `http://localhost:8000/mcp` (configurable via `--streamableHttpPath`).
+
+## stdio → WS
+
+Expose an MCP stdio server as a WebSocket server:
+
+```bash
+npx -y supergateway \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem ./my-folder" \
+    --port 8000 --outputTransport ws --messagePath /message
+```
+
+- **WebSocket endpoint**: `ws://localhost:8000/message`
+
+## Example with MCP Inspector (stdio → SSE mode)
+
+1. **Run Supergateway**:
+
+```bash
+npx -y supergateway --port 8000 \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem /Users/MyName/Desktop"
+```
+
+2. **Use MCP Inspector**:
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+You can now list tools, resources, or perform MCP actions via Supergateway.
+
+## Using with ngrok
+
+Use [ngrok](https://ngrok.com/) to share your local MCP server publicly:
+
+```bash
+npx -y supergateway --port 8000 --stdio "npx -y @modelcontextprotocol/server-filesystem ."
+
+# In another terminal:
+ngrok http 8000
+```
+
+ngrok provides a public URL for remote access.
+
+MCP server will be available at URL similar to: https://1234-567-890-12-456.ngrok-free.app/sse
+
+## Running with Docker
+
+A Docker-based workflow avoids local Node.js setup. A ready-to-run Docker image is available here:
+[supercorp/supergateway](https://hub.docker.com/r/supercorp/supergateway). Also on GHCR: [ghcr.io/supercorp-ai/supergateway](https://github.com/supercorp-ai/supergateway/pkgs/container/supergateway)
+
+### Using the Official Image
+
+```bash
+docker run -it --rm -p 8000:8000 supercorp/supergateway \
+    --stdio "npx -y @modelcontextprotocol/server-filesystem /" \
+    --port 8000
+```
+
+Docker pulls the image automatically. The MCP server runs in the container’s root directory (`/`). You can mount host directories if needed.
+
+#### Images with dependencies
+
+Pull any of these pre-built Supergateway images for various dependencies you might need.
+
+- **uvx**
+  Supergateway + uv/uvx, so you can call `uvx` directly:
+
+  ```bash
+  docker run -it --rm -p 8000:8000 supercorp/supergateway:uvx \
+    --stdio "uvx mcp-server-fetch"
+  ```
+
+- **deno**
+  Supergateway + Deno, ready to run Deno-based MCP servers:
+  ```bash
+  docker run -it --rm -p 8000:8000 supercorp/supergateway:deno \
+    --stdio "deno run -A jsr:@omedia/mcp-server-drupal --drupal-url https://your-drupal-server.com"
+  ```
+
+### Building the Image Yourself
+
+Use provided Dockerfile:
+
+```bash
+docker build -f docker/base.Dockerfile -t supergateway .
+
+docker run -it --rm -p 8000:8000 supergateway --stdio "npx -y @modelcontextprotocol/server-filesystem ."
+```
+
+## Using with Claude Desktop (SSE → stdio mode)
+
+Claude Desktop can use Supergateway’s SSE→stdio mode.
+
+### NPX-based MCP Server Example
+
+```json
+{
+  "mcpServers": {
+    "supermachineExampleNpx": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "supergateway",
+        "--sse",
+        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+      ]
+    }
+  }
+}
+```
+
+### Docker-based MCP Server Example
+
+```json
+{
+  "mcpServers": {
+    "supermachineExampleDocker": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "supercorp/supergateway",
+        "--sse",
+        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+      ]
+    }
+  }
+}
+```
+
+## Using with Cursor (SSE → stdio mode)
+
+Cursor can also integrate with Supergateway in SSE→stdio mode. The configuration is similar to Claude Desktop.
+
+### NPX-based MCP Server Example for Cursor
+
+```json
+{
+  "mcpServers": {
+    "cursorExampleNpx": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "supergateway",
+        "--sse",
+        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+      ]
+    }
+  }
+}
+```
+
+### Docker-based MCP Server Example for Cursor
+
+```json
+{
+  "mcpServers": {
+    "cursorExampleDocker": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "supercorp/supergateway",
+        "--sse",
+        "https://mcp-server-ab71a6b2-cd55-49d0-adba-562bc85956e3.supermachine.app"
+      ]
+    }
+  }
+}
+```
+
+**Note:** Although the setup supports sending headers via the `--header` flag, if you need to pass an Authorization header (which typically includes a space, e.g. `"Bearer 123"`), you must use the `--oauth2Bearer` flag due to a known Cursor bug with spaces in command-line arguments.
+
+## Why MCP?
+
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) standardizes AI tool interactions. Supergateway converts MCP stdio servers into SSE or WS services, simplifying integration and debugging with web-based or remote clients.
+
+## Advanced Configuration
+
+Supergateway emphasizes modularity:
+
+- Automatically manages JSON-RPC versioning.
+- Retransmits package metadata where possible.
+- stdio→SSE or stdio→WS mode logs via standard output; SSE→stdio mode logs via stderr.
+
+## Additional resources
+
+- [Superargs](https://github.com/supercorp-ai/superargs) - provide arguments to MCP servers during runtime.
+
+## Contributors
+
+- [@longfin](https://github.com/longfin)
+- [@griffinqiu](https://github.com/griffinqiu)
+- [@folkvir](https://github.com/folkvir)
+- [@wizizm](https://github.com/wizizm)
+- [@dtinth](https://github.com/dtinth)
+- [@rajivml](https://github.com/rajivml)
+- [@NicoBonaminio](https://github.com/NicoBonaminio)
+- [@sibbl](https://github.com/sibbl)
+- [@podarok](https://github.com/podarok)
+- [@jmn8718](https://github.com/jmn8718)
+- [@TraceIvan](https://github.com/TraceIvan)
+- [@zhoufei0622](https://github.com/zhoufei0622)
+- [@ezyang](https://github.com/ezyang)
+- [@aleksadvaisly](https://github.com/aleksadvaisly)
+- [@wuzhuoquan](https://github.com/wuzhuoquan)
+- [@mantrakp04](https://github.com/mantrakp04)
+- [@mheubi](https://github.com/mheubi)
+- [@mjmendo](https://github.com/mjmendo)
+- [@CyanMystery](https://github.com/CyanMystery)
+- [@earonesty](https://github.com/earonesty)
+- [@StefanBurscher](https://github.com/StefanBurscher)
+- [@tarasyarema](https://github.com/tarasyarema)
+- [@pcnfernando](https://github.com/pcnfernando)
+- [@Areo-Joe](https://github.com/Areo-Joe)
+- [@Joffref](https://github.com/Joffref)
+- [@michaeljguarino](https://github.com/michaeljguarino)
+
+## Contributing
+
+Issues and PRs welcome. Please open one if you encounter problems or have feature suggestions.
+
+## Tests
+
+Supergateway is tested with the Node Test Runner.
+
+To run the suite locally you need Node **24+**. Using [nvm](https://github.com/nvm-sh/nvm) you can install and activate it with:
+
+```bash
+nvm install 24
+nvm use 24
+npm install
+npm run build
+npm test
+```
+
+The `tests/helpers/mock-mcp-server.js` script provides a local MCP server so all
+tests run without network access.
+
+## License
+
+[MIT License](./LICENSE)

package/dist/gateways/sseToStdio.js

@@ -0,0 +1,139 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getVersion } from '../lib/getVersion.js';
+import { onSignals } from '../lib/onSignals.js';
+let sseClient;
+const newInitializeSseClient = ({ message }) => {
+    const clientInfo = message.params?.clientInfo;
+    const clientCapabilities = message.params?.capabilities;
+    return new Client({
+        name: clientInfo?.name ?? 'supergateway',
+        version: clientInfo?.version ?? getVersion(),
+    }, {
+        capabilities: clientCapabilities ?? {},
+    });
+};
+const newFallbackSseClient = async ({ sseTransport, }) => {
+    const fallbackSseClient = new Client({
+        name: 'supergateway',
+        version: getVersion(),
+    }, {
+        capabilities: {},
+    });
+    await fallbackSseClient.connect(sseTransport);
+    return fallbackSseClient;
+};
+export async function sseToStdio(args) {
+    const { sseUrl, logger, headers } = args;
+    logger.info(`  - sse: ${sseUrl}`);
+    logger.info(`  - Headers: ${Object.keys(headers).length ? JSON.stringify(headers) : '(none)'}`);
+    logger.info('Connecting to SSE...');
+    onSignals({ logger });
+    const sseTransport = new SSEClientTransport(new URL(sseUrl), {
+        eventSourceInit: {
+            fetch: (...props) => {
+                const [url, init = {}] = props;
+                return fetch(url, { ...init, headers: { ...init.headers, ...headers } });
+            },
+        },
+        requestInit: {
+            headers,
+        },
+    });
+    sseTransport.onerror = (err) => {
+        logger.error('SSE error:', err);
+    };
+    sseTransport.onclose = () => {
+        logger.error('SSE connection closed');
+        process.exit(1);
+    };
+    const stdioServer = new Server({
+        name: 'supergateway',
+        version: getVersion(),
+    }, {
+        capabilities: {},
+    });
+    const stdioTransport = new StdioServerTransport();
+    await stdioServer.connect(stdioTransport);
+    const wrapResponse = (req, payload) => ({
+        jsonrpc: req.jsonrpc || '2.0',
+        id: req.id,
+        ...payload,
+    });
+    stdioServer.transport.onmessage = async (message) => {
+        const isRequest = 'method' in message && 'id' in message;
+        if (isRequest) {
+            logger.info('Stdio → SSE:', message);
+            const req = message;
+            let result;
+            try {
+                if (!sseClient) {
+                    if (message.method === 'initialize') {
+                        sseClient = newInitializeSseClient({
+                            message,
+                        });
+                        const originalRequest = sseClient.request;
+                        sseClient.request = async function (requestMessage, ...restArgs) {
+                            // pass protocol version from original client
+                            if (requestMessage.method === 'initialize' &&
+                                message.params?.protocolVersion &&
+                                requestMessage.params?.protocolVersion) {
+                                requestMessage.params.protocolVersion =
+                                    message.params.protocolVersion;
+                            }
+                            result = await originalRequest.apply(this, [
+                                requestMessage,
+                                ...restArgs,
+                            ]);
+                            return result;
+                        };
+                        await sseClient.connect(sseTransport);
+                        sseClient.request = originalRequest;
+                    }
+                    else {
+                        logger.info('SSE client not initialized, creating fallback client');
+                        sseClient = await newFallbackSseClient({ sseTransport });
+                    }
+                    logger.info('SSE connected');
+                }
+                else {
+                    result = await sseClient.request(req, z.any());
+                }
+            }
+            catch (err) {
+                logger.error('Request error:', err);
+                const errorCode = err && typeof err === 'object' && 'code' in err
+                    ? err.code
+                    : -32000;
+                let errorMsg = err && typeof err === 'object' && 'message' in err
+                    ? err.message
+                    : 'Internal error';
+                const prefix = `MCP error ${errorCode}:`;
+                if (errorMsg.startsWith(prefix)) {
+                    errorMsg = errorMsg.slice(prefix.length).trim();
+                }
+                const errorResp = wrapResponse(req, {
+                    error: {
+                        code: errorCode,
+                        message: errorMsg,
+                    },
+                });
+                process.stdout.write(JSON.stringify(errorResp) + '\n');
+                return;
+            }
+            const response = wrapResponse(req, result.hasOwnProperty('error')
+                ? { error: { ...result.error } }
+                : { result: { ...result } });
+            logger.info('Response:', response);
+            process.stdout.write(JSON.stringify(response) + '\n');
+        }
+        else {
+            logger.info('SSE → Stdio:', message);
+            process.stdout.write(JSON.stringify(message) + '\n');
+        }
+    };
+    logger.info('Stdio server listening');
+}