fix(filesystem): reject non-init requests before MCP handshake completes

Currently, the secure-filesystem-server accepts and successfully handles
tools/list (and other requests) before the MCP lifecycle handshake
completes. Per the MCP spec, the only methods a server should accept
pre-handshake are initialize and ping.

The MCP TypeScript SDK does not currently expose a middleware or
pre-dispatch hook for request gating, so we wrap the protocol's internal
request handler map. After all tool registrations have installed
SDK-managed tools/list and tools/call handlers, installHandshakeGate()
replaces each entry except initialize and ping with a wrapper that
throws InvalidRequest until oninitialized has fired.

Add an integration test that exercises both directions:
- tools/list before initialize -> rejected with code -32600
- full initialize -> notifications/initialized -> tools/list -> accepted

Closes #4195

Author: nakshatra-nahar

src/filesystem/__tests__/handshake-gating.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+
+const SERVER_PATH = path.join(__dirname, '..', 'dist', 'index.js');
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id?: number | string;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/**
+ * Minimal stdio JSON-RPC client for tests. Spawns the filesystem server
+ * and exchanges line-delimited JSON messages over stdin/stdout.
+ */
+class StdioRpcClient {
+  private proc: ChildProcessWithoutNullStreams;
+  private buffer = '';
+  private pending: Array<(line: string) => void> = [];
+
+  constructor(args: string[]) {
+    this.proc = spawn('node', [SERVER_PATH, ...args], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.proc.stdout.setEncoding('utf8');
+    this.proc.stdout.on('data', (chunk: string) => {
+      this.buffer += chunk;
+      let newlineIndex: number;
+      while ((newlineIndex = this.buffer.indexOf('\n')) !== -1) {
+        const line = this.buffer.slice(0, newlineIndex).trim();
+        this.buffer = this.buffer.slice(newlineIndex + 1);
+        if (line.length === 0) continue;
+        const resolver = this.pending.shift();
+        if (resolver) resolver(line);
+      }
+    });
+  }
+
+  send(message: object): void {
+    this.proc.stdin.write(JSON.stringify(message) + '\n');
+  }
+
+  async recv(timeoutMs = 2000): Promise<JsonRpcResponse> {
+    const line = await new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`recv timed out after ${timeoutMs}ms`)),
+        timeoutMs,
+      );
+      this.pending.push((received) => {
+        clearTimeout(timer);
+        resolve(received);
+      });
+    });
+    return JSON.parse(line) as JsonRpcResponse;
+  }
+
+  close(): void {
+    this.proc.kill('SIGTERM');
+  }
+}
+
+describe('MCP handshake gating', () => {
+  let allowedDir: string;
+
+  beforeEach(async () => {
+    allowedDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fs-handshake-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(allowedDir, { recursive: true, force: true });
+  });
+
+  it('rejects tools/list with InvalidRequest before initialize handshake', async () => {
+    const client = new StdioRpcClient([allowedDir]);
+    try {
+      client.send({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} });
+      const response = await client.recv();
+
+      expect(response.id).toBe(1);
+      expect(response.result).toBeUndefined();
+      expect(response.error).toBeDefined();
+      expect(response.error?.code).toBe(-32600);
+      expect(response.error?.message).toMatch(/handshake|initialize/i);
+    } finally {
+      client.close();
+    }
+  });
+
+  it('accepts tools/list after completing initialize handshake', async () => {
+    const client = new StdioRpcClient([allowedDir]);
+    try {
+      // 1. initialize request
+      client.send({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'handshake-gating-test', version: '0.0.0' },
+        },
+      });
+      const initResponse = await client.recv();
+      expect(initResponse.result).toBeDefined();
+      expect(initResponse.error).toBeUndefined();
+
+      // 2. notifications/initialized (no response expected)
+      client.send({
+        jsonrpc: '2.0',
+        method: 'notifications/initialized',
+        params: {},
+      });
+
+      // 3. tools/list now allowed
+      client.send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+      const listResponse = await client.recv();
+      expect(listResponse.id).toBe(2);
+      expect(listResponse.error).toBeUndefined();
+      expect(listResponse.result).toBeDefined();
+      const tools = (listResponse.result as { tools: unknown[] }).tools;
+      expect(Array.isArray(tools)).toBe(true);
+      expect(tools.length).toBeGreaterThan(0);
+    } finally {
+      client.close();
+    }
+  });
+});

src/filesystem/index.ts

@@ -4,6 +4,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolResult,
+  ErrorCode,
+  McpError,
   RootsListChangedNotificationSchema,
   type Root,
 } from "@modelcontextprotocol/sdk/types.js";
@@ -167,6 +169,12 @@ const server = new McpServer(
   }
 );
 
+// Tracks whether the MCP lifecycle handshake has completed
+// (initialize request handled + notifications/initialized received).
+// Requests other than `initialize` and `ping` are rejected until this flips
+// to true. See installHandshakeGate() below.
+let handshakeComplete = false;
+
 // Reads a file as a stream of buffers, concatenates them, and then encodes
 // the result to a Base64 string. This is a memory-efficient way to handle
 // binary data from a stream before the final encoding.
@@ -729,6 +737,11 @@ server.server.setNotificationHandler(RootsListChangedNotificationSchema, async (
 
 // Handles post-initialization setup, specifically checking for and fetching MCP roots.
 server.server.oninitialized = async () => {
+  // Mark the handshake complete before any further work so subsequent
+  // requests (including the listRoots() round-trip below) are not blocked
+  // by installHandshakeGate().
+  handshakeComplete = true;
+
   const clientCapabilities = server.server.getClientCapabilities();
 
   if (clientCapabilities?.roots) {
@@ -751,6 +764,49 @@ server.server.oninitialized = async () => {
   }
 };
 
+/**
+ * Install a pre-dispatch gate that rejects requests received before the MCP
+ * lifecycle handshake (initialize request → server response →
+ * notifications/initialized) has completed. Per the MCP spec, the only
+ * methods a server should accept pre-handshake are `initialize` and `ping`.
+ *
+ * The MCP TypeScript SDK does not currently expose a middleware or
+ * pre-dispatch hook, so we wrap the protocol's internal request handler map
+ * here. Each entry except `initialize` and `ping` is replaced with a wrapper
+ * that throws InvalidRequest when `handshakeComplete` is false and otherwise
+ * delegates to the original handler.
+ *
+ * Must be called after all `server.registerTool(...)` calls have run, so
+ * that the SDK-installed `tools/list` and `tools/call` handlers are in the
+ * map and get wrapped.
+ */
+function installHandshakeGate(): void {
+  const ALWAYS_ALLOWED_METHODS = new Set([
+    "initialize", // by definition - this is what completes the handshake
+    "ping",       // health check; allowed pre-handshake per MCP spec
+  ]);
+
+  type ProtocolInternals = {
+    _requestHandlers: Map<string, (req: unknown, extra: unknown) => unknown>;
+  };
+  const handlers = (server.server as unknown as ProtocolInternals)._requestHandlers;
+
+  for (const [method, originalHandler] of handlers) {
+    if (ALWAYS_ALLOWED_METHODS.has(method)) continue;
+    handlers.set(method, async (req: unknown, extra: unknown) => {
+      if (!handshakeComplete) {
+        throw new McpError(
+          ErrorCode.InvalidRequest,
+          "Request received before MCP initialization handshake completed",
+        );
+      }
+      return originalHandler(req, extra);
+    });
+  }
+}
+
+installHandshakeGate();
+
 // Start server
 async function runServer() {
   const transport = new StdioServerTransport();