Merge pull request 'feat: replace StdioTransport with StreamableHTTP + Node.js cluster' (#10) from feat/streamable-http into main

Integrates StreamableHTTP natively into the MCP server instead of
using StdioServerTransport. Adds Node.js cluster support so multiple
workers can handle concurrent MCP clients simultaneously.

Changes:
- src/index.ts: replace StdioServerTransport with StreamableHTTPServerTransport
  + Node.js cluster (primary forks N workers, each worker handles HTTP
  requests on :8080/mcp with a serializing mutex)
- Dockerfile: multi-stage build (node:22-slim builder + runtime)
- .gitea/workflows/docker-build.yml: CI/CD pipeline — on push to main,
  builds and pushes Docker image to gitea.p-lao.com registry

Environment variables:
- MCP_WORKERS (default: 4) — number of cluster workers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/docker-build.yml

@@ -0,0 +1,52 @@
+name: Docker Build & Push
+
+on:
+  push:
+    branches: [ main ]
+
+env:
+  REGISTRY: gitea.p-lao.com
+
+jobs:
+  build-and-push:
+    if: gitea.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          github-server-url: https://gitea.p-lao.com
+          token: ${{ secrets.TOKEN_GITEA }}
+
+      - name: Get version
+        id: get_version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if [ "$VERSION" != "" ]; then
+            echo "version=$VERSION" >> $GITEA_ENV
+          else
+            echo "Version not found in package.json"
+            exit 1
+          fi
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Gitea Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: |
+            gitea.p-lao.com/aleleba/docmost-mcp:${{ env.version }}
+            gitea.p-lao.com/aleleba/docmost-mcp:latest

Dockerfile

@@ -0,0 +1,15 @@
+FROM node:22-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=builder /app/build ./build
+COPY package*.json ./
+RUN npm ci --omit=dev
+ENV MCP_WORKERS=4
+EXPOSE 8080
+CMD ["node", "build/index.js"]

src/index.ts

@@ -1,5 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
+import cluster from "node:cluster";
 import FormData from "form-data";
 import axios, { AxiosInstance } from "axios";
 import { z } from "zod";
@@ -857,11 +859,59 @@ server.registerTool(
   },
 );
 
-async function run() {
+const NUM_WORKERS = parseInt(process.env.MCP_WORKERS ?? "4", 10);
-  const transport = new StdioServerTransport();
+
-  await server.connect(transport);
+if (cluster.isPrimary) {
+  // ── Proceso primario: solo hace fork de workers ──
+  console.log(`[docmost-mcp] Primary PID=${process.pid}, starting ${NUM_WORKERS} workers`);
+  for (let i = 0; i < NUM_WORKERS; i++) {
+    cluster.fork();
+  }
+  cluster.on("exit", (worker, code) => {
+    console.log(`[docmost-mcp] Worker PID=${worker.process.pid} died (code=${code}), restarting...`);
+    cluster.fork();
+  });
+} else {
+  // ── Worker: cada uno tiene su propio McpServer singleton ──
+  // El mutex serializa las requests dentro de este worker (stateless, 1 request a la vez por worker)
+  let workerBusy: Promise<void> = Promise.resolve();
+
+  async function handleMcpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined, // stateless: un transport por request
+    });
+    await server.connect(transport);
+    try {
+      await transport.handleRequest(req, res);
+    } finally {
+      await transport.close();
+    }
+  }
+
+  const httpServer = createServer((req: IncomingMessage, res: ServerResponse) => {
+    if (!req.url?.startsWith("/mcp")) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    workerBusy = workerBusy
+      .then(() => handleMcpRequest(req, res))
+      .catch((err) => {
+        console.error(`[docmost-mcp] Worker PID=${process.pid} error:`, err);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" }).end(
+            JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: String(err) }, id: null })
+          );
+        }
+      });
+  });
+
+  httpServer.listen(8080, () => {
+    console.log(`[docmost-mcp] Worker PID=${process.pid} listening on port 8080, path /mcp`);
+  });
 }
 
+// run() vacía — el cluster ya se inició en el top-level de arriba
+async function run() {}
 run().catch((error) => {
   console.error("Fatal error running server:", error);
   process.exit(1);