@prmichaelsen/reddit-mcp 0.1.0

package/agent/tasks/milestone-4-subreddits-and-flair/task-13-subreddit-tools.md

@@ -0,0 +1,47 @@
+# Task 13: Subreddit Tools
+
+**Milestone**: [M4 - Subreddits & Flair](../../milestones/milestone-4-subreddits-and-flair.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2.5 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for subreddit discovery, info, rules, subscription management, and search.
+
+---
+
+## Steps
+
+### 1. Create src/tools/subreddits.ts
+
+Register 8 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_subreddit_about` | GET /r/{subreddit}/about | subreddit | read |
+| `reddit_subreddit_rules` | GET /r/{subreddit}/about/rules | subreddit | read |
+| `reddit_subscribe` | POST /api/subscribe | sr_name, action=sub | subscribe |
+| `reddit_unsubscribe` | POST /api/subscribe | sr_name, action=unsub | subscribe |
+| `reddit_subreddits_mine` | GET /subreddits/mine/subscriber | limit, after, before | mysubreddits |
+| `reddit_subreddits_popular` | GET /subreddits/popular | limit, after, before | read |
+| `reddit_subreddits_new` | GET /subreddits/new | limit, after, before | read |
+| `reddit_subreddits_search` | GET /subreddits/search | q, limit, after, before | read |
+
+---
+
+## Verification
+
+- [ ] `reddit_subreddit_about` returns subreddit metadata
+- [ ] `reddit_subreddit_rules` returns rules list
+- [ ] Subscribe/unsubscribe toggle subscription
+- [ ] `reddit_subreddits_mine` lists user's subscriptions
+- [ ] `reddit_subreddits_search` finds subreddits by query
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 14: Flair Tools](task-14-flair-tools.md)

package/agent/tasks/milestone-4-subreddits-and-flair/task-14-flair-tools.md

@@ -0,0 +1,46 @@
+# Task 14: Flair Tools
+
+**Milestone**: [M4 - Subreddits & Flair](../../milestones/milestone-4-subreddits-and-flair.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 1.5 hours
+**Dependencies**: Task 13
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for reading and setting flair on posts and users.
+
+---
+
+## Steps
+
+### 1. Create src/tools/flair.ts
+
+Register 3 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_link_flair` | GET /r/{subreddit}/api/link_flair_v2 | subreddit | flair |
+| `reddit_user_flair` | GET /r/{subreddit}/api/user_flair_v2 | subreddit | flair |
+| `reddit_select_flair` | POST /r/{subreddit}/api/selectflair | subreddit, flair_template_id, link? (fullname), name? (username), text? | flair |
+
+### 2. Select flair details
+- If `link` provided: sets link flair on a post
+- If `name` provided: sets user flair
+- `flair_template_id` from the link_flair or user_flair listing
+- Optional `text` to customize flair text
+
+---
+
+## Verification
+
+- [ ] `reddit_link_flair` returns available post flair templates
+- [ ] `reddit_user_flair` returns available user flair templates
+- [ ] `reddit_select_flair` sets flair on a post or user
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 15: HTTP Transport](task-15-http-transport.md)

package/agent/tasks/milestone-4-subreddits-and-flair/task-15-http-transport.md

@@ -0,0 +1,53 @@
+# Task 15: HTTP Transport
+
+**Milestone**: [M4 - Subreddits & Flair](../../milestones/milestone-4-subreddits-and-flair.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 4
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement the streamable HTTP transport, following the youtube-mcp pattern.
+
+---
+
+## Steps
+
+### 1. Implement src/transport/http.ts
+
+```typescript
+export async function startHttpTransport(
+  server: McpServer,
+  options: { port: number; host: string }
+): Promise<void>
+```
+
+- Use MCP SDK's `StreamableHTTPServerTransport`
+- Per-session transport creation
+- Routes:
+  - POST /mcp — MCP requests
+  - GET /health — health check (`{ status: "ok" }`)
+  - Anything else — 404
+
+### 2. Update src/index.ts
+- Parse --transport flag (stdio | http)
+- Parse --port and --host flags
+- Fallback to TRANSPORT, HTTP_PORT, HTTP_HOST env vars
+- Default: stdio on port 3000
+
+---
+
+## Verification
+
+- [ ] HTTP transport serves MCP requests on /mcp
+- [ ] Health check returns 200 with `{ status: "ok" }`
+- [ ] Unknown routes return 404
+- [ ] Transport selection works via CLI flags and env vars
+- [ ] Unit tests for HTTP transport
+
+---
+
+**Next Task**: [Task 16: Mod Action Tools](../milestone-5-moderation/task-16-mod-action-tools.md)

package/agent/tasks/milestone-5-moderation/task-16-mod-action-tools.md

@@ -0,0 +1,48 @@
+# Task 16: Mod Action Tools
+
+**Milestone**: [M5 - Moderation](../../milestones/milestone-5-moderation.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement moderator action tools — approve, remove, distinguish, ignore reports, lock/unlock.
+
+---
+
+## Steps
+
+### 1. Create src/tools/moderation.ts
+
+Register 7 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_approve` | POST /api/approve | id (fullname) | modposts |
+| `reddit_remove` | POST /api/remove | id, spam? (boolean) | modposts |
+| `reddit_distinguish` | POST /api/distinguish | id, how (yes/no/admin/special) | modposts |
+| `reddit_ignore_reports` | POST /api/ignore_reports | id | modposts |
+| `reddit_unignore_reports` | POST /api/unignore_reports | id | modposts |
+| `reddit_lock` | POST /api/lock | id | modposts |
+| `reddit_unlock` | POST /api/unlock | id | modposts |
+
+### 2. Distinguish details
+- `how`: "yes" = mod distinguish, "no" = remove distinguish, "admin" = admin, "special" = special
+
+---
+
+## Verification
+
+- [ ] All 7 mod action tools registered
+- [ ] Each tool requires modposts scope
+- [ ] `reddit_remove` supports spam flag
+- [ ] `reddit_distinguish` handles all `how` values
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 17: Mod Listing Tools](task-17-mod-listing-tools.md)

package/agent/tasks/milestone-5-moderation/task-17-mod-listing-tools.md

@@ -0,0 +1,47 @@
+# Task 17: Mod Listing Tools
+
+**Milestone**: [M5 - Moderation](../../milestones/milestone-5-moderation.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 16
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for viewing moderation queues, reports, spam, edited items, and the moderation log.
+
+---
+
+## Steps
+
+### 1. Add to src/tools/moderation.ts (or create src/tools/mod-listings.ts)
+
+Register 5 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_modqueue` | GET /r/{subreddit}/about/modqueue | subreddit, limit, after, before | modposts |
+| `reddit_reports` | GET /r/{subreddit}/about/reports | subreddit, limit, after, before | modposts |
+| `reddit_spam` | GET /r/{subreddit}/about/spam | subreddit, limit, after, before | modposts |
+| `reddit_edited` | GET /r/{subreddit}/about/edited | subreddit, limit, after, before | modposts |
+| `reddit_modlog` | GET /r/{subreddit}/about/log | subreddit, type?, mod?, limit, after, before | modlog |
+
+### 2. Modlog details
+- `type` filter: banuser, unbanuser, removelink, removecomment, approvelink, approvecomment, etc.
+- `mod` filter: moderator username
+
+---
+
+## Verification
+
+- [ ] All 5 mod listing tools registered
+- [ ] `reddit_modqueue` returns items awaiting review
+- [ ] `reddit_modlog` supports type and mod filters
+- [ ] Pagination works correctly
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 18: Mod Management Tools](task-18-mod-management-tools.md)

package/agent/tasks/milestone-5-moderation/task-18-mod-management-tools.md

@@ -0,0 +1,42 @@
+# Task 18: Mod Management Tools
+
+**Milestone**: [M5 - Moderation](../../milestones/milestone-5-moderation.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 1.5 hours
+**Dependencies**: Task 16
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for listing moderators, approved contributors, banned users, and muted users.
+
+---
+
+## Steps
+
+### 1. Add to src/tools/moderation.ts
+
+Register 4 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_moderators` | GET /r/{subreddit}/about/moderators | subreddit | read |
+| `reddit_contributors` | GET /r/{subreddit}/about/contributors | subreddit, limit, after, before | modcontributors |
+| `reddit_banned` | GET /r/{subreddit}/about/banned | subreddit, limit, after, before | modcontributors |
+| `reddit_muted` | GET /r/{subreddit}/about/muted | subreddit, limit, after, before | modcontributors |
+
+---
+
+## Verification
+
+- [ ] All 4 tools registered with correct scopes
+- [ ] `reddit_moderators` returns mod list
+- [ ] `reddit_banned` returns banned user list with reasons
+- [ ] Pagination works for contributor/banned/muted lists
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 19: Multireddit Tools](../milestone-6-advanced-features-and-polish/task-19-multireddit-tools.md)

package/agent/tasks/milestone-6-advanced-features-and-polish/task-19-multireddit-tools.md

@@ -0,0 +1,49 @@
+# Task 19: Multireddit Tools
+
+**Milestone**: [M6 - Advanced Features & Polish](../../milestones/milestone-6-advanced-features-and-polish.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for managing multireddits (custom feeds) — list, get, create, update, delete, and manage subreddits within them.
+
+---
+
+## Steps
+
+### 1. Create src/tools/multireddits.ts
+
+Register 7 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_multi_mine` | GET /api/multi/mine | — | read |
+| `reddit_multi_get` | GET /api/multi/{multipath} | multipath | read |
+| `reddit_multi_create` | POST /api/multi/{multipath} | multipath, model (JSON: display_name, subreddits, visibility) | subscribe |
+| `reddit_multi_update` | PUT /api/multi/{multipath} | multipath, model (JSON) | subscribe |
+| `reddit_multi_delete` | DELETE /api/multi/{multipath} | multipath | subscribe |
+| `reddit_multi_add_sub` | PUT /api/multi/{multipath}/r/{srname} | multipath, srname, model ({name: srname}) | subscribe |
+| `reddit_multi_remove_sub` | DELETE /api/multi/{multipath}/r/{srname} | multipath, srname | subscribe |
+
+### 2. Multipath format
+- Format: `/user/{username}/m/{multiname}`
+- Example: `/user/spez/m/frontpage`
+
+---
+
+## Verification
+
+- [ ] `reddit_multi_mine` returns user's multireddits
+- [ ] CRUD operations work on multireddits
+- [ ] Add/remove subreddit from multi works
+- [ ] Multipath format correctly handled
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 20: Wiki Tools](task-20-wiki-tools.md)

package/agent/tasks/milestone-6-advanced-features-and-polish/task-20-wiki-tools.md

@@ -0,0 +1,47 @@
+# Task 20: Wiki Tools
+
+**Milestone**: [M6 - Advanced Features & Polish](../../milestones/milestone-6-advanced-features-and-polish.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 2 hours
+**Dependencies**: Task 6
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement tools for reading, editing, and browsing subreddit wiki pages and their revision history.
+
+---
+
+## Steps
+
+### 1. Create src/tools/wiki.ts
+
+Register 5 tools:
+
+| Tool | Endpoint | Parameters | Scope |
+|------|----------|------------|-------|
+| `reddit_wiki_page` | GET /r/{subreddit}/wiki/{page} | subreddit, page | wikiread |
+| `reddit_wiki_edit` | POST /r/{subreddit}/api/wiki/edit | subreddit, page, content, reason? | wikiedit |
+| `reddit_wiki_pages` | GET /r/{subreddit}/wiki/pages | subreddit | wikiread |
+| `reddit_wiki_revisions` | GET /r/{subreddit}/wiki/revisions | subreddit, limit, after, before | wikiread |
+| `reddit_wiki_page_revisions` | GET /r/{subreddit}/wiki/revisions/{page} | subreddit, page, limit, after, before | wikiread |
+
+### 2. Wiki edit details
+- `content` is the full wiki page content (markdown)
+- `reason` is an optional edit reason (like a commit message)
+
+---
+
+## Verification
+
+- [ ] `reddit_wiki_page` returns wiki page content
+- [ ] `reddit_wiki_edit` updates a wiki page
+- [ ] `reddit_wiki_pages` lists all wiki pages in a subreddit
+- [ ] Revision history tools return edit history
+- [ ] Unit tests for each tool
+
+---
+
+**Next Task**: [Task 21: Documentation & Polish](task-21-documentation-polish.md)

package/agent/tasks/milestone-6-advanced-features-and-polish/task-21-documentation-polish.md

@@ -0,0 +1,65 @@
+# Task 21: Documentation & Polish
+
+**Milestone**: [M6 - Advanced Features & Polish](../../milestones/milestone-6-advanced-features-and-polish.md)
+**Design Reference**: [Requirements](../../design/requirements.md)
+**Estimated Time**: 3 hours
+**Dependencies**: Tasks 1-20
+**Status**: Not Started
+
+---
+
+## Objective
+
+Complete README documentation, CHANGELOG, factory export for mcp-auth, and ensure the package is publish-ready.
+
+---
+
+## Steps
+
+### 1. Create comprehensive README.md
+- Project overview and description
+- Quick start guide (OAuth setup, configuration)
+- All 88 tools documented in a reference table
+- OAuth scopes per category
+- Transport options (stdio/HTTP)
+- Claude Desktop configuration example
+- Rate limit information
+- Environment variables reference
+
+### 2. Create CHANGELOG.md
+- Document all milestones as releases
+- List tools added per milestone
+
+### 3. Finalize factory export (src/factory.ts)
+```typescript
+export function createServer(accessToken: string): McpServer
+```
+- Used by reddit-mcp-server for mcp-auth integration
+- Creates server with raw access token (no OAuth flow)
+
+### 4. Package verification
+- Ensure package.json exports are correct
+- Verify `npm pack` produces clean package
+- Check no dev files included in package
+- Verify all tools registered (count = 88)
+
+### 5. Final test pass
+- Run full test suite
+- Verify coverage >= 70%
+- Check for any TODO/FIXME items
+
+---
+
+## Verification
+
+- [ ] README documents all 88 tools
+- [ ] CHANGELOG covers all milestones
+- [ ] Factory export creates server from access token
+- [ ] `npm pack` produces clean package
+- [ ] All tests pass
+- [ ] No TODO/FIXME items remaining
+- [ ] Package publishable to npm
+
+---
+
+**Related Design Docs**: [Requirements](../../design/requirements.md)

package/agent/tasks/task-1-{title}.template.md

@@ -0,0 +1,244 @@
+# Task {N}: {Descriptive Task Name}
+
+**Milestone**: [M{N} - Milestone Name](../milestones/milestone-{N}-{name}.md)
+**Design Reference**: [{Design Name}](../design/{namespace}.{design-name}.md) | None
+**Estimated Time**: [e.g., "2 hours", "4 hours", "1 day"]
+**Dependencies**: [List prerequisite tasks, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Objective
+
+[Clearly state what this task accomplishes. Be specific and focused on a single, achievable goal.]
+
+**Example**: "Create the basic project structure with all necessary configuration files and directory organization for a TypeScript-based MCP server."
+
+---
+
+## Context
+
+[Provide background information that helps understand why this task is necessary and how it fits into the larger milestone.]
+
+**Example**: "This task establishes the foundation for the project. Without proper structure and configuration, subsequent development tasks cannot proceed. The structure follows industry best practices for TypeScript projects and MCP server organization."
+
+---
+
+## Steps
+
+[Provide a detailed, sequential list of actions to complete this task. Each step should be concrete and actionable.]
+
+### 1. [Step Category or Action]
+[Detailed description of what to do]
+
+```bash
+# Command examples if applicable
+command --with-flags
+```
+
+```typescript
+// Code examples if applicable
+const example = "code";
+```
+
+### 2. [Next Step]
+[Detailed description]
+
+### 3. [Next Step]
+[Detailed description]
+
+**Example**:
+
+### 1. Create Project Directory
+Create the root directory for the project and navigate into it:
+
+```bash
+mkdir -p my-project
+cd my-project
+```
+
+### 2. Initialize npm Project
+Initialize a new npm project with default settings:
+
+```bash
+npm init -y
+```
+
+### 3. Update package.json
+Edit the generated package.json to include proper metadata and scripts:
+
+```json
+{
+  "name": "my-project",
+  "version": "0.1.0",
+  "description": "Description of what this project does",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.build.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "relevant", "keywords"],
+  "author": "Your Name",
+  "license": "MIT"
+}
+```
+
+### 4. Create Directory Structure
+Create all necessary directories:
+
+```bash
+mkdir -p src/{types,utils,tools}
+mkdir -p tests/{unit,integration}
+mkdir -p agent/{design,milestones,patterns,tasks}
+```
+
+### 5. Create Configuration Files
+Create TypeScript configuration, build scripts, and other config files.
+
+**tsconfig.json**:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+[Continue with other config files...]
+
+---
+
+## Verification
+
+[Provide a checklist of items to verify the task is complete. Each item should be objectively verifiable.]
+
+- [ ] Verification item 1: [Specific condition to check]
+- [ ] Verification item 2: [Specific condition to check]
+- [ ] Verification item 3: [Specific condition to check]
+- [ ] Verification item 4: [Specific condition to check]
+- [ ] Verification item 5: [Specific condition to check]
+
+**Example**:
+- [ ] Project directory created and contains expected subdirectories
+- [ ] package.json exists and contains correct metadata
+- [ ] tsconfig.json exists and is valid JSON
+- [ ] All configuration files created (.gitignore, .env.example, etc.)
+- [ ] Directory structure matches specification
+- [ ] No syntax errors in configuration files
+
+---
+
+## Expected Output
+
+[Describe what the project should look like after this task is complete.]
+
+**File Structure**:
+```
+project-root/
+├── file1
+├── file2
+└── directory/
+    └── file3
+```
+
+**Key Files Created**:
+- `file1`: [Purpose]
+- `file2`: [Purpose]
+- `directory/file3`: [Purpose]
+
+---
+
+## Key Design Decisions (Optional)
+
+<!-- This section is populated by @acp.clarification-capture when
+     create commands are invoked with --from-clar, --from-chat, or
+     --from-context. It can also be manually authored.
+     Omit this section entirely if no decisions to capture.
+
+     Group decisions by agent-inferred category using tables:
+
+### {Category}
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| {decision} | {choice} | {rationale} |
+-->
+
+---
+
+## Common Issues and Solutions
+
+[Document potential problems and how to resolve them:]
+
+### Issue 1: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+### Issue 2: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+**Example**:
+
+### Issue 1: npm init fails
+**Symptom**: Error message about permissions or missing npm
+**Solution**: Ensure Node.js and npm are installed correctly. Run `node --version` and `npm --version` to verify.
+
+### Issue 2: TypeScript configuration errors
+**Symptom**: tsc complains about invalid configuration
+**Solution**: Validate JSON syntax in tsconfig.json. Ensure all required fields are present.
+
+---
+
+## Resources
+
+[Link to relevant documentation, examples, or references:]
+
+- [Resource 1 Name](URL): Description
+- [Resource 2 Name](URL): Description
+- [Resource 3 Name](URL): Description
+
+**Example**:
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/): Official TypeScript documentation
+- [esbuild Documentation](https://esbuild.github.io/): Build tool documentation
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk): MCP protocol reference
+
+---
+
+## Notes
+
+[Any additional context, warnings, or considerations:]
+
+- Note 1: [Important information]
+- Note 2: [Important information]
+- Note 3: [Important information]
+
+**Example**:
+- This task creates the foundation for all subsequent work
+- Configuration files may need adjustment based on specific project requirements
+- Keep .env files out of version control (ensure .gitignore is correct)
+
+---
+
+**Next Task**: [Link to next task: task-{N+1}-{name}.md]
+**Related Design Docs**: [Links to relevant design documents]
+**Estimated Completion Date**: [YYYY-MM-DD or "TBD"]