# Requirements: reddit-mcp

**Defined:** 2026-04-14
**Core Value:** A user can install reddit-mcp once, complete setup once, and then have a working MCP integration that starts reliably from their AI client.

## v1 Requirements

### Installation Runtime

- [ ] **INST-01**: User setup installs reddit-mcp through `uv tool install`, not through a parallel official runtime path
- [ ] **INST-02**: The system has one canonical runtime command for all docs, registration, and verification: `reddit-mcp serve`
- [ ] **INST-03**: Setup never persists a guessed runtime like `python3` when the actual resolved runtime differs

### Setup Orchestration

- [ ] **SETUP-01**: `reddit-mcp setup` is the single orchestrator for install, auth, cookies, registration, and verification
- [ ] **SETUP-02**: Each required setup phase has an explicit success/failure result instead of implicit fallthrough
- [ ] **SETUP-03**: If any required phase fails, setup exits non-zero and reports the exact failed phase

### AI Client Registration

- [ ] **REG-01**: Setup auto-detects supported AI clients and auto-registers reddit-mcp where supported
- [ ] **REG-02**: Setup fails if no supported AI client is detected
- [ ] **REG-03**: Registration writes the same canonical runtime command for every supported client

### Verification

- [ ] **VER-01**: Verification confirms the installed runtime command is actually runnable on the host platform
- [ ] **VER-02**: Verification checks auth, Reddit cookies, and client registration as distinct required conditions
- [ ] **VER-03**: Installer and setup never print a final success message unless all required verification checks pass

## v2 Requirements

### Migration

- **MIG-01**: Existing pip/launcher-based installs can be migrated to the uv-based runtime path with explicit guidance
- **MIG-02**: Setup can detect legacy configuration and offer a deterministic migration path

## Out of Scope

| Feature | Reason |
|---------|--------|
| Native standalone binary packaging | Not required to remove current installer complexity |
| Supporting multiple long-term official runtime models | Directly conflicts with the simplification goal |
| Best-effort success after failed required setup phases | Creates ambiguous unusable installs |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| INST-01 | Phase 1 | Pending |
| INST-02 | Phase 1 | Pending |
| INST-03 | Phase 1 | Pending |
| SETUP-01 | Phase 1 | Pending |
| SETUP-02 | Phase 1 | Pending |
| SETUP-03 | Phase 1 | Pending |
| REG-01 | Phase 1 | Pending |
| REG-02 | Phase 1 | Pending |
| REG-03 | Phase 1 | Pending |
| VER-01 | Phase 1 | Pending |
| VER-02 | Phase 1 | Pending |
| VER-03 | Phase 1 | Pending |

**Coverage:**
- v1 requirements: 12 total
- Mapped to phases: 12
- Unmapped: 0

---
*Requirements defined: 2026-04-14*
*Last updated: 2026-04-14 after initial GSD project setup*
