reddit-mcp-server 1.0.10 → 1.1.1

package/CHANGELOG.md

@@ -5,30 +5,36 @@ All notable changes to this project will be documented in this file.
 ## [1.0.7] - 2025-06-27
 
 ### Fixed
+
 - Fixed server crash issue caused by stdout pollution in bin.js
 - Cleaned up published package to only include necessary files (reduced from 112KB to 24KB)
 
 ### Added
+
 - Search Reddit functionality (`search_reddit` tool)
-- Get post comments with threaded display (`get_post_comments` tool)  
+- Get post comments with threaded display (`get_post_comments` tool)
 - Get user posts (`get_user_posts` tool)
 - Get user comments (`get_user_comments` tool)
 - Comprehensive test suite for all new functionality
 
 ### Changed
+
 - Migrated from axios to native fetch API
 - Improved error handling and removed console output that violated MCP protocol
 
 ## [1.0.6] - 2025-06-27
 
 ### Added
+
 - New Reddit API endpoints (had packaging issues, use 1.0.7 instead)
 
 ## [1.0.5] - 2025-06-27
 
 ### Changed
+
 - Migrated from axios to fetch for HTTP requests
 - Fixed linting errors and improved code formatting
 
 ## [1.0.4] and earlier
-- Previous versions with axios-based implementation
+
+- Previous versions with axios-based implementation

package/README.md

@@ -4,8 +4,6 @@ A Model Context Protocol (MCP) that provides tools for fetching and creating Red
 
 > **Note**: This is a fork of the original [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas, updated with pnpm, tsup build system, and npx execution support.
 
-https://github.com/user-attachments/assets/caa37704-7c92-4bf8-b7e8-56d02ccb4983
-
 ## 🔧 Available Tools (Features)
 
 **Read-only Tools (Client Credentials):**
@@ -29,13 +27,14 @@ https://github.com/user-attachments/assets/caa37704-7c92-4bf8-b7e8-56d02ccb4983
 
 ### Installing via Smithery
 
-To install Reddit Content Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@alexandros-lekkas/reddit-mcp-server):
+To install Reddit Content Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@jordanburke/reddit-mcp-server):
 
 ```bash
 npx -y @smithery/cli install reddit-mcp-server --client claude
 ```
 
 ### Manual Installation
+
 1. `git clone https://github.com/jordanburke/reddit-mcp-server`
 
 2. Create a Reddit app [here](https://www.reddit.com/prefs/apps)
@@ -50,7 +49,7 @@ Make sure to select "script"!
 
 Do this with your `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET`
 
-If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDIT_PASSWORD` (don't worry, I won't steal them 😜)
+If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDIT_PASSWORD`
 
 5. Install dependencies with `pnpm install`
 
@@ -92,8 +91,6 @@ If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDI
   }
 ```
 
-(Make sure to replace the environmental variables with your actual keys, not the 😜 emoji)
-
 ## 🛠️ Development
 
 ### Commands
@@ -129,6 +126,349 @@ npx reddit-mcp-server --version
 
 # Show help
 npx reddit-mcp-server --help
+
+# Generate OAuth token for HTTP server
+npx reddit-mcp-server --generate-token
+```
+
+### Streamable MCP Endpoint (Hono Server)
+
+In addition to the standard npx execution, this server also supports a Streamable MCP endpoint via Hono for direct HTTP integration:
+
+```bash
+# Start the Hono server on port 3000 (default)
+pnpm serve
+
+# Start with custom port
+PORT=8080 pnpm serve
+
+# Development mode with auto-reload
+pnpm serve:dev
+```
+
+The server will be available at `http://localhost:3000` with the MCP endpoint at `http://localhost:3000/mcp`.
+
+#### OAuth Security (Optional)
+
+The HTTP server supports optional OAuth protection to secure your endpoints:
+
+**Generate a secure token:**
+
+```bash
+npx reddit-mcp-server --generate-token
+# Output: Generated OAuth token: A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j
+```
+
+**Enable OAuth with generated token:**
+
+```bash
+export OAUTH_ENABLED=true
+export OAUTH_TOKEN="A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j"
+pnpm serve
+```
+
+**Make authenticated requests:**
+
+```bash
+curl -H "Authorization: Bearer A8f2Kp9x3NmQ7vR4tL6eZ1sW5yB8hC2j" \
+     -H "Content-Type: application/json" \
+     -d '{"method":"tools/list","params":{}}' \
+     http://localhost:3000/mcp
+```
+
+**OAuth Configuration:**
+
+- `OAUTH_ENABLED=true` - Enables OAuth protection (disabled by default)
+- `OAUTH_TOKEN=your-token` - Your custom token (or use `--generate-token`)
+- Without OAuth, the server is accessible without authentication
+- Health check (`/`) is always unprotected; only `/mcp` requires authentication
+
+#### MCP Client Configuration
+
+For MCP clients connecting to an OAuth-protected server, configure according to the [MCP Authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization):
+
+**HTTP-based MCP Clients (e.g., web applications):**
+
+```javascript
+// Example using fetch API
+const response = await fetch("http://localhost:3000/mcp", {
+  method: "POST",
+  headers: {
+    Authorization: "Bearer YOUR_TOKEN",
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/list",
+    params: {},
+  }),
+})
+
+const result = await response.json()
+```
+
+**Direct HTTP MCP Client:**
+
+```javascript
+const client = new MCP.Client({
+  transport: new MCP.HTTPTransport({
+    url: "http://localhost:3000/mcp",
+    headers: {
+      Authorization: "Bearer YOUR_TOKEN",
+    },
+  }),
+})
+```
+
+**Custom MCP Client Implementation:**
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { HTTPTransport } from "@modelcontextprotocol/sdk/client/http.js"
+
+const transport = new HTTPTransport({
+  url: "http://localhost:3000/mcp",
+  headers: {
+    Authorization: "Bearer YOUR_TOKEN",
+    "Content-Type": "application/json",
+  },
+})
+
+const client = new Client(
+  {
+    name: "reddit-client",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {},
+  },
+)
+
+await client.connect(transport)
+```
+
+**Important Notes:**
+
+- Replace `YOUR_TOKEN` with your generated OAuth token
+- Authorization header MUST be included in every request to `/mcp`
+- Tokens MUST NOT be included in URI query strings per MCP specification
+- Use HTTPS in production for secure token transmission
+
+**For Remote/Deployed Servers:**
+When connecting to a remote Reddit MCP server (e.g., deployed on your infrastructure):
+
+```javascript
+// Production server with OAuth
+const response = await fetch("https://your-server.com/mcp", {
+  method: "POST",
+  headers: {
+    Authorization: "Bearer YOUR_TOKEN",
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/list",
+    params: {},
+  }),
+})
+```
+
+**MCP Client Configuration for Remote Server:**
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { HTTPTransport } from "@modelcontextprotocol/sdk/client/http.js"
+
+// For your deployed server
+const transport = new HTTPTransport({
+  url: "https://your-reddit-mcp.company.com/mcp",
+  headers: {
+    Authorization: "Bearer YOUR_GENERATED_TOKEN",
+    "Content-Type": "application/json",
+  },
+})
+
+const client = new Client(
+  {
+    name: "reddit-client",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {},
+  },
+)
+
+await client.connect(transport)
+```
+
+**Claude Desktop/Cursor with Remote Server (HTTP):**
+For remote servers, you can use a proxy approach:
+
+```json
+{
+  "mcpServers": {
+    "reddit-remote": {
+      "command": "node",
+      "args": [
+        "-e",
+        "const http = require('https'); const req = http.request('https://your-server.com/mcp', {method:'POST',headers:{'Authorization':'Bearer YOUR_TOKEN','Content-Type':'application/json'}}, res => res.pipe(process.stdout)); process.stdin.pipe(req);"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+**For Claude Desktop/Cursor (stdio transport):**
+OAuth is not applicable when using the traditional npx execution method. Use the stdio configuration instead:
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "npx",
+      "args": ["reddit-mcp-server"],
+      "env": {
+        "REDDIT_CLIENT_ID": "your_client_id",
+        "REDDIT_CLIENT_SECRET": "your_client_secret"
+      }
+    }
+  }
+}
+```
+
+#### Remote Deployment Examples
+
+**Deploy to your infrastructure and share the URL:**
+
+1. **Generate secure token:**
+
+   ```bash
+   npx reddit-mcp-server --generate-token
+   # Output: Generated OAuth token: xyz123abc456def789
+   ```
+
+2. **Deploy with Docker on your server:**
+
+   ```bash
+   docker run -d \
+     --name reddit-mcp \
+     -p 3000:3000 \
+     -e REDDIT_CLIENT_ID=your_reddit_client_id \
+     -e REDDIT_CLIENT_SECRET=your_reddit_client_secret \
+     -e OAUTH_ENABLED=true \
+     -e OAUTH_TOKEN=xyz123abc456def789 \
+     ghcr.io/jordanburke/reddit-mcp-server:latest
+   ```
+
+3. **Share with your team:**
+
+   ```
+   Server URL: https://your-server.com/mcp
+   OAuth Token: xyz123abc456def789
+   ```
+
+4. **Team members connect:**
+   ```typescript
+   const client = new Client(...);
+   const transport = new HTTPTransport({
+     url: 'https://your-server.com/mcp',
+     headers: { 'Authorization': 'Bearer xyz123abc456def789' }
+   });
+   await client.connect(transport);
+   ```
+
+This allows integration with systems that support HTTP-based MCP communication, similar to the cq-api and agent-todo implementations.
+
+## 🐳 Docker Usage
+
+### Pull from GitHub Container Registry
+
+```bash
+# Pull the latest image
+docker pull ghcr.io/jordanburke/reddit-mcp-server:latest
+
+# Pull a specific version
+docker pull ghcr.io/jordanburke/reddit-mcp-server:v1.0.10
+```
+
+### Run with Docker
+
+```bash
+# Run the HTTP server (recommended)
+docker run -d \
+  --name reddit-mcp \
+  -p 3000:3000 \
+  -e REDDIT_CLIENT_ID=your_client_id \
+  -e REDDIT_CLIENT_SECRET=your_client_secret \
+  -e REDDIT_USERNAME=your_username \
+  -e REDDIT_PASSWORD=your_password \
+  ghcr.io/jordanburke/reddit-mcp-server:latest
+
+# Run with OAuth enabled (secure)
+docker run -d \
+  --name reddit-mcp \
+  -p 3000:3000 \
+  -e REDDIT_CLIENT_ID=your_client_id \
+  -e REDDIT_CLIENT_SECRET=your_client_secret \
+  -e OAUTH_ENABLED=true \
+  -e OAUTH_TOKEN=your_generated_token \
+  ghcr.io/jordanburke/reddit-mcp-server:latest
+
+# Run with custom port
+docker run -d \
+  --name reddit-mcp \
+  -p 8080:3000 \
+  --env-file .env \
+  ghcr.io/jordanburke/reddit-mcp-server:latest
+
+# Generate token using Docker
+docker run --rm \
+  ghcr.io/jordanburke/reddit-mcp-server:latest \
+  node dist/bin.js --generate-token
+
+# Run as stdio MCP server (for direct integration)
+docker run -it \
+  --env-file .env \
+  ghcr.io/jordanburke/reddit-mcp-server:latest \
+  node dist/index.js
+```
+
+### Build Locally
+
+```bash
+# Build the image
+docker build -t reddit-mcp-server .
+
+# Run the locally built image
+docker run -d \
+  --name reddit-mcp \
+  -p 3000:3000 \
+  --env-file .env \
+  reddit-mcp-server
+```
+
+### Docker Compose Example
+
+```yaml
+version: "3.8"
+
+services:
+  reddit-mcp:
+    image: ghcr.io/jordanburke/reddit-mcp-server:latest
+    ports:
+      - "3000:3000"
+    environment:
+      - REDDIT_CLIENT_ID=${REDDIT_CLIENT_ID}
+      - REDDIT_CLIENT_SECRET=${REDDIT_CLIENT_SECRET}
+      - REDDIT_USERNAME=${REDDIT_USERNAME}
+      - REDDIT_PASSWORD=${REDDIT_PASSWORD}
+      # Optional OAuth settings
+      - OAUTH_ENABLED=${OAUTH_ENABLED:-false}
+      - OAUTH_TOKEN=${OAUTH_TOKEN}
+    restart: unless-stopped
 ```
 
 ## 📚 Credits