@prmichaelsen/reddit-mcp 0.1.0

package/src/server.ts

@@ -0,0 +1,36 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RedditAuth } from "./auth/oauth.js";
+import { RedditClient } from "./client/reddit.js";
+import { registerListingTools } from "./tools/listings.js";
+import { registerSearchTools } from "./tools/search.js";
+
+export function createServer(auth?: RedditAuth): McpServer {
+  const server = new McpServer({
+    name: "reddit-mcp",
+    version: "0.1.0",
+  });
+
+  if (auth) {
+    const client = new RedditClient(auth);
+    registerAllTools(server, client);
+  }
+
+  return server;
+}
+
+export function createServerWithToken(accessToken: string): McpServer {
+  const server = new McpServer({
+    name: "reddit-mcp",
+    version: "0.1.0",
+  });
+
+  const client = new RedditClient(accessToken);
+  registerAllTools(server, client);
+
+  return server;
+}
+
+function registerAllTools(server: McpServer, client: RedditClient): void {
+  registerListingTools(server, client);
+  registerSearchTools(server, client);
+}

package/src/tools/listings.ts

@@ -0,0 +1,202 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { RedditClient } from "../client/reddit.js";
+
+const paginationParams = {
+  limit: z
+    .number()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Number of items to return (1-100, default 25)"),
+  after: z.string().optional().describe("Fullname of item to paginate after"),
+  before: z
+    .string()
+    .optional()
+    .describe("Fullname of item to paginate before"),
+};
+
+const timeFilter = z
+  .enum(["hour", "day", "week", "month", "year", "all"])
+  .optional()
+  .describe("Time filter for top/controversial listings");
+
+function buildParams(
+  input: Record<string, unknown>,
+): Record<string, string | undefined> {
+  const params: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined && value !== null) {
+      params[key] = String(value);
+    }
+  }
+  return params;
+}
+
+export function registerListingTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_listings_best",
+    "Get the best posts from Reddit. Requires 'read' scope.",
+    { ...paginationParams },
+    async (input) => {
+      const data = await client.get("/best", buildParams(input));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_listings_hot",
+    "Get hot posts from Reddit frontpage or a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z
+        .string()
+        .optional()
+        .describe("Subreddit name (without r/ prefix). Omit for frontpage."),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const path = subreddit ? `/r/${subreddit}/hot` : "/hot";
+      const data = await client.get(path, buildParams(rest));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_listings_new",
+    "Get newest posts from Reddit frontpage or a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z
+        .string()
+        .optional()
+        .describe("Subreddit name (without r/ prefix). Omit for frontpage."),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const path = subreddit ? `/r/${subreddit}/new` : "/new";
+      const data = await client.get(path, buildParams(rest));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_listings_rising",
+    "Get rising posts from Reddit frontpage or a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z
+        .string()
+        .optional()
+        .describe("Subreddit name (without r/ prefix). Omit for frontpage."),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const path = subreddit ? `/r/${subreddit}/rising` : "/rising";
+      const data = await client.get(path, buildParams(rest));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_listings_top",
+    "Get top posts from Reddit frontpage or a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z
+        .string()
+        .optional()
+        .describe("Subreddit name (without r/ prefix). Omit for frontpage."),
+      t: timeFilter,
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const path = subreddit ? `/r/${subreddit}/top` : "/top";
+      const data = await client.get(path, buildParams(rest));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_listings_controversial",
+    "Get controversial posts from Reddit frontpage or a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z
+        .string()
+        .optional()
+        .describe("Subreddit name (without r/ prefix). Omit for frontpage."),
+      t: timeFilter,
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const path = subreddit
+        ? `/r/${subreddit}/controversial`
+        : "/controversial";
+      const data = await client.get(path, buildParams(rest));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_comments_thread",
+    "Get a post with its full comment tree. Requires 'read' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      article: z.string().describe("Post ID (without t3_ prefix)"),
+      sort: z
+        .enum(["confidence", "top", "new", "controversial", "old", "qa"])
+        .optional()
+        .describe("Comment sort order"),
+      limit: z
+        .number()
+        .optional()
+        .describe("Maximum number of comments to return"),
+      depth: z.number().optional().describe("Maximum comment depth"),
+    },
+    async (input) => {
+      const { subreddit, article, ...rest } = input;
+      const data = await client.get(
+        `/r/${subreddit}/comments/${article}`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_duplicates",
+    "Get cross-posts and duplicates of a post. Requires 'read' scope.",
+    {
+      article: z.string().describe("Post ID (without t3_ prefix)"),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { article, ...rest } = input;
+      const data = await client.get(
+        `/duplicates/${article}`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_info",
+    "Get info about things by fullname (e.g. t3_abc123, t1_xyz789). Requires 'read' scope.",
+    {
+      id: z
+        .string()
+        .describe(
+          "Comma-separated fullnames (e.g. t3_abc123,t1_xyz789)",
+        ),
+    },
+    async (input) => {
+      const data = await client.get("/api/info", { id: input.id });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/src/tools/search.ts

@@ -0,0 +1,85 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { RedditClient } from "../client/reddit.js";
+
+function buildParams(
+  input: Record<string, unknown>,
+): Record<string, string | undefined> {
+  const params: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined && value !== null) {
+      params[key] = String(value);
+    }
+  }
+  return params;
+}
+
+export function registerSearchTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_search",
+    "Search across all of Reddit for posts, subreddits, or users. Requires 'read' scope.",
+    {
+      q: z.string().describe("Search query"),
+      sort: z
+        .enum(["relevance", "hot", "top", "new", "comments"])
+        .optional()
+        .describe("Sort order for results"),
+      t: z
+        .enum(["hour", "day", "week", "month", "year", "all"])
+        .optional()
+        .describe("Time filter"),
+      type: z
+        .enum(["link", "sr", "user"])
+        .optional()
+        .describe("Type of results: link (posts), sr (subreddits), user"),
+      limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of results (1-100, default 25)"),
+      after: z.string().optional().describe("Pagination cursor (after)"),
+      before: z.string().optional().describe("Pagination cursor (before)"),
+    },
+    async (input) => {
+      const data = await client.get("/search", buildParams(input));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_search_subreddit",
+    "Search for posts within a specific subreddit. Requires 'read' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      q: z.string().describe("Search query"),
+      sort: z
+        .enum(["relevance", "hot", "top", "new", "comments"])
+        .optional()
+        .describe("Sort order for results"),
+      t: z
+        .enum(["hour", "day", "week", "month", "year", "all"])
+        .optional()
+        .describe("Time filter"),
+      limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of results (1-100, default 25)"),
+      after: z.string().optional().describe("Pagination cursor (after)"),
+      before: z.string().optional().describe("Pagination cursor (before)"),
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const data = await client.get(`/r/${subreddit}/search`, {
+        ...buildParams(rest),
+        restrict_sr: "true",
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/src/transport/http.ts

@@ -0,0 +1,49 @@
+import {
+  createServer as createHttpServer,
+  IncomingMessage,
+  ServerResponse,
+} from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export interface HttpTransportOptions {
+  port: number;
+  host: string;
+}
+
+export async function startHttpTransport(
+  server: McpServer,
+  options: HttpTransportOptions,
+): Promise<void> {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+  });
+
+  const httpServer = createHttpServer(
+    (req: IncomingMessage, res: ServerResponse) => {
+      if (req.url === "/mcp" || req.url === "/mcp/") {
+        transport.handleRequest(req, res);
+      } else if (req.url === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+      }
+    },
+  );
+
+  await server.connect(transport);
+
+  return new Promise((resolve, reject) => {
+    httpServer.listen(options.port, options.host, () => {
+      console.error(
+        `Reddit MCP server running on http://${options.host}:${options.port}/mcp`,
+      );
+      resolve();
+    });
+
+    httpServer.on("error", reject);
+  });
+}

package/src/types/index.ts

@@ -0,0 +1,83 @@
+export interface RedditAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  userAgent: string;
+  tokenStoragePath?: string;
+}
+
+export interface TokenData {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+  scope: string;
+  obtained_at: number;
+}
+
+export interface RedditApiError {
+  status: number;
+  reason: string;
+  message: string;
+}
+
+export interface RedditListing<T> {
+  kind: "Listing";
+  data: {
+    after: string | null;
+    before: string | null;
+    children: Array<{
+      kind: string;
+      data: T;
+    }>;
+    dist: number;
+    modhash: string;
+  };
+}
+
+export interface RedditPost {
+  id: string;
+  name: string;
+  title: string;
+  author: string;
+  subreddit: string;
+  subreddit_name_prefixed: string;
+  selftext: string;
+  url: string;
+  permalink: string;
+  score: number;
+  ups: number;
+  downs: number;
+  num_comments: number;
+  created_utc: number;
+  is_self: boolean;
+  over_18: boolean;
+  spoiler: boolean;
+  locked: boolean;
+  stickied: boolean;
+  link_flair_text: string | null;
+  thumbnail: string;
+}
+
+export interface RedditComment {
+  id: string;
+  name: string;
+  body: string;
+  author: string;
+  subreddit: string;
+  score: number;
+  ups: number;
+  downs: number;
+  created_utc: number;
+  parent_id: string;
+  link_id: string;
+  is_submitter: boolean;
+  stickied: boolean;
+  distinguished: string | null;
+}
+
+export interface RateLimitInfo {
+  remaining: number;
+  used: number;
+  resetSeconds: number;
+}

package/tests/fixtures/reddit-responses.ts

@@ -0,0 +1,132 @@
+export const mockListing = {
+  kind: "Listing",
+  data: {
+    after: "t3_abc123",
+    before: null,
+    children: [
+      {
+        kind: "t3",
+        data: {
+          id: "abc123",
+          name: "t3_abc123",
+          title: "Test Post",
+          author: "testuser",
+          subreddit: "test",
+          subreddit_name_prefixed: "r/test",
+          selftext: "This is a test post",
+          url: "https://www.reddit.com/r/test/comments/abc123/test_post/",
+          permalink: "/r/test/comments/abc123/test_post/",
+          score: 42,
+          ups: 50,
+          downs: 8,
+          num_comments: 10,
+          created_utc: 1710000000,
+          is_self: true,
+          over_18: false,
+          spoiler: false,
+          locked: false,
+          stickied: false,
+          link_flair_text: null,
+          thumbnail: "self",
+        },
+      },
+    ],
+    dist: 1,
+    modhash: "",
+  },
+};
+
+export const mockCommentThread = [
+  mockListing,
+  {
+    kind: "Listing",
+    data: {
+      after: null,
+      before: null,
+      children: [
+        {
+          kind: "t1",
+          data: {
+            id: "xyz789",
+            name: "t1_xyz789",
+            body: "This is a test comment",
+            author: "commenter",
+            subreddit: "test",
+            score: 5,
+            ups: 6,
+            downs: 1,
+            created_utc: 1710001000,
+            parent_id: "t3_abc123",
+            link_id: "t3_abc123",
+            is_submitter: false,
+            stickied: false,
+            distinguished: null,
+          },
+        },
+      ],
+      dist: 1,
+      modhash: "",
+    },
+  },
+];
+
+export const mockSearchResults = {
+  kind: "Listing",
+  data: {
+    after: null,
+    before: null,
+    children: [
+      {
+        kind: "t3",
+        data: {
+          id: "search1",
+          name: "t3_search1",
+          title: "Search Result Post",
+          author: "searchuser",
+          subreddit: "programming",
+          selftext: "Found via search",
+          score: 100,
+          num_comments: 25,
+          created_utc: 1710000000,
+        },
+      },
+    ],
+    dist: 1,
+    modhash: "",
+  },
+};
+
+export const mockUserProfile = {
+  kind: "t2",
+  data: {
+    name: "testuser",
+    id: "user123",
+    created_utc: 1600000000,
+    link_karma: 1000,
+    comment_karma: 5000,
+    is_gold: false,
+    is_mod: true,
+    has_verified_email: true,
+    icon_img: "https://www.redditstatic.com/avatars/default.png",
+  },
+};
+
+export const mockSubredditAbout = {
+  kind: "t5",
+  data: {
+    display_name: "test",
+    title: "Test Subreddit",
+    public_description: "A subreddit for testing",
+    subscribers: 100000,
+    active_user_count: 500,
+    created_utc: 1500000000,
+    over18: false,
+    description: "Full description of the test subreddit",
+  },
+};
+
+export const mockErrorResponse = {
+  error: 403,
+  message: "Forbidden",
+  reason: "private",
+};

package/tests/helpers/mock-client.ts

@@ -0,0 +1,36 @@
+import { jest } from "@jest/globals";
+import { RedditClient } from "../../src/client/reddit.js";
+
+export function createMockClient(
+  responses: Map<string, unknown> = new Map(),
+): RedditClient & {
+  mockGet: jest.Mock;
+  mockPost: jest.Mock;
+} {
+  const mockGet = jest.fn().mockImplementation(async (path: string) => {
+    if (responses.has(path)) {
+      return responses.get(path);
+    }
+    return { kind: "Listing", data: { children: [], after: null, before: null, dist: 0, modhash: "" } };
+  });
+
+  const mockPost = jest.fn().mockImplementation(async (path: string) => {
+    if (responses.has(path)) {
+      return responses.get(path);
+    }
+    return { json: { errors: [] } };
+  });
+
+  const client = {
+    get: mockGet,
+    post: mockPost,
+    patch: jest.fn(),
+    put: jest.fn(),
+    delete: jest.fn(),
+    getRateLimitInfo: jest.fn().mockReturnValue(null),
+    mockGet,
+    mockPost,
+  } as unknown as RedditClient & { mockGet: jest.Mock; mockPost: jest.Mock };
+
+  return client;
+}