Metadata-Version: 2.4
Name: drg-home-buying-dd
Version: 0.1.0
Summary: Home-buying due-diligence MCP server: public-API tools (FEMA, USDA, Census, RentCast) + screenshot intake + evidence-packet PDF generation.
Project-URL: Homepage, https://github.com/dandelionrosegroup/drg-plugins/tree/main/home-buying-dd
Project-URL: Documentation, https://github.com/dandelionrosegroup/drg-plugins/blob/main/home-buying-dd/ONBOARDING.md
Project-URL: Repository, https://github.com/dandelionrosegroup/drg-plugins.git
Project-URL: Issues, https://github.com/dandelionrosegroup/drg-plugins/issues
Author-email: "Dandelion Rose Group, LLC" <jack@jackderro.com>
License: MIT
Keywords: claude,due-diligence,fema-flood,home-buying,mcp,property-valuation,real-estate,usda-soil
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: reportlab>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# drg-home-buying-dd

Home-buying due-diligence MCP server. Public-API tools (FEMA flood, USDA soil, Census demographics) + screenshot intake for listing/auditor data + Pre-Visit Brief and Buyer's Evidence Packet PDF generators.

Designed to be installed once by a non-developer friend/family member and used inside Claude Code for residential property evaluation.

## Why this exists

Real estate listing sites (Zillow, Realtor.com, Redfin) and most county auditor portals block automated requests. The reliable path for an AI agent is:

1. The **user** opens the listing in their normal browser (logged-in, looks human to anti-bot systems)
2. They drag a **screenshot** into Claude
3. The MCP server uses Claude vision to extract structured data
4. The MCP server hits **public, ToS-compliant APIs** (FEMA NFHL, USDA SDA, Census) for environmental and demographic data
5. The MCP server generates a PDF — either a *Pre-Visit Brief* (before site visit) or *Buyer's Evidence Packet* (after inspection)

No scraping. No ToS violations. No subscription costs. Robust to listing-site redesigns.

## Tools

### Public-API (Phase 1)
| Tool | What it does |
|---|---|
| `geocode_address` | US address → lat/lon + county + tract GEOID (Census Geocoder, free, keyless) |
| `get_fema_flood_zone` | lat/lon → flood zone + FIRM panel (FEMA NFHL ArcGIS) |
| `get_soil_report` | lat/lon → USDA SSURGO soil components + drainage + hydrologic group |
| `get_census_demographics` | tract GEOID → ACS 5-year demographics (requires free Census API key) |

### Workflow Guidance + Screenshot Archive
| Tool | What it does |
|---|---|
| `get_intake_guide` | Returns the screenshot checklist — which screenshots to capture, where to find them, and what fields to extract. Always call this first to drive the conversation. |
| `stage_intake_screenshot` | Copy a screenshot into the property's intake/ archive for traceability |

### Headless / Paid Extraction (advanced — skips the conversation)
| Tool | What it does |
|---|---|
| `extract_listing_data` | **\[Paid\]** Screenshot → `ListingFacts` JSON via the Anthropic API. Only for batch/headless use. The free interactive path is to let Claude in the conversation read the screenshot. |
| `extract_auditor_data` | **\[Paid\]** Same pattern for auditor pages. |

### Property Store (Phase 3)
| Tool | What it does |
|---|---|
| `create_property` | Initialize a new property record by address |
| `get_property` | Load a property record |
| `list_properties` | List all property IDs in the local store |
| `update_property_facts` | Merge a fact patch with provenance tagging |
| `enrich_property_from_public_apis` | Run all four Phase-1 enrichments in one call |
| `generate_pre_visit_brief` | Produce a Pre-Visit Initial Assessment PDF |

### Packet Generation (Phase 4)
| Tool | What it does |
|---|---|
| `generate_buyers_evidence_packet` | Produce a Buyer's Evidence Packet PDF (seller-facing, post-inspection) |

## Install

### Prerequisites

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** (`brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- **Claude Code** ([claude.com/claude-code](https://claude.com/claude-code))
- **(Optional, free)** RentCast API key for comp lookups — [app.rentcast.io/app/api](https://app.rentcast.io/app/api)
- **(Optional, free)** Census API key for demographics — [api.census.gov/data/key_signup.html](https://api.census.gov/data/key_signup.html)
- **(Advanced only)** Anthropic API key — only needed for headless extraction tools (`extract_listing_data`, `extract_auditor_data`). The normal interactive workflow runs on your Claude Code subscription alone.

### One-line install (recommended)

```bash
curl -LsSf https://raw.githubusercontent.com/dandelionrosegroup/drg-plugins/main/home-buying-dd/install.sh | bash
```

The installer will: install `uv` if missing, clone the repo to `~/.local/share/drg/`, set up a venv, prompt you interactively for API keys, wire keys into your shell config, and register the MCP server with Claude Code. Idempotent — safe to re-run for updates.

### Manual install

```bash
# 1. Clone the drg-plugins repo
git clone https://github.com/dandelionrosegroup/drg-plugins.git
cd drg-plugins/home-buying-dd

# 2. Create venv and install
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

# 3. Add to your shell profile (~/.zshrc or ~/.bash_profile):
#    export ANTHROPIC_API_KEY="sk-ant-..."
#    export RENTCAST_API_KEY="..."   # optional (free tier: 50 calls/mo)
#    export CENSUS_API_KEY="..."     # optional (free, instant signup)

# 4. Register the MCP server with Claude Code
claude mcp add home-buying-dd --scope user -- \
    "$(pwd)/.venv/bin/python" -m home_buying_dd.server

# 5. Verify
claude mcp list | grep home-buying-dd
# Should show: ✓ Connected
```

For the full workflow walkthrough, see [ONBOARDING.md](ONBOARDING.md).

## Workflow

Once installed, open Claude Code in any directory and prompt:

```
I'm looking at a property at 1225 Stoney Rd, Peebles, OH 45660. 
Help me work up a Pre-Visit Brief.
```

Claude will then walk you through:
1. `create_property("1225 Stoney Rd, Peebles, OH 45660")`
2. `get_intake_guide(property_id)` — fetches the screenshot checklist
3. Asks you to capture and drag in the **listing page screenshot**
4. Reads the screenshot directly (no API call — your Claude Code subscription covers it) and calls `update_property_facts(...)` with the extracted fields
5. Asks for an optional **county auditor screenshot**; same pattern
6. `enrich_property_from_public_apis(property_id)` — FEMA + USDA + Census + RentCast comps
7. `generate_pre_visit_brief(property_id)` → produces the PDF

After your site visit and inspections:
8. `generate_buyers_evidence_packet(property_id, defects=[...], repair_estimates=[...], target_offer=...)` → the seller-facing offer document

## Data storage

All property data lives at:

```
~/.drg/home-buying-dd/properties/{property-id}/
  property.json       # the full record (verified facts + provenance)
  intake/             # original screenshots and other primary-source artifacts
  output/             # generated PDFs
```

The store is local-only. Nothing leaves your machine except for the public-API lookups (which are address-only — no personal data).

## Underlying methodology

This MCP server implements the [Home-Buying-Due-Diligence-Process](https://github.com/dandelion-rose-group/drg-plugins) methodology developed in the DRG Claude-Meta vault. Key principles:

- **Primary-Source-or-Stop Rule** — never substitute aggregator data for blocked primary sources
- **Confidence labeling** — every fact carries provenance (`screenshot:zillow-...`, `api:fema-nfhl`, `manual:...`)
- **Pre-Commit Verification Gate** — fundamentals reviewed by the buyer before any deliverable is finalized
- **Same-Road Conflation Guard** — multiple addresses on the same road are treated as suspect until verified

## License

MIT
