feat(remote): add remote server capabilities

README.md

@@ -110,6 +110,8 @@ _Coming soon._
 
 ### Claude Desktop Setup
 
+#### Local
+
 1. Open Claude Desktop settings
 2. Add the following to your configuration:
    ```json
@@ -126,6 +128,53 @@ _Coming soon._
 > [!TIP]
 > You can refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user) for Claude Desktop.
 
+#### Remote
+To run an HTTP server, as Claude Desktop doesn't natively support it yet, you'll have to use a gateway:
+```json
+{
+  "mcpServers": {
+    "algolia-mcp": {
+      "command": "<PATH_TO_BIN>/npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "http://localhost:4243/mcp"
+      ]
+    }
+  }
+}
+```
+> [!INFO]
+> Our HTTP server leverages the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
+> It is also backward compatible with the [SSE transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse).
+
+### OpenAI Playground (SSE server)
+![alt text](assets/openai_playgroud_add_mcp.png)
+
+Run the Algolia MCP server in SSE mode
+1.	Set up the project
+2.	Build the server
+3.	Authenticate with Algolia
+4.	Launch the server in SSE mode (default: on port 4243)
+
+```sh
+cd dist
+./algolia-mcp start-server --transport http
+```
+5.	Make the SSE server accessible from the internet using ngrok (installation guide)
+```sh
+ngrok http 4243
+```
+
+Add the SSE server to the Playground
+1.	Go to https://platform.openai.com/playground
+2.	Select Tools > “MCP Server”
+3.	Add the `https://[random].ngrok-free.app` obtained after running ngrok
+4.	Select “None” for authentication
+
+### n8n or any other MCP client using an SSE server
+Follow the same instructions as for the OpenAI Playground.
+
 ### CLI Options
 
 #### Available Commands
@@ -134,14 +183,14 @@ _Coming soon._
 Usage: algolia-mcp [options] [command]
 
 Options:
-  -h, --help              display help for command
+  -h, --help                  Display help for command
 
 Commands:
-  start-server [options]  Starts the Algolia MCP server
-  authenticate            Authenticate with Algolia
-  logout                  Remove all stored credentials
-  list-tools              List all available tools
-  help [command]          display help for command
+  start-server [options]      Starts the Algolia MCP server ()
+  authenticate                Authenticate with Algolia
+  logout                      Remove all stored credentials
+  list-tools                  List all available tools
+  help [command]              Display help for command
 ```
 
 #### Server Options
@@ -154,7 +203,8 @@ Starts the Algolia MCP server
 Options:
   -t, --allow-tools <tools>             Comma separated list of tool ids (default: getUserInfo,getApplications,...,listIndices)
   --credentials <applicationId:apiKey>  Application ID and associated API key to use. Optional: the MCP will authenticate you if unspecified, giving you access to all your applications.
-  -h, --help                            display help for command
+  --transport [stdio|http]              Transport type (default:stdio)
+  -h, --help                            Display help for command
 ```
 
 ## 🛠 Development

package.json

@@ -7,7 +7,7 @@
     "type-check": "tsc --noEmit",
     "lint": "eslint --ext .ts src",
     "test": "vitest",
-    "build": "bun build ./src/app.ts --compile",
+    "build": "bun build ./src/app.ts --compile --outfile dist/app",
     "debug": "mcp-inspector npm start"
   },
   "type": "module",
@@ -20,12 +20,16 @@
     "ajv": "^8.17.1",
     "algoliasearch": "^5.23.4",
     "commander": "^13.1.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
     "open": "^10.1.0",
     "zod": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
     "@modelcontextprotocol/inspector": "^0.9.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.1",
     "@types/node": "^22.14.0",
     "@vitest/coverage-v8": "^3.1.1",
     "bun": "^1.2.9",

src/app.ts

@@ -1,6 +1,5 @@
 import { Command } from "commander";
 import { type ListToolsOptions } from "./commands/list-tools.ts";
-import { ZodError } from "zod";
 
 const program = new Command("algolia-mcp");
 
@@ -63,20 +62,6 @@ const ALLOW_TOOLS_OPTIONS_TUPLE = [
   DEFAULT_ALLOW_TOOLS,
 ] as const;
 
-function formatErrorForCli(error: unknown): string {
-  if (error instanceof ZodError) {
-    return [...error.errors.map((e) => `- ${e.path.join(".") || "<root>"}: ${e.message}`)].join(
-      "\n",
-    );
-  }
-
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return "Unknown error";
-}
-
 program
   .command("start-server", { isDefault: true })
   .description("Starts the Algolia MCP server")
@@ -92,13 +77,24 @@ program
       return { applicationId, apiKey };
     },
   )
+
+  .option("--transport [stdio|http]", "Transport type, either `stdio` (default) or `http`", "stdio")
   .action(async (opts) => {
-    try {
-      const { startServer } = await import("./commands/start-server.ts");
-      await startServer(opts);
-    } catch (error) {
-      console.error(formatErrorForCli(error));
-      process.exit(1);
+    switch (opts.transport) {
+      case "stdio": {
+        const { startServer } = await import("./commands/start-server.ts");
+        await startServer(opts);
+        break;
+      }
+      case "http": {
+        console.info('Starting server with HTTP transport support');
+        const { startHttpServer } = await import("./commands/start-http-server.ts");
+        await startHttpServer(opts);
+        break;
+      }
+      default:
+        console.error(`Unknown transport type: ${opts.transport}\nAllowed values: stdio, http`);
+        process.exit(1);
     }
   });