PRD Forge

Stop feeding your entire spec to Claude every time you change one paragraph.

PRD Forge splits your product requirements into independently addressable sections stored in PostgreSQL, then gives Claude surgical read/write access through 33 MCP tools. The result: edits that used to burn ~15,000 tokens now cost 500-2,000 — an 85-95% reduction in context per operation.

The Problem

Every AI-assisted PRD workflow today has the same bottleneck: Claude needs the full document loaded into context to make a single edit. A 20-page spec means ~15K tokens of context consumed on every interaction — even if you're only changing one section.

How PRD Forge Solves It

Each section stores both its full content and a short summary (1-3 sentences). When Claude reads a section, it gets:

• Full content for the target section
• Only summaries of related (dependent) sections
• Inline comments and revision history

Real example: Reading data-model (820 words, ~1,200 tokens) loads summaries of tech-stack (~60 tokens) and pipeline (~60 tokens). Total: ~1,320 tokens instead of ~15,000.

Features

• 33 MCP tools — read, write, search, import/export, manage dependencies, track revisions, resolve comments
• Multi-user auth — Better Auth (email/password + Google OAuth), 5 roles (owner/admin/editor/commenter/viewer), org-scoped access control
• Real-time collaboration — WebSocket presence, live section updates across clients
• Project templates — start with Blank, SaaS MVP, Mobile App, or API Design — pre-built section structures with starter content
• Dependency-aware context — sections know what they depend on; Claude automatically gets upstream summaries
• Full revision history — every content change creates a revision, roll back to any point
• Google Docs-style comments — inline comments anchored to specific text, threaded replies
• AI chat — streaming chat panel with Claude (Anthropic API or CLI), tool-calling into your PRD
• Dependency graph — interactive SVG visualization of section relationships
• Token stats — dashboard showing per-section token usage
• Next.js frontend — React 19, Tailwind v4, shadcn/ui, dark/light theme
• One command install — ./install.sh handles Docker, MCP config, validation

Architecture

graph LR
    A[Claude.ai / Claude Code / Claude Desktop] <-->|MCP Protocol| B[MCP Server<br/>FastMCP/Python<br/>:8080]
    B <-->|asyncpg| C[(PostgreSQL 16<br/>sections, revisions<br/>dependencies, comments)]
    D[Python API<br/>FastAPI<br/>:8088] <-->|read + write + chat| C
    E[Frontend<br/>Next.js 15<br/>:3000] <-->|REST proxy| D
    F[Redis 7] <-->|pub/sub, jti| D
    A -.->|reads comments| D

Five Docker services:

Service	Stack	Port	Purpose
PostgreSQL 16	15+ tables, 2 views	5432	Source of truth
MCP Server	FastMCP / Python	8080	34 tools for Claude
Python API	FastAPI	8088	REST backend (projects, sections, chat, auth, audit)
Frontend	Next.js 15, React 19, Tailwind v4, shadcn/ui, Better Auth	3000	Web UI
Redis 7	—	6379	WebSocket token uniqueness, real-time pub/sub

Quick Start

cd PRDforge
./install.sh

This single command:

1. Pulls pre-built images from ghcr.io (or builds locally if unavailable)
2. Starts Docker services (PostgreSQL, MCP server, API, Frontend, Redis)
3. Configures your Claude client (Code or Desktop)
4. Validates everything works

# Options
./install.sh --claude-code      # Non-interactive (HTTP transport)
./install.sh --claude-desktop   # Non-interactive (stdio transport)
./install.sh --build            # Force local build instead of pulling images
./install.sh --uninstall        # Remove config + optionally stop services
POSTGRES_PORT=5433 ./install.sh # Override host PostgreSQL port

If 5432 is already in use, install.sh automatically picks the first free port in 5433-5500.

The stack starts in ~15 seconds. PostgreSQL seeds a sample "SnapHabit" project (12 sections, 12 dependencies) on first boot.

After install, restart your Claude client. Web UI: http://localhost:3000

Configuration

MCP Configuration (Manual)

<details> <summary>Claude Code (HTTP — recommended with Docker)</summary>

Add to ~/.claude/mcp.json (or .claude/mcp.json in project):

{
  "mcpServers": {
    "prd-forge": {
      "type": "http",
      "url": "http://localhost:8080/mcp/"
    }
  }
}

Start services: docker compose up -d </details>

<details> <summary>Claude Desktop (stdio)</summary>

1. Install Python dependencies:

   cd PRDforge/mcp_server
   python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
   

2. Open Claude Desktop → Settings → Developer → Edit Config:

   {
     "mcpServers": {
       "prd-forge": {
         "command": "/absolute/path/to/PRDforge/mcp_server/.venv/bin/python",
         "args": ["/absolute/path/to/PRDforge/mcp_server/server.py"],
         "env": {
           "DATABASE_URL": "postgresql://prdforge:prdforge@localhost:5432/prdforge"
         }
       }
     }
   }
   

3. Start postgres: docker compose up -d postgres

4. Restart Claude Desktop (Cmd+Q, reopen)

Note: Claude Desktop does not support HTTP transport. Use stdio (spawns server as subprocess). </details>

<details> <summary>HTTP transport (claude.ai or other MCP clients)</summary>

{
  "mcpServers": {
    "prd-forge": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp/"
    }
  }
}

</details>

Chat Configuration

Chat is an experimental feature, disabled by default. Enable per-project in Settings → Experimental Features.

Variable	Default	Description
ANTHROPIC_API_KEY	—	Anthropic API key for chat
ANTHROPIC_MODEL	claude-haiku-4-5-20251001	Model for chat responses
CHAT_MAX_ATTACHMENTS	5	Max files per chat turn
CHAT_ATTACHMENT_MAX_BYTES	200000	Max size per file payload

MCP Tools Reference

See docs/tool-reference.md for workflows and usage examples.

<details> <summary>All 33 MCP Tools</summary>

Project (3)

Tool	Description
prd_create_project	Create project (optional template: saas-mvp, mobile-app, api-design)
prd_delete_project	Delete project and all sections (cascades)
prd_list_projects	List all projects with section counts

Sections (9)

Tool	Description
prd_create_section	Create new section with content, tags, type
prd_delete_section	Delete section (warns about dependencies)
prd_duplicate_section	Copy section with new slug
prd_list_sections	List sections — metadata only, no content
prd_merge_sections	Merge source into target (content, deps, comments, children)
prd_move_section	Change sort_order or parent section
prd_read_section	Read full content + dependency context summaries
prd_reorder_sections	Reorder sections by slug list
prd_update_section	Update fields, auto-revision on content change, atomic comment resolve

Dependencies (3)

Tool	Description
prd_add_dependency	Add/update dependency link (idempotent)
prd_remove_dependency	Remove a dependency link
prd_suggest_dependencies	Auto-suggest deps via content similarity (TF-IDF)

Comments (5)

Tool	Description
prd_add_comment	Add inline comment anchored to selected text
prd_add_comment_reply	Add a reply to an inline comment
prd_delete_comment	Delete a comment
prd_list_comments	List all comments across project with section pointers
prd_resolve_comment	Resolve or reopen a comment

Context & Search (4)

Tool	Description
prd_get_changelog	Recent revision history across all sections
prd_get_overview	Project overview with section summaries (~10% of full doc)
prd_search	Full-text or tag search across sections
prd_token_stats	Token savings statistics for the project

Revisions (3)

Tool	Description
prd_get_revisions	List revision metadata for a section
prd_read_revision	Read a specific historical revision's content
prd_rollback_section	Rollback to a previous revision (current saved as backup)

Import & Export (3)

Tool	Description
prd_export_markdown	Export full document as assembled markdown
prd_import_markdown	Import from markdown (configurable heading level or delimiter)
prd_import_url	Import from URL (SSRF-protected, Google Docs/GitHub support)

Settings (2)

Tool	Description
prd_get_settings	Get project settings (merged defaults + overrides)
prd_update_settings	Update project settings

Batch (1)

Tool	Description
prd_bulk_status	Update status for multiple sections at once

</details>

Inline Comments

Google Docs-style comments anchored to specific text in any section:

1. In the UI — select text → click "+ Comment" → write your note → Save
2. Via MCP — prd_add_comment(project, section, anchor_text, body)
3. Claude scans comments — prd_list_comments returns all open comments
4. Resolve after implementing — prd_resolve_comment or click "Resolve" in the UI

Development

# Run backend tests (requires postgres running)
docker compose up -d postgres
pip install -r tests/requirements.txt
pytest tests/ -x -v

# Frontend type checking and lint
cd frontend && yarn typecheck && yarn lint && yarn test --run

# Smoke tests (requires full stack)
docker compose up -d
pytest tests/test_smoke.py -v

# Record demo video
pip install -r scripts/requirements.txt
playwright install chromium
python scripts/record_demo.py

Project structure:

PRDforge/
├── docker-compose.yml
├── frontend/            # Next.js 15 app (React 19, Tailwind v4, shadcn/ui)
├── api/                 # FastAPI backend (REST, chat, auth, WebSocket)
├── mcp_server/          # FastMCP server (34 tools, stdio + HTTP)
├── shared/              # Shared Python modules (settings, constants, templates)
├── db/                  # PostgreSQL schema migrations (13 files)
├── tests/               # pytest test suite
├── scripts/             # Demo recording, utilities
└── docs/                # Tool reference, data model, scaling guide

Security & Deployment

PRD Forge ships with Better Auth (email/password + Google OAuth) and role-based access control. Sign-up is closed after the first user is created — new users are invited via organization member management.

Localhost-only by default:

• All ports bound to 127.0.0.1 — not accessible from LAN
• No TLS — acceptable only for localhost
• Database credentials are defaults (prdforge/prdforge)

For production deployment:

• Put behind a reverse proxy with TLS (nginx, Caddy, Traefik)
• Change database credentials in .env
• Set BETTER_AUTH_SECRET to a strong random value
• See docs/scaling.md for detailed guidance
• Do NOT bind ports to 0.0.0.0 or expose via tunnels without auth

Data Model

15+ tables, 2 views. See docs/data-model.md for the full ER diagram, dependency types, tags, statuses, and the SnapHabit example.

Backup & Restore

# Export as markdown
curl http://localhost:8088/api/projects/snaphabit/export > backup.md

# PostgreSQL dump
docker exec prdforge-postgres-1 pg_dump -U prdforge prdforge > backup.sql

# Full reset (destroys all data)
docker compose down -v && docker compose up -d

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

MIT