feat: add HTTP transport support with McpServer API

- Migrate from Server class to modern McpServer
- Add StreamableHTTP transport with session management and SSE support
- Maintain backward compatibility for existing STDIO users
- Preserve all tool annotations

Author: kesku

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official Perplexity AI plugin providing real-time web search, reasoning, and research capabilities",
-    "version": "0.4.1"
+    "version": "0.5.0"
   },
   "plugins": [
     {
       "name": "perplexity",
       "source": "./",
       "description": "Real-time web search, reasoning, and research through Perplexity's API",
-      "version": "0.4.1",
+      "version": "0.5.0",
       "author": {
         "name": "Perplexity AI",
         "email": "[email protected]"

.github/workflows/test.yml

@@ -22,4 +22,6 @@ jobs:
         run: npm ci
 
       - name: Run tests
+        env:
+          PERPLEXITY_API_KEY: test-api-key
         run: npm test

DOCKER.md

@@ -17,20 +17,22 @@ docker build -t perplexity-mcp-server .
 
 ## Running the Container
 
-### Basic Usage
+### HTTP Mode (Default)
 
-Run the container with your API key:
+The Docker container runs in HTTP mode by default, making it accessible via HTTP requests:
 
 ```bash
-docker run --rm -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
+docker run --rm -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
 ```
 
+The server will be accessible at `http://localhost:8080/mcp`
+
 ### With Custom Timeout
 
 Set a custom timeout for requests (default is 5 minutes):
 
 ```bash
-docker run --rm \
+docker run --rm -p 8080:8080 \
   -e PERPLEXITY_API_KEY=your_key_here \
   -e PERPLEXITY_TIMEOUT_MS=600000 \
   perplexity-mcp-server
@@ -41,7 +43,7 @@ docker run --rm \
 If you're behind a corporate proxy, configure it:
 
 ```bash
-docker run --rm \
+docker run --rm -p 8080:8080 \
   -e PERPLEXITY_API_KEY=your_key_here \
   -e PERPLEXITY_PROXY=https://your-proxy-host:8080 \
   perplexity-mcp-server
@@ -50,7 +52,7 @@ docker run --rm \
 Or with authentication:
 
 ```bash
-docker run --rm \
+docker run --rm -p 8080:8080 \
   -e PERPLEXITY_API_KEY=your_key_here \
   -e PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080 \
   perplexity-mcp-server
@@ -64,34 +66,38 @@ Create a `.env` file:
 PERPLEXITY_API_KEY=your_key_here
 PERPLEXITY_TIMEOUT_MS=600000
 PERPLEXITY_PROXY=https://your-proxy-host:8080
+PORT=8080
 ```
 
 Then run:
 
 ```bash
-docker run --rm --env-file .env perplexity-mcp-server
+docker run --rm -p 8080:8080 --env-file .env perplexity-mcp-server
 ```
 
 ## Integration with MCP Clients
 
-When using Docker with MCP clients, configure them to run the Docker container. For example, in Cursor/VS Code's `mcp.json`:
+When using the HTTP Docker server, configure your MCP client to connect to the HTTP endpoint:
 
 ```json
 {
   "mcpServers": {
     "perplexity": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i",
-        "-e", "PERPLEXITY_API_KEY=your_key_here",
-        "perplexity-mcp-server"
-      ]
+      "url": "http://localhost:8080/mcp"
     }
   }
 }
 ```
 
-> **Note**: Docker-based MCP server configuration may have limitations compared to direct `npx` usage. For most use cases, the `npx` method documented in the main README is recommended.
+## STDIO Mode (Local Development)
+
+For local development with STDIO transport, you can still run the server locally without Docker:
+
+```bash
+npm install
+npm run build
+PERPLEXITY_API_KEY=your_key_here npm start
+```
+
+> **Note**: The Docker image is optimized for HTTP mode deployment. For local STDIO usage, the `npx` method documented in the main README is recommended.
 

Dockerfile

@@ -7,7 +7,7 @@ COPY tsconfig.json ./
 
 RUN --mount=type=cache,target=/root/.npm npm install --ignore-scripts
 
-COPY . .
+COPY src/ ./src/
 
 RUN npm run build
 
@@ -23,4 +23,6 @@ ENV NODE_ENV=production
 
 RUN npm ci --ignore-scripts --omit-dev
 
-ENTRYPOINT ["node", "dist/index.js"]
+EXPOSE 8080
+
+ENTRYPOINT ["node", "dist/http.js"]

README.md

@@ -167,6 +167,31 @@ If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_P
 > The server checks proxy settings in this order: `PERPLEXITY_PROXY` → `HTTPS_PROXY` → `HTTP_PROXY`. If none are set, it connects directly to the internet.
 > URLs must include `https://`. Typical ports are `8080`, `3128`, and `80`.
 
+
+### HTTP Server Deployment
+
+For cloud or shared deployments, you can run the server in HTTP mode:
+
+#### Using Docker
+
+```bash
+docker build -t perplexity-mcp-server .
+docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
+```
+
+The server will be accessible at `http://localhost:8080/mcp`
+
+#### Using Node.js Directly
+
+```bash
+npm install
+npm run build
+PORT=8080 npm run start:http
+```
+
+Connect your MCP client to: `http://localhost:8080/mcp`
+
+
 ## Troubleshooting
 
 - **API Key Issues**: Ensure `PERPLEXITY_API_KEY` is set correctly