@prmichaelsen/reddit-mcp 0.1.0

package/agent/milestones/milestone-1-{title}.template.md

@@ -0,0 +1,206 @@
+# Milestone {N}: {Descriptive Name}
+
+**Goal**: [One-line objective that clearly states what this milestone achieves]
+**Duration**: [Estimated time: e.g., "1-2 weeks", "3-5 days"]
+**Dependencies**: [List prerequisite milestones or external dependencies, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Overview
+
+[Provide a comprehensive description of what this milestone accomplishes and why it's important to the project. Explain how it fits into the overall project roadmap.]
+
+**Example**: "This milestone establishes the foundational infrastructure for the project, including build system, database connections, and basic server setup. It creates the scaffolding that all future features will build upon."
+
+---
+
+## Deliverables
+
+[List concrete, measurable outputs this milestone will produce. Be specific about what will exist when this milestone is complete.]
+
+### 1. [Deliverable Category 1]
+- Specific item 1
+- Specific item 2
+- Specific item 3
+
+### 2. [Deliverable Category 2]
+- Specific item 1
+- Specific item 2
+
+### 3. [Deliverable Category 3]
+- Specific item 1
+- Specific item 2
+
+**Example**:
+
+### 1. Project Structure
+- New `project-name/` directory with organized subdirectories
+- package.json with all metadata and scripts
+- TypeScript configuration (tsconfig.json)
+- Build system using esbuild
+- Directory structure: src/, tests/, agent/
+
+### 2. Core Dependencies
+- @modelcontextprotocol/sdk installed and configured
+- Database client libraries installed
+- Development tools (TypeScript, testing framework)
+
+---
+
+## Success Criteria
+
+[Define objective, verifiable criteria that indicate this milestone is complete. Each criterion should be testable.]
+
+- [ ] Criterion 1: [Specific, measurable condition]
+- [ ] Criterion 2: [Specific, measurable condition]
+- [ ] Criterion 3: [Specific, measurable condition]
+- [ ] Criterion 4: [Specific, measurable condition]
+- [ ] Criterion 5: [Specific, measurable condition]
+
+**Example**:
+- [ ] Project builds successfully (`npm run build` completes without errors)
+- [ ] TypeScript compiles without errors (`npm run typecheck` passes)
+- [ ] All dependencies install correctly (`npm install` succeeds)
+- [ ] Basic server starts and responds to health check
+- [ ] All tests pass (`npm test` succeeds)
+
+---
+
+## Key Files to Create
+
+[List the specific files and directories that will be created during this milestone. Use a tree structure for clarity.]
+
+```
+project-root/
+├── file1.ext
+├── file2.ext
+├── directory1/
+│   ├── file3.ext
+│   └── file4.ext
+└── directory2/
+    ├── subdirectory/
+    │   └── file5.ext
+    └── file6.ext
+```
+
+**Example**:
+```
+my-project/
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── .gitignore
+├── .env.example
+├── README.md
+├── src/
+│   ├── index.ts
+│   ├── server.ts
+│   ├── types/
+│   │   └── index.ts
+│   └── utils/
+│       └── logger.ts
+└── tests/
+    └── setup.test.ts
+```
+
+---
+
+## Tasks
+
+[List the tasks that comprise this milestone. Reference task documents if they exist.]
+
+1. [Task 1: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+2. [Task 2: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+3. [Task 3: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+4. [Task 4: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+
+**Example**:
+1. [Task 1: Initialize Project Structure](../tasks/task-1-initialize-project-structure.md) - Set up directories and config files
+2. [Task 2: Install Dependencies](../tasks/task-2-install-dependencies.md) - Install and configure npm packages
+3. [Task 3: Create Basic Server](../tasks/task-3-create-basic-server.md) - Implement minimal MCP server
+
+---
+
+## Environment Variables
+
+[If this milestone requires environment configuration, document it here:]
+
+```env
+# Category 1
+VAR_NAME_1=example_value
+VAR_NAME_2=example_value
+
+# Category 2
+VAR_NAME_3=example_value
+VAR_NAME_4=example_value
+```
+
+**Example**:
+```env
+# Database Configuration
+DATABASE_URL=postgresql://localhost:5432/mydb
+DATABASE_POOL_SIZE=10
+
+# API Configuration
+API_KEY=your_api_key_here
+API_URL=https://api.example.com
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+```
+
+---
+
+## Testing Requirements
+
+[Describe what testing should be in place by the end of this milestone:]
+
+- [ ] Test category 1: [Description]
+- [ ] Test category 2: [Description]
+- [ ] Test category 3: [Description]
+
+**Example**:
+- [ ] Unit tests for core utilities
+- [ ] Integration test for database connection
+- [ ] Server initialization test
+- [ ] Environment variable loading test
+
+---
+
+## Documentation Requirements
+
+[List documentation that should be created or updated:]
+
+- [ ] Document 1: [Description]
+- [ ] Document 2: [Description]
+- [ ] Document 3: [Description]
+
+**Example**:
+- [ ] README.md with project overview and quick start
+- [ ] API documentation for core interfaces
+- [ ] Development setup guide
+
+---
+
+## Risks and Mitigation
+
+[Identify potential risks and how to address them:]
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| Database connection issues | High | Medium | Provide clear error messages and connection testing utilities |
+| Dependency conflicts | Medium | Low | Pin dependency versions and test thoroughly |
+
+---
+
+**Next Milestone**: [Link to next milestone: milestone-{N+1}-{name}.md]
+**Blockers**: [List any current blockers, or "None"]
+**Notes**: [Any additional context or considerations]

package/agent/milestones/milestone-2-content-interaction.md

@@ -0,0 +1,56 @@
+# Milestone 2: Content Interaction
+
+**Goal**: Implement write operations — posting, commenting, voting, saving, and reporting
+**Duration**: 1 week
+**Dependencies**: M1 - Foundation + Listings MVP
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds all content interaction tools — the ability to create posts, write comments, vote on content, save items, and report content. These are the core write operations that make the MCP server useful for active Reddit participation.
+
+---
+
+## Deliverables
+
+### 1. Post Tools (8 tools)
+- Submit new posts (link and self-post)
+- Edit self-posts
+- Delete posts
+- Hide/unhide, NSFW marking, spoiler marking
+
+### 2. Comment Tools (2 tools)
+- Post comments and replies
+- Load more comments from collapsed threads
+
+### 3. Vote, Save & Report Tools (4 tools)
+- Upvote/downvote/unvote
+- Save/unsave content
+- Report content
+
+---
+
+## Success Criteria
+
+- [ ] `reddit_submit` creates a self-post and link post
+- [ ] `reddit_comment` posts a reply to a post
+- [ ] `reddit_vote` upvotes/downvotes content
+- [ ] `reddit_save` and `reddit_unsave` work correctly
+- [ ] All tools have proper zod validation
+- [ ] All tools include scope requirements in descriptions
+- [ ] Unit tests pass with 70%+ coverage
+
+---
+
+## Tasks
+
+1. [Task 7: Post Tools](../tasks/milestone-2-content-interaction/task-7-post-tools.md) - Submit, edit, delete, hide, NSFW, spoiler
+2. [Task 8: Comment Tools](../tasks/milestone-2-content-interaction/task-8-comment-tools.md) - Comment, reply, more_children
+3. [Task 9: Vote, Save & Report Tools](../tasks/milestone-2-content-interaction/task-9-vote-save-report-tools.md) - Vote, save/unsave, report
+
+---
+
+**Next Milestone**: [Milestone 3: Users & Messaging](milestone-3-users-and-messaging.md)
+**Blockers**: None

package/agent/milestones/milestone-3-users-and-messaging.md

@@ -0,0 +1,54 @@
+# Milestone 3: Users & Messaging
+
+**Goal**: Implement account info, user profile browsing, and private messaging tools
+**Duration**: 1 week
+**Dependencies**: M1 - Foundation + Listings MVP
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds user-facing tools — viewing your own account info, browsing other users' profiles and history, and managing private messages. These tools enable agents to understand user context and communicate via Reddit's messaging system.
+
+---
+
+## Deliverables
+
+### 1. Account Tools (7 tools)
+- Authenticated user info, karma, prefs, trophies
+- Friends and blocked user lists
+- Update preferences
+
+### 2. User Profile Tools (9 tools)
+- Public profile info
+- User post/comment history, saved items, votes
+- Trophies, block user
+
+### 3. Private Message Tools (7 tools)
+- Inbox, unread, sent messages
+- Compose, mark read/unread, delete
+
+---
+
+## Success Criteria
+
+- [ ] `reddit_me` returns authenticated user info
+- [ ] `reddit_user_about` returns another user's profile
+- [ ] `reddit_user_submitted` returns a user's post history
+- [ ] `reddit_inbox` returns inbox messages
+- [ ] `reddit_compose` sends a private message
+- [ ] All tools tested with 70%+ coverage
+
+---
+
+## Tasks
+
+1. [Task 10: Account Tools](../tasks/milestone-3-users-and-messaging/task-10-account-tools.md) - Me, karma, prefs, trophies, friends, blocked
+2. [Task 11: User Profile Tools](../tasks/milestone-3-users-and-messaging/task-11-user-profile-tools.md) - About, submitted, comments, overview, saved, votes, trophies, block
+3. [Task 12: Private Message Tools](../tasks/milestone-3-users-and-messaging/task-12-private-message-tools.md) - Inbox, unread, sent, compose, read/unread, delete
+
+---
+
+**Next Milestone**: [Milestone 4: Subreddits & Flair](milestone-4-subreddits-and-flair.md)
+**Blockers**: None

package/agent/milestones/milestone-4-subreddits-and-flair.md

@@ -0,0 +1,56 @@
+# Milestone 4: Subreddits & Flair
+
+**Goal**: Implement subreddit discovery, subscription management, flair tools, and HTTP transport
+**Duration**: 1 week
+**Dependencies**: M1 - Foundation + Listings MVP
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds subreddit management tools (info, rules, subscribe, search, discovery), flair tools (read and set link/user flair), and the streamable HTTP transport for deployment scenarios.
+
+---
+
+## Deliverables
+
+### 1. Subreddit Tools (8 tools)
+- Subreddit info and rules
+- Subscribe/unsubscribe
+- List my subs, popular, new, search
+
+### 2. Flair Tools (3 tools)
+- Get link flair options
+- Get user flair options
+- Set flair on post or user
+
+### 3. Streamable HTTP Transport
+- HTTP server with MCP StreamableHTTPServerTransport
+- Health check endpoint
+- Per-session transport handling
+
+---
+
+## Success Criteria
+
+- [ ] `reddit_subreddit_about` returns subreddit info
+- [ ] `reddit_subscribe` subscribes to a subreddit
+- [ ] `reddit_subreddits_search` finds subreddits
+- [ ] `reddit_link_flair` returns available flair
+- [ ] HTTP transport serves MCP requests
+- [ ] Health check returns OK
+- [ ] All tools tested with 70%+ coverage
+
+---
+
+## Tasks
+
+1. [Task 13: Subreddit Tools](../tasks/milestone-4-subreddits-and-flair/task-13-subreddit-tools.md) - About, rules, subscribe, mine, popular, new, search
+2. [Task 14: Flair Tools](../tasks/milestone-4-subreddits-and-flair/task-14-flair-tools.md) - Link flair, user flair, select flair
+3. [Task 15: HTTP Transport](../tasks/milestone-4-subreddits-and-flair/task-15-http-transport.md) - Streamable HTTP transport implementation
+
+---
+
+**Next Milestone**: [Milestone 5: Moderation](milestone-5-moderation.md)
+**Blockers**: None

package/agent/milestones/milestone-5-moderation.md

@@ -0,0 +1,53 @@
+# Milestone 5: Moderation
+
+**Goal**: Implement moderation action tools, mod listing tools, and mod management tools
+**Duration**: 1 week
+**Dependencies**: M2 - Content Interaction (for approve/remove patterns)
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds the full suite of moderation tools — actions (approve, remove, distinguish, lock), listing views (modqueue, reports, spam, edited, modlog), and user management (moderators, contributors, banned, muted). These tools enable AI agents to assist with subreddit moderation.
+
+---
+
+## Deliverables
+
+### 1. Mod Action Tools (7 tools)
+- Approve, remove, distinguish
+- Ignore/unignore reports
+- Lock/unlock threads
+
+### 2. Mod Listing Tools (5 tools)
+- Modqueue, reports, spam, edited items
+- Moderation log
+
+### 3. Mod Management Tools (4 tools)
+- List moderators, contributors, banned, muted users
+
+---
+
+## Success Criteria
+
+- [ ] `reddit_approve` approves a queued item
+- [ ] `reddit_remove` removes content
+- [ ] `reddit_modqueue` returns items awaiting review
+- [ ] `reddit_modlog` returns moderation log entries
+- [ ] `reddit_moderators` lists subreddit mods
+- [ ] All mod tools require correct scopes
+- [ ] All tools tested with 70%+ coverage
+
+---
+
+## Tasks
+
+1. [Task 16: Mod Action Tools](../tasks/milestone-5-moderation/task-16-mod-action-tools.md) - Approve, remove, distinguish, ignore reports, lock/unlock
+2. [Task 17: Mod Listing Tools](../tasks/milestone-5-moderation/task-17-mod-listing-tools.md) - Modqueue, reports, spam, edited, modlog
+3. [Task 18: Mod Management Tools](../tasks/milestone-5-moderation/task-18-mod-management-tools.md) - Moderators, contributors, banned, muted
+
+---
+
+**Next Milestone**: [Milestone 6: Advanced Features & Polish](milestone-6-advanced-features-and-polish.md)
+**Blockers**: None

package/agent/milestones/milestone-6-advanced-features-and-polish.md

@@ -0,0 +1,56 @@
+# Milestone 6: Advanced Features & Polish
+
+**Goal**: Implement multireddit and wiki tools, finalize documentation, publish-ready
+**Duration**: 1 week
+**Dependencies**: M1 - Foundation
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone adds multireddit management tools, wiki tools, comprehensive documentation, and the factory export for mcp-auth integration. This completes the full Reddit API coverage and makes the package publish-ready.
+
+---
+
+## Deliverables
+
+### 1. Multireddit Tools (7 tools)
+- List, get, create, update, delete multireddits
+- Add/remove subreddits from multis
+
+### 2. Wiki Tools (5 tools)
+- Read, edit, list pages
+- Revision history
+
+### 3. Documentation & Polish
+- Complete README with all 88 tools documented
+- CHANGELOG with release history
+- Factory export for mcp-auth
+- Claude Desktop configuration example
+
+---
+
+## Success Criteria
+
+- [ ] `reddit_multi_mine` returns user's multireddits
+- [ ] `reddit_multi_create` creates a multireddit
+- [ ] `reddit_wiki_page` reads a wiki page
+- [ ] `reddit_wiki_edit` edits a wiki page
+- [ ] Factory export works with mcp-auth
+- [ ] README documents all tools
+- [ ] All tools tested with 70%+ coverage
+- [ ] Package publishable to npm
+
+---
+
+## Tasks
+
+1. [Task 19: Multireddit Tools](../tasks/milestone-6-advanced-features-and-polish/task-19-multireddit-tools.md) - Mine, get, create, update, delete, add/remove sub
+2. [Task 20: Wiki Tools](../tasks/milestone-6-advanced-features-and-polish/task-20-wiki-tools.md) - Read, edit, pages, revisions
+3. [Task 21: Documentation & Polish](../tasks/milestone-6-advanced-features-and-polish/task-21-documentation-polish.md) - README, CHANGELOG, factory export, publish readiness
+
+---
+
+**Blockers**: None
+**Notes**: After this milestone, the companion reddit-mcp-server project can be built following the youtube-mcp-server pattern.

package/agent/package.template.yaml

@@ -0,0 +1,86 @@
+# package.yaml Template
+# This file defines an ACP package for distribution
+
+name: package-name
+version: 1.0.0
+description: Package description (10-200 characters)
+author: Author Name
+license: MIT
+homepage: https://github.com/user/package-name
+repository: https://github.com/user/package-name.git
+
+# Release configuration
+release:
+  branch: main
+
+# Package contents
+# List files that will be installed when users install this package
+# Format: Each entry is an object with a 'name' field
+contents:
+  patterns:
+    - name: namespace.pattern-name.md
+      description: Pattern description
+  
+  commands:
+    - name: namespace.command-name.md
+      description: Command description
+      scripts:  # REQUIRED: Must match command frontmatter **Scripts**: field
+        - namespace.command-name.sh
+        - acp.common.sh
+        - acp.yaml-parser.sh
+  
+  designs:
+    - name: namespace.design-name.md
+      description: Design description
+  
+  scripts:
+    - name: namespace.command-name.sh
+      description: Main command script
+    - name: acp.common.sh
+      description: Shared utility functions
+      type: utility
+    - name: acp.yaml-parser.sh
+      description: YAML parsing utilities
+      type: utility
+
+  # Template source files (code, configs, project scaffolding)
+  # Installed to agent/files/ - users copy to project as needed
+  # Variable substitution: {{VARIABLE_NAME}} placeholders replaced at install time
+  files:
+    # Required configuration template
+    - name: config/tsconfig.json
+      description: TypeScript configuration for core libraries
+      target: ./
+      required: true
+
+    # Template with variable substitution
+    - name: config/package.json.template
+      description: npm package.json with subpath exports
+      target: ./
+      required: true
+      variables:
+        - PACKAGE_NAME
+        - PACKAGE_DESCRIPTION
+        - AUTHOR_NAME
+
+    # Optional source code template
+    - name: src/schemas/example.schema.ts
+      description: Example Zod schema structure for data validation
+      target: src/schemas/
+      required: false
+
+    # Experimental template
+    - name: src/experimental/feature.ts
+      description: Experimental feature template for early testing
+      target: src/experimental/
+      required: false
+      experimental: true
+
+# Compatibility requirements
+requires:
+  acp: ">=2.8.0"
+
+# Tags for package discovery
+tags:
+  - tag1
+  - tag2