Feat/reddit (#86)

* Add Reddit MCP module with tools for subreddit interaction

- Introduced a new `reddit` module, including package.json, README, and TypeScript configuration.
- Implemented tools for fetching posts from subreddits and searching Reddit content.
- Updated bun.lock and package.json to include new dependencies for the Reddit module.
- Created server structure and types for handling API requests and responses.
- Added comprehensive documentation in README for usage and development instructions.

* Update input schemas to use z.coerce for limit validation in subreddit and search requests

Author: viniciusventura29

bun.lock

@@ -32,6 +32,7 @@
     "perplexity",
     "pinecone",
     "readonly-sql",
+    "reddit",
     "registry",
     "replicate",
     "shared",

package.json

@@ -0,0 +1,61 @@
+# Reddit MCP
+
+MCP server para interagir com o Reddit. Permite buscar posts de subreddits e pesquisar conteúdo.
+
+## Tools Disponíveis
+
+### GET_SUBREDDIT_POSTS
+
+Busca posts de um subreddit específico.
+
+**Parâmetros:**
+- `subreddit` (obrigatório): Nome do subreddit (sem o "r/"). Ex: "mcp", "programming", "news"
+- `sort` (opcional): Como ordenar os posts - "hot", "new", "top", "rising" (padrão: "hot")
+- `time` (opcional): Filtro de tempo para ordenação "top" - "hour", "day", "week", "month", "year", "all"
+- `limit` (opcional): Número de posts a retornar (1-100, padrão: 25)
+- `after` (opcional): Cursor para paginação
+
+**Exemplo de uso:**
+```
+Busque os posts mais recentes do r/mcp
+```
+
+### SEARCH_REDDIT
+
+Pesquisa posts no Reddit por termo de busca.
+
+**Parâmetros:**
+- `query` (obrigatório): Termo de busca
+- `subreddit` (opcional): Limitar busca a um subreddit específico
+- `sort` (opcional): Como ordenar - "relevance", "hot", "top", "new", "comments" (padrão: "relevance")
+- `time` (opcional): Filtro de tempo - "hour", "day", "week", "month", "year", "all" (padrão: "all")
+- `limit` (opcional): Número de resultados (1-100, padrão: 25)
+- `after` (opcional): Cursor para paginação
+
+**Exemplo de uso:**
+```
+Pesquise por "MCP server" no Reddit
+Busque posts sobre "AI agents" no r/LocalLLaMA
+```
+
+## Instalação
+
+Este MCP não requer configuração adicional - utiliza a API pública do Reddit que não requer autenticação.
+
+## Desenvolvimento
+
+```bash
+# Instalar dependências
+bun install
+
+# Rodar em desenvolvimento
+bun run dev
+
+# Verificar tipos
+bun run check
+
+# Deploy
+bun run deploy
+```
+
+

reddit/README.md

@@ -0,0 +1,36 @@
+{
+  "name": "reddit",
+  "version": "1.0.0",
+  "description": "MCP server for Reddit - search subreddits and browse posts",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "deco dev --vite",
+    "configure": "deco configure",
+    "gen": "deco gen --output=shared/deco.gen.ts",
+    "deploy": "npm run build && deco deploy ./dist/server",
+    "check": "tsc --noEmit",
+    "build": "bun --bun vite build"
+  },
+  "dependencies": {
+    "@decocms/runtime": "0.25.1",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.13.4",
+    "@cloudflare/workers-types": "^4.20251014.0",
+    "@decocms/mcps-shared": "1.0.0",
+    "@mastra/core": "^0.24.0",
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "@types/mime-db": "^1.43.6",
+    "deco-cli": "^0.26.0",
+    "typescript": "^5.7.2",
+    "vite": "7.2.0",
+    "wrangler": "^4.28.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
+
+

reddit/package.json

@@ -0,0 +1,188 @@
+import { z } from "zod";
+
+/**
+ * Reddit Post data structure
+ */
+export interface RedditPost {
+  id: string;
+  title: string;
+  author: string;
+  subreddit: string;
+  subreddit_name_prefixed: string;
+  selftext: string;
+  url: string;
+  permalink: string;
+  score: number;
+  upvote_ratio: number;
+  num_comments: number;
+  created_utc: number;
+  is_self: boolean;
+  is_video: boolean;
+  thumbnail: string;
+  link_flair_text: string | null;
+  over_18: boolean;
+  spoiler: boolean;
+  stickied: boolean;
+}
+
+/**
+ * Reddit API listing response structure
+ */
+export interface RedditListingResponse {
+  kind: string;
+  data: {
+    after: string | null;
+    before: string | null;
+    dist: number;
+    modhash: string;
+    geo_filter: string;
+    children: Array<{
+      kind: string;
+      data: RedditPost;
+    }>;
+  };
+}
+
+/**
+ * Sort options for subreddit posts
+ */
+export const sortOptions = ["hot", "new", "top", "rising"] as const;
+export type SortOption = (typeof sortOptions)[number];
+
+/**
+ * Time filter options for top posts
+ */
+export const timeFilterOptions = [
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year",
+  "all",
+] as const;
+export type TimeFilterOption = (typeof timeFilterOptions)[number];
+
+/**
+ * GET_SUBREDDIT_POSTS input schema
+ */
+export const getSubredditPostsInputSchema = z.object({
+  subreddit: z
+    .string()
+    .describe(
+      "Name of the subreddit to fetch posts from (without the 'r/' prefix). Example: 'mcp', 'programming', 'news'",
+    ),
+  sort: z
+    .enum(sortOptions)
+    .optional()
+    .default("hot")
+    .describe("How to sort the posts: hot, new, top, or rising"),
+  time: z
+    .enum(timeFilterOptions)
+    .optional()
+    .describe(
+      "Time filter for 'top' sort: hour, day, week, month, year, all. Only used when sort is 'top'",
+    ),
+  limit: z.coerce
+    .number()
+    .min(1)
+    .max(100)
+    .optional()
+    .default(25)
+    .describe("Number of posts to return (1-100, default: 25)"),
+  after: z
+    .string()
+    .optional()
+    .describe("Fullname of a post to fetch posts after (for pagination)"),
+});
+
+/**
+ * GET_SUBREDDIT_POSTS output schema
+ */
+export const getSubredditPostsOutputSchema = z.object({
+  subreddit: z.string().describe("The subreddit name"),
+  sort: z.string().describe("The sort order used"),
+  count: z.number().describe("Number of posts returned"),
+  after: z.string().nullable().describe("Pagination cursor for next page"),
+  posts: z
+    .array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        author: z.string(),
+        selftext: z.string().describe("Post body text (empty if link post)"),
+        url: z.string().describe("URL of the post or linked content"),
+        permalink: z.string().describe("Reddit permalink to the post"),
+        score: z.number().describe("Upvotes minus downvotes"),
+        num_comments: z.number(),
+        created_utc: z.number().describe("Unix timestamp of creation"),
+        is_self: z.boolean().describe("True if text post, false if link post"),
+        flair: z.string().nullable().describe("Post flair text"),
+        nsfw: z.boolean().describe("True if marked NSFW"),
+      }),
+    )
+    .describe("List of posts"),
+});
+
+/**
+ * SEARCH_REDDIT input schema
+ */
+export const searchRedditInputSchema = z.object({
+  query: z.string().describe("Search query to find posts"),
+  subreddit: z
+    .string()
+    .optional()
+    .describe(
+      "Limit search to a specific subreddit (without 'r/' prefix). If not provided, searches all of Reddit",
+    ),
+  sort: z
+    .enum(["relevance", "hot", "top", "new", "comments"])
+    .optional()
+    .default("relevance")
+    .describe("How to sort search results"),
+  time: z
+    .enum(timeFilterOptions)
+    .optional()
+    .default("all")
+    .describe("Time filter: hour, day, week, month, year, all"),
+  limit: z.coerce
+    .number()
+    .min(1)
+    .max(100)
+    .optional()
+    .default(25)
+    .describe("Number of results to return (1-100, default: 25)"),
+  after: z.string().optional().describe("Pagination cursor"),
+});
+
+/**
+ * SEARCH_REDDIT output schema
+ */
+export const searchRedditOutputSchema = z.object({
+  query: z.string().describe("The search query used"),
+  subreddit: z
+    .string()
+    .nullable()
+    .describe("Subreddit searched (null if all Reddit)"),
+  sort: z.string().describe("Sort order used"),
+  count: z.number().describe("Number of results returned"),
+  after: z.string().nullable().describe("Pagination cursor for next page"),
+  posts: z
+    .array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        author: z.string(),
+        subreddit: z.string(),
+        selftext: z.string(),
+        url: z.string(),
+        permalink: z.string(),
+        score: z.number(),
+        num_comments: z.number(),
+        created_utc: z.number(),
+        is_self: z.boolean(),
+        flair: z.string().nullable(),
+        nsfw: z.boolean(),
+      }),
+    )
+    .describe("List of matching posts"),
+});

reddit/server/lib/types.ts

@@ -0,0 +1,59 @@
+/**
+ * This is the main entry point for the Reddit MCP server.
+ * This is a Cloudflare workers app, and serves your MCP server at /mcp.
+ *
+ * This MCP provides tools to interact with Reddit:
+ * - GET_SUBREDDIT_POSTS: Fetch posts from a specific subreddit
+ * - SEARCH_REDDIT: Search for posts across Reddit or within a subreddit
+ */
+import { DefaultEnv, withRuntime } from "@decocms/runtime";
+import {
+  type Env as DecoEnv,
+  StateSchema as BaseStateSchema,
+} from "../shared/deco.gen.ts";
+
+import { tools } from "./tools/index.ts";
+
+/**
+ * State schema for Reddit MCP configuration.
+ * No API key required - uses Reddit's public JSON API.
+ */
+export const StateSchema = BaseStateSchema.extend({});
+
+/**
+ * This Env type is the main context object that is passed to
+ * all of your Application.
+ *
+ * It includes all of the generated types from your
+ * Deco bindings, along with the default ones.
+ */
+export type Env = DefaultEnv &
+  DecoEnv & {
+    ASSETS: {
+      fetch: (request: Request, init?: RequestInit) => Promise<Response>;
+    };
+  };
+
+const runtime = withRuntime<Env, typeof StateSchema>({
+  oauth: {
+    /**
+     * These scopes define the asking permissions of your
+     * app when a user is installing it.
+     * Reddit public API doesn't require authentication.
+     */
+    scopes: [],
+    /**
+     * The state schema of your Application defines what
+     * your installed App state will look like.
+     * No configuration needed for Reddit public API.
+     */
+    state: StateSchema,
+  },
+  tools,
+  /**
+   * Fallback directly to assets for all requests that do not match a tool or auth.
+   */
+  fetch: (req: Request, env: Env) => env.ASSETS.fetch(req),
+});
+
+export default runtime;

reddit/server/main.ts

@@ -0,0 +1,16 @@
+/**
+ * Central export point for all tools organized by domain.
+ *
+ * This file aggregates all tools from different domains into a single
+ * export, making it easy to import all tools in main.ts while keeping
+ * the domain separation.
+ */
+import { userTools } from "@decocms/mcps-shared/tools/user";
+import { redditTools } from "./reddit.ts";
+
+// Export all tools from all domains
+export const tools = [...userTools, ...redditTools];
+
+// Re-export domain-specific tools for direct access if needed
+export { userTools } from "@decocms/mcps-shared/tools/user";
+export { redditTools } from "./reddit.ts";