# reddit-mcp

## What This Is

reddit-mcp is a local Python MCP server that lets AI clients read Reddit data through a stdio MCP process. It depends on mkterswingman auth plus local Reddit cookies, and it is intended to feel installable and operable by normal users without manual environment surgery.

## 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.

## Requirements

### Validated

- ✓ Local stdio MCP server can expose Reddit read/search tools through FastMCP
- ✓ Shared mkterswingman auth token can be reused across first-party local MCP clients
- ✓ Local Reddit cookies can be stored and validated for Reddit API access
- ✓ Hosted shell and PowerShell installers can bootstrap package installation
- ✓ AI client registration can be automated for supported local clients

### Active

- [ ] Replace the current multi-entrypoint install model with one canonical uv-based runtime path
- [ ] Make `setup` the single orchestrator for install/auth/cookies/register/verify state transitions
- [ ] Eliminate false-success installer outcomes; any failed required phase must fail setup
- [ ] Keep AI client auto-registration, but require at least one detected client for setup success
- [ ] Preserve low-friction install while reducing fallback layering and cross-platform drift

### Out of Scope

- Standalone native packaging for macOS/Windows/Linux — too much release complexity for this cleanup
- Supporting parallel long-term runtime models (`pip` global script, launcher indirection, `uvx`) — this is the complexity source being removed
- Broad backwards-compatibility magic for every historical install shape — explicit migration is preferred over permanent self-healing debt

## Context

The current install/setup stack has accumulated logic across hosted installers, reddit-mcp CLI commands, launcher generation, and shared client registration. Recent review found two concrete failures: Windows installs can register unusable `python3` runtimes, and shell/PowerShell installers can report success after setup/bootstrap failure. The architectural diagnosis is that the system currently maintains multiple execution truths at once and collapses several different setup states into one "install complete" outcome.

The chosen direction is to unify on uv, use `uv tool install` for installation, keep `reddit-mcp serve` as the only supported runtime command, retain automatic AI client registration, and fail setup if any required phase does not complete. This work is brownfield architecture simplification on an already shipped package, not greenfield product design.

## Constraints

- **Runtime**: Standardize on `uv tool install` and a single stable command path — avoid parallel official execution models
- **User experience**: Keep one primary setup entrypoint — do not force users to manually orchestrate multiple commands
- **Correctness**: Required phases must fail loudly instead of degrading to fake success
- **Integration**: AI client auto-registration remains part of the product contract
- **Detection**: Setup must fail if no supported AI client is detected for registration
- **Scope**: This phase is architecture cleanup and migration planning, not a full packaging-platform rewrite

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Standardize on uv for install/runtime management | Multiple install/runtime paths are the main complexity multiplier | — Pending |
| Use `uv tool install` as the primary install path | Persistent CLI install fits end-user MCP usage better than `uvx` | — Pending |
| Use `reddit-mcp serve` as the only supported runtime command | Registration, docs, installer, and verification need one truth source | — Pending |
| Keep automatic AI client registration | Users still need low-friction MCP onboarding | — Pending |
| Any failed required setup phase makes setup fail | Prevent fake-green installs and ambiguous support state | — Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition**:
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone**:
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-04-14 after initializing GSD planning for installer/setup architecture simplification*
