reddit-mcp-server 1.0.9 → 1.1.0

package/README.md

@@ -4,30 +4,24 @@ 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.
 
-[![smithery badge](https://smithery.ai/badge/@jordanburke/reddit-mcp-server)](https://smithery.ai/server/@jordanburke/reddit-mcp-server)
-
-https://github.com/user-attachments/assets/caa37704-7c92-4bf8-b7e8-56d02ccb4983
-
-## 🧑‍💻 About
-
-https://www.linkedin.com/feed/update/urn:li:activity:7328864060534419457/
-
-![image](https://github.com/user-attachments/assets/aedc0966-75d4-45c4-a384-df03d232e29d)
-
 ## 🔧 Available Tools (Features)
 
 **Read-only Tools (Client Credentials):**
 
-- `get_user_info(username)` - Get detailed user analysis with engagement insights
-- `get_top_posts(subreddit, time_filter, limit)` - Get and analyze top posts
-- `get_subreddit_stats(subreddit)` - Get comprehensive subreddit analysis
-- `get_trending_subreddits()` - Get list of trending subreddits
+- `get_reddit_post(subreddit, post_id)` - Get a specific Reddit post
+- `get_top_posts(subreddit, time_filter, limit)` - Get top posts from a subreddit
+- `get_user_info(username)` - Get information about a Reddit user
+- `get_subreddit_info(subreddit_name)` - Get information about a subreddit
+- `get_trending_subreddits()` - Get currently trending subreddits
+- `search_reddit(query, subreddit?, sort?, time_filter?, limit?, type?)` - Search for posts on Reddit
+- `get_post_comments(post_id, subreddit, sort?, limit?)` - Get comments for a specific Reddit post
+- `get_user_posts(username, sort?, time_filter?, limit?)` - Get posts submitted by a specific user
+- `get_user_comments(username, sort?, time_filter?, limit?)` - Get comments made by a specific user
 
-**Read-write Tools (User Credentials):**
+**Write Tools (User Credentials Required):**
 
-- `create_post(subreddit, title, content, flair, is_self)` - Create an optimized post
-- `reply_to_post(post_id, content, subreddit)` - Add a reply with engagement insights
-- `reply_to_comment(comment_id, content, subreddit)` - Add a strategic reply
+- `create_post(subreddit, title, content, is_self)` - Create a new post in a subreddit
+- `reply_to_post(post_id, content, subreddit?)` - Post a reply to an existing Reddit post
 
 ## 🔌 Installation
 
@@ -36,7 +30,7 @@ https://www.linkedin.com/feed/update/urn:li:activity:7328864060534419457/
 To install Reddit Content Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@alexandros-lekkas/reddit-mcp-server):
 
 ```bash
-npx -y @smithery/cli install @jordanburke/reddit-mcp-server --client claude
+npx -y @smithery/cli install reddit-mcp-server --client claude
 ```
 
 ### Manual Installation
@@ -54,15 +48,17 @@ 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`
 
-6. Run with `pnpm dev` and open the inspection server (http://127.0.0.1:6274/)
+6. Build the project with `pnpm build`
+
+7. Run with `pnpm dev` and open the inspection server (http://127.0.0.1:6274/)
 
 ![image](https://github.com/user-attachments/assets/705c63ef-5d3c-4a68-8d3b-18dfda0a29f2)
 
-7. If the connection works, add this to your MCP config (for Cursor or Claude, depending on which agent you are using)
+8. If the connection works, add this to your MCP config (for Cursor or Claude Desktop)
 
 ```json
   "mcpServers": {
@@ -72,10 +68,10 @@ If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDI
         "reddit-mcp-server"
       ],
       "env": {
-        "REDDIT_CLIENT_ID": "😜",
-        "REDDIT_CLIENT_SECRET": "😜",
-        "REDDIT_USERNAME": "😜",
-        "REDDIT_PASSWORD": "😜"
+        "REDDIT_CLIENT_ID": "<YOUR_CLIENT_ID>",
+        "REDDIT_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
+        "REDDIT_USERNAME": "<YOUR_USERNAME_OPTIONAL>",
+        "REDDIT_PASSWORD": "<YOUR_PASSWORD_OPTIONAL>"
       },
       "autoApprove": [
         "get_reddit_post",
@@ -83,6 +79,10 @@ If you want to write posts you need to include your `REDDIT_USERNAME` and `REDDI
         "get_user_info",
         "get_subreddit_info",
         "get_trending_subreddits",
+        "search_reddit",
+        "get_post_comments",
+        "get_user_posts",
+        "get_user_comments",
         "create_post",
         "reply_to_post"
       ] // You don't need to add this, but it makes it so that you don't have to keep clicking approve
@@ -90,12 +90,368 @@ 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
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build TypeScript to JavaScript
+pnpm build
+
+# Run the MCP inspector for development/testing
+pnpm inspect
+
+# Build and run inspector in one command
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Lint code
+pnpm lint
+
+# Format code
+pnpm format
+```
+
+### Version & Help
+
+```bash
+# Check version
+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
 
 - This is a fork of the original [reddit-mcp-server](https://github.com/alexandros-lekkas/reddit-mcp-server) by Alexandros Lekkas.
 
-- Credit goes to the [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200 for the inspiration and implementation of these tools. This repository is, at the moment, simply a Node.js port of the Python implementation.
-
-- Credit goes to [Eugene Sh](https://medium.com/@eugenesh4work/how-to-build-an-mcp-server-fast-a-step-by-step-tutorial-e09faa5f7e3b) for the tutorial on how to build an MCP server (which was used as a reference for this implementation).
+- Credit goes to the [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200 for the inspiration and implementation of these tools.

package/dist/bin.js

@@ -30,13 +30,66 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_typescript@5.8.3/node_modules/tsup/assets/cjs_shims.js
+// node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.20.3_typescript@5.8.3/node_modules/tsup/assets/cjs_shims.js
 var init_cjs_shims = __esm({
-  "node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_typescript@5.8.3/node_modules/tsup/assets/cjs_shims.js"() {
+  "node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.20.3_typescript@5.8.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
   }
 });
 
+// src/middleware/auth.ts
+var auth_exports = {};
+__export(auth_exports, {
+  createAuthMiddleware: () => createAuthMiddleware,
+  generateRandomToken: () => generateRandomToken
+});
+function createAuthMiddleware(config = {}) {
+  return async (c, next) => {
+    if (!config.enabled || !config.token) {
+      return next();
+    }
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader) {
+      throw new import_http_exception.HTTPException(401, {
+        message: "Authorization header required"
+      });
+    }
+    const [scheme, token] = authHeader.split(" ");
+    if (scheme !== "Bearer") {
+      throw new import_http_exception.HTTPException(401, {
+        message: "Invalid authorization scheme. Use 'Bearer <token>'"
+      });
+    }
+    if (!token) {
+      throw new import_http_exception.HTTPException(401, {
+        message: "Bearer token required"
+      });
+    }
+    if (token !== config.token) {
+      throw new import_http_exception.HTTPException(403, {
+        message: "Invalid token"
+      });
+    }
+    return next();
+  };
+}
+function generateRandomToken(length = 32) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+var import_http_exception;
+var init_auth = __esm({
+  "src/middleware/auth.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_http_exception = require("hono/http-exception");
+  }
+});
+
 // src/client/reddit-client.ts
 function initializeRedditClient(config) {
   redditClient = new RedditClient(config);
@@ -181,7 +234,7 @@ var init_reddit_client = __esm({
             description: data.description || "",
             publicDescription: data.public_description || "",
             subscribers: data.subscribers,
-            activeUserCount: data.active_user_count,
+            activeUserCount: data.active_user_count ?? void 0,
             createdUtc: data.created_utc,
             over18: data.over18,
             subredditType: data.subreddit_type,
@@ -221,7 +274,7 @@ var init_reddit_client = __esm({
               spoiler: post.spoiler,
               edited: !!post.edited,
               isSelf: post.is_self,
-              linkFlairText: post.link_flair_text,
+              linkFlairText: post.link_flair_text ?? void 0,
               permalink: post.permalink
             };
           });
@@ -404,7 +457,7 @@ var init_reddit_client = __esm({
               spoiler: post.spoiler,
               edited: !!post.edited,
               isSelf: post.is_self,
-              linkFlairText: post.link_flair_text,
+              linkFlairText: post.link_flair_text ?? void 0,
               permalink: post.permalink
             };
           });
@@ -508,7 +561,7 @@ var init_reddit_client = __esm({
               spoiler: post.spoiler,
               edited: !!post.edited,
               isSelf: post.is_self,
-              linkFlairText: post.link_flair_text,
+              linkFlairText: post.link_flair_text ?? void 0,
               permalink: post.permalink
             };
           });
@@ -1787,6 +1840,26 @@ if (args.includes("--version") || args.includes("-v")) {
   console.log(packageJson.version);
   process.exit(0);
 }
+if (args.includes("--generate-token")) {
+  async function generateToken() {
+    const { generateRandomToken: generateRandomToken2 } = await Promise.resolve().then(() => (init_auth(), auth_exports));
+    const token = generateRandomToken2(32);
+    console.log(`Generated OAuth token: ${token}`);
+    console.log(`
+To use this token, set the environment variable:`);
+    console.log(`export OAUTH_TOKEN="${token}"`);
+    console.log(`export OAUTH_ENABLED=true`);
+    console.log(`
+Then start the HTTP server with: pnpm serve`);
+    process.exit(0);
+  }
+  generateToken().catch((error) => {
+    console.error("Failed to generate token:", error);
+    process.exit(1);
+  });
+} else {
+  main().then();
+}
 if (args.includes("--help") || args.includes("-h")) {
   console.log(`
 Reddit MCP Server v${packageJson.version}
@@ -1794,8 +1867,9 @@ Reddit MCP Server v${packageJson.version}
 Usage: reddit-mcp-server [options]
 
 Options:
-  -v, --version     Show version number
-  -h, --help        Show help
+  -v, --version        Show version number
+  -h, --help           Show help
+  --generate-token     Generate a secure OAuth token for HTTP server
 
 Environment Variables:
   REDDIT_CLIENT_ID      Reddit API client ID (required)
@@ -1804,6 +1878,10 @@ Environment Variables:
   REDDIT_PASSWORD       Reddit password (optional, for write operations)
   REDDIT_USER_AGENT     Custom user agent (optional)
 
+HTTP Server OAuth Variables:
+  OAUTH_ENABLED         Set to "true" to enable OAuth protection
+  OAUTH_TOKEN           Custom OAuth token (use --generate-token to create one)
+
 For more information, visit: https://github.com/jordanburke/reddit-mcp-server
 `);
   process.exit(0);
@@ -1816,4 +1894,3 @@ async function main() {
     process.exit(1);
   });
 }
-main().then();

package/dist/index.js

@@ -169,7 +169,7 @@ var RedditClient = class {
         description: data.description || "",
         publicDescription: data.public_description || "",
         subscribers: data.subscribers,
-        activeUserCount: data.active_user_count,
+        activeUserCount: data.active_user_count ?? void 0,
         createdUtc: data.created_utc,
         over18: data.over18,
         subredditType: data.subreddit_type,
@@ -209,7 +209,7 @@ var RedditClient = class {
           spoiler: post.spoiler,
           edited: !!post.edited,
           isSelf: post.is_self,
-          linkFlairText: post.link_flair_text,
+          linkFlairText: post.link_flair_text ?? void 0,
           permalink: post.permalink
         };
       });
@@ -392,7 +392,7 @@ var RedditClient = class {
           spoiler: post.spoiler,
           edited: !!post.edited,
           isSelf: post.is_self,
-          linkFlairText: post.link_flair_text,
+          linkFlairText: post.link_flair_text ?? void 0,
           permalink: post.permalink
         };
       });
@@ -496,7 +496,7 @@ var RedditClient = class {
           spoiler: post.spoiler,
           edited: !!post.edited,
           isSelf: post.is_self,
-          linkFlairText: post.link_flair_text,
+          linkFlairText: post.link_flair_text ?? void 0,
           permalink: post.permalink
         };
       });

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import * as _hono_node_server from '@hono/node-server';
+
+declare function startServer(port?: number): _hono_node_server.ServerType;
+
+export { startServer };