@imenam/mcp-http-gateway 2.0.0 → 2.0.2

package/README.md

@@ -45,11 +45,17 @@ npm install @imenam/mcp-http-gateway
 
 ```env
 GATEWAY_PORT=3500
+GATEWAY_CONFIG_DIR=./config
 ```
 
-### `config/mcp-servers.json`
+| Variable | Défaut | Description |
+|---|---|---|
+| `GATEWAY_PORT` | `3500` | Port HTTP du gateway |
+| `GATEWAY_CONFIG_DIR` | `./config` (relatif au cwd) | Dossier contenant `mcp-servers.json` |
 
-À créer dans le **répertoire courant** depuis lequel tu lances le gateway (pas dans le package lui-même). Un fichier `config/mcp-servers.example.json` est disponible comme point de départ.
+### `mcp-servers.json`
+
+À créer dans le dossier de configuration (`./config` par défaut, ou le chemin pointé par `GATEWAY_CONFIG_DIR`). Un fichier `config/mcp-servers.example.json` est fourni comme point de départ.
 
 Même format que la configuration `mcpServers` de Cursor. Ajouter `MCP_SERVER_ROUTE` dans `env` pour définir la route HTTP du MCP, et `description` pour la documentation.
 
@@ -190,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,35 @@
+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) {
+      const { payload } = await jwtVerify(token, JWKS, {
+        issuer: process.env.OAUTH_ISSUER,
+        audience: process.env.MCP_PUBLIC_URL,
+      });
+      return {
+        token,
+        clientId: payload.client_id ?? 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,148 @@
+import { randomUUID } from 'node:crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  isInitializeRequest,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createMcpTokenVerifier, 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;
+}
+
+export function registerMcpEndpoint(app, { clients, registry }) {
+  app.get('/.well-known/oauth-protected-resource', (req, res) => {
+    res.json(getProtectedResourceMetadata());
+  });
+
+  const verifier = createMcpTokenVerifier();
+  const authMw = verifier
+    ? requireBearerAuth({
+        verifier,
+        requiredScopes: [],
+        resourceMetadataUrl: `${process.env.MCP_PUBLIC_URL?.replace(/\/mcp$/, '')}/.well-known/oauth-protected-resource`,
+      })
+    : (req, res, next) => next();
+
+  const transports = {};
+
+  const handleMcpRequest = async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'];
+      let transport = sessionId ? transports[sessionId] : undefined;
+
+      if (!transport && isInitializeRequest(req.body)) {
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (sid) => { transports[sid] = transport; },
+        });
+        transport.onclose = () => {
+          if (transport.sessionId) delete transports[transport.sessionId];
+        };
+        await buildMcpServer({ registry }).connect(transport);
+      } else if (!transport) {
+        return res.status(400).json({
+          jsonrpc: '2.0',
+          error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
+          id: null,
+        });
+      }
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      console.error('[mcp-endpoint] handleMcpRequest error:', err.message);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal server error' },
+          id: null,
+        });
+      }
+    }
+  };
+
+  app.post('/mcp', authMw, handleMcpRequest);
+  app.get('/mcp', authMw, handleMcpRequest);
+  app.delete('/mcp', authMw, 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.0",
+  "version": "2.0.2",
   "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,7 @@ 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';
 
 // Normalise les différents formats de config rencontrés dans la nature :
 // - `command` string + `args` array  (format Cursor)
@@ -71,10 +72,12 @@ function registerMcpRoutes(app, route, client, name) {
 async function main() {
   const GATEWAY_PORT = parseInt(process.env.GATEWAY_PORT ?? '3500', 10);
 
-  // GATEWAY_CONFIG overrides the default path (config/mcp-servers.json in cwd).
-  const configPath = process.env.GATEWAY_CONFIG
-    ? path.resolve(process.env.GATEWAY_CONFIG)
-    : path.join(process.cwd(), 'config', 'mcp-servers.json');
+  // GATEWAY_CONFIG_DIR overrides the directory in which mcp-servers.json is looked up
+  // (defaults to ./config relative to cwd).
+  const configDir = process.env.GATEWAY_CONFIG_DIR
+    ? path.resolve(process.env.GATEWAY_CONFIG_DIR)
+    : path.join(process.cwd(), 'config');
+  const configPath = path.join(configDir, 'mcp-servers.json');
   const config = JSON.parse(readFileSync(configPath, 'utf-8'));
   const servers = config.mcpServers ?? {};
 
@@ -99,7 +102,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;
@@ -163,6 +166,8 @@ async function main() {
     res.type('text/plain').send(lines.join('\n'));
   });
 
+  registerMcpEndpoint(app, { clients, registry });
+
   app.listen(GATEWAY_PORT, () => {
     console.log(`[gateway] Listening on http://localhost:${GATEWAY_PORT}`);
   });