arv-mcp 0.1.0__tar.gz

arv_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest

arv_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,137 @@
+name: Release
+
+# Publishes a tagged version to PyPI and the MCP Registry.
+# Release by bumping __version__ in src/arv_mcp/__init__.py, then pushing a
+# matching tag: git tag v0.2.0 && git push origin v0.2.0
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Check, test and build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Tag must match __version__
+        id: version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c 'import re; print(re.search(r"__version__ = \"([^\"]+)\"", open("src/arv_mcp/__init__.py").read()).group(1))')"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match __version__ $pkg in src/arv_mcp/__init__.py"
+            exit 1
+          fi
+          echo "version=$pkg" >> "$GITHUB_OUTPUT"
+
+      - name: README carries the MCP Registry ownership marker
+        run: |
+          name="$(jq -r .name server.json)"
+          grep -q "mcp-name: $name" README.md || { echo "::error::README.md is missing 'mcp-name: $name'"; exit 1; }
+
+      - name: Lint and test
+        run: |
+          pip install -e ".[dev]"
+          ruff check src tests
+          pytest
+
+      - name: Build and check distributions
+        run: |
+          pip install build twine
+          python -m build
+          twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/arv-mcp/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write  # PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  registry:
+    name: Publish to MCP Registry
+    needs: [build, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry GitHub OIDC login
+      contents: read
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      # Pinned and signature-verified below. Bump deliberately; if publishing
+      # fails with "invalid audience", this release is too old for the registry.
+      MCP_PUBLISHER_VERSION: v1.8.1
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Stamp version into server.json
+        run: |
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > server.tmp
+          mv server.tmp server.json
+          cat server.json
+
+      - name: Wait for the release to appear on PyPI
+        run: |
+          for i in $(seq 1 30); do
+            if curl -fsS "https://pypi.org/pypi/arv-mcp/$VERSION/json" > /dev/null; then
+              echo "arv-mcp $VERSION is live on PyPI"; exit 0
+            fi
+            sleep 10
+          done
+          echo "::error::arv-mcp $VERSION did not appear on PyPI within 5 minutes"
+          exit 1
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6  # v4.1.2
+
+      - name: Download and verify mcp-publisher
+        run: |
+          set -euo pipefail
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
+          curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob \
+            --bundle "$archive.sigstore.json" \
+            --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "$archive"
+          tar xzf "$archive" mcp-publisher
+          rm -f "$archive" "$archive.sigstore.json"
+
+      - name: Log in to the MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to the MCP Registry
+        run: ./mcp-publisher publish

arv_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Secrets — never commit
+.env
+.env.*
+
+# Local planning notes
+SCOPE.md
+
+# Local data (never source code)
+*.db
+*.sqlite
+*.gpkg
+/data/
+*.log
+*.log.*
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling
+.claude/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/

arv_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Verdugo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arv_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: arv-mcp
+Version: 0.1.0
+Summary: MCP server that estimates after-repair value (ARV) from scored, gated sold comps.
+Project-URL: Repository, https://github.com/mariov7757/arv-mcp
+Project-URL: Issues, https://github.com/mariov7757/arv-mcp/issues
+Author: Mario Verdugo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: appraisal,arv,comps,mcp,real-estate
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Requires-Dist: homeharvest<0.9,>=0.8.18
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+Requires-Dist: tenacity>=8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# arv-mcp
+
+<!-- mcp-name: io.github.mariov7757/arv-mcp -->
+
+An [MCP](https://modelcontextprotocol.io) server that estimates a home's
+**after-repair value (ARV)** from nearby sold comps, and hands the model the
+scored evidence behind the number so it can explain, check and challenge it.
+
+Ask Claude *"What's the ARV of 1234 Main St?"* and it gets back a typical
+value, a renovated range, a confidence tier, the comps that support it (and
+the ones that were thrown out, with reasons), what's listed nearby right
+now, and warnings about anything that should make it cautious.
+
+```
+You:    What's the ARV of 1234 Main Street?
+
+Claude: Typical value is about $516k ($263/sqft on 1,961 sqft), based on
+        20 eligible sales, 5+ of them within a quarter mile (confidence 5/5).
+        Renovated comps support $541k–$586k. The closest match, 1260 Main
+        Street, sold 23 days ago for $465k ($272/sqft): same subdivision,
+        a bit smaller, no pool.
+
+        Worth knowing: this house itself sold this week for $432,500
+        ($220/sqft), well under the comp-based value. That usually means it
+        sold in rough condition, which fits a flip at the renovated range.
+        Two of the eligible comps were distressed sales; without them the
+        median barely moves.
+```
+
+> **Not an appraisal.** Data comes from public listings on Realtor.com via
+> [HomeHarvest](https://github.com/ZacharyHampton/HomeHarvest) and can be
+> wrong or missing. Use it for research and as a starting point, not for
+> lending or legal decisions.
+
+## How it works
+
+```
+address ──► verify the property ──► sold comps ──► score & gate ──► estimate
+               │  (any status)        within 1.5 mi    each comp       + evidence
+               └─ not verified? ──► locate it + ask for its facts
+```
+
+1. **Find the subject.** The address is resolved to Realtor.com's record
+   for exactly that street and unit, whether it's for sale, pending, sold
+   or off market. Realtor.com's geocoder will happily return the wrong
+   house for a bad address, so every result is checked against the street
+   and unit typed. If nothing verifies, the address is located (Census
+   geocoder, or caller-supplied lat/lon) and the tool asks for the facts it
+   needs (`sqft`, `property_type`) instead of guessing.
+2. **Pull comps around the subject's coordinates:** sold in the last 180
+   days within 1.5 miles (both adjustable per call), ±40% of the subject's
+   size, same property type. The subject's own sale is pulled out and
+   reported separately, so a just-sold house can't comp itself.
+3. **Score every comp** on 13 factors: size, year built, lot, beds/baths,
+   property type, recency, condition signals, distance, subdivision,
+   garage, stories, pool and basement. Each known factor also has a
+   **floor**. A comp that fails any one (a different property type, a much
+   bigger house, one built decades apart) is excluded outright, however good
+   it looks elsewhere. Size, age and lot floors loosen for comps right next
+   door and tighten with distance.
+4. **Check the micro-market.** Each comp's subdivision median (or its own
+   $/sqft) must sit within ±20% of the subject's local price level, so a
+   great physical match in a pricier pocket doesn't inflate the estimate.
+   Subdivisions come from the MLS "Subdivision" field, with phases like
+   "Unit 2" or "Ph 04 Sec 01" merged.
+5. **Estimate:**
+   - **Typical value:** similarity-weighted median $/sqft × subject sqft.
+   - **Renovated range:** weighted 75th–90th percentile, what the top of
+     the pool supports.
+   - **Confidence 1–5:** how close the supporting comps are.
+
+   If no comp survives, the tool falls back to the area's going rate and
+   says plainly that the number isn't comp-backed.
+
+## Tools
+
+### `get_arv`
+
+| Parameter | Description |
+|---|---|
+| `address` (required) | Full street address, including any unit number. |
+| `sqft`, `property_type` | Override the record. Required when the address can't be verified. |
+| `beds`, `baths`, `year_built`, `lot_sqft`, `stories`, `garage`, `has_pool` | Override or supply facts; also how what-ifs work ("what if it had a pool?"). |
+| `latitude`, `longitude` | Locate a property no geocoder can find. |
+| `radius_mi`, `days_back` | Comp search window: 0.25–5 mi (default 1.5), 30–730 days (default 180). |
+| `include_market_context` | Also fetch nearby active/pending listings (default true). |
+| `max_comps` | Eligible comps to return, 1–25 (default 10). |
+
+Returns `subject`, `estimate` (`arv`, `renovated_range`, `arv_fallback`,
+window), `confidence`, `pool_stats`, `eligible_comps` (each with the factors
+that cost it points and any distress flags), `excluded_comps` (with
+reasons), `market_context` and `guidance`. Unknown facts are `null`, never
+`0`.
+
+### `lookup_property`
+
+The verified record for an address: size, beds/baths, year, lot, stories,
+garage, pool, subdivision, status, list price (only while it's on the
+market) and last sale.
+
+### Prompt: `analyze_arv`
+
+An appraiser-style walkthrough (subject → comps → adjustments → range).
+Shows up as a slash command in Claude Code.
+
+### Errors
+
+Failures come back as `{"error": {"code", "message", ...}}` so the model
+can act on them:
+
+| Code | Meaning |
+|---|---|
+| `ADDRESS_NOT_VERIFIED` | Located, but no record matches; `needs` lists the facts to ask for. |
+| `ADDRESS_NOT_FOUND` | Couldn't find or locate the address. |
+| `MISSING_FACTS` | The record lacks something the estimate needs (e.g. sqft). |
+| `UNSUPPORTED_PROPERTY_TYPE` | Vacant land: no living area to price per sqft. |
+| `NO_COMPS` | No sales in the window; try a larger `radius_mi` / `days_back`. |
+| `RATE_LIMITED` | Local rate limit; `retry_after_s` says when to retry. |
+| `UPSTREAM_ERROR` | Realtor.com refused or failed the request. |
+
+## Install
+
+Requires Python 3.11+. Published on [PyPI](https://pypi.org/project/arv-mcp/)
+and listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.mariov7757/arv-mcp`.
+
+**Claude Code**
+
+```bash
+claude mcp add arv-mcp -- uvx arv-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "arv-mcp": {
+      "command": "uvx",
+      "args": ["arv-mcp"]
+    }
+  }
+}
+```
+
+**pip**
+
+```bash
+pip install arv-mcp
+```
+
+To run the unreleased `main` branch instead, use
+`uvx --from git+https://github.com/mariov7757/arv-mcp arv-mcp`.
+
+**From a clone**
+
+```bash
+git clone https://github.com/mariov7757/arv-mcp && cd arv-mcp
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+claude mcp add arv-mcp -- "$PWD/.venv/bin/arv-mcp"
+```
+
+**Windows: if `uvx` fails installing `pywin32`** (`os error 32` /
+"being used by another process", usually antivirus scanning uv's temporary
+build folder), install into a regular virtualenv instead and point the
+client at the installed executable:
+
+```powershell
+uv venv $HOME\.arv-mcp
+uv pip install --python $HOME\.arv-mcp\Scripts\python.exe arv-mcp
+claude mcp add arv-mcp -- $HOME\.arv-mcp\Scripts\arv-mcp.exe
+```
+
+## Configuration
+
+All optional, via environment variables:
+
+| Variable | Default | |
+|---|---|---|
+| `ARV_MCP_REQUESTS_PER_MIN` | `30` | Realtor.com requests per minute (token bucket)… |
+| `ARV_MCP_REQUEST_BURST` | `10` | …and how many can go at once. |
+| `ARV_MCP_GEOCODER_PER_SEC` | `1` | Census geocoder requests per second. |
+| `ARV_MCP_RATE_WAIT_S` | `15` | Longest a call waits for a rate-limit slot before returning `RATE_LIMITED`. |
+| `ARV_MCP_MAX_CONCURRENT` | `2` | Tool calls processed at once. |
+| `ARV_MCP_LOG_LEVEL` | `WARNING` | Logs go to stderr. |
+
+A full `get_arv` makes 5 requests to Realtor.com (2 to look up the subject,
+1 for sold comps, 2 for active/pending) and takes ~4–6 s. Results are cached
+for 15 minutes, so follow-ups and what-ifs on the same address return
+instantly.
+
+## Limitations
+
+- **Tuned on Phoenix metro.** Gate bands and confidence tiers were
+  calibrated on ~8,000 Phoenix-area valuations. The engine runs anywhere in
+  the US, but in other markets (especially rural or low-volume ones) lean
+  on the comps and confidence tier, and widen `radius_mi` / `days_back`.
+- **Typical value isn't condition-aware.** Distressed sales are flagged
+  (MLS REO/short-sale conditions, "fixer"/"as-is" language) and their
+  effect on the median is reported, but they aren't excluded.
+- **$/sqft is the wrong tool for some properties.** Land is refused; farms,
+  multi-family and mobile homes get a warning.
+- **Unofficial data source.** HomeHarvest scrapes Realtor.com's public
+  site. Requests run from your own machine and are rate-limited, but the
+  site can change or block access at any time. `homeharvest` is pinned to
+  a tested range because the client relies on its internals.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest            # offline suite; real network calls are blocked
+ARV_MCP_LIVE_ADDRESS="<a real address>" pytest -m live   # smoke tests against Realtor.com + Census
+ruff check src tests
+```
+
+```
+src/arv_mcp/
+  server.py         MCP tools, instructions and prompt
+  service.py        address in, estimate + evidence out
+  arv.py            eligibility, weighted median, renovated range, confidence
+  scoring.py        per-comp gated scoring
+  comps.py          comp normalization and bad-data filters
+  ratelimit.py      token buckets
+  data/client.py    Realtor.com transport over HomeHarvest
+  data/homeharvest.py  subject lookup, comp searches, field extraction
+  data/geocode.py   Census geocoder
+```
+
+The scoring engine was extracted from a private wholesale-real-estate
+pipeline where it priced thousands of Phoenix-area listings.
+
+### Releasing
+
+The version lives in one place: `__version__` in `src/arv_mcp/__init__.py`.
+
+1. Bump `__version__` (patch for fixes, minor for new tools, parameters or
+   fields) and merge to `main` with CI green.
+2. Tag the release and push the tag:
+
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+The [Release workflow](.github/workflows/release.yml) then:
+
+- checks that the tag matches `__version__`
+- runs lint and tests, and builds the package
+- publishes to PyPI with Trusted Publishing (no API token)
+- stamps the version into `server.json` and publishes it to the
+  [MCP Registry](https://registry.modelcontextprotocol.io) as
+  `io.github.mariov7757/arv-mcp`, authenticated by GitHub OIDC
+
+PyPI versions are permanent. A broken release gets yanked on PyPI and
+replaced by the next patch version; a version number is never reused.
+
+## License
+
+MIT