feat: rest mode for storage server (#23)

Author: fforbeck

Dockerfile

@@ -1,41 +1,33 @@
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
-WORKDIR /app
+# Install pnpm
+RUN npm install -g pnpm
 
-# Copy package files
-COPY package.json pnpm-lock.yaml ./
+COPY ./ /app
 
-# Install dependencies
-RUN npm install -g pnpm && \
-    pnpm install
+WORKDIR /app
 
-# Copy source code
-COPY . .
+# Force install without any prompts
+RUN --mount=type=cache,target=/root/.pnpm-store HUSKY=0 pnpm install --force --no-optional --frozen-lockfile --ignore-scripts --prod
 
-# Build the application
-RUN pnpm build
+FROM node:22-alpine AS release
 
-# Production stage
-FROM node:20-alpine
+# Install pnpm
+RUN npm install -g pnpm
 
 WORKDIR /app
 
-# Copy only the necessary files from the builder stage
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/package.json ./
-COPY --from=builder /app/pnpm-lock.yaml ./
-
-# Install only production dependencies
-RUN npm install -g pnpm && \
-    HUSKY=0 pnpm install --prod --ignore-scripts
-
-# Expose the port for SSE mode
-EXPOSE 3000
+COPY --from=builder /app/dist /app/dist
+COPY --from=builder /app/package.json /app/package.json
+COPY --from=builder /app/pnpm-lock.yaml /app/pnpm-lock.yaml
 
 # Set default environment variables
 ENV NODE_ENV=production
-ENV MCP_TRANSPORT_MODE=sse
-ENV MCP_SERVER_PORT=3000
+ENV MCP_TRANSPORT_MODE=rest
+ENV MCP_SERVER_PORT=3001
+
+# Remove node_modules if exists to avoid prompts
+RUN rm -rf node_modules || true
+RUN pnpm install --force --no-optional --frozen-lockfile --ignore-scripts --prod
 
-# Run the server in SSE mode
-CMD ["node", "dist/index.js"] 
+ENTRYPOINT ["node", "dist/index.js"]

README.md

@@ -93,7 +93,7 @@ Get started with the Storacha MCP Storage Server in just a few simple steps.
          "command": "node",
          "args": ["./dist/index.js"],
          "env": {
-           // The server also supports `sse` mode, the default is `stdio`.
+           // The server supports `stdio`, `sse`, and `rest` modes, the default is `stdio`.
            "MCP_TRANSPORT_MODE": "stdio",
            // The Storacha Agent private key that is authorized to store data into the Space.
            "PRIVATE_KEY": "<agent_private_key>",
@@ -109,6 +109,22 @@ Get started with the Storacha MCP Storage Server in just a few simple steps.
 
    _Replace `<agent_private_key>` with the PrivateKey you created in step 3. Then, replace the `<base64_delegation>` with the delegation you created in step 3._
 
+   ### REST Mode and Cloud Hosting
+
+   The Storacha MCP Storage Server supports REST transport mode, which is compatible with MCP.so cloud hosting. To use REST mode:
+
+   ```jsonc
+   {
+     "mcpServers": {
+       "storacha-storage-server-rest": {
+         "url": "http://localhost:3001/rest",
+       },
+     },
+   }
+   ```
+
+   For more information on deploying to MCP.so cloud, see the [integrations.md](https://github.com/storacha/mcp-storage-server/blob/main/docs/integrations.md#mcpso-cloud-hosting) guide.
+
    _:warning: There are several ways to configure MCP clients, please read the [integrations.md](https://github.com/storacha/mcp-storage-server/blob/main/docs/integrations.md) guide for more information._
 
 ## Tools

chatmcp.yaml

@@ -0,0 +1,50 @@
+params:
+  type: object
+  properties:
+    PRIVATE_KEY:
+      type: string
+      description: The Storacha Agent private key
+    DELEGATION:
+      type: string
+      description: Base64 encoded delegation
+  required:
+    - PRIVATE_KEY
+    - DELEGATION
+
+rest:
+  name: storacha-storage
+  port: 3001
+  endpoint: /rest
+  dockerfile: ./Dockerfile
+
+docker:
+  command: |
+    docker run -i --rm -p 3001:3001 -e PRIVATE_KEY={PRIVATE_KEY} -e DELEGATION={DELEGATION} -e MCP_TRANSPORT_MODE=rest -e MCP_SERVER_PORT=3001 storacha-mcp-server
+  config: |
+    {
+      "mcpServers": {
+        "storacha-storage": {
+          "command": "docker",
+          "args": [
+            "run",
+            "-i",
+            "--rm",
+            "-p",
+            "3001:3001",
+            "-e",
+            "PRIVATE_KEY",
+            "-e",
+            "DELEGATION",
+            "-e",
+            "MCP_TRANSPORT_MODE=rest",
+            "-e",
+            "MCP_SERVER_PORT=3001",
+            "storacha-mcp-server"
+          ],
+          "env": {
+            "PRIVATE_KEY": "YOUR_PRIVATE_KEY_HERE",
+            "DELEGATION": "YOUR_DELEGATION_HERE"
+          }
+        }
+      }
+    } 

docs/integrations.md

@@ -2,20 +2,26 @@
 
 ## Start Your Server
 
-You can run the MCP server in two different modes:
+You can run the MCP server in multiple different modes:
 
 - **Local Communication**
 
 ```bash
 pnpm start:stdio
 ```
 
-- **Remote Communication**
+- **Remote Communication (SSE)**
 
 ```bash
 pnpm start:sse
 ```
 
+- **Remote Communication (REST)**
+
+```bash
+pnpm start:rest
+```
+
 ## Client Integrations
 
 You can integrate your client with Storacha MCP Storage Server with any of the following patterns.
@@ -82,6 +88,42 @@ client = new Client(
 await client.connect(transport);
 ```
 
+### SDK (rest mode)
+
+Uses Express with REST for HTTP-based communication. This mode is compatible with MCP.so cloud hosting.
+
+```typescript
+import { fetch } from 'node-fetch';
+
+// Make direct JSON-RPC requests to the REST endpoint
+async function callTool(toolName, args) {
+  const response = await fetch(`http://${HOST}:${PORT}/rest`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'client-request',
+      method: 'tools/call',
+      params: {
+        name: toolName,
+        arguments: args,
+      },
+    }),
+  });
+
+  return await response.json();
+}
+
+// Example: Upload a file
+const fileContent = Buffer.from('test content').toString('base64');
+const result = await callTool('upload', {
+  file: fileContent,
+  name: 'test-file.txt',
+});
+```
+
 ### MCP Client Config
 
 Most MCP clients store the configuration as JSON in the following format:
@@ -93,7 +135,7 @@ Most MCP clients store the configuration as JSON in the following format:
       "command": "node",
       "args": ["./dist/index.js"],
       "env": {
-        // The server also supports `sse` mode, the default is `stdio`.
+        // The server supports `stdio`, `sse`, and `rest` modes, the default is `stdio`.
         "MCP_TRANSPORT_MODE": "stdio",
         // The Storacha Agent private key that is authorized to store data into the Space.
         "PRIVATE_KEY": "<agent_private_key>",
@@ -111,7 +153,7 @@ Replace `<agent_private_key>` and `<base64_delegation>` with your actual values.
 
 ### Docker
 
-You can run the Storacha MCP Storage Server in a Docker container, which makes it easy to deploy across different environments without worrying about dependencies or configuration. It uses SSE mode by default.
+You can run the Storacha MCP Storage Server in a Docker container, which makes it easy to deploy across different environments without worrying about dependencies or configuration. It uses SSE mode by default but can be configured to use REST mode.
 
 ### Building the Docker Image
 
@@ -125,19 +167,50 @@ docker build -t storacha-mcp-server .
 docker run -p 3000:3000 \
   -e PRIVATE_KEY="<agent_private_key>" \
   -e DELEGATION="<base64_delegation>" \
+  -e MCP_TRANSPORT_MODE="sse" \
+  -e MCP_SERVER_PORT="3001" \
+  storacha-mcp-server
+```
+
+### Running the Server in REST Mode
+
+```bash
+docker run -p 3001:3001 \
+  -e PRIVATE_KEY="<agent_private_key>" \
+  -e DELEGATION="<base64_delegation>" \
+  -e MCP_TRANSPORT_MODE="rest" \
+  -e MCP_SERVER_PORT="3001" \
   storacha-mcp-server
 ```
 
 Replace `<agent_private_key>` and `<base64_delegation>` with your actual values.
 
+In case you want to keep the private key and delegation in a `.env` file, you can run the following:
+
+```bash
+source .env && docker run -p 3001:3001 \
+  -e PRIVATE_KEY="$PRIVATE_KEY" \
+  -e DELEGATION="$DELEGATION" \
+  -e MCP_TRANSPORT_MODE=rest \
+  -e MCP_SERVER_PORT=3001 \
+  storacha-mcp-server
+```
+
+Test the REST connection:
+
+```bash
+curl -X POST http://127.0.0.1:3001/rest -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":"2","method":"tools/list"}' | jq
+```
+
 ### Environment Variables
 
-| Variable             | Description                       | Default  |
-| -------------------- | --------------------------------- | -------- |
-| `MCP_TRANSPORT_MODE` | Transport mode (`stdio` or `sse`) | `sse`    |
-| `MCP_SERVER_PORT`    | Port for SSE mode                 | `3000`   |
-| `PRIVATE_KEY`        | The Storacha Agent private key    | required |
-| `DELEGATION`         | Base64 encoded delegation         | optional |
+| Variable             | Description                                | Default   |
+| -------------------- | ------------------------------------------ | --------- |
+| `MCP_TRANSPORT_MODE` | Transport mode (`stdio`, `sse`, or `rest`) | `stdio`   |
+| `MCP_SERVER_PORT`    | Port for SSE or REST mode                  | `3001`    |
+| `MCP_SERVER_HOST`    | Host for SSE or REST mode                  | `0.0.0.0` |
+| `PRIVATE_KEY`        | The Storacha Agent private key             | required  |
+| `DELEGATION`         | Base64 encoded delegation                  | optional  |
 
 ### Docker Compose Example
 
@@ -148,12 +221,12 @@ services:
     build:
       context: .
     ports:
-      - '3000:3000'
+      - '3001:3001'
     environment:
       - PRIVATE_KEY=<agent_private_key>
       - DELEGATION=<base64_delegation>
-      - MCP_TRANSPORT_MODE=sse
-      - MCP_SERVER_PORT=3000
+      - MCP_TRANSPORT_MODE=rest
+      - MCP_SERVER_PORT=3001
 ```
 
 ### MCP Client Configuration for Docker SSE Mode
@@ -172,6 +245,14 @@ For Cursor IDE or other MCP clients, you can use this configuration:
 }
 ```
 
+### MCP.so Cloud Hosting
+
+The Storacha MCP Storage Server can be deployed to MCP.so cloud using the REST transport mode. This allows your server to be accessible from anywhere without having to manage your own infrastructure.
+
+Find the Storacha MCP Storage Server on the [MCP Playground](https://mcp.so/playground?server=storacha-storage), set the Private Key and the Delegation, and you are ready to go.
+
+For more details on hosting your MCP server on MCP.so, see the [official documentation](https://docs.mcp.so/server-hosting).
+
 ### Tools
 
 #### List Tools

index.ts

@@ -9,6 +9,7 @@ import { loadConfig as loadStorageConfig } from './src/core/storage/config.js';
  * Server mode is determined by the MCP_TRANSPORT_MODE environment variable:
  * - 'stdio': Starts the server in stdio mode (default)
  * - 'http': Starts the server in HTTP mode with SSE transport
+ * - 'rest': Starts the server in REST mode (MCP.so Cloud)
  */
 async function main() {
   try {

package.json

@@ -13,6 +13,7 @@
     "start": "node dist/index.js",
     "start:stdio": "MCP_TRANSPORT_MODE=stdio pnpm start",
     "start:sse": "MCP_TRANSPORT_MODE=sse pnpm start",
+    "start:rest": "MCP_TRANSPORT_MODE=rest pnpm start",
     "dev": "tsc-watch --onSuccess \"node dist/index.js\"",
     "clean": "rm -rf dist",
     "lint": "eslint \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\"",
@@ -23,9 +24,11 @@
     "test:coverage": "pnpm typecheck && vitest run --coverage",
     "test": "pnpm typecheck && vitest run",
     "test:integration": "pnpm build && pnpm typecheck && vitest run test/integration/**.test.ts",
+    "test:integration:only": "pnpm build && pnpm typecheck && vitest run",
     "inspect": "pnpm build && npx @modelcontextprotocol/inspector node dist/index.js",
     "inspect:sse": "MCP_TRANSPORT_MODE=sse pnpm inspect",
     "inspect:stdio": "MCP_TRANSPORT_MODE=stdio pnpm inspect",
+    "inspect:rest": "MCP_TRANSPORT_MODE=rest pnpm inspect",
     "prepare": "husky install",
     "prepublishOnly": "pnpm build"
   },
@@ -51,6 +54,7 @@
     "dist"
   ],
   "dependencies": {
+    "@chatmcp/sdk": "^1.0.6",
     "@ipld/car": "^5.4.0",
     "@ipld/dag-json": "^10.2.3",
     "@ipld/unixfs": "^3.0.0",
@@ -72,13 +76,15 @@
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.1",
     "@types/node": "^22.13.13",
+    "@types/node-fetch": "^2.6.12",
     "@typescript-eslint/eslint-plugin": "^8.29.0",
     "@typescript-eslint/parser": "^8.29.0",
     "@vitest/coverage-v8": "3.0.9",
     "eslint": "^9.23.0",
     "eslint-config-prettier": "^10.1.1",
     "husky": "^9.1.7",
     "lint-staged": "^15.5.0",
+    "node-fetch": "^3.3.2",
     "prettier": "^3.5.3",
     "ts-node": "^10.9.2",
     "tsc-watch": "^6.2.1",