# Reddit MCP — API 字段参考

> 每个 MCP tool 返回的完整字段说明。**所有返回示例都是真实数据**（2026-03-28 从 Reddit 实际请求获取）。

## Tools 总览

| Tool | 用途 | 返回结构 |
|------|------|---------|
| `get_subreddit_posts` | 获取 subreddit 帖子列表 | `{ posts, after }` |
| `get_post_content` | 获取帖子内容 + 评论树 | `{ post, comments, has_more }` |
| `search_reddit` | 搜索帖子 | `{ results, after }` |
| `get_subreddit_info` | 获取 subreddit 信息 | `{ name, title, ... }` |
| `check_cookies` | 检查 cookie 状态 | `{ valid, age_days, ... }` |
| `get_rate_limit_status` | API 配额状态 | `{ remaining, reset_seconds, used }` |

---

## 1. `get_subreddit_posts`

获取某个 subreddit 的帖子列表。

**参数：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `subreddit` | string | (必填) | subreddit 名称，不带 `r/`。如 `"technology"` |
| `sort` | string | `"hot"` | 排序方式：`hot` / `new` / `top` / `rising` |
| `limit` | int | 25 | 返回数量，1-100 |
| `time_filter` | string | `"day"` | 仅 `sort=top` 时生效：`hour` / `day` / `week` / `month` / `year` / `all` |
| `after` | string | null | 分页游标，从上一次返回的 `after` 字段获取 |

**真实返回示例** — `get_subreddit_posts(subreddit="technology", sort="hot", limit=2)`：

```json
{
  "posts": [
    {
      "id": "1s5yfpx",
      "title": "L.A. Dodgers Tell 82-Year-Old, 50-Year Season Ticket Holder: 'Go Digital'—Or Don't Go At All",
      "author": "-d1sc0nn3ct-",
      "subreddit": "technology",
      "score": 2912,
      "upvote_ratio": 0.95,
      "num_comments": 358,
      "created_utc": 1774699207.0,
      "created_time": "2026-03-28 20:00:07",
      "link_url": "https://www.loscerritosnews.net/2026/03/25/l-a-dodgers-tell-82-year-old-50-year-season-ticket-holder-go-digital-or-dont-go-at-all/",
      "reddit_url": "https://www.reddit.com/r/technology/comments/1s5yfpx/la_dodgers_tell_82yearold_50year_season_ticket/",
      "body": "",
      "is_text_post": false,
      "tag": "Society",
      "over_18": false
    },
    {
      "id": "1s5tgiu",
      "title": "The Shocking Speed of China's Scientific Rise",
      "author": "straightdge",
      "subreddit": "technology",
      "score": 2813,
      "upvote_ratio": 0.92,
      "num_comments": 576,
      "created_utc": 1774681330.0,
      "created_time": "2026-03-28 15:02:10",
      "link_url": "https://www.theatlantic.com/science/2026/03/china-science-superpower/686564/",
      "reddit_url": "https://www.reddit.com/r/technology/comments/1s5tgiu/the_shocking_speed_of_chinas_scientific_rise/",
      "body": "",
      "is_text_post": false,
      "tag": "Business",
      "over_18": false
    }
  ],
  "after": "t3_1s5tgiu"
}
```

**字段说明：**

| 字段 | 说明 |
|------|------|
| `posts` | 帖子数组，结构见下方 [Post 对象](#post-对象) |
| `after` | 分页游标。传给下一次请求的 `after` 参数可翻下一页。`null` = 没有更多了 |

---

## 2. `get_post_content`

获取单个帖子的完整内容和评论树。

**参数：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `post_id` | string | (必填) | 帖子 ID（如 `"1s5yfpx"`）或完整 Reddit URL |
| `comment_limit` | int | 50 | 顶级评论数量，1-200 |
| `comment_depth` | int | 3 | 评论树最大深度，1-10 |
| `comment_sort` | string | `"best"` | 评论排序：`best` / `top` / `new` / `controversial` / `old` |

**真实返回示例** — `get_post_content(post_id="1s5yfpx", comment_limit=3, comment_sort="top")`：

```json
{
  "post": {
    "id": "1s5yfpx",
    "title": "L.A. Dodgers Tell 82-Year-Old, 50-Year Season Ticket Holder: 'Go Digital'—Or Don't Go At All",
    "author": "-d1sc0nn3ct-",
    "subreddit": "technology",
    "score": 2912,
    "upvote_ratio": 0.95,
    "num_comments": 358,
    "created_utc": 1774699207.0,
    "created_time": "2026-03-28 20:00:07",
    "link_url": "https://www.loscerritosnews.net/2026/03/25/...",
    "reddit_url": "https://www.reddit.com/r/technology/comments/1s5yfpx/...",
    "body": "",
    "is_text_post": false,
    "tag": "Society",
    "over_18": false
  },
  "comments": [
    {
      "id": "ocxzy0j",
      "author": "Strange-Effort1305",
      "body": "At least they are ruining baseball for their fans too",
      "score": 2910,
      "created_utc": 1774700602.0,
      "created_time": "2026-03-28 20:23:22",
      "depth": 0,
      "replies": [
        { "kind": "more", "count": 16 }
      ]
    },
    {
      "id": "ocy0raz",
      "author": "Pr0ducer",
      "body": "The term for what to do is called Grandfathering. Just let the old guy be the exception. WTF? Yo, Magic Johnson, you're a co-owner, do something about that.",
      "score": 1191,
      "created_utc": 1774700924.0,
      "created_time": "2026-03-28 20:28:44",
      "depth": 0,
      "replies": [
        { "kind": "more", "count": 93 }
      ]
    },
    { "kind": "more", "count": 168 }
  ],
  "has_more": true
}
```

**字段说明：**

| 字段 | 说明 |
|------|------|
| `post` | 帖子内容，结构见 [Post 对象](#post-对象)。帖子被删除时为 `null` |
| `comments` | 评论数组，结构见 [Comment 对象](#comment-对象)。子评论嵌套在 `replies` 字段中 |
| `has_more` | `true` = 还有更多评论被截断了（看到数组末尾的 `"kind": "more"` 标记） |

---

## 3. `search_reddit`

全站或限定 subreddit 搜索帖子。

**参数：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | string | (必填) | 搜索关键词 |
| `sort` | string | `"relevance"` | 排序：`relevance` / `new` / `hot` / `top` / `comments` |
| `time_filter` | string | `"all"` | 时间范围：`hour` / `day` / `week` / `month` / `year` / `all` |
| `limit` | int | 25 | 返回数量，1-100 |
| `subreddit` | string | null | 限定在某个 subreddit 内搜索。不传则全站搜索 |
| `after` | string | null | 分页游标 |

**真实返回示例** — `search_reddit(query="artificial intelligence", sort="top", time_filter="week", limit=2)`：

```json
{
  "results": [
    {
      "id": "1s2p3sx",
      "title": "Sora is dead. We're going to win",
      "author": "2RINITY",
      "subreddit": "antiai",
      "score": 13341,
      "upvote_ratio": 0.95,
      "num_comments": 655,
      "created_utc": 1774383400.0,
      "created_time": "2026-03-26 08:16:40",
      "link_url": "https://i.redd.it/ivnzmi9uw1rg1.jpeg",
      "reddit_url": "https://www.reddit.com/r/antiai/comments/1s2p3sx/sora_is_dead_were_going_to_win/",
      "body": "",
      "is_text_post": false,
      "tag": "AI News 🗞️ ",
      "over_18": false
    },
    {
      "id": "1s38ef8",
      "title": "With context, this is the funniest image of the whole show.",
      "author": "_theKataclysm_",
      "subreddit": "TheDigitalCircus",
      "score": 9048,
      "upvote_ratio": 0.99,
      "num_comments": 241,
      "created_utc": 1774439150.0,
      "created_time": "2026-03-26 23:45:50",
      "link_url": "https://i.redd.it/ju5j89ami6rg1.jpeg",
      "reddit_url": "https://www.reddit.com/r/TheDigitalCircus/comments/1s38ef8/...",
      "body": "I've yet to see anyone else point out just how funny this whole bit is...",
      "is_text_post": false,
      "tag": "s:Censor1::Censor2:posts!",
      "over_18": false
    }
  ],
  "after": "t3_1s38ef8"
}
```

**字段说明：**

| 字段 | 说明 |
|------|------|
| `results` | 搜索结果数组，结构同 [Post 对象](#post-对象)。注意搜索结果来自多个 subreddit |
| `after` | 分页游标 |

---

## 4. `get_subreddit_info`

获取 subreddit 的基本信息。

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `subreddit` | string | subreddit 名称，如 `"technology"` |

**真实返回示例** — `get_subreddit_info(subreddit="technology")`：

```json
{
  "name": "technology",
  "title": "/r/Technology ",
  "description": "Subreddit dedicated to the news and discussions about the creation and use of technology and its surrounding issues.",
  "subscribers": 20204859,
  "active_users": null,
  "created_utc": 1201231675.0,
  "created_time": "2008-01-25 11:27:55",
  "over18": false,
  "subreddit_type": "public"
}
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | subreddit 短名称 |
| `title` | string | subreddit 显示标题（版主自定义的） |
| `description` | string | 公开描述文字 |
| `subscribers` | int | 订阅人数。上面的例子：r/technology 有 2020 万订阅者 |
| `active_users` | int / null | 当前在线活跃用户。Reddit 有时不返回这个数据，为 `null` |
| `created_utc` | float | 社区创建时间（Unix 时间戳，秒） |
| `created_time` | string | 社区创建时间（本地时间，24 小时制）。`"2008-01-25 11:27:55"` = 2008 年 1 月 25 日上午 11 点 |
| `over18` | bool | 是否为 NSFW（成人内容）社区 |
| `subreddit_type` | string | 社区类型：`"public"`（公开）/ `"private"`（私密）/ `"restricted"`（受限） |

---

## 5. `check_cookies`

检查当前 Reddit cookie 的状态。无参数。

**真实返回示例：**

```json
{
  "valid": true,
  "age_days": 0.3,
  "username": "Budget-Anxiety4023",
  "warning": null
}
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `valid` | bool | cookie 是否有效（能不能成功调 Reddit API） |
| `age_days` | float / null | cookie 创建了多少天。上面的 `0.3` 表示创建了约 7 小时 |
| `username` | string | 当前登录的 Reddit 用户名（仅 `valid=true` 时返回） |
| `warning` | string / null | 过期预警。cookie 快到期时会返回类似 `"⚠️ Reddit session cookie expires in 29 days..."` 的文案。正常时为 `null` |

---

## 6. `get_rate_limit_status`

获取 Reddit API 当前的请求配额状态。无参数。

**真实返回示例：**

```json
{
  "remaining": 94.0,
  "reset_seconds": 480,
  "used": 6.0
}
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `remaining` | float | 当前窗口内还能发多少次请求。Reddit 配额是 **每 10 分钟 100 次**。上面的 `94.0` 表示还剩 94 次 |
| `reset_seconds` | int | 多少秒后配额重置回 100。上面的 `480` 表示 8 分钟后重置 |
| `used` | float | 本窗口已用了多少次请求 |

---

## 公共数据结构

### Post 对象

每个帖子包含 15 个字段。以真实帖子为例：

```json
{
  "id": "1s5yfpx",
  "title": "L.A. Dodgers Tell 82-Year-Old, 50-Year Season Ticket Holder: 'Go Digital'—Or Don't Go At All",
  "author": "-d1sc0nn3ct-",
  "subreddit": "technology",
  "score": 2912,
  "upvote_ratio": 0.95,
  "num_comments": 358,
  "created_utc": 1774699207.0,
  "created_time": "2026-03-28 20:00:07",
  "link_url": "https://www.loscerritosnews.net/2026/03/25/...",
  "reddit_url": "https://www.reddit.com/r/technology/comments/1s5yfpx/...",
  "body": "",
  "is_text_post": false,
  "tag": "Society",
  "over_18": false
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 帖子唯一 ID。传给 `get_post_content` 可拿到完整内容和评论 |
| `title` | string | 帖子标题 |
| `author` | string | 发帖人的用户名 |
| `subreddit` | string | 所属社区名称 |
| `score` | int | **净投票分 = 点赞数 - 点踩数**。`2912` 表示这个帖子获得了 2912 净赞。Reddit 用这个排序帖子 |
| `upvote_ratio` | float | 点赞占总投票的比例。`0.95` = 95% 的人点了赞，5% 点了踩 |
| `num_comments` | int | 评论总数（包括所有层级的回复）。`358` = 这个帖子下有 358 条评论 |
| `created_utc` | float | 发帖时间，Unix 时间戳（秒）。保留此字段方便程序处理 |
| `created_time` | string | 发帖时间，客户端本地时间，24 小时制。`"2026-03-28 20:00:07"` = 今天晚上 8 点 |
| `link_url` | string | 帖子链接到的**目标地址**。链接帖指向外部文章（上面是一篇新闻），文字帖指向帖子自身 |
| `reddit_url` | string | 这个帖子**在 Reddit 上的地址**，点开是评论页 |
| `body` | string | 帖子正文（Markdown 格式）。链接帖为空字符串，文字帖有内容 |
| `is_text_post` | bool | `true` = 文字帖（用户自己写的内容），`false` = 链接帖（分享外部链接） |
| `tag` | string / null | 版主设置的分类标签。如 `"Society"`, `"Energy"`。没有标签时为 `null` |
| `over_18` | bool | 是否为 NSFW（成人内容） |

### Comment 对象

每条评论包含 8 个字段。以真实评论为例：

```json
{
  "id": "ocxzy0j",
  "author": "Strange-Effort1305",
  "body": "At least they are ruining baseball for their fans too",
  "score": 2910,
  "created_utc": 1774700602.0,
  "created_time": "2026-03-28 20:23:22",
  "depth": 0,
  "replies": [
    { "kind": "more", "count": 16 }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 评论唯一 ID |
| `author` | string | 评论者用户名 |
| `body` | string | 评论正文（Markdown 格式） |
| `score` | int | 净投票分，含义同 Post 的 score。这条评论获得了 2910 净赞 |
| `created_utc` | float | 评论时间，Unix 时间戳 |
| `created_time` | string | 评论时间，客户端本地时间，24 小时制 |
| `depth` | int | 嵌套层级。`0` = 顶级评论（直接回复帖子），`1` = 回复顶级评论，`2` = 回复的回复... |
| `replies` | Comment[] | 子评论数组，递归嵌套同样的结构。受 `comment_depth` 参数控制最大深度 |

### 截断标记（More 对象）

当评论太多被截断时，数组中会出现这种特殊对象：

```json
{ "kind": "more", "count": 168 }
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `kind` | string | 固定为 `"more"`，表示后面还有评论没返回 |
| `count` | int | 被截断了多少条评论。`168` = 还有 168 条评论没展示 |

这个对象可以出现在两个位置：
- `comments` 数组末尾 — 还有更多顶级评论没返回
- 某条评论的 `replies` 数组中 — 这条评论下还有更多子回复没展开
