@prmichaelsen/reddit-mcp 0.1.0 → 0.1.1

package/.claude/settings.local.json

@@ -17,7 +17,10 @@
       "WebFetch(domain:publicapis.io)",
       "Bash(git add:*)",
       "Bash(npm install:*)",
-      "Bash(npm run:*)"
+      "Bash(npm run:*)",
+      "Bash(gh repo:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx jest:*)"
     ]
   }
 }

package/README.md

@@ -1,50 +1,276 @@
 # reddit-mcp
 
-MCP server wrapping the Reddit API for AI agents.
+MCP server wrapping the Reddit API for AI agents. Provides **88 tools** covering listings, search, posts, comments, voting, messaging, moderation, multireddits, wiki, and more.
 
 > Built with [Agent Context Protocol](https://github.com/prmichaelsen/agent-context-protocol)
 
+## Features
+
+- **88 MCP tools** — full Reddit API coverage across 13 categories
+- **Reddit OAuth 2.0** authentication with automatic token refresh
+- **Dual transport**: stdio (default) and Streamable HTTP
+- **Rate-limit aware**: respects Reddit's X-Ratelimit headers (100 QPM)
+- **Retry logic**: automatic retry with exponential backoff for transient errors
+- **Error mapping**: clear, actionable error messages for all API errors
+- **Factory export**: for multi-tenant use via mcp-auth
+
 ## Quick Start
 
-[Add installation and usage instructions here]
+### 1. Install
 
-## Features
+```bash
+npm install
+npm run build
+```
+
+### 2. Configure OAuth
+
+Create a Reddit app at https://www.reddit.com/prefs/apps and set these environment variables:
+
+```env
+REDDIT_CLIENT_ID=your_client_id
+REDDIT_CLIENT_SECRET=your_client_secret
+REDDIT_REDIRECT_URI=http://localhost:8080/callback
+REDDIT_USER_AGENT=platform:app-id:v0.1.0 (by /u/username)
+```
+
+### 3. Run
+
+```bash
+# stdio transport (default)
+npm start
+
+# HTTP transport
+node dist/index.js --transport http --port 3000
+```
+
+### 4. Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "node",
+      "args": ["/path/to/reddit-mcp/dist/index.js"],
+      "env": {
+        "REDDIT_CLIENT_ID": "your_client_id",
+        "REDDIT_CLIENT_SECRET": "your_client_secret",
+        "REDDIT_USER_AGENT": "platform:app-id:v0.1.0 (by /u/username)"
+      }
+    }
+  }
+}
+```
+
+## Transport Options
+
+| Transport | Flag | Default |
+|-----------|------|---------|
+| stdio | `--transport stdio` | Yes |
+| HTTP | `--transport http` | No |
+
+| Option | CLI | Env Var | Default |
+|--------|-----|---------|---------|
+| Port | `--port 3000` | `HTTP_PORT` | 3000 |
+| Host | `--host localhost` | `HTTP_HOST` | localhost |
+
+## Tools Reference
+
+### Listings (9 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_listings_best` | Get best posts | read |
+| `reddit_listings_hot` | Get hot posts (frontpage or subreddit) | read |
+| `reddit_listings_new` | Get newest posts | read |
+| `reddit_listings_rising` | Get rising posts | read |
+| `reddit_listings_top` | Get top posts (with time filter) | read |
+| `reddit_listings_controversial` | Get controversial posts | read |
+| `reddit_comments_thread` | Get post with full comment tree | read |
+| `reddit_duplicates` | Get cross-posts / duplicates | read |
+| `reddit_info` | Get info about things by fullname | read |
+
+### Search (2 tools)
 
-- Feature 1
-- Feature 2
-- Feature 3
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_search` | Search across all of Reddit | read |
+| `reddit_search_subreddit` | Search within a specific subreddit | read |
 
-## Development
+### Posts (9 tools)
 
-This project uses the Agent Context Protocol for development:
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_submit` | Create a new post (link or self) | submit |
+| `reddit_edit` | Edit a self-post or comment | edit |
+| `reddit_delete` | Delete a post or comment | edit |
+| `reddit_hide` | Hide a post from listings | report |
+| `reddit_unhide` | Unhide a post | report |
+| `reddit_mark_nsfw` | Mark a post as NSFW | modposts |
+| `reddit_unmark_nsfw` | Remove NSFW mark | modposts |
+| `reddit_spoiler` | Mark a post as spoiler | modposts |
+| `reddit_unspoiler` | Remove spoiler mark | modposts |
 
-- `@acp.init` - Initialize agent context
-- `@acp.plan` - Plan milestones and tasks
-- `@acp.proceed` - Continue with next task
-- `@acp.status` - Check project status
+### Comments (2 tools)
 
-See [AGENT.md](./AGENT.md) for complete ACP documentation.
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_comment` | Post a comment or reply | submit |
+| `reddit_more_children` | Load more comments from collapsed threads | read |
+
+### Voting, Save & Report (4 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_vote` | Upvote/downvote/unvote | vote |
+| `reddit_save` | Save content | save |
+| `reddit_unsave` | Unsave content | save |
+| `reddit_report` | Report content | report |
+
+### Account (7 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_me` | Get authenticated user info | identity |
+| `reddit_me_karma` | Get karma breakdown by subreddit | mysubreddits |
+| `reddit_me_prefs` | Get user preferences | identity |
+| `reddit_me_prefs_update` | Update user preferences | account |
+| `reddit_me_trophies` | Get user trophies | identity |
+| `reddit_me_friends` | Get friends list | mysubreddits |
+| `reddit_me_blocked` | Get blocked users list | mysubreddits |
+
+### Users (9 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_user_about` | Get user profile | read |
+| `reddit_user_overview` | Get user's recent posts and comments | history |
+| `reddit_user_submitted` | Get user's submitted posts | history |
+| `reddit_user_comments` | Get user's comments | history |
+| `reddit_user_saved` | Get user's saved items | history |
+| `reddit_user_upvoted` | Get user's upvoted posts | history |
+| `reddit_user_downvoted` | Get user's downvoted posts | history |
+| `reddit_user_trophies` | Get user's trophies | read |
+| `reddit_block_user` | Block a user | account |
+
+### Messages (7 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_inbox` | Get inbox messages | privatemessages |
+| `reddit_unread` | Get unread messages | privatemessages |
+| `reddit_sent` | Get sent messages | privatemessages |
+| `reddit_compose` | Send a private message | privatemessages |
+| `reddit_read_message` | Mark message as read | privatemessages |
+| `reddit_unread_message` | Mark message as unread | privatemessages |
+| `reddit_del_msg` | Delete a message | privatemessages |
+
+### Subreddits (8 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_subreddit_about` | Get subreddit metadata | read |
+| `reddit_subreddit_rules` | Get subreddit rules | read |
+| `reddit_subscribe` | Subscribe to a subreddit | subscribe |
+| `reddit_unsubscribe` | Unsubscribe from a subreddit | subscribe |
+| `reddit_subreddits_mine` | List subscribed subreddits | mysubreddits |
+| `reddit_subreddits_popular` | List popular subreddits | read |
+| `reddit_subreddits_new` | List newest subreddits | read |
+| `reddit_subreddits_search` | Search for subreddits | read |
+
+### Flair (3 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_link_flair` | Get available post flair templates | flair |
+| `reddit_user_flair` | Get available user flair templates | flair |
+| `reddit_select_flair` | Set flair on a post or user | flair |
+
+### Moderation (16 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_approve` | Approve a post or comment | modposts |
+| `reddit_remove` | Remove a post or comment | modposts |
+| `reddit_distinguish` | Distinguish as moderator | modposts |
+| `reddit_ignore_reports` | Ignore future reports | modposts |
+| `reddit_unignore_reports` | Stop ignoring reports | modposts |
+| `reddit_lock` | Lock a thread | modposts |
+| `reddit_unlock` | Unlock a thread | modposts |
+| `reddit_modqueue` | Get mod queue items | modposts |
+| `reddit_reports` | Get reported items | modposts |
+| `reddit_spam` | Get spam items | modposts |
+| `reddit_edited` | Get recently edited items | modposts |
+| `reddit_modlog` | Get moderation log | modlog |
+| `reddit_moderators` | List moderators | read |
+| `reddit_contributors` | List approved contributors | modcontributors |
+| `reddit_banned` | List banned users | modcontributors |
+| `reddit_muted` | List muted users | modcontributors |
+
+### Multireddits (7 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_multi_mine` | List your multireddits | read |
+| `reddit_multi_get` | Get a multireddit | read |
+| `reddit_multi_create` | Create a multireddit | subscribe |
+| `reddit_multi_update` | Update a multireddit | subscribe |
+| `reddit_multi_delete` | Delete a multireddit | subscribe |
+| `reddit_multi_add_sub` | Add subreddit to multireddit | subscribe |
+| `reddit_multi_remove_sub` | Remove subreddit from multireddit | subscribe |
+
+### Wiki (5 tools)
+
+| Tool | Description | Scope |
+|------|-------------|-------|
+| `reddit_wiki_page` | Read a wiki page | wikiread |
+| `reddit_wiki_edit` | Edit a wiki page | wikiedit |
+| `reddit_wiki_pages` | List all wiki pages | wikiread |
+| `reddit_wiki_revisions` | Get wiki revision history | wikiread |
+| `reddit_wiki_page_revisions` | Get revisions for a specific page | wikiread |
+
+## Reddit API Rate Limits
+
+- **100 queries per minute** per OAuth client ID (averaged over 10-minute window)
+- Rate limit headers are automatically parsed and respected
+- 429 responses trigger automatic backoff and retry
 
 ## Project Structure
 
 ```
 reddit-mcp/
-├── AGENT.md              # ACP methodology
-├── agent/                # ACP directory
-│   ├── design/          # Design documents
-│   ├── milestones/      # Project milestones
-│   ├── tasks/           # Task breakdown
-│   ├── patterns/        # Architectural patterns
-│   └── progress.yaml    # Progress tracking
-└── (your project files)
+├── src/
+│   ├── index.ts              # Transport selector (stdio/HTTP)
+│   ├── server.ts             # MCP server factory
+│   ├── factory.ts            # Public factory export (for mcp-auth)
+│   ├── auth/oauth.ts         # Reddit OAuth 2.0
+│   ├── client/reddit.ts      # Reddit API HTTP client
+│   ├── tools/
+│   │   ├── listings.ts       # 9 listing tools
+│   │   ├── search.ts         # 2 search tools
+│   │   ├── posts.ts          # 9 post tools
+│   │   ├── comments.ts       # 2 comment tools
+│   │   ├── voting.ts         # 4 vote/save/report tools
+│   │   ├── account.ts        # 7 account tools
+│   │   ├── users.ts          # 9 user profile tools
+│   │   ├── messages.ts       # 7 message tools
+│   │   ├── subreddits.ts     # 8 subreddit tools
+│   │   ├── flair.ts          # 3 flair tools
+│   │   ├── moderation.ts     # 16 moderation tools
+│   │   ├── multireddits.ts   # 7 multireddit tools
+│   │   └── wiki.ts           # 5 wiki tools
+│   ├── transport/http.ts     # Streamable HTTP transport
+│   └── types/index.ts        # Shared types
+├── tests/
+│   ├── unit/                 # 17 test suites (135 tests)
+│   ├── fixtures/             # Mock Reddit API responses
+│   └── helpers/              # Mock client
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+└── jest.config.js
 ```
 
-## Getting Started
-
-1. Initialize context: `@acp.init`
-2. Plan your project: `@acp.plan`
-3. Start building: `@acp.proceed`
-
 ## License
 
 MIT

package/agent/progress.yaml

@@ -16,37 +16,37 @@ milestones:
     file: agent/milestones/milestone-1-foundation-listings-mvp.md
   - id: M2
     title: Content Interaction
-    status: not_started
+    status: completed
     tasks_total: 3
-    tasks_complete: 0
+    tasks_complete: 3
     estimated_weeks: 1
     file: agent/milestones/milestone-2-content-interaction.md
   - id: M3
     title: Users & Messaging
-    status: not_started
+    status: completed
     tasks_total: 3
-    tasks_complete: 0
+    tasks_complete: 3
     estimated_weeks: 1
     file: agent/milestones/milestone-3-users-and-messaging.md
   - id: M4
     title: Subreddits & Flair
-    status: not_started
+    status: completed
     tasks_total: 3
-    tasks_complete: 0
+    tasks_complete: 3
     estimated_weeks: 1
     file: agent/milestones/milestone-4-subreddits-and-flair.md
   - id: M5
     title: Moderation
-    status: not_started
+    status: completed
     tasks_total: 3
-    tasks_complete: 0
+    tasks_complete: 3
     estimated_weeks: 1
     file: agent/milestones/milestone-5-moderation.md
   - id: M6
     title: Advanced Features & Polish
-    status: not_started
+    status: completed
     tasks_total: 3
-    tasks_complete: 0
+    tasks_complete: 3
     estimated_weeks: 1
     file: agent/milestones/milestone-6-advanced-features-and-polish.md
 
@@ -90,95 +90,95 @@ tasks:
   milestone_2:
     - id: T7
       title: Post Tools
-      status: not_started
+      status: completed
       estimated_hours: 3
       dependencies: [T6]
       file: agent/tasks/milestone-2-content-interaction/task-7-post-tools.md
     - id: T8
       title: Comment Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T7]
       file: agent/tasks/milestone-2-content-interaction/task-8-comment-tools.md
     - id: T9
       title: Vote, Save & Report Tools
-      status: not_started
+      status: completed
       estimated_hours: 1.5
       dependencies: [T7]
       file: agent/tasks/milestone-2-content-interaction/task-9-vote-save-report-tools.md
   milestone_3:
     - id: T10
       title: Account Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T6]
       file: agent/tasks/milestone-3-users-and-messaging/task-10-account-tools.md
     - id: T11
       title: User Profile Tools
-      status: not_started
+      status: completed
       estimated_hours: 2.5
       dependencies: [T6]
       file: agent/tasks/milestone-3-users-and-messaging/task-11-user-profile-tools.md
     - id: T12
       title: Private Message Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T6]
       file: agent/tasks/milestone-3-users-and-messaging/task-12-private-message-tools.md
   milestone_4:
     - id: T13
       title: Subreddit Tools
-      status: not_started
+      status: completed
       estimated_hours: 2.5
       dependencies: [T6]
       file: agent/tasks/milestone-4-subreddits-and-flair/task-13-subreddit-tools.md
     - id: T14
       title: Flair Tools
-      status: not_started
+      status: completed
       estimated_hours: 1.5
       dependencies: [T13]
       file: agent/tasks/milestone-4-subreddits-and-flair/task-14-flair-tools.md
     - id: T15
       title: HTTP Transport
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T4]
       file: agent/tasks/milestone-4-subreddits-and-flair/task-15-http-transport.md
   milestone_5:
     - id: T16
       title: Mod Action Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T6]
       file: agent/tasks/milestone-5-moderation/task-16-mod-action-tools.md
     - id: T17
       title: Mod Listing Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T16]
       file: agent/tasks/milestone-5-moderation/task-17-mod-listing-tools.md
     - id: T18
       title: Mod Management Tools
-      status: not_started
+      status: completed
       estimated_hours: 1.5
       dependencies: [T16]
       file: agent/tasks/milestone-5-moderation/task-18-mod-management-tools.md
   milestone_6:
     - id: T19
       title: Multireddit Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T6]
       file: agent/tasks/milestone-6-advanced-features-and-polish/task-19-multireddit-tools.md
     - id: T20
       title: Wiki Tools
-      status: not_started
+      status: completed
       estimated_hours: 2
       dependencies: [T6]
       file: agent/tasks/milestone-6-advanced-features-and-polish/task-20-wiki-tools.md
     - id: T21
       title: Documentation & Polish
-      status: not_started
+      status: completed
       estimated_hours: 3
       dependencies: [T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19, T20]
       file: agent/tasks/milestone-6-advanced-features-and-polish/task-21-documentation-polish.md
@@ -191,8 +191,8 @@ documentation:
 
 progress:
   planning: 100
-  implementation: 17
-  overall: 20
+  implementation: 100
+  overall: 100
 
 recent_work:
   - date: 2026-03-10
@@ -210,9 +210,8 @@ recent_work:
       - Implemented stdio and HTTP transports
 
 next_steps:
-  - Start M2 Task 7: Post Tools
-  - Continue with M2 Content Interaction (submit, comment, vote, save)
-  - Then M3 Users & Messaging
+  - All milestones complete
+  - npm publish when ready
 
 notes:
   - Following youtube-mcp reference pattern (same architecture)