Remote Muster MCP endpoint for Hermes

.github/workflows/ci.yml

@@ -148,6 +148,9 @@ jobs:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
+      # load:true (PR path) cannot export manifest lists. Provenance/SBOM
+      # attestations produce multi-artifact images, so only enable them on
+      # push where we publish to the registry instead of loading locally.
       - uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         id: build
         with:
@@ -160,8 +163,8 @@ jobs:
             org.opencontainers.image.title=Muster
             org.opencontainers.image.description=Shared workspace for human and agent-driven security operations
             org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
-          provenance: mode=max
-          sbom: true
+          provenance: ${{ github.event_name == 'push' && 'mode=max' || false }}
+          sbom: ${{ github.event_name == 'push' }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
       - name: Scan built image with Trivy

.github/workflows/security.yml

@@ -67,21 +67,25 @@ jobs:
           scanners: vuln
           exit-code: "1"
       - uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0
+        if: always()
         with:
           image: muster:security
           format: cyclonedx-json
           output-file: muster-sbom.cdx.json
           upload-artifact: false
       - name: Generate provenance metadata and checksums
+        if: always()
         run: |
           printf '{"commit":"%s","workflow":"%s","runId":"%s","image":"muster:security"}\n' \
             "$GITHUB_SHA" "$GITHUB_WORKFLOW" "$GITHUB_RUN_ID" > provenance.json
           sha256sum muster-sbom.cdx.json provenance.json > SHA256SUMS
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
         with:
           name: security-artifacts
           path: |
             muster-sbom.cdx.json
             provenance.json
             SHA256SUMS
             trivy.sarif
+          if-no-files-found: ignore

apps/mcp-server/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@muster/mcp-server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@muster/config": "workspace:*",
+    "@muster/database": "workspace:*",
+    "@muster/mcp": "workspace:*",
+    "drizzle-orm": "catalog:",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "catalog:",
+    "vitest": "4.1.10"
+  }
+}

apps/mcp-server/src/health.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { checkDatabaseHealth } from "./health.ts";
+
+describe("checkDatabaseHealth", () => {
+  it("is ready when the database responds", async () => {
+    const db = { execute: async () => undefined } as never;
+    expect(await checkDatabaseHealth(db)).toBe(true);
+  });
+
+  it("is not ready when the database is unreachable", async () => {
+    const db = {
+      execute: async () => {
+        throw new Error("connection refused");
+      },
+    } as never;
+    expect(await checkDatabaseHealth(db)).toBe(false);
+  });
+});

apps/mcp-server/src/health.ts

@@ -0,0 +1,18 @@
+import { sql } from "drizzle-orm";
+import type { database } from "@muster/database";
+
+/**
+ * A real dependency-aware readiness check, not a static liveness stub: a
+ * Postgres outage must surface as a non-ready response, not a false-positive
+ * "ready" that orchestrators route traffic to anyway.
+ */
+export async function checkDatabaseHealth(
+  db: ReturnType<typeof database>,
+): Promise<boolean> {
+  try {
+    await db.execute(sql`select 1`);
+    return true;
+  } catch {
+    return false;
+  }
+}

apps/mcp-server/src/index.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { redactObservationText } from "@muster/config";
+import { closeDatabase, database } from "@muster/database";
+import { createMusterMcpServer, resolveInstallation } from "@muster/mcp";
+import { checkDatabaseHealth } from "./health.ts";
+import { gracefulShutdown } from "./shutdown.ts";
+
+const db = database();
+
+function bearerToken(header: string | undefined): string | null {
+  if (!header?.startsWith("Bearer ")) return null;
+  const token = header.slice("Bearer ".length).trim();
+  return token.length > 0 ? token : null;
+}
+
+function requestTraceId(request: IncomingMessage): string {
+  const header = request.headers["x-trace-id"];
+  const value = Array.isArray(header) ? header[0] : header;
+  return redactObservationText(value ?? randomUUID(), { maxStringLength: 200 });
+}
+
+function respondJson(response: ServerResponse, status: number, body: unknown) {
+  response.writeHead(status, { "content-type": "application/json" });
+  response.end(JSON.stringify(body));
+}
+
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url ?? "/", "http://mcp-server.local");
+
+  if (request.method === "GET" && url.pathname === "/health") {
+    const healthy = await checkDatabaseHealth(db);
+    respondJson(response, healthy ? 200 : 503, {
+      status: healthy ? "ready" : "not_ready",
+      authority: "postgresql",
+    });
+    return;
+  }
+
+  if (url.pathname !== "/mcp") {
+    respondJson(response, 404, { error: "Not found" });
+    return;
+  }
+
+  // A missing, malformed, revoked, or cross-organisation credential all fail
+  // the same way here: a generic 401 that never reveals which case applied.
+  const token = bearerToken(request.headers.authorization);
+  const context = token ? await resolveInstallation(db, token) : null;
+  if (!context) {
+    respondJson(response, 401, { error: "Unauthorised" });
+    return;
+  }
+
+  const mcpServer = createMusterMcpServer({
+    db,
+    context,
+    traceId: requestTraceId(request),
+  });
+  // Omitting `sessionIdGenerator` (rather than setting it to `undefined`)
+  // selects stateless mode under `exactOptionalPropertyTypes`; every request
+  // is authorised independently by its own bearer token regardless.
+  const transport = new StreamableHTTPServerTransport({});
+  response.on("close", () => void transport.close());
+  try {
+    // The installed SDK's concrete transport class types `onclose`/`onerror`
+    // as `(() => void) | undefined` while `Transport` declares them as
+    // optional `() => void`; those are equivalent at runtime but disagree
+    // under `exactOptionalPropertyTypes`, hence the assertion.
+    await mcpServer.connect(transport as unknown as Transport);
+    await transport.handleRequest(request, response);
+  } catch (error) {
+    console.error(
+      "mcp.request.failed",
+      redactObservationText(error instanceof Error ? error.message : "unknown"),
+    );
+    if (!response.headersSent)
+      respondJson(response, 500, { error: "Request failed" });
+  }
+});
+
+// Kelpie tool calls poll for up to KELPIE_POLL_OPTIONS.timeoutMs (8s) inside
+// the request; these bound the socket/request lifecycle around that with
+// headroom, so a burst of concurrent bounded polls can't hold connections
+// open indefinitely instead of being bounded like everything else here.
+server.requestTimeout = 15_000;
+server.headersTimeout = 12_000;
+server.keepAliveTimeout = 5_000;
+
+server.listen(Number(process.env.MCP_SERVER_PORT ?? 3003), "0.0.0.0");
+
+async function shutdown() {
+  await gracefulShutdown(server, closeDatabase);
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

apps/mcp-server/src/shutdown.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { gracefulShutdown } from "./shutdown.ts";
+
+describe("gracefulShutdown", () => {
+  it("closes the database only after the server finishes draining", async () => {
+    const events: string[] = [];
+    const server = {
+      close: (callback: (error?: Error) => void) => {
+        setTimeout(() => {
+          events.push("server.closed");
+          callback();
+        }, 10);
+      },
+    };
+    const closeDb = async () => {
+      events.push("db.closed");
+    };
+    await gracefulShutdown(server, closeDb);
+    expect(events).toEqual(["server.closed", "db.closed"]);
+  });
+
+  it("propagates a server close error instead of closing the database", async () => {
+    const server = {
+      close: (callback: (error?: Error) => void) => {
+        callback(new Error("close failed"));
+      },
+    };
+    let dbClosed = false;
+    const closeDb = async () => {
+      dbClosed = true;
+    };
+    await expect(gracefulShutdown(server, closeDb)).rejects.toThrow(
+      "close failed",
+    );
+    expect(dbClosed).toBe(false);
+  });
+});

apps/mcp-server/src/shutdown.ts

@@ -0,0 +1,20 @@
+export interface CloseableServer {
+  close(callback: (error?: Error) => void): unknown;
+}
+
+/**
+ * `server.close()` is asynchronous: it stops accepting new connections but
+ * existing keep-alive requests continue until it emits its completion
+ * callback. Closing the database pool before that drain completes can tear
+ * it down under an in-flight MCP tool call (including its audit write), on
+ * every SIGTERM/rolling deploy. Await the callback first.
+ */
+export async function gracefulShutdown(
+  server: CloseableServer,
+  closeDb: () => Promise<void>,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+  await closeDb();
+}

apps/mcp-server/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "include": ["src/**/*.ts"]
+}

apps/web/components/room-view.tsx

@@ -64,13 +64,13 @@ type TimelineItem = (typeof roomTimeline)[number];
 type ThreadParent = TimelineItem | RoomMessageRecord;
 
 const persistedTimelineIds = new Set([
-  "018f55d8-c4c7-7c3e-88ef-000000000701",
-  "018f55d8-c4c7-7c3e-88ef-000000000705",
+  "019e7a10-0000-7000-8000-000000000701",
+  "019e7a10-0000-7000-8000-000000000705",
 ]);
 const seededThreadMessageIds = new Set([
-  "018f55d8-c4c7-7c3e-88ef-000000000702",
-  "018f55d8-c4c7-7c3e-88ef-000000000703",
-  "018f55d8-c4c7-7c3e-88ef-000000000704",
+  "019e7a10-0000-7000-8000-000000000702",
+  "019e7a10-0000-7000-8000-000000000703",
+  "019e7a10-0000-7000-8000-000000000704",
 ]);
 const actorIdentity: Record<
   string,