Add comprehensive documentation for per-session server instances

Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com>

docs/configuration/mcp-settings.mdx

@@ -47,7 +47,8 @@ MCPHub uses several configuration files:
     },
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest", "--headless"]
+      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
+      "perSession": true
     },
     "slack": {
       "command": "npx",
@@ -75,6 +76,42 @@ MCPHub uses several configuration files:
 | Field          | Type    | Default         | Description                 |
 | -------------- | ------- | --------------- | --------------------------- |
 | `env`          | object  | `{}`            | Environment variables       |
+| `perSession`   | boolean | `false`         | Create separate server instance per user session (for stateful servers like playwright) |
+| `enabled`      | boolean | `true`          | Enable/disable the server   |
+| `timeout`      | number  | `60000`         | Request timeout in milliseconds |
+| `keepAliveInterval` | number | `60000`    | Keep-alive ping interval for SSE servers (ms) |
+
+## Per-Session Server Instances
+
+Some MCP servers maintain state that should be isolated between different users. For example, the Playwright server maintains browser sessions that could leak form data or other state between concurrent users.
+
+To prevent this, you can set `perSession: true` in the server configuration. This creates a separate server instance for each user session instead of sharing a single instance across all users.
+
+### When to Use Per-Session Servers
+
+Use `perSession: true` for servers that:
+- Maintain browser state (like Playwright)
+- Store user-specific data in memory
+- Have file handles or database connections that shouldn't be shared
+- Could cause race conditions when multiple users access simultaneously
+
+### Example Configuration
+
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
+    "perSession": true
+  }
+}
+```
+
+**Important Notes:**
+- Each per-session server instance consumes additional resources (memory, CPU)
+- Per-session servers are automatically cleaned up when the user session ends
+- For Playwright, also use the `--isolated` flag to ensure browser contexts are isolated
+- Not recommended for stateless servers that can safely be shared
 
 ## Common MCP Server Examples
 
@@ -101,8 +138,9 @@ MCPHub uses several configuration files:
 {
   "playwright": {
     "command": "npx",
-    "args": ["@playwright/mcp@latest", "--headless"],
+    "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
     "timeout": 60000,
+    "perSession": true,
     "env": {
       "PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
     }
@@ -110,6 +148,8 @@ MCPHub uses several configuration files:
 }
 ```
 
+**Note**: The `--isolated` flag ensures each browser session is isolated, and `perSession: true` creates a separate server instance for each user session, preventing state leakage between concurrent users.
+
 ### File and System Servers
 
 #### Filesystem Server

docs/zh/configuration/mcp-settings.mdx

@@ -50,8 +50,9 @@ MCPHub 使用几个配置文件：
     },
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest", "--headless"],
-      "timeout": 60000
+      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
+      "timeout": 60000,
+      "perSession": true
     },
     "slack": {
       "command": "npx",
@@ -79,13 +80,48 @@ MCPHub 使用几个配置文件：
 | 字段           | 类型    | 默认值          | 描述               |
 | -------------- | ------- | --------------- | ------------------ |
 | `env`          | object  | `{}`            | 环境变量           |
+| `perSession`   | boolean | `false`         | 为每个用户会话创建独立的服务器实例（用于有状态的服务器，如 playwright） |
+| `enabled`      | boolean | `true`          | 启用/禁用服务器    |
+| `timeout`      | number  | `60000`         | 请求超时（毫秒）   |
+| `keepAliveInterval` | number | `60000`    | SSE 服务器的保活 ping 间隔（毫秒） |
 | `cwd`          | string  | `process.cwd()` | 工作目录           |
-| `timeout`      | number  | `30000`         | 启动超时（毫秒）   |
 | `restart`      | boolean | `true`          | 失败时自动重启     |
 | `maxRestarts`  | number  | `5`             | 最大重启次数       |
 | `restartDelay` | number  | `5000`          | 重启间延迟（毫秒） |
 | `stdio`        | string  | `pipe`          | stdio 配置         |
 
+## 会话隔离的服务器实例
+
+某些 MCP 服务器会维护应该在不同用户之间隔离的状态。例如，Playwright 服务器维护可能在并发用户之间泄漏表单数据或其他状态的浏览器会话。
+
+为了防止这种情况，您可以在服务器配置中设置 `perSession: true`。这将为每个用户会话创建一个单独的服务器实例，而不是在所有用户之间共享单个实例。
+
+### 何时使用会话隔离的服务器
+
+对于以下服务器使用 `perSession: true`：
+- 维护浏览器状态（如 Playwright）
+- 在内存中存储用户特定数据
+- 具有不应共享的文件句柄或数据库连接
+- 当多个用户同时访问时可能导致竞争条件
+
+### 示例配置
+
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
+    "perSession": true
+  }
+}
+```
+
+**重要提示：**
+- 每个会话隔离的服务器实例都会消耗额外的资源（内存、CPU）
+- 会话隔离的服务器在用户会话结束时会自动清理
+- 对于 Playwright，还要使用 `--isolated` 标志以确保浏览器上下文被隔离
+- 不建议用于可以安全共享的无状态服务器
+
 ## 常见 MCP 服务器示例
 
 ### Web 和 API 服务器
@@ -111,8 +147,9 @@ MCPHub 使用几个配置文件：
 {
   "playwright": {
     "command": "npx",
-    "args": ["@playwright/mcp@latest", "--headless"],
+    "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
     "timeout": 60000,
+    "perSession": true,
     "env": {
       "PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
     }
@@ -120,6 +157,8 @@ MCPHub 使用几个配置文件：
 }
 ```
 
+**注意**: `--isolated` 标志确保每个浏览器会话是隔离的，而 `perSession: true` 为每个用户会话创建单独的服务器实例，防止并发用户之间的状态泄漏。
+
 ### 文件和系统服务器
 
 #### 文件系统服务器

mcp_settings.json

@@ -14,8 +14,10 @@
       "command": "npx",
       "args": [
         "@playwright/mcp@latest",
-        "--headless"
-      ]
+        "--headless",
+        "--isolated"
+      ],
+      "perSession": true
     },
     "fetch": {
       "command": "uvx",

src/services/mcpService.ts

@@ -24,6 +24,10 @@ import { getServerDao, ServerConfigWithName } from '../dao/index.js';
 
 const servers: { [sessionId: string]: Server } = {};
 
+// Per-session server instances for servers with perSession=true
+// Key format: `${sessionId}:${serverName}`
+const perSessionServerInfos: { [key: string]: ServerInfo } = {};
+
 const serverDao = getServerDao();
 
 // Helper function to set up keep-alive ping for SSE connections
@@ -79,6 +83,8 @@ export const getMcpServer = (sessionId?: string, group?: string): Server => {
 
 export const deleteMcpServer = (sessionId: string): void => {
   delete servers[sessionId];
+  // Clean up any per-session servers for this session
+  cleanupPerSessionServers(sessionId);
 };
 
 export const notifyToolChanged = async (name?: string) => {
@@ -223,6 +229,144 @@ const createTransportFromConfig = (name: string, conf: ServerConfig): any => {
   return transport;
 };
 
+// Helper function to get or create per-session server instance
+export const getOrCreatePerSessionServer = async (
+  sessionId: string,
+  serverName: string,
+  serverConfig: ServerConfig,
+): Promise<ServerInfo> => {
+  const key = `${sessionId}:${serverName}`;
+  
+  // Return existing session server if it exists
+  if (perSessionServerInfos[key]) {
+    return perSessionServerInfos[key];
+  }
+
+  console.log(`Creating per-session server instance for session ${sessionId}, server ${serverName}`);
+
+  // Create new transport for this session
+  const transport = createTransportFromConfig(serverName, serverConfig);
+
+  const client = new Client(
+    {
+      name: `mcp-client-${serverName}-${sessionId}`,
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        prompts: {},
+        resources: {},
+        tools: {},
+      },
+    },
+  );
+
+  // Get request options from server configuration, with fallbacks
+  const serverRequestOptions = serverConfig.options || {};
+  const requestOptions = {
+    timeout: serverRequestOptions.timeout || 60000,
+    resetTimeoutOnProgress: serverRequestOptions.resetTimeoutOnProgress || false,
+    maxTotalTimeout: serverRequestOptions.maxTotalTimeout,
+  };
+
+  // Create server info for this session
+  const serverInfo: ServerInfo = {
+    name: serverName,
+    owner: serverConfig.owner,
+    status: 'connecting',
+    error: null,
+    tools: [],
+    prompts: [],
+    client,
+    transport,
+    options: requestOptions,
+    createTime: Date.now(),
+    config: serverConfig,
+    sessionId: sessionId,
+  };
+  
+  perSessionServerInfos[key] = serverInfo;
+
+  // Connect asynchronously
+  client
+    .connect(transport, requestOptions)
+    .then(() => {
+      console.log(`Successfully connected per-session client for server: ${serverName}, session: ${sessionId}`);
+      const capabilities = client.getServerCapabilities();
+      
+      if (capabilities?.tools) {
+        client
+          .listTools({}, requestOptions)
+          .then((tools) => {
+            console.log(`Successfully listed ${tools.tools.length} tools for per-session server: ${serverName}, session: ${sessionId}`);
+            serverInfo.tools = tools.tools.map((tool) => ({
+              name: `${serverName}${getNameSeparator()}${tool.name}`,
+              description: tool.description || '',
+              inputSchema: cleanInputSchema(tool.inputSchema || {}),
+            }));
+          })
+          .catch((error) => {
+            console.error(`Failed to list tools for per-session server ${serverName}, session ${sessionId}:`, error);
+          });
+      }
+
+      if (capabilities?.prompts) {
+        client
+          .listPrompts({}, requestOptions)
+          .then((prompts) => {
+            console.log(`Successfully listed ${prompts.prompts.length} prompts for per-session server: ${serverName}, session: ${sessionId}`);
+            serverInfo.prompts = prompts.prompts.map((prompt) => ({
+              name: `${serverName}${getNameSeparator()}${prompt.name}`,
+              title: prompt.title,
+              description: prompt.description,
+              arguments: prompt.arguments,
+            }));
+          })
+          .catch((error) => {
+            console.error(`Failed to list prompts for per-session server ${serverName}, session ${sessionId}:`, error);
+          });
+      }
+
+      serverInfo.status = 'connected';
+      serverInfo.error = null;
+    })
+    .catch((error) => {
+      console.error(`Failed to connect per-session client for server ${serverName}, session ${sessionId}:`, error);
+      serverInfo.status = 'disconnected';
+      serverInfo.error = `Failed to connect: ${error.stack}`;
+    });
+
+  return serverInfo;
+};
+
+// Helper function to clean up per-session servers for a session
+export const cleanupPerSessionServers = (sessionId: string): void => {
+  const keysToDelete: string[] = [];
+  
+  for (const key in perSessionServerInfos) {
+    if (key.startsWith(`${sessionId}:`)) {
+      const serverInfo = perSessionServerInfos[key];
+      try {
+        if (serverInfo.client) {
+          serverInfo.client.close();
+        }
+        if (serverInfo.transport) {
+          serverInfo.transport.close();
+        }
+        if (serverInfo.keepAliveIntervalId) {
+          clearInterval(serverInfo.keepAliveIntervalId);
+        }
+      } catch (error) {
+        console.warn(`Error closing per-session server ${key}:`, error);
+      }
+      keysToDelete.push(key);
+    }
+  }
+  
+  keysToDelete.forEach(key => delete perSessionServerInfos[key]);
+  console.log(`Cleaned up ${keysToDelete.length} per-session servers for session ${sessionId}`);
+};
+
 // Helper function to handle client.callTool with reconnection logic
 const callToolWithReconnect = async (
   serverInfo: ServerInfo,
@@ -625,6 +769,45 @@ export const getServerByName = (name: string): ServerInfo | undefined => {
   return serverInfos.find((serverInfo) => serverInfo.name === name);
 };
 
+// Get server by name with session support (for per-session servers)
+const getServerByNameWithSession = async (name: string, sessionId?: string): Promise<ServerInfo | undefined> => {
+  // First check if this server is configured for per-session instances
+  const serverConfig = await serverDao.findById(name);
+  
+  if (serverConfig?.perSession && sessionId) {
+    // Try to get or create per-session server
+    const key = `${sessionId}:${name}`;
+    if (perSessionServerInfos[key]) {
+      return perSessionServerInfos[key];
+    }
+    // Create new per-session server instance
+    return await getOrCreatePerSessionServer(sessionId, name, serverConfig);
+  }
+  
+  // Fall back to shared server
+  return serverInfos.find((serverInfo) => serverInfo.name === name && !serverInfo.sessionId);
+};
+
+// Get server by tool name with session support (for per-session servers)
+const getServerByToolWithSession = async (toolName: string, sessionId?: string): Promise<ServerInfo | undefined> => {
+  // First try to find in per-session servers if sessionId is provided
+  if (sessionId) {
+    for (const key in perSessionServerInfos) {
+      if (key.startsWith(`${sessionId}:`)) {
+        const serverInfo = perSessionServerInfos[key];
+        if (serverInfo.tools.some((tool) => tool.name === toolName)) {
+          return serverInfo;
+        }
+      }
+    }
+  }
+  
+  // Fall back to shared servers
+  return serverInfos.find((serverInfo) => 
+    !serverInfo.sessionId && serverInfo.tools.some((tool) => tool.name === toolName)
+  );
+};
+
 // Filter tools by server configuration
 const filterToolsByConfig = async (serverName: string, tools: Tool[]): Promise<Tool[]> => {
   const serverConfig = await serverDao.findById(serverName);
@@ -640,8 +823,8 @@ const filterToolsByConfig = async (serverName: string, tools: Tool[]): Promise<T
   });
 };
 
-// Get server by tool name
-const getServerByTool = (toolName: string): ServerInfo | undefined => {
+// Get server by tool name (legacy - use getServerByToolWithSession instead)
+const _getServerByTool = (toolName: string): ServerInfo | undefined => {
   return serverInfos.find((serverInfo) => serverInfo.tools.some((tool) => tool.name === toolName));
 };
 
@@ -826,15 +1009,35 @@ Available servers: ${serversList}`;
     };
   }
 
-  const allServerInfos = getDataService()
+  // Get shared servers
+  let allServerInfos = getDataService()
     .filterData(serverInfos)
     .filter((serverInfo) => {
+      if (serverInfo.enabled === false) return false;
+      if (serverInfo.sessionId) return false; // Exclude per-session servers from shared list
+      if (!group) return true;
+      const serversInGroup = getServersInGroup(group);
+      if (!serversInGroup || serversInGroup.length === 0) return serverInfo.name === group;
+      return serversInGroup.includes(serverInfo.name);
+    });
+
+  // Add per-session servers for this session
+  if (sessionId) {
+    const sessionServers = Object.values(perSessionServerInfos).filter(
+      (serverInfo) => serverInfo.sessionId === sessionId && serverInfo.status === 'connected'
+    );
+    
+    // Filter session servers by group if applicable
+    const filteredSessionServers = sessionServers.filter((serverInfo) => {
       if (serverInfo.enabled === false) return false;
       if (!group) return true;
       const serversInGroup = getServersInGroup(group);
       if (!serversInGroup || serversInGroup.length === 0) return serverInfo.name === group;
       return serversInGroup.includes(serverInfo.name);
     });
+    
+    allServerInfos = [...allServerInfos, ...filteredSessionServers];
+  }
 
   const allTools = [];
   for (const serverInfo of allServerInfos) {
@@ -998,17 +1201,13 @@ export const handleCallToolRequest = async (request: any, extra: any) => {
       }
 
       const { arguments: toolArgs = {} } = request.params.arguments || {};
+      const sessionId = extra?.sessionId;
       let targetServerInfo: ServerInfo | undefined;
       if (extra && extra.server) {
-        targetServerInfo = getServerByName(extra.server);
+        targetServerInfo = await getServerByNameWithSession(extra.server, sessionId);
       } else {
-        // Find the first server that has this tool
-        targetServerInfo = serverInfos.find(
-          (serverInfo) =>
-            serverInfo.status === 'connected' &&
-            serverInfo.enabled !== false &&
-            serverInfo.tools.some((tool) => tool.name === toolName),
-        );
+        // Find the first server that has this tool (session-aware)
+        targetServerInfo = await getServerByToolWithSession(toolName, sessionId);
       }
 
       if (!targetServerInfo) {
@@ -1114,7 +1313,8 @@ export const handleCallToolRequest = async (request: any, extra: any) => {
     }
 
     // Regular tool handling
-    const serverInfo = getServerByTool(request.params.name);
+    const sessionId = extra?.sessionId;
+    const serverInfo = await getServerByToolWithSession(request.params.name, sessionId);
     if (!serverInfo) {
       throw new Error(`Server not found: ${request.params.name}`);
     }

src/types/index.ts

@@ -178,6 +178,7 @@ export interface ServerConfig {
   enabled?: boolean; // Flag to enable/disable the server
   owner?: string; // Owner of the server, defaults to 'admin' user
   keepAliveInterval?: number; // Keep-alive ping interval in milliseconds (default: 60000ms for SSE servers)
+  perSession?: boolean; // If true, creates a separate server instance for each session (useful for stateful servers like playwright)
   tools?: Record<string, { enabled: boolean; description?: string }>; // Tool-specific configurations with enable/disable state and custom descriptions
   prompts?: Record<string, { enabled: boolean; description?: string }>; // Prompt-specific configurations with enable/disable state and custom descriptions
   options?: Partial<Pick<RequestOptions, 'timeout' | 'resetTimeoutOnProgress' | 'maxTotalTimeout'>>; // MCP request options configuration
@@ -239,6 +240,7 @@ export interface ServerInfo {
   enabled?: boolean; // Flag to indicate if the server is enabled
   keepAliveIntervalId?: NodeJS.Timeout; // Timer ID for keep-alive ping interval
   config?: ServerConfig; // Reference to the original server configuration for OpenAPI passthrough headers
+  sessionId?: string; // Session ID for per-session server instances (undefined for shared servers)
 }
 
 // Details about a tool available on the server

tests/services/perSessionServers.test.ts

@@ -0,0 +1,111 @@
+import {
+  getOrCreatePerSessionServer,
+  cleanupPerSessionServers,
+} from '../../src/services/mcpService';
+import { ServerConfig } from '../../src/types';
+
+// Mock the serverDao
+jest.mock('../../src/dao/index.js', () => ({
+  getServerDao: () => ({
+    findById: jest.fn((name: string) => {
+      if (name === 'playwright') {
+        return Promise.resolve({
+          name: 'playwright',
+          command: 'npx',
+          args: ['@playwright/mcp@latest', '--headless', '--isolated'],
+          perSession: true,
+          enabled: true,
+        });
+      }
+      return Promise.resolve(null);
+    }),
+    findAll: jest.fn(() => Promise.resolve([])),
+  }),
+}));
+
+// Mock the Client and Transport classes
+jest.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: jest.fn().mockImplementation(() => ({
+    connect: jest.fn(() => Promise.resolve()),
+    close: jest.fn(),
+    listTools: jest.fn(() => Promise.resolve({ tools: [] })),
+    listPrompts: jest.fn(() => Promise.resolve({ prompts: [] })),
+    getServerCapabilities: jest.fn(() => ({ tools: true, prompts: true })),
+    callTool: jest.fn((params) => Promise.resolve({ content: [{ type: 'text', text: `Tool ${params.name} called` }] })),
+  })),
+}));
+
+jest.mock('@modelcontextprotocol/sdk/client/stdio.js', () => ({
+  StdioClientTransport: jest.fn().mockImplementation(() => ({
+    close: jest.fn(),
+    stderr: {
+      on: jest.fn(),
+    },
+  })),
+}));
+
+describe('Per-Session Server Instances', () => {
+  afterEach(() => {
+    // Clean up any created sessions
+    cleanupPerSessionServers('session1');
+    cleanupPerSessionServers('session2');
+  });
+
+  it('should create separate server instances for different sessions', async () => {
+    const config: ServerConfig = {
+      command: 'npx',
+      args: ['@playwright/mcp@latest', '--headless', '--isolated'],
+      perSession: true,
+    };
+
+    // Create server for session1
+    const server1 = await getOrCreatePerSessionServer('session1', 'playwright', config);
+    expect(server1).toBeDefined();
+    expect(server1.sessionId).toBe('session1');
+
+    // Create server for session2
+    const server2 = await getOrCreatePerSessionServer('session2', 'playwright', config);
+    expect(server2).toBeDefined();
+    expect(server2.sessionId).toBe('session2');
+
+    // They should be different instances
+    expect(server1).not.toBe(server2);
+  });
+
+  it('should reuse existing per-session server for the same session', async () => {
+    const config: ServerConfig = {
+      command: 'npx',
+      args: ['@playwright/mcp@latest', '--headless', '--isolated'],
+      perSession: true,
+    };
+
+    // Create server for session1
+    const server1 = await getOrCreatePerSessionServer('session1', 'playwright', config);
+    
+    // Request the same server again
+    const server2 = await getOrCreatePerSessionServer('session1', 'playwright', config);
+
+    // Should be the same instance
+    expect(server1).toBe(server2);
+  });
+
+  it('should clean up per-session servers when session ends', async () => {
+    const config: ServerConfig = {
+      command: 'npx',
+      args: ['@playwright/mcp@latest', '--headless', '--isolated'],
+      perSession: true,
+    };
+
+    // Create server for session1
+    const server1 = await getOrCreatePerSessionServer('session1', 'playwright', config);
+    expect(server1).toBeDefined();
+
+    // Clean up session1
+    cleanupPerSessionServers('session1');
+
+    // Create again should create a new instance (not the same object)
+    const server2 = await getOrCreatePerSessionServer('session1', 'playwright', config);
+    expect(server2).toBeDefined();
+    expect(server2).not.toBe(server1);
+  });
+});