@imenam/mcp-http-gateway 2.0.1 → 2.0.4

package/README.md

@@ -196,6 +196,75 @@ L'agent découvre d'abord les MCPs disponibles, explore les outils d'un MCP si b
 
 ---
 
+## Mode MCP distant (HTTPS / Claude.ai)
+
+Le gateway expose également un **endpoint MCP natif** sur `/mcp` via le transport **Streamable HTTP** (sessions `mcp-session-id`). Ce mode permet à Claude.ai — et à tout client MCP distant compatible — de se connecter directement au gateway, sans intermédiaire.
+
+### Flow
+
+```
+Claude.ai
+    │  HTTPS + Bearer JWT
+    ▼
+[mcp-http-gateway /mcp]  ──── 401 + WWW-Authenticate si non authentifié
+    │
+    │  (découverte OAuth 2.1)
+    ▼
+[Authorization Server externe]  (Auth0, Keycloak, Authentik, Zitadel, Logto…)
+```
+
+Le gateway agit uniquement comme **Resource Server** : il valide les JWT via JWKS et expose l'URL de l'AS via le Protected Resource Metadata (RFC 9728). Toute la logique OAuth (DCR, PKCE, `/authorize`, `/token`) est déléguée à l'AS externe.
+
+### Variables d'environnement
+
+| Variable | Description |
+|---|---|
+| `MCP_OAUTH_ENABLED` | `true` pour activer la protection OAuth (recommandé en production) |
+| `MCP_PUBLIC_URL` | URL publique canonique du endpoint — ex. `https://gateway.example.com/mcp`. Utilisée comme `resource` (RFC 9728) et `aud` JWT. |
+| `OAUTH_JWKS_URI` | URI du JWKS de l'Authorization Server — ex. `https://your-auth-server/.well-known/jwks.json` |
+| `OAUTH_ISSUER` | Issuer attendu dans les JWT — ex. `https://your-auth-server` |
+
+> Sans `MCP_OAUTH_ENABLED=true`, `/mcp` est ouvert (utile pour les tests locaux). Claude.ai refusera cependant de s'y connecter sans 401 + `WWW-Authenticate`.
+
+### Configuration Claude.ai
+
+Dans Claude.ai → **Paramètres → Connecteurs** → Ajouter un connecteur MCP :
+
+```
+URL : https://gateway.example.com/mcp
+Authentification : OAuth (auto-détectée via /.well-known/oauth-protected-resource)
+```
+
+### Prérequis côté Authorization Server
+
+L'AS doit supporter :
+- **DCR** (RFC 7591) — `registration_endpoint` exposé
+- **PKCE S256** — `code_challenge_methods_supported: ["S256"]`
+- `redirect_uri` autorisé : `https://claude.ai/api/mcp/auth_callback`
+- JWT signés (RS256 ou ES256) avec claims `iss`, `aud=MCP_PUBLIC_URL`, `exp`
+
+### Exposition HTTPS publique
+
+Le endpoint `/mcp` doit être accessible depuis l'IP range `160.79.104.0/21` (Anthropic) en HTTPS. Options :
+
+| Option | Commande / Notes |
+|---|---|
+| **Cloudflare Tunnel** | `cloudflared tunnel --url http://localhost:3500` |
+| **ngrok** | `ngrok http 3500` — idéal pour les tests |
+| **Reverse-proxy** | Caddy / Traefik en frontal avec cert Let's Encrypt |
+
+### Outils exposés
+
+Les mêmes 3 outils que le mode stdio — avec accès direct aux clients MCP internes (sans repasser par HTTP) :
+
+| Outil | Description |
+|---|---|
+| `list_mcps` | Liste les MCPs disponibles avec leur route et description |
+| `list_tools` | Liste les outils d'un MCP donné (`route` requis) |
+| `call_tool` | Appelle un outil (`route`, `tool_name`, `arguments`) |
+
+---
+
 ## Ajouter un MCP
 
 1. Ajouter l'entrée dans `config/mcp-servers.json` avec `MCP_SERVER_ROUTE` dans `env`

package/auth.js

@@ -0,0 +1,43 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const OAUTH_ENABLED = process.env.MCP_OAUTH_ENABLED === 'true';
+
+let JWKS;
+if (OAUTH_ENABLED) {
+  JWKS = createRemoteJWKSet(new URL(process.env.OAUTH_JWKS_URI));
+}
+
+export function createMcpTokenVerifier() {
+  if (!OAUTH_ENABLED) return null;
+  return {
+    async verifyAccessToken(token) {
+      let payload;
+      try {
+        const issuer = process.env.OAUTH_ISSUER?.replace(/\/*$/, '/');
+        ({ payload } = await jwtVerify(token, JWKS, {
+          issuer,
+          audience: process.env.MCP_PUBLIC_URL,
+        }));
+      } catch (err) {
+        console.error('[auth] jwtVerify FAILED:', err.code ?? err.constructor.name, err.message);
+        throw err;
+      }
+      return {
+        token,
+        clientId: payload.client_id ?? payload.sub,
+        sub: payload.sub,
+        scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
+        expiresAt: payload.exp,
+      };
+    },
+  };
+}
+
+export function getProtectedResourceMetadata() {
+  return {
+    resource: process.env.MCP_PUBLIC_URL,
+    authorization_servers: [process.env.OAUTH_ISSUER],
+    scopes_supported: ['mcp:tools'],
+    bearer_methods_supported: ['header'],
+  };
+}

package/mcp-endpoint.js

@@ -0,0 +1,212 @@
+import { randomUUID } from 'node:crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  isInitializeRequest,
+} from '@modelcontextprotocol/sdk/types.js';
+import { getProtectedResourceMetadata } from './auth.js';
+
+const tools = [
+  {
+    name: 'list_mcps',
+    description: 'List all MCPs available on the gateway with their route and description.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_tools',
+    description: 'List all tools available for a given MCP route.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        route: { type: 'string', description: 'MCP route as returned by list_mcps (e.g. "/documentor")' },
+      },
+      required: ['route'],
+    },
+  },
+  {
+    name: 'call_tool',
+    description: 'Call a tool on a given MCP route.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        route:     { type: 'string', description: 'MCP route (e.g. "/documentor")' },
+        tool_name: { type: 'string', description: 'Tool name to call' },
+        arguments: { type: 'object', description: 'Arguments to pass to the tool' },
+      },
+      required: ['route', 'tool_name'],
+    },
+  },
+];
+
+function buildMcpServer({ registry }) {
+  const server = new Server(
+    { name: 'mcp-http-gateway-remote', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    try {
+      if (name === 'list_mcps') {
+        const text = registry
+          .map(m => `- ${m.name} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
+          .join('\n');
+        return { content: [{ type: 'text', text }] };
+      }
+
+      if (name === 'list_tools') {
+        const entry = registry.find(m => m.route === args.route);
+        if (!entry) {
+          return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
+        }
+        const text = JSON.stringify(entry.tools, null, 2);
+        return { content: [{ type: 'text', text }] };
+      }
+
+      if (name === 'call_tool') {
+        const entry = registry.find(m => m.route === args.route);
+        if (!entry) {
+          return { content: [{ type: 'text', text: `No MCP found for route: ${args.route}` }], isError: true };
+        }
+        const result = await entry.client.callTool({
+          name: args.tool_name,
+          arguments: args.arguments ?? {},
+        });
+        return result;
+      }
+
+      return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Request failed: ${err.message}` }], isError: true };
+    }
+  });
+
+  return server;
+}
+
+function buildDnsRebindingConfig() {
+  const port = process.env.GATEWAY_PORT ?? '3500';
+  const extraHosts = process.env.GATEWAY_ALLOWED_HOSTS
+    ? process.env.GATEWAY_ALLOWED_HOSTS.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
+  const publicHost = process.env.MCP_PUBLIC_URL
+    ? (() => { try { return new URL(process.env.MCP_PUBLIC_URL).host; } catch { return null; } })()
+    : null;
+  const allowedHosts = [
+    `localhost:${port}`,
+    ...(publicHost ? [publicHost] : []),
+    ...extraHosts,
+  ];
+
+  const extraOrigins = process.env.GATEWAY_ALLOWED_ORIGINS
+    ? process.env.GATEWAY_ALLOWED_ORIGINS.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
+  const allowedOrigins = ['https://claude.ai', ...extraOrigins];
+
+  return { allowedHosts, allowedOrigins };
+}
+
+export function registerMcpEndpoint(app, { clients, registry }) {
+  app.get('/.well-known/oauth-protected-resource', (req, res) => {
+    res.json(getProtectedResourceMetadata());
+  });
+
+  const { allowedHosts, allowedOrigins } = buildDnsRebindingConfig();
+  console.log('[gateway] DNS rebinding protection — allowedHosts:', allowedHosts);
+  console.log('[gateway] DNS rebinding protection — allowedOrigins:', allowedOrigins);
+
+  const SESSION_TTL_MS = parseInt(process.env.SESSION_TTL_MINUTES ?? '30', 10) * 60_000;
+  const SESSION_MAX = parseInt(process.env.SESSION_MAX_COUNT ?? '100', 10);
+  console.log(`[gateway] Session limits — TTL: ${SESSION_TTL_MS / 60_000} min, max: ${SESSION_MAX}`);
+
+  const transports = {};
+
+  const cleanupExpiredSessions = () => {
+    const now = Date.now();
+    for (const [sid, entry] of Object.entries(transports)) {
+      if (now - entry.lastActivity > SESSION_TTL_MS) {
+        console.log(`[mcp-endpoint] Session ${sid} expired (TTL), closing.`);
+        entry.transport.close?.();
+        delete transports[sid];
+      }
+    }
+  };
+
+  const cleanupTimer = setInterval(cleanupExpiredSessions, 60_000);
+  cleanupTimer.unref();
+
+  const handleMcpRequest = async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'];
+      const entry = sessionId ? transports[sessionId] : undefined;
+
+      let transport;
+
+      if (!entry && isInitializeRequest(req.body)) {
+        const activeCount = Object.keys(transports).length;
+        if (activeCount >= SESSION_MAX) {
+          console.warn(`[mcp-endpoint] Session cap reached (${activeCount}/${SESSION_MAX}), rejecting initialize.`);
+          return res.status(429).json({
+            jsonrpc: '2.0',
+            error: { code: -32000, message: 'Too Many Requests: session limit reached' },
+            id: null,
+          });
+        }
+
+        const ownerSub = req.auth?.sub ?? null;
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          enableDnsRebindingProtection: true,
+          allowedHosts,
+          allowedOrigins,
+          onsessioninitialized: (sid) => {
+            transports[sid] = { transport, ownerSub, lastActivity: Date.now() };
+          },
+        });
+        transport.onclose = () => {
+          if (transport.sessionId) delete transports[transport.sessionId];
+        };
+        await buildMcpServer({ registry }).connect(transport);
+      } else if (!entry) {
+        return res.status(400).json({
+          jsonrpc: '2.0',
+          error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
+          id: null,
+        });
+      } else {
+        if (entry.ownerSub !== null && req.auth?.sub !== entry.ownerSub) {
+          console.warn(`[mcp-endpoint] Session hijacking attempt: session owned by "${entry.ownerSub}", request by "${req.auth?.sub}"`);
+          return res.status(403).json({
+            jsonrpc: '2.0',
+            error: { code: -32000, message: 'Forbidden: session belongs to another client' },
+            id: null,
+          });
+        }
+        entry.lastActivity = Date.now();
+        transport = entry.transport;
+      }
+
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      console.error('[mcp-endpoint] handleMcpRequest error:', err);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal server error' },
+          id: null,
+        });
+      }
+    }
+  };
+
+  app.post('/mcp', handleMcpRequest);
+  app.get('/mcp', handleMcpRequest);
+  app.delete('/mcp', handleMcpRequest);
+
+  console.log('[gateway] MCP remote endpoint registered at /mcp');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-http-gateway",
-  "version": "2.0.1",
+  "version": "2.0.4",
   "type": "module",
   "description": "HTTP gateway that exposes MCP servers as REST routes — bridge between MCP and any HTTP-capable agent",
   "main": "server.js",
@@ -10,6 +10,8 @@
   "files": [
     "server.js",
     "mcp-mode.js",
+    "mcp-endpoint.js",
+    "auth.js",
     "README.md",
     "embeddings/"
   ],
@@ -45,6 +47,7 @@
     "better-sqlite3": "^12.8.0",
     "dotenv": "^17.3.1",
     "express": "^5.2.1",
+    "jose": "^6.2.3",
     "openai": "^6.31.0"
   }
 }

package/server.js

@@ -13,6 +13,10 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { initDb, getOrComputeToolEmbedding, getAllToolEmbeddings } from './embeddings/db.js';
 import { getEmbedding, cosineSimilarity } from './embeddings/vectorizer.js';
+import { registerMcpEndpoint } from './mcp-endpoint.js';
+import { createMcpTokenVerifier } from './auth.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { rateLimit } from 'express-rate-limit';
 
 // Normalise les différents formats de config rencontrés dans la nature :
 // - `command` string + `args` array  (format Cursor)
@@ -25,13 +29,33 @@ function normalizeCfg(cfg) {
   return { ...cfg, command, args, env };
 }
 
+// Variables système minimales transmises aux MCPs enfants.
+// On exclut délibérément toutes les variables propres au gateway
+// (OPENAI_API_KEY, OAUTH_*, GATEWAY_*, MCP_*, etc.).
+const CHILD_ENV_WHITELIST = new Set([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL',
+  'LANG', 'LC_ALL', 'LC_CTYPE',
+  'TEMP', 'TMP', 'TMPDIR',
+  'USERPROFILE', 'APPDATA', 'LOCALAPPDATA',
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR',
+  'COMSPEC', 'PATHEXT', 'USERNAME',
+  'PROGRAMFILES', 'NODE_PATH',
+]);
+
+function buildChildEnv(cfgEnv = {}) {
+  const safeEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k]) => CHILD_ENV_WHITELIST.has(k))
+  );
+  return { ...safeEnv, ...cfgEnv };
+}
+
 // --- MCP client ---
 
 async function connectMcp(name, cfg) {
   const transport = new StdioClientTransport({
     command: cfg.command,
     args: cfg.args ?? [],
-    env: { ...process.env, ...(cfg.env ?? {}) },
+    env: buildChildEnv(cfg.env),
   });
   const client = new Client({ name: 'mcp-gateway', version: '1.0.0' }, { capabilities: {} });
   await client.connect(transport);
@@ -68,8 +92,11 @@ function registerMcpRoutes(app, route, client, name) {
 
 // --- Bootstrap ---
 
+const LOCALHOST_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+
 async function main() {
   const GATEWAY_PORT = parseInt(process.env.GATEWAY_PORT ?? '3500', 10);
+  const GATEWAY_HOST = process.env.GATEWAY_HOST ?? '127.0.0.1';
 
   // GATEWAY_CONFIG_DIR overrides the directory in which mcp-servers.json is looked up
   // (defaults to ./config relative to cwd).
@@ -83,6 +110,65 @@ async function main() {
   const app = express();
   app.use(express.json({ type: '*/*' }));
 
+  const globalWindowMin = parseInt(process.env.RATE_LIMIT_GLOBAL_WINDOW_MINUTES ?? '15', 10);
+  const globalMax       = parseInt(process.env.RATE_LIMIT_GLOBAL_MAX ?? '300', 10);
+  const searchWindowMin = parseInt(process.env.RATE_LIMIT_SEARCH_WINDOW_MINUTES ?? '1', 10);
+  const searchMax       = parseInt(process.env.RATE_LIMIT_SEARCH_MAX ?? '30', 10);
+
+  app.use(rateLimit({
+    windowMs: globalWindowMin * 60_000,
+    max: globalMax,
+    standardHeaders: 'draft-8',
+    legacyHeaders: false,
+    message: { error: 'Too Many Requests' },
+  }));
+  console.log(`[gateway] Rate limit — global: ${globalMax} req/${globalWindowMin} min/IP`);
+
+  const searchLimiter = rateLimit({
+    windowMs: searchWindowMin * 60_000,
+    max: searchMax,
+    standardHeaders: 'draft-8',
+    legacyHeaders: false,
+    message: { error: 'Too Many Requests' },
+  });
+  console.log(`[gateway] Rate limit — /tools/search: ${searchMax} req/${searchWindowMin} min/IP`);
+
+  const verifier = createMcpTokenVerifier();
+  if (verifier) {
+    const bearerMw = requireBearerAuth({
+      verifier,
+      requiredScopes: ['mcp:tools'],
+      resourceMetadataUrl: `${process.env.MCP_PUBLIC_URL?.replace(/\/mcp$/, '')}/.well-known/oauth-protected-resource`,
+    });
+
+    const allowedSubs = process.env.OAUTH_ALLOWED_SUBS
+      ? new Set(process.env.OAUTH_ALLOWED_SUBS.split(',').map(s => s.trim()).filter(Boolean))
+      : null;
+
+    const subAllowListMw = allowedSubs
+      ? (req, res, next) => {
+          if (!allowedSubs.has(req.auth?.sub)) {
+            return res.status(403).json({ error: 'Forbidden' });
+          }
+          return next();
+        }
+      : null;
+
+    app.use((req, res, next) => {
+      if (req.path.startsWith('/.well-known/')) return next();
+      return bearerMw(req, res, subAllowListMw ? () => subAllowListMw(req, res, next) : next);
+    });
+    console.log('[gateway] OAuth protection enabled — required scope: mcp:tools');
+    if (allowedSubs) console.log(`[gateway] Sub allow-list active (${allowedSubs.size} entr${allowedSubs.size > 1 ? 'ies' : 'y'})`);
+  } else if (!LOCALHOST_HOSTS.has(GATEWAY_HOST)) {
+    console.error('[gateway] FATAL: OAuth is disabled but GATEWAY_HOST is not localhost.');
+    console.error(`[gateway] Refusing to expose an unauthenticated gateway on ${GATEWAY_HOST}:${GATEWAY_PORT}.`);
+    console.error('[gateway] → Set MCP_OAUTH_ENABLED=true, or set GATEWAY_HOST=127.0.0.1.');
+    process.exit(1);
+  } else {
+    console.warn('[gateway] WARNING: OAuth is disabled — gateway is open, bound to localhost only.');
+  }
+
   const dataDir = process.env.GATEWAY_DATA_DIR ?? path.join(process.cwd(), 'data');
   const dbPath = path.join(dataDir, 'embeddings', 'embeddings.db');
   initDb(dbPath);
@@ -101,7 +187,7 @@ async function main() {
       const client = await connectMcp(name, cfg);
       const { tools } = await client.listTools();
       clients.push(client);
-      registry.push({ name, route, description: cfg.description ?? null, tools });
+      registry.push({ name, route, description: cfg.description ?? null, tools, client });
       registerMcpRoutes(app, route, client, name);
       for (const tool of tools) {
         if (!tool.description) continue;
@@ -114,7 +200,7 @@ async function main() {
     }
   }
 
-  app.get('/tools/search', async (req, res) => {
+  app.get('/tools/search', searchLimiter, async (req, res) => {
     const q = req.query.q?.trim();
     const limit = Math.min(parseInt(req.query.limit ?? '5', 10), 20);
     if (!q) return res.status(400).json({ error: 'Missing query parameter: q' });
@@ -165,8 +251,15 @@ async function main() {
     res.type('text/plain').send(lines.join('\n'));
   });
 
-  app.listen(GATEWAY_PORT, () => {
-    console.log(`[gateway] Listening on http://localhost:${GATEWAY_PORT}`);
+  registerMcpEndpoint(app, { clients, registry });
+
+  const httpServer = app.listen(GATEWAY_PORT, GATEWAY_HOST, () => {
+    console.log(`[gateway] Listening on http://${GATEWAY_HOST}:${GATEWAY_PORT}`);
+  });
+
+  httpServer.on('error', (err) => {
+    console.error('[gateway] HTTP server error:', err.message);
+    process.exit(1);
   });
 
   const shutdown = async () => {