@prmichaelsen/reddit-mcp 0.1.0 → 0.1.1

package/src/tools/subreddits.ts

@@ -0,0 +1,137 @@
+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 to paginate after"),
+  before: z.string().optional().describe("Fullname to paginate before"),
+};
+
+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 registerSubredditTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_subreddit_about",
+    "Get a subreddit's metadata (description, subscribers, rules summary, etc). Requires 'read' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.get(`/r/${input.subreddit}/about`);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subreddit_rules",
+    "Get a subreddit's rules list. Requires 'read' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.get(`/r/${input.subreddit}/about/rules`);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subscribe",
+    "Subscribe to a subreddit. Requires 'subscribe' scope.",
+    {
+      sr_name: z.string().describe("Subreddit name to subscribe to (without r/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.post("/api/subscribe", {
+        sr_name: input.sr_name,
+        action: "sub",
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_unsubscribe",
+    "Unsubscribe from a subreddit. Requires 'subscribe' scope.",
+    {
+      sr_name: z.string().describe("Subreddit name to unsubscribe from (without r/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.post("/api/subscribe", {
+        sr_name: input.sr_name,
+        action: "unsub",
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subreddits_mine",
+    "List subreddits the authenticated user is subscribed to. Requires 'mysubreddits' scope.",
+    { ...paginationParams },
+    async (input) => {
+      const data = await client.get(
+        "/subreddits/mine/subscriber",
+        buildParams(input),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subreddits_popular",
+    "List popular subreddits. Requires 'read' scope.",
+    { ...paginationParams },
+    async (input) => {
+      const data = await client.get(
+        "/subreddits/popular",
+        buildParams(input),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subreddits_new",
+    "List newest subreddits. Requires 'read' scope.",
+    { ...paginationParams },
+    async (input) => {
+      const data = await client.get("/subreddits/new", buildParams(input));
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_subreddits_search",
+    "Search for subreddits by name or topic. Requires 'read' scope.",
+    {
+      q: z.string().describe("Search query"),
+      ...paginationParams,
+    },
+    async (input) => {
+      const data = await client.get(
+        "/subreddits/search",
+        buildParams(input),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/src/tools/users.ts

@@ -0,0 +1,181 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { RedditClient } from "../client/reddit.js";
+
+const userListingParams = {
+  sort: z
+    .enum(["hot", "new", "top", "controversial"])
+    .optional()
+    .describe("Sort order"),
+  t: z
+    .enum(["hour", "day", "week", "month", "year", "all"])
+    .optional()
+    .describe("Time filter (for top/controversial)"),
+  limit: z
+    .number()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Number of items to return (1-100, default 25)"),
+  after: z.string().optional().describe("Fullname to paginate after"),
+  before: z.string().optional().describe("Fullname to paginate before"),
+};
+
+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 registerUserTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_user_about",
+    "Get a user's public profile info. Requires 'read' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.get(`/user/${input.username}/about`);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_overview",
+    "Get a user's recent posts and comments. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/overview`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_submitted",
+    "Get a user's submitted posts. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/submitted`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_comments",
+    "Get a user's comments. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/comments`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_saved",
+    "Get a user's saved posts and comments. Only works for the authenticated user. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/saved`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_upvoted",
+    "Get a user's upvoted posts. Only works for the authenticated user. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/upvoted`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_downvoted",
+    "Get a user's downvoted posts. Only works for the authenticated user. Requires 'history' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+      ...userListingParams,
+    },
+    async (input) => {
+      const { username, ...rest } = input;
+      const data = await client.get(
+        `/user/${username}/downvoted`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_user_trophies",
+    "Get a user's trophies. Requires 'read' scope.",
+    {
+      username: z.string().describe("Username (without /u/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.get(
+        `/api/v1/user/${input.username}/trophies`,
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_block_user",
+    "Block a user. Requires 'account' scope.",
+    {
+      name: z.string().describe("Username to block (without /u/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.post("/api/block_user", {
+        name: input.name,
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/src/tools/voting.ts

@@ -0,0 +1,90 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { RedditClient } from "../client/reddit.js";
+
+export function registerVotingTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_vote",
+    "Upvote, downvote, or remove vote on a post or comment. Requires 'vote' scope.",
+    {
+      id: z
+        .string()
+        .describe("Fullname of the post (t3_) or comment (t1_) to vote on"),
+      dir: z
+        .enum(["1", "0", "-1"])
+        .describe("Vote direction: '1' = upvote, '0' = unvote, '-1' = downvote"),
+    },
+    async (input) => {
+      const data = await client.post("/api/vote", {
+        id: input.id,
+        dir: input.dir,
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_save",
+    "Save a post or comment to your saved list. Requires 'save' scope.",
+    {
+      id: z
+        .string()
+        .describe("Fullname of the post (t3_) or comment (t1_) to save"),
+      category: z
+        .string()
+        .optional()
+        .describe("Save category name (Reddit Gold feature)"),
+    },
+    async (input) => {
+      const params: Record<string, string | undefined> = {
+        id: input.id,
+        category: input.category,
+      };
+      const data = await client.post("/api/save", params);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_unsave",
+    "Remove a post or comment from your saved list. Requires 'save' scope.",
+    {
+      id: z
+        .string()
+        .describe("Fullname of the post (t3_) or comment (t1_) to unsave"),
+    },
+    async (input) => {
+      const data = await client.post("/api/unsave", { id: input.id });
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_report",
+    "Report a post or comment to subreddit moderators. Requires 'report' scope.",
+    {
+      thing_id: z
+        .string()
+        .describe("Fullname of the post (t3_) or comment (t1_) to report"),
+      reason: z
+        .string()
+        .describe("Subreddit rule violated (from subreddit rules list)"),
+      other_reason: z
+        .string()
+        .optional()
+        .describe("Additional explanation (for 'other' reason)"),
+    },
+    async (input) => {
+      const params: Record<string, string | undefined> = {
+        thing_id: input.thing_id,
+        reason: input.reason,
+        other_reason: input.other_reason,
+      };
+      const data = await client.post("/api/report", params);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/src/tools/wiki.ts

@@ -0,0 +1,118 @@
+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 to paginate after"),
+  before: z.string().optional().describe("Fullname to paginate before"),
+};
+
+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 registerWikiTools(
+  server: McpServer,
+  client: RedditClient,
+): void {
+  server.tool(
+    "reddit_wiki_page",
+    "Get the content of a wiki page. Requires 'wikiread' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      page: z.string().describe("Wiki page name (e.g. 'index', 'faq')"),
+    },
+    async (input) => {
+      const data = await client.get(
+        `/r/${input.subreddit}/wiki/${input.page}`,
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_wiki_edit",
+    "Edit a wiki page. Requires 'wikiedit' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      page: z.string().describe("Wiki page name"),
+      content: z.string().describe("Full wiki page content (markdown)"),
+      reason: z
+        .string()
+        .optional()
+        .describe("Edit reason (like a commit message)"),
+    },
+    async (input) => {
+      const data = await client.post(
+        `/r/${input.subreddit}/api/wiki/edit`,
+        {
+          page: input.page,
+          content: input.content,
+          reason: input.reason,
+        },
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_wiki_pages",
+    "List all wiki pages in a subreddit. Requires 'wikiread' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+    },
+    async (input) => {
+      const data = await client.get(`/r/${input.subreddit}/wiki/pages`);
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_wiki_revisions",
+    "Get revision history for all wiki pages in a subreddit. Requires 'wikiread' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, ...rest } = input;
+      const data = await client.get(
+        `/r/${subreddit}/wiki/revisions`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+
+  server.tool(
+    "reddit_wiki_page_revisions",
+    "Get revision history for a specific wiki page. Requires 'wikiread' scope.",
+    {
+      subreddit: z.string().describe("Subreddit name (without r/ prefix)"),
+      page: z.string().describe("Wiki page name"),
+      ...paginationParams,
+    },
+    async (input) => {
+      const { subreddit, page, ...rest } = input;
+      const data = await client.get(
+        `/r/${subreddit}/wiki/revisions/${page}`,
+        buildParams(rest),
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    },
+  );
+}

package/tests/fixtures/reddit-responses.ts

@@ -125,6 +125,165 @@ export const mockSubredditAbout = {
   },
 };
 
+export const mockSubmitResponse = {
+  json: {
+    errors: [],
+    data: {
+      url: "https://www.reddit.com/r/test/comments/newpost/my_new_post/",
+      drafts_count: 0,
+      id: "t3_newpost",
+      name: "t3_newpost",
+    },
+  },
+};
+
+export const mockEditResponse = {
+  json: {
+    errors: [],
+    data: {
+      things: [
+        {
+          kind: "t3",
+          data: {
+            id: "abc123",
+            name: "t3_abc123",
+            selftext: "Updated text",
+          },
+        },
+      ],
+    },
+  },
+};
+
+export const mockCommentResponse = {
+  json: {
+    errors: [],
+    data: {
+      things: [
+        {
+          kind: "t1",
+          data: {
+            id: "comment1",
+            name: "t1_comment1",
+            body: "This is my comment",
+            author: "testuser",
+            parent_id: "t3_abc123",
+          },
+        },
+      ],
+    },
+  },
+};
+
+export const mockMoreChildrenResponse = {
+  json: {
+    errors: [],
+    data: {
+      things: [
+        {
+          kind: "t1",
+          data: {
+            id: "more1",
+            name: "t1_more1",
+            body: "Expanded comment",
+            author: "otheruser",
+            parent_id: "t1_xyz789",
+          },
+        },
+      ],
+    },
+  },
+};
+
+export const mockMeResponse = {
+  name: "testuser",
+  id: "user123",
+  created_utc: 1600000000,
+  link_karma: 1000,
+  comment_karma: 5000,
+  is_gold: false,
+  is_mod: true,
+  has_verified_email: true,
+  subreddit: { display_name: "u_testuser", subscribers: 10 },
+};
+
+export const mockKarmaResponse = {
+  kind: "KarmaList",
+  data: [
+    { sr: "programming", comment_karma: 500, link_karma: 200 },
+    { sr: "typescript", comment_karma: 300, link_karma: 100 },
+  ],
+};
+
+export const mockPrefsResponse = {
+  over_18: false,
+  hide_downs: false,
+  default_comment_sort: "confidence",
+  lang: "en",
+  num_comments: 200,
+};
+
+export const mockTrophiesResponse = {
+  kind: "TrophyList",
+  data: {
+    trophies: [
+      { kind: "t6", data: { name: "Verified Email", icon_70: "icon.png" } },
+    ],
+  },
+};
+
+export const mockFriendsResponse = {
+  kind: "UserList",
+  data: {
+    children: [
+      { name: "friend1", date: 1700000000, id: "t2_friend1" },
+    ],
+  },
+};
+
+export const mockBlockedResponse = {
+  kind: "UserList",
+  data: {
+    children: [
+      { name: "blocked1", date: 1700000000, id: "t2_blocked1" },
+    ],
+  },
+};
+
+export const mockMessageListing = {
+  kind: "Listing",
+  data: {
+    after: null,
+    before: null,
+    children: [
+      {
+        kind: "t4",
+        data: {
+          id: "msg1",
+          name: "t4_msg1",
+          subject: "Hello",
+          body: "Hi there!",
+          author: "sender",
+          dest: "testuser",
+          created_utc: 1710000000,
+          new: true,
+        },
+      },
+    ],
+    dist: 1,
+    modhash: "",
+  },
+};
+
+export const mockComposeResponse = {
+  json: {
+    errors: [],
+    data: {},
+  },
+};
+
+export const mockEmptyResponse = {};
+
 export const mockErrorResponse = {
   error: 403,
   message: "Forbidden",