@prmichaelsen/reddit-mcp 0.1.0

package/agent/progress.yaml

@@ -0,0 +1,223 @@
+project:
+  name: reddit-mcp
+  version: 0.1.0
+  started: 2026-03-10
+  status: in_progress
+  description: |
+    MCP server wrapping the Reddit API for AI agents
+
+milestones:
+  - id: M1
+    title: Foundation + Listings MVP
+    status: completed
+    tasks_total: 6
+    tasks_complete: 6
+    estimated_weeks: 1
+    file: agent/milestones/milestone-1-foundation-listings-mvp.md
+  - id: M2
+    title: Content Interaction
+    status: not_started
+    tasks_total: 3
+    tasks_complete: 0
+    estimated_weeks: 1
+    file: agent/milestones/milestone-2-content-interaction.md
+  - id: M3
+    title: Users & Messaging
+    status: not_started
+    tasks_total: 3
+    tasks_complete: 0
+    estimated_weeks: 1
+    file: agent/milestones/milestone-3-users-and-messaging.md
+  - id: M4
+    title: Subreddits & Flair
+    status: not_started
+    tasks_total: 3
+    tasks_complete: 0
+    estimated_weeks: 1
+    file: agent/milestones/milestone-4-subreddits-and-flair.md
+  - id: M5
+    title: Moderation
+    status: not_started
+    tasks_total: 3
+    tasks_complete: 0
+    estimated_weeks: 1
+    file: agent/milestones/milestone-5-moderation.md
+  - id: M6
+    title: Advanced Features & Polish
+    status: not_started
+    tasks_total: 3
+    tasks_complete: 0
+    estimated_weeks: 1
+    file: agent/milestones/milestone-6-advanced-features-and-polish.md
+
+tasks:
+  milestone_1:
+    - id: T1
+      title: Project Scaffolding
+      status: completed
+      estimated_hours: 2
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-1-project-scaffolding.md
+    - id: T2
+      title: Reddit OAuth 2.0
+      status: completed
+      estimated_hours: 3
+      dependencies: [T1]
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-2-reddit-oauth.md
+    - id: T3
+      title: Reddit API Client Wrapper
+      status: completed
+      estimated_hours: 3
+      dependencies: [T2]
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-3-reddit-api-client.md
+    - id: T4
+      title: Listing Tools
+      status: completed
+      estimated_hours: 3
+      dependencies: [T3]
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-4-listing-tools.md
+    - id: T5
+      title: Search Tools
+      status: completed
+      estimated_hours: 1.5
+      dependencies: [T4]
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-5-search-tools.md
+    - id: T6
+      title: Testing & Verification
+      status: completed
+      estimated_hours: 3
+      dependencies: [T1, T2, T3, T4, T5]
+      file: agent/tasks/milestone-1-foundation-listings-mvp/task-6-testing-verification.md
+  milestone_2:
+    - id: T7
+      title: Post Tools
+      status: not_started
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+      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
+
+documentation:
+  design_documents: 1
+  milestone_documents: 6
+  pattern_documents: 0
+  task_documents: 21
+
+progress:
+  planning: 100
+  implementation: 17
+  overall: 20
+
+recent_work:
+  - date: 2026-03-10
+    items:
+      - Created requirements.md with 88 Reddit API endpoints mapped to MCP tools
+      - Created 6 milestone documents
+      - Created 21 task documents organized by milestone
+      - Updated progress.yaml with full project plan
+      - "Completed M1: Foundation + Listings MVP (all 6 tasks)"
+      - Implemented project scaffolding (package.json, tsconfig, esbuild, jest)
+      - Implemented Reddit OAuth 2.0 with token refresh and file storage
+      - Implemented Reddit API client with error handling, retry, rate limits
+      - Implemented 9 listing tools + 2 search tools (11 total)
+      - Created 5 test suites (36 tests passing)
+      - 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
+
+notes:
+  - Following youtube-mcp reference pattern (same architecture)
+  - No official Reddit Node.js SDK — using raw fetch with OAuth headers
+  - Rate limit: 100 QPM per OAuth client ID
+  - 88 total MCP tools planned across 6 milestones
+
+current_blockers: []

package/agent/schemas/package.schema.yaml

@@ -0,0 +1,276 @@
+# Package YAML Schema
+# Schema for validating ACP package.yaml files
+# Version: 1.0.0
+
+schema_version: 1.0.0
+description: Schema for ACP package.yaml files
+
+# Required fields that must be present
+required_fields:
+  - name
+  - version
+  - description
+  - author
+  - license
+  - repository
+
+# Field definitions with validation rules
+fields:
+  name:
+    type: string
+    pattern: "^[a-z0-9-]+$"
+    description: "Package name (lowercase, alphanumeric, hyphens only)"
+    error_message: "Package name must be lowercase letters, numbers, and hyphens only"
+    
+  version:
+    type: string
+    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    description: "Semantic version (X.Y.Z)"
+    error_message: "Version must be in semantic versioning format (e.g., 1.0.0)"
+    
+  description:
+    type: string
+    min_length: 10
+    max_length: 200
+    description: "One-line package description"
+    error_message: "Description must be between 10 and 200 characters"
+    
+  author:
+    type: string
+    min_length: 2
+    description: "Package author name"
+    error_message: "Author name must be at least 2 characters"
+    
+  license:
+    type: string
+    description: "License identifier (e.g., MIT, Apache-2.0)"
+    error_message: "License must be specified"
+    
+  repository:
+    type: string
+    pattern: "^https?://.*\\.git$"
+    description: "Git repository URL (must end with .git)"
+    error_message: "Repository must be a valid git URL ending with .git"
+    
+  homepage:
+    type: string
+    pattern: "^https?://.*"
+    required: false
+    description: "Package homepage URL"
+    error_message: "Homepage must be a valid HTTP/HTTPS URL"
+    
+  tags:
+    type: array
+    item_type: string
+    required: false
+    description: "Tags for package discovery"
+    
+  release:
+    type: object
+    required: false
+    description: "Release configuration"
+    fields:
+      branch:
+        type: string
+        description: "Release branch name (e.g., main, master, mainline)"
+      branches:
+        type: array
+        item_type: string
+        required: false
+        description: "Additional valid release branches"
+    
+  contents:
+    type: object
+    required: true
+    description: "Package contents (patterns, commands, designs)"
+    fields:
+      patterns:
+        type: array
+        item_type: object
+        required: false
+        description: "List of pattern files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Pattern filename (e.g., namespace.pattern-name.md)"
+          description:
+            type: string
+            required: false
+            description: "Pattern description"
+          experimental:
+            type: boolean
+            required: false
+            default: false
+            description: "Mark as experimental (requires --experimental flag to install)"
+      commands:
+        type: array
+        item_type: object
+        required: false
+        description: "List of command files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Command filename (e.g., namespace.command-name.md)"
+          description:
+            type: string
+            required: false
+            description: "Command description"
+          scripts:
+            type: array
+            item_type: string
+            required: true
+            description: "Script dependencies for this command (must match command frontmatter)"
+            pattern: "^[a-z0-9-]+\\.[a-z0-9-]+\\.sh$"
+          experimental:
+            type: boolean
+            required: false
+            default: false
+            description: "Mark as experimental (requires --experimental flag to install)"
+      designs:
+        type: array
+        item_type: object
+        required: false
+        description: "List of design files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            description: "Design filename (e.g., namespace.design-name.md)"
+          description:
+            type: string
+            required: false
+            description: "Design description"
+          experimental:
+            type: boolean
+            required: false
+            default: false
+            description: "Mark as experimental (requires --experimental flag to install)"
+      scripts:
+        type: array
+        item_type: object
+        required: false
+        description: "List of script files (each with 'name' field)"
+        item_fields:
+          name:
+            type: string
+            required: true
+            pattern: "^[a-z0-9-]+\\.[a-z0-9-]+\\.sh$"
+            description: "Script filename with namespace (e.g., namespace.script-name.sh)"
+          description:
+            type: string
+            required: false
+            description: "Script description"
+          experimental:
+            type: boolean
+            required: false
+            default: false
+            description: "Mark as experimental (requires --experimental flag to install)"
+      # Templates: Source code files, configurations, and project scaffolding
+      #
+      # Templates are installed to agent/files/ (preserving subdirectory structure)
+      # NOT to project root like patterns/commands/designs go to agent/
+      # Users copy files from agent/files/ to their project as needed
+      #
+      # Variable Substitution:
+      #   - Templates can contain {{VARIABLE_NAME}} placeholders
+      #   - User prompted for values during installation
+      #   - Variables must be declared in variables array
+      #
+      # Security:
+      #   - target paths validated (no ../, no absolute paths)
+      #   - User warned when overwriting existing files
+      #   - Conflict detection before overwriting
+      #
+      # Validation Rules:
+      #   1. name must be valid file path (no .., no absolute paths)
+      #   2. target must be relative path (starts with ./ or directory name)
+      #   3. target must not escape project root (no ../)
+      #   4. variables must be UPPER_SNAKE_CASE
+      #   5. File must exist in agent/files/ directory
+      #   6. If experimental: true, file must have appropriate metadata
+      files:
+        type: array
+        item_type: object
+        required: false
+        description: "Template source files (code, configs, etc.) to bundle with package"
+        item_fields:
+          name:
+            type: string
+            required: true
+            pattern: "^[a-zA-Z0-9_/.@-]+$"
+            description: "Path to template file relative to agent/files/ directory"
+            examples:
+              - "config/tsconfig.json"
+              - "src/schemas/example.schema.ts"
+              - "config/package.json.template"
+          description:
+            type: string
+            required: true
+            min_length: 10
+            max_length: 200
+            description: "What this template provides"
+          target:
+            type: string
+            required: true
+            pattern: "^\\./|^[a-zA-Z0-9_/-]+/$"
+            description: "Where to install (relative to project root, must be relative path)"
+            examples:
+              - "./"
+              - "src/schemas/"
+              - "config/"
+          required:
+            type: boolean
+            required: false
+            default: false
+            description: "Must be installed (true) or optional (false)"
+          variables:
+            type: array
+            item_type: string
+            required: false
+            description: "Placeholder variables for {{VARIABLE}} substitution in template"
+            item_pattern: "^[A-Z_][A-Z0-9_]*$"
+            examples:
+              - "PACKAGE_NAME"
+              - "AUTHOR_NAME"
+              - "PROJECT_DESCRIPTION"
+          experimental:
+            type: boolean
+            required: false
+            default: false
+            description: "Mark as experimental (requires --experimental flag to install)"
+    
+  requires:
+    type: object
+    required: false
+    description: "Compatibility requirements"
+    fields:
+      acp:
+        type: string
+        pattern: "^>=?[0-9]+\\.[0-9]+\\.[0-9]+$"
+        description: "Minimum ACP version (e.g., >=2.0.0)"
+      npm:
+        type: object
+        required: false
+        description: "Required npm packages"
+      pip:
+        type: object
+        required: false
+        description: "Required Python packages"
+      cargo:
+        type: object
+        required: false
+        description: "Required Rust packages"
+      go:
+        type: object
+        required: false
+        description: "Required Go packages"
+
+# Reserved package names that cannot be used
+reserved_names:
+  - acp
+  - local
+  - core
+  - system
+  - global