@prmichaelsen/reddit-mcp 0.1.0

package/agent/design/requirements.template.md

@@ -0,0 +1,387 @@
+# Project Requirements
+
+**Project Name**: [Your Project Name]
+**Created**: YYYY-MM-DD
+**Status**: Draft | Active | Implemented
+
+---
+
+## Overview
+
+[Provide a high-level description of what this project is and what it aims to accomplish. This should be a clear, concise summary that anyone can understand.]
+
+**Example**: "A multi-tenant memory system that enables AI agents to store, retrieve, and manage contextual information across sessions with vector search capabilities and relationship tracking."
+
+---
+
+## Problem Statement
+
+[Describe the problem this project solves. What pain points or needs does it address?]
+
+**Example**: "AI agents currently have no persistent memory between sessions, leading to loss of context and requiring users to repeatedly provide the same information."
+
+---
+
+## Goals and Objectives
+
+[List the primary goals this project aims to achieve. Be specific and measurable where possible.]
+
+### Primary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+3. Goal 3: [Description]
+
+### Secondary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+
+**Example**:
+
+### Primary Goals
+1. Enable persistent memory storage across agent sessions
+2. Provide fast vector-based semantic search
+3. Support multi-tenant isolation for data security
+
+### Secondary Goals
+1. Implement relationship tracking between memories
+2. Add trust-based access control
+3. Support template-based memory creation
+
+---
+
+## Functional Requirements
+
+[List what the system must do. These are the features and capabilities.]
+
+### Core Features
+1. **Feature 1**: [Description of what it does]
+2. **Feature 2**: [Description of what it does]
+3. **Feature 3**: [Description of what it does]
+
+### Additional Features
+1. **Feature 1**: [Description]
+2. **Feature 2**: [Description]
+
+**Example**:
+
+### Core Features
+1. **Memory Storage**: Store structured memories with metadata (title, content, tags, timestamps)
+2. **Vector Search**: Find semantically similar memories using vector embeddings
+3. **Multi-Tenancy**: Isolate user data with per-user access control
+
+### Additional Features
+1. **Relationship Graph**: Track connections between related memories
+2. **Template System**: Pre-defined memory structures for common use cases
+3. **Trust Levels**: Control memory visibility based on trust scores
+
+---
+
+## Non-Functional Requirements
+
+[Describe quality attributes and constraints.]
+
+### Performance
+- Requirement 1: [Specific metric]
+- Requirement 2: [Specific metric]
+
+### Security
+- Requirement 1: [Security requirement]
+- Requirement 2: [Security requirement]
+
+### Scalability
+- Requirement 1: [Scalability requirement]
+- Requirement 2: [Scalability requirement]
+
+### Reliability
+- Requirement 1: [Reliability requirement]
+- Requirement 2: [Reliability requirement]
+
+**Example**:
+
+### Performance
+- Search queries return results in < 200ms for 95th percentile
+- Support 1000+ concurrent users
+
+### Security
+- Complete data isolation between tenants
+- All API endpoints require authentication
+- Sensitive data encrypted at rest
+
+### Scalability
+- Horizontal scaling for increased load
+- Support millions of memories per tenant
+
+### Reliability
+- 99.9% uptime SLA
+- Automatic backups every 24 hours
+- Graceful degradation under load
+
+---
+
+## Technical Requirements
+
+[Specify technical constraints and requirements.]
+
+### Technology Stack
+- **Language**: [Programming language and version]
+- **Framework**: [Framework and version]
+- **Database**: [Database technology]
+- **Infrastructure**: [Hosting/deployment platform]
+
+### Dependencies
+- Dependency 1: [Purpose]
+- Dependency 2: [Purpose]
+- Dependency 3: [Purpose]
+
+### Integrations
+- Integration 1: [What it integrates with and why]
+- Integration 2: [What it integrates with and why]
+
+**Example**:
+
+### Technology Stack
+- **Language**: TypeScript 5.x
+- **Runtime**: Node.js 20+
+- **Protocol**: Model Context Protocol (MCP)
+- **Vector DB**: Weaviate
+- **Document DB**: Firestore
+- **Authentication**: Firebase Auth
+
+### Dependencies
+- @modelcontextprotocol/sdk: MCP protocol implementation
+- weaviate-client: Vector database client
+- firebase-admin: Firestore and auth
+
+### Integrations
+- OpenAI API: Generate vector embeddings
+- Firebase Auth: User authentication and authorization
+
+---
+
+## User Stories
+
+[Describe functionality from the user's perspective.]
+
+### As a [User Type]
+1. I want to [action] so that [benefit]
+2. I want to [action] so that [benefit]
+3. I want to [action] so that [benefit]
+
+**Example**:
+
+### As an AI Agent
+1. I want to store memories about user preferences so that I can personalize responses
+2. I want to search for relevant memories so that I can provide contextual answers
+3. I want to create relationships between memories so that I can understand connections
+
+### As a User
+1. I want my data isolated from other users so that my privacy is protected
+2. I want to control which memories are shared so that I maintain control over my data
+3. I want to export my memories so that I can back them up
+
+---
+
+## Constraints
+
+[List any limitations or constraints on the project.]
+
+### Technical Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Business Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Resource Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+**Example**:
+
+### Technical Constraints
+- Must use existing Firebase infrastructure
+- Vector embeddings limited to OpenAI models
+- MCP protocol requires stdio or SSE transport
+
+### Business Constraints
+- Must launch MVP within 3 months
+- Free tier must support 1000 memories per user
+- Must comply with GDPR and data privacy regulations
+
+### Resource Constraints
+- Single developer for initial implementation
+- Limited budget for cloud infrastructure
+- No dedicated QA team
+
+---
+
+## Success Criteria
+
+[Define what success looks like. How will you know the project is complete and successful?]
+
+### MVP Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+### Full Release Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+**Example**:
+
+### MVP Success Criteria
+- [ ] Users can create, read, update, and delete memories
+- [ ] Vector search returns relevant results
+- [ ] Multi-tenant isolation verified through security testing
+- [ ] Basic documentation complete
+
+### Full Release Success Criteria
+- [ ] All core and additional features implemented
+- [ ] Performance meets specified metrics
+- [ ] Security audit passed
+- [ ] 100 active users with positive feedback
+- [ ] Comprehensive documentation and examples
+
+---
+
+## Out of Scope
+
+[Explicitly list what is NOT included in this project to manage expectations.]
+
+1. Feature/capability 1: [Why it's out of scope]
+2. Feature/capability 2: [Why it's out of scope]
+3. Feature/capability 3: [Why it's out of scope]
+
+**Example**:
+
+1. **Mobile app**: Focus is on MCP server, not end-user applications
+2. **Real-time collaboration**: Single-user focus for MVP
+3. **Advanced analytics**: Basic usage stats only, no complex analytics
+4. **Custom embedding models**: OpenAI only for MVP
+5. **On-premise deployment**: Cloud-only for initial release
+
+---
+
+## Assumptions
+
+[List assumptions being made about the project.]
+
+1. Assumption 1: [Description]
+2. Assumption 2: [Description]
+3. Assumption 3: [Description]
+
+**Example**:
+
+1. Users have stable internet connectivity
+2. OpenAI API will remain available and affordable
+3. Firebase infrastructure will scale to meet demand
+4. MCP protocol will remain stable (no breaking changes)
+5. Users understand basic AI agent concepts
+
+---
+
+## Risks
+
+[Identify potential risks and mitigation strategies.]
+
+| 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] |
+| [Risk 3] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| OpenAI API cost escalation | High | Medium | Implement caching, batch processing, consider alternative providers |
+| Security vulnerability | High | Low | Regular security audits, follow best practices, bug bounty program |
+| Performance degradation at scale | Medium | Medium | Load testing, performance monitoring, optimization plan |
+| MCP protocol changes | Medium | Low | Stay updated with MCP community, version pinning |
+
+---
+
+## Timeline
+
+[Provide a high-level timeline for the project.]
+
+### Phase 1: [Phase Name] (Duration)
+- Milestone 1
+- Milestone 2
+
+### Phase 2: [Phase Name] (Duration)
+- Milestone 3
+- Milestone 4
+
+### Phase 3: [Phase Name] (Duration)
+- Milestone 5
+- Milestone 6
+
+**Example**:
+
+### Phase 1: Foundation (Weeks 1-2)
+- Project setup and infrastructure
+- Basic MCP server implementation
+- Database connections
+
+### Phase 2: Core Features (Weeks 3-6)
+- Memory CRUD operations
+- Vector search implementation
+- Multi-tenant isolation
+
+### Phase 3: Advanced Features (Weeks 7-10)
+- Relationship tracking
+- Template system
+- Trust-based access control
+
+### Phase 4: Polish & Launch (Weeks 11-12)
+- Testing and bug fixes
+- Documentation
+- Deployment and monitoring
+
+---
+
+## Stakeholders
+
+[Identify who is involved in or affected by this project.]
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| [Role 1] | [Name] | [What they do] |
+| [Role 2] | [Name] | [What they do] |
+| [Role 3] | [Name] | [What they do] |
+
+**Example**:
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| Product Owner | [Name] | Define requirements, prioritize features |
+| Lead Developer | [Name] | Architecture, implementation, code review |
+| DevOps | [Name] | Infrastructure, deployment, monitoring |
+| Users | AI Agent Developers | Provide feedback, report issues |
+
+---
+
+## References
+
+[Link to related documents, research, or resources.]
+
+- [Document/Resource 1](URL): Description
+- [Document/Resource 2](URL): Description
+- [Document/Resource 3](URL): Description
+
+**Example**:
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io): MCP protocol documentation
+- [Weaviate Documentation](https://weaviate.io/developers/weaviate): Vector database docs
+- [Firebase Documentation](https://firebase.google.com/docs): Firebase platform docs
+- [Similar Project Analysis](URL): Research on existing solutions
+
+---
+
+**Status**: [Current status of requirements]
+**Last Updated**: [YYYY-MM-DD]
+**Next Review**: [YYYY-MM-DD]

package/agent/index/local.main.template.yaml

@@ -0,0 +1,37 @@
+# agent/index/local.main.yaml
+# Key file index for project-local files
+# See: agent/design/local.key-file-index-system.md
+#
+# Naming convention: {namespace}.{qualifier}.yaml
+#   - namespace: "local" for project files, package name for packages
+#   - qualifier: "main" is the default, can use others for categorization
+#
+# Schema:
+#   path        (string, required)  - Explicit file path, no globs
+#   weight      (float, required)   - 0.0 to 1.0 importance (1.0 = always read)
+#   kind        (enum, required)    - pattern, command, design, requirements
+#   description (string, required)  - What the file contains and why it matters
+#   rationale   (string, required)  - Why this file is in the index
+#   applies     (string, required)  - Comma-separated fully qualified command names
+#
+# Recommended limits:
+#   - Per-namespace: 5-10 entries maximum
+#   - Total across namespaces: 15-20 entries maximum
+#   - High-weight files (>= 0.8): 3-5 per namespace
+#
+# Implicit key files (NOT listed here):
+#   - AGENT.md (always read by @acp.init)
+#   - agent/progress.yaml (always read by @acp.init)
+
+local:
+  index:
+    - path: agent/design/requirements.md
+      weight: 1.0
+      kind: requirements
+      description: |
+        Core project requirements defining goals, constraints,
+        and success criteria for the application.
+      rationale: |
+        Must be read before any design or task creation to ensure
+        alignment with project goals.
+      applies: acp.init, acp.design-create, acp.task-create, acp.plan, acp.proceed

package/agent/manifest.template.yaml

@@ -0,0 +1,13 @@
+# agent/manifest.template.yaml
+# Template for ACP package manifest
+# This file tracks installed ACP packages and their versions
+
+# Installed packages
+# Each package entry tracks source, version, and installed files
+packages: {}
+
+# Manifest format version (for future compatibility)
+manifest_version: 1.0.0
+
+# Last time manifest was updated
+last_updated: null

package/agent/manifest.yaml

@@ -0,0 +1,61 @@
+# ACP Package Manifest
+# Tracks installed packages and their versions
+
+packages:
+  acp-core:
+    source: https://github.com/prmichaelsen/agent-context-protocol.git
+    package_version: 5.15.1
+    installed_at: 2026-03-10T17:47:16Z
+    updated_at: 2026-03-10T17:47:16Z
+    files:
+      commands:
+        - name: acp.clarification-capture.md
+        - name: acp.clarification-create.md
+        - name: acp.clarifications-research.md
+        - name: acp.command-create.md
+        - name: acp.design-create.md
+        - name: acp.design-reference.md
+        - name: acp.index.md
+        - name: acp.init.md
+        - name: acp.package-create.md
+        - name: acp.package-info.md
+        - name: acp.package-install.md
+        - name: acp.package-list.md
+        - name: acp.package-publish.md
+        - name: acp.package-remove.md
+        - name: acp.package-search.md
+        - name: acp.package-update.md
+        - name: acp.package-validate.md
+        - name: acp.pattern-create.md
+        - name: acp.plan.md
+        - name: acp.proceed.md
+        - name: acp.project-create.md
+        - name: acp.project-info.md
+        - name: acp.project-list.md
+        - name: acp.project-remove.md
+        - name: acp.project-set.md
+        - name: acp.project-update.md
+        - name: acp.projects-restore.md
+        - name: acp.projects-sync.md
+        - name: acp.report.md
+        - name: acp.resume.md
+        - name: acp.sessions.md
+        - name: acp.status.md
+        - name: acp.sync.md
+        - name: acp.task-create.md
+        - name: acp.update.md
+        - name: acp.validate.md
+        - name: acp.version-check-for-updates.md
+        - name: acp.version-check.md
+        - name: acp.version-update.md
+        - name: git.commit.md
+        - name: git.init.md
+      patterns:
+        - name: bootstrap.template.md
+        - name: pattern.template.md
+      designs:
+        - name: design.template.md
+        - name: requirements.template.md
+
+manifest_version: 1.0.0
+last_updated: 2026-03-10T17:47:16Z

package/agent/milestones/milestone-1-foundation-listings-mvp.md

@@ -0,0 +1,140 @@
+# Milestone 1: Foundation + Listings MVP
+
+**Goal**: Establish project infrastructure and implement core read-only Reddit browsing tools
+**Duration**: 1 week
+**Dependencies**: None
+**Status**: Not Started
+
+---
+
+## Overview
+
+This milestone creates the foundational project infrastructure — build system, OAuth authentication, Reddit API client wrapper — and implements the core read-only listing and search tools. This is the MVP that proves the MCP server can authenticate with Reddit and return content.
+
+---
+
+## Deliverables
+
+### 1. Project Infrastructure
+- package.json with all metadata, scripts, and dependencies
+- TypeScript configuration (tsconfig.json)
+- Build system (esbuild.build.js)
+- Jest test configuration
+- Directory structure: src/, tests/
+
+### 2. Reddit OAuth 2.0 Authentication
+- Authorization code flow with PKCE
+- Token storage and automatic refresh
+- Scope-based access control
+- Factory function from environment variables
+
+### 3. Reddit API Client
+- HTTP client wrapper using fetch
+- Proper User-Agent header
+- Rate limit header parsing (X-Ratelimit-Remaining/Reset)
+- Error mapping (400, 401, 403, 404, 429, 5xx)
+- Retry with exponential backoff
+
+### 4. MCP Server + Listing Tools
+- MCP server factory (createServer / createServerWithToken)
+- 11 listing and search tools
+- stdio transport
+
+---
+
+## Success Criteria
+
+- [ ] `npm run build` completes without errors
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes with 70%+ coverage
+- [ ] OAuth flow authenticates with Reddit
+- [ ] `reddit_listings_hot` returns posts from a subreddit
+- [ ] `reddit_search` returns search results
+- [ ] `reddit_comments_thread` returns a post with comments
+- [ ] Server starts via stdio transport
+
+---
+
+## Key Files to Create
+
+```
+reddit-mcp/
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── jest.config.js
+├── .env.example
+├── src/
+│   ├── index.ts              # Transport selector
+│   ├── server.ts             # MCP server factory
+│   ├── factory.ts            # Public factory export
+│   ├── auth/
+│   │   └── oauth.ts          # Reddit OAuth 2.0
+│   ├── client/
+│   │   └── reddit.ts         # Reddit API HTTP client
+│   ├── tools/
+│   │   ├── listings.ts       # Listing tools (hot, new, top, etc.)
+│   │   └── search.ts         # Search tools
+│   ├── transport/
+│   │   └── http.ts           # HTTP transport (stubbed)
+│   └── types/
+│       └── index.ts          # Shared types
+└── tests/
+    ├── unit/
+    │   ├── auth.test.ts
+    │   ├── client.test.ts
+    │   ├── server.test.ts
+    │   ├── listings.test.ts
+    │   └── search.test.ts
+    ├── fixtures/
+    │   └── reddit-responses.ts
+    └── helpers/
+        └── mock-client.ts
+```
+
+---
+
+## Tasks
+
+1. [Task 1: Project Scaffolding](../tasks/milestone-1-foundation-listings-mvp/task-1-project-scaffolding.md) - Set up project structure, config files, dependencies
+2. [Task 2: Reddit OAuth 2.0](../tasks/milestone-1-foundation-listings-mvp/task-2-reddit-oauth.md) - Implement OAuth authentication flow
+3. [Task 3: Reddit API Client Wrapper](../tasks/milestone-1-foundation-listings-mvp/task-3-reddit-api-client.md) - HTTP client with error handling and retry
+4. [Task 4: Listing Tools](../tasks/milestone-1-foundation-listings-mvp/task-4-listing-tools.md) - Implement browsing and comment thread tools
+5. [Task 5: Search Tools](../tasks/milestone-1-foundation-listings-mvp/task-5-search-tools.md) - Implement search across Reddit and subreddits
+6. [Task 6: Testing & Verification](../tasks/milestone-1-foundation-listings-mvp/task-6-testing-verification.md) - Unit tests, fixtures, CI readiness
+
+---
+
+## Environment Variables
+
+```env
+# Reddit OAuth
+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)
+
+# Token Storage
+TOKEN_STORAGE_PATH=./.tokens/reddit.json
+
+# Transport
+TRANSPORT=stdio
+HTTP_PORT=3000
+HTTP_HOST=localhost
+```
+
+---
+
+## Testing Requirements
+
+- [ ] Unit tests for OAuth flow (token exchange, refresh)
+- [ ] Unit tests for API client (error mapping, retry logic)
+- [ ] Unit tests for each listing tool (parameter validation, response formatting)
+- [ ] Unit tests for search tools
+- [ ] Mock client for isolated testing
+- [ ] Response fixtures for consistent test data
+
+---
+
+**Next Milestone**: [Milestone 2: Content Interaction](milestone-2-content-interaction.md)
+**Blockers**: None