@goonnguyen/human-mcp 1.0.2 → 1.2.0

package/src/index.ts

@@ -1,5 +1,47 @@
 #!/usr/bin/env bun
 
-import { startStdioServer } from "./server.js";
+import { createServer } from "./server.js";
+import { TransportManager } from "./transports/index.js";
+import { loadConfig } from "./utils/config.js";
+import { logger } from "./utils/logger.js";
 
-await startStdioServer();
+async function main() {
+  try {
+    const config = loadConfig();
+    const server = await createServer();
+    
+    const transportConfig = {
+      type: config.transport.type,
+      http: config.transport.http?.enabled ? {
+        port: config.transport.http.port,
+        host: config.transport.http.host,
+        sessionMode: config.transport.http.sessionMode,
+        enableSse: config.transport.http.enableSse,
+        enableJsonResponse: config.transport.http.enableJsonResponse,
+        security: config.transport.http.security
+      } : undefined
+    };
+    
+    const transportManager = new TransportManager(server, transportConfig);
+    await transportManager.start();
+    
+    logger.info(`Human MCP Server started with ${config.transport.type} transport`);
+    
+    // Graceful shutdown
+    process.on('SIGINT', async () => {
+      logger.info('Shutting down server...');
+      process.exit(0);
+    });
+    
+    process.on('SIGTERM', async () => {
+      logger.info('Shutting down server...');
+      process.exit(0);
+    });
+    
+  } catch (error) {
+    logger.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/transports/http/middleware.ts

@@ -0,0 +1,46 @@
+import type { Request, Response, NextFunction } from "express";
+import type { SecurityConfig } from "../types.js";
+
+export function createSecurityMiddleware(config?: SecurityConfig) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    // DNS Rebinding Protection
+    if (config?.enableDnsRebindingProtection) {
+      const host = req.headers.host?.split(':')[0];
+      const allowedHosts = config.allowedHosts || ['127.0.0.1', 'localhost'];
+      
+      if (host && !allowedHosts.includes(host)) {
+        res.status(403).json({
+          error: 'Forbidden: Invalid host'
+        });
+        return;
+      }
+    }
+
+    // Rate Limiting (basic implementation)
+    if (config?.enableRateLimiting) {
+      // Implement rate limiting logic here
+      // Could use express-rate-limit package
+    }
+
+    // Secret-based authentication (optional)
+    if (config?.secret) {
+      const authHeader = req.headers.authorization;
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        res.status(401).json({
+          error: 'Unauthorized: Missing authentication'
+        });
+        return;
+      }
+      
+      const token = authHeader.substring(7);
+      if (token !== config.secret) {
+        res.status(401).json({
+          error: 'Unauthorized: Invalid token'
+        });
+        return;
+      }
+    }
+
+    next();
+  };
+}

package/src/transports/http/routes.ts

@@ -0,0 +1,136 @@
+import { Router } from "express";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { SessionManager } from "./session.js";
+import type { HttpTransportConfig } from "../types.js";
+
+export function createRoutes(
+  mcpServer: McpServer,
+  sessionManager: SessionManager,
+  config: HttpTransportConfig
+): Router {
+  const router = Router();
+
+  // POST /mcp - Handle client requests
+  router.post('/', async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+      
+      if (config.sessionMode === 'stateless') {
+        await handleStatelessRequest(mcpServer, req, res);
+      } else {
+        await handleStatefulRequest(mcpServer, sessionManager, sessionId, req, res);
+      }
+    } catch (error) {
+      handleError(res, error);
+    }
+  });
+
+  // GET /mcp - SSE endpoint for notifications
+  router.get('/', async (req, res) => {
+    if (config.sessionMode === 'stateless') {
+      res.status(405).json({
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "SSE not supported in stateless mode"
+        },
+        id: null
+      });
+      return;
+    }
+
+    const sessionId = req.headers['mcp-session-id'] as string;
+    const transport = await sessionManager.getTransport(sessionId);
+    
+    if (!transport) {
+      res.status(400).send('Invalid or missing session ID');
+      return;
+    }
+
+    await transport.handleRequest(req, res);
+  });
+
+  // DELETE /mcp - Session termination
+  router.delete('/', async (req, res) => {
+    if (config.sessionMode === 'stateless') {
+      res.status(405).json({
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "Session termination not applicable in stateless mode"
+        },
+        id: null
+      });
+      return;
+    }
+
+    const sessionId = req.headers['mcp-session-id'] as string;
+    await sessionManager.terminateSession(sessionId);
+    res.status(204).send();
+  });
+
+  return router;
+}
+
+async function handleStatelessRequest(
+  mcpServer: McpServer,
+  req: any,
+  res: any
+): Promise<void> {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+
+  res.on('close', () => {
+    transport.close();
+  });
+
+  await mcpServer.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+}
+
+async function handleStatefulRequest(
+  mcpServer: McpServer,
+  sessionManager: SessionManager,
+  sessionId: string | undefined,
+  req: any,
+  res: any
+): Promise<void> {
+  let transport = sessionId ? 
+    await sessionManager.getTransport(sessionId) : null;
+
+  if (!transport && isInitializeRequest(req.body)) {
+    const session = await sessionManager.createSession(mcpServer);
+    transport = session.transport;
+    res.setHeader('Mcp-Session-Id', session.sessionId);
+  } else if (!transport) {
+    res.status(400).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Bad Request: No valid session ID provided',
+      },
+      id: null,
+    });
+    return;
+  }
+
+  await transport.handleRequest(req, res, req.body);
+}
+
+function handleError(res: any, error: any): void {
+  console.error('MCP request error:', error);
+  if (!res.headersSent) {
+    res.status(500).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32603,
+        message: 'Internal server error',
+      },
+      id: null,
+    });
+  }
+}

package/src/transports/http/server.ts

@@ -0,0 +1,66 @@
+import express from "express";
+import cors from "cors";
+import compression from "compression";
+import helmet from "helmet";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createRoutes } from "./routes.js";
+import { SessionManager } from "./session.js";
+import { createSecurityMiddleware } from "./middleware.js";
+import type { HttpTransportConfig } from "../types.js";
+
+export async function startHttpTransport(
+  mcpServer: McpServer,
+  config: HttpTransportConfig
+): Promise<void> {
+  const app = express();
+  const sessionManager = new SessionManager(config.sessionMode, config);
+
+  // Apply middleware
+  app.use(express.json({ limit: '50mb' }));
+  app.use(compression());
+  app.use(helmet({
+    contentSecurityPolicy: false, // Disable CSP for API server
+    crossOriginEmbedderPolicy: false
+  }));
+  
+  if (config.security?.enableCors !== false) {
+    app.use(cors({
+      origin: config.security?.corsOrigins || '*',
+      exposedHeaders: ['Mcp-Session-Id'],
+      allowedHeaders: ['Content-Type', 'mcp-session-id'],
+      credentials: true
+    }));
+  }
+
+  app.use(createSecurityMiddleware(config.security));
+
+  // Create routes
+  const routes = createRoutes(mcpServer, sessionManager, config);
+  app.use('/mcp', routes);
+
+  // Health check endpoint
+  app.get('/health', (req, res) => {
+    res.json({ status: 'healthy', transport: 'streamable-http' });
+  });
+
+  // Start server
+  const port = config.port || 3000;
+  const host = config.host || '0.0.0.0';
+  
+  app.listen(port, host, () => {
+    console.log(`MCP HTTP Server listening on http://${host}:${port}`);
+    console.log(`Health check: http://${host}:${port}/health`);
+    console.log(`MCP endpoint: http://${host}:${port}/mcp`);
+  });
+
+  // Graceful shutdown handling
+  process.on('SIGTERM', async () => {
+    console.log('Shutting down HTTP server...');
+    await sessionManager.cleanup();
+  });
+
+  process.on('SIGINT', async () => {
+    console.log('Shutting down HTTP server...');
+    await sessionManager.cleanup();
+  });
+}

package/src/transports/http/session.ts

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { SessionStore, TransportSession, HttpTransportConfig } from "../types.js";
+
+export class SessionManager {
+  private transports: Map<string, StreamableHTTPServerTransport>;
+  private sessionMode: 'stateful' | 'stateless';
+  private store?: SessionStore;
+  private config: HttpTransportConfig;
+
+  constructor(sessionMode: 'stateful' | 'stateless', config: HttpTransportConfig, store?: SessionStore) {
+    this.transports = new Map();
+    this.sessionMode = sessionMode;
+    this.config = config;
+    this.store = store;
+  }
+
+  async createSession(mcpServer: McpServer): Promise<{ transport: StreamableHTTPServerTransport, sessionId: string }> {
+    const sessionId = randomUUID();
+    
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => sessionId,
+      enableJsonResponse: this.config.enableJsonResponse,
+      enableDnsRebindingProtection: this.config.security?.enableDnsRebindingProtection ?? true,
+      allowedHosts: this.config.security?.allowedHosts ?? ['127.0.0.1', 'localhost'],
+    });
+
+    // Store the transport by the generated session ID
+    this.transports.set(sessionId, transport);
+    
+    transport.onclose = () => {
+      this.terminateSession(sessionId);
+    };
+
+    if (this.store) {
+      await this.store.set(sessionId, {
+        id: sessionId,
+        createdAt: Date.now(),
+        transport: transport
+      });
+    }
+
+    await mcpServer.connect(transport);
+    
+    return { transport, sessionId };
+  }
+
+  async getTransport(sessionId: string): Promise<StreamableHTTPServerTransport | null> {
+    let transport = this.transports.get(sessionId);
+    
+    if (!transport && this.store) {
+      const session = await this.store.get(sessionId);
+      if (session && session.transport) {
+        transport = session.transport;
+        this.transports.set(sessionId, transport);
+      }
+    }
+    
+    return transport || null;
+  }
+
+  async terminateSession(sessionId: string): Promise<void> {
+    const transport = this.transports.get(sessionId);
+    if (transport) {
+      transport.close();
+      this.transports.delete(sessionId);
+    }
+    
+    if (this.store) {
+      await this.store.delete(sessionId);
+    }
+  }
+
+  async cleanup(): Promise<void> {
+    for (const [sessionId, transport] of this.transports) {
+      transport.close();
+    }
+    this.transports.clear();
+    
+    if (this.store) {
+      await this.store.cleanup();
+    }
+  }
+}

package/src/transports/index.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { startStdioTransport } from "./stdio.js";
+import { startHttpTransport } from "./http/server.js";
+import type { TransportConfig } from "./types.js";
+
+export class TransportManager {
+  private server: McpServer;
+  private config: TransportConfig;
+
+  constructor(server: McpServer, config: TransportConfig) {
+    this.server = server;
+    this.config = config;
+  }
+
+  async start(): Promise<void> {
+    switch (this.config.type) {
+      case 'stdio':
+        await startStdioTransport(this.server);
+        break;
+      case 'http':
+        await startHttpTransport(this.server, this.config.http!);
+        break;
+      case 'both':
+        await Promise.all([
+          startStdioTransport(this.server),
+          startHttpTransport(this.server, this.config.http!)
+        ]);
+        break;
+    }
+  }
+}

package/src/transports/stdio.ts

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+export async function startStdioTransport(server: McpServer): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/transports/types.ts

@@ -0,0 +1,37 @@
+import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+export interface TransportConfig {
+  type: 'stdio' | 'http' | 'both';
+  http?: HttpTransportConfig;
+}
+
+export interface HttpTransportConfig {
+  port: number;
+  host?: string;
+  sessionMode: 'stateful' | 'stateless';
+  enableSse?: boolean;
+  enableJsonResponse?: boolean;
+  security?: SecurityConfig;
+}
+
+export interface SecurityConfig {
+  enableCors?: boolean;
+  corsOrigins?: string[];
+  enableDnsRebindingProtection?: boolean;
+  allowedHosts?: string[];
+  enableRateLimiting?: boolean;
+  secret?: string;
+}
+
+export interface TransportSession {
+  id: string;
+  createdAt: number;
+  transport: StreamableHTTPServerTransport;
+}
+
+export interface SessionStore {
+  get(sessionId: string): Promise<TransportSession | null>;
+  set(sessionId: string, session: TransportSession): Promise<void>;
+  delete(sessionId: string): Promise<void>;
+  cleanup(): Promise<void>;
+}

package/src/utils/config.ts

@@ -5,6 +5,25 @@ const ConfigSchema = z.object({
     apiKey: z.string().min(1, "Google Gemini API key is required"),
     model: z.string().default("gemini-2.5-flash"),
   }),
+  transport: z.object({
+    type: z.enum(["stdio", "http", "both"]).default("stdio"),
+    http: z.object({
+      enabled: z.boolean().default(false),
+      port: z.number().default(3000),
+      host: z.string().default("0.0.0.0"),
+      sessionMode: z.enum(["stateful", "stateless"]).default("stateful"),
+      enableSse: z.boolean().default(true),
+      enableJsonResponse: z.boolean().default(true),
+      security: z.object({
+        enableCors: z.boolean().default(true),
+        corsOrigins: z.array(z.string()).optional(),
+        enableDnsRebindingProtection: z.boolean().default(true),
+        allowedHosts: z.array(z.string()).default(["127.0.0.1", "localhost"]),
+        enableRateLimiting: z.boolean().default(false),
+        secret: z.string().optional(),
+      }).optional(),
+    }).optional(),
+  }),
   server: z.object({
     port: z.number().default(3000),
     maxRequestSize: z.string().default("50MB"),
@@ -26,11 +45,38 @@ const ConfigSchema = z.object({
 export type Config = z.infer<typeof ConfigSchema>;
 
 export function loadConfig(): Config {
+  const corsOrigins = process.env.HTTP_CORS_ORIGINS ? 
+    process.env.HTTP_CORS_ORIGINS.split(',').map(origin => origin.trim()) : 
+    undefined;
+  
+  const allowedHosts = process.env.HTTP_ALLOWED_HOSTS ? 
+    process.env.HTTP_ALLOWED_HOSTS.split(',').map(host => host.trim()) : 
+    ["127.0.0.1", "localhost"];
+
   return ConfigSchema.parse({
     gemini: {
       apiKey: process.env.GOOGLE_GEMINI_API_KEY || "",
       model: process.env.GOOGLE_GEMINI_MODEL || "gemini-2.5-flash",
     },
+    transport: {
+      type: (process.env.TRANSPORT_TYPE as any) || "stdio",
+      http: {
+        enabled: process.env.TRANSPORT_TYPE === "http" || process.env.TRANSPORT_TYPE === "both",
+        port: parseInt(process.env.HTTP_PORT || "3000"),
+        host: process.env.HTTP_HOST || "0.0.0.0",
+        sessionMode: (process.env.HTTP_SESSION_MODE as any) || "stateful",
+        enableSse: process.env.HTTP_ENABLE_SSE !== "false",
+        enableJsonResponse: process.env.HTTP_ENABLE_JSON_RESPONSE !== "false",
+        security: {
+          enableCors: process.env.HTTP_CORS_ENABLED !== "false",
+          corsOrigins,
+          enableDnsRebindingProtection: process.env.HTTP_DNS_REBINDING_ENABLED !== "false",
+          allowedHosts,
+          enableRateLimiting: process.env.HTTP_ENABLE_RATE_LIMITING === "true",
+          secret: process.env.HTTP_SECRET,
+        },
+      },
+    },
     server: {
       port: parseInt(process.env.PORT || "3000"),
       maxRequestSize: process.env.MAX_REQUEST_SIZE || "50MB",