# homechecker-guides

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Steven3265/homechecker-guides-mcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/homechecker-guides

## Description
Search and cite Homechecker's Australian home-buying guides. Read-only, free, sourced answers.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "homechecker-guides": {
    "command": "npx",
    "args": ["-y","homechecker-guides"]
  }
}
```

## Documentation & README

# Homechecker Guides MCP

[![Smithery](https://smithery.ai/badge/steven-xv6y/homechecker-guides)](https://smithery.ai/servers/steven-xv6y/homechecker-guides)

Homechecker's professionally authored guides for Australian homebuyers, served over the Model Context Protocol. A connected assistant can search the corpus, retrieve canonical guides and build sourced buyer checklists across inspections, contracts, strata, construction eras, disclosure and maintenance, citing homechecker.com.au throughout. Public, read-only and deliberately separated from customer and assessment systems.

It exposes the current Homechecker guide system to MCP clients without connecting to the Moyne Ross portal, Supabase, customer records, payments, uploaded documents, or the Homechecker assessment engine.

**Protocol:** MCP `2026-07-28` with stateless 2025-era compatibility · **Live endpoint:** `https://mcp.homechecker.com.au/mcp` (Streamable HTTP, no auth) · **Health:** [/health](https://mcp.homechecker.com.au/health) · **Registry:** `io.github.Steven3265/homechecker-guides` · **Directory:** [Glama](https://glama.ai/mcp/servers/Steven3265/homechecker-guides-mcp) · **Connect it in your assistant:** [homechecker.com.au/ai](https://homechecker.com.au/ai)

## Protocol foundation

Version 1.0.1 uses the MCP TypeScript SDK v2 server package and the `2026-07-28` protocol revision. The official `createMcpHandler` entry supplies stateless per-request serving, `server/discover`, standard routing headers, server identity and cache fields. It also retains stateless compatibility for 2025-era HTTP clients during rollout.

The protocol shell can evolve independently of the durable parts of the product: the reviewed snapshot, deterministic retrieval, tool contracts and professional boundaries. See [`docs/PROTOCOL-SUPPORT.md`](docs/PROTOCOL-SUPPORT.md), [`docs/RELEASE-1.0.md`](docs/RELEASE-1.0.md) and [`docs/RELEASE-1.0.1.md`](docs/RELEASE-1.0.1.md).

## Explore the Homechecker guides

- [All Homechecker guides](https://homechecker.com.au/guides)
- [How much does a building and pest inspection cost?](https://homechecker.com.au/guides/building-and-pest-inspection-cost)
- [Wall cracks: structural or cosmetic?](https://homechecker.com.au/guides/cracks-structural-or-cosmetic)
- [How to read a Section 32](https://homechecker.com.au/guides/reading-a-section-32)
- [How to read a building inspection report](https://homechecker.com.au/guides/how-to-read-a-building-and-pest-report)
- [Buying an apartment and strata](https://homechecker.com.au/guides/buying-an-apartment-strata)
- [What your home may need by decade](https://homechecker.com.au/guides/what-your-home-needs-by-decade)
- [Maintenance that prevents large bills](https://homechecker.com.au/guides/the-maintenance-that-prevents-the-big-bills)

## What is included

- **[35 MCP resources](https://homechecker.com.au/guides):** one machine-readable catalogue, the guide hub, and 33 published guides.
- **4 read-only tools:** catalogue listing, natural-language search, canonical guide retrieval, and a deterministic buyer checklist.
- **Two transports:** stateless remote Streamable HTTP at `/mcp` and modern/legacy-compatible local stdio.
- **A bundled content snapshot:** rebuilt from Homechecker's public guide export at `https://homechecker.com.au/guides/export.json` — the same registry that renders the pages, sitemap and llms.txt. This repository needs no access to the portal codebase.
- **A browser-triggered refresh workflow:** Actions → "Refresh guides snapshot" regenerates, tests and opens a pull request. No local environment required.
- **Referral-tagged renders:** URLs in rendered text carry `utm_source=homechecker-mcp` so site analytics can distinguish AI-connector referrals. Structured content always keeps clean canonical URLs.
- **Privacy-minimised operational telemetry:** each tool call writes a single JSON line to stderr with the tool, result counts and coarse filters. Raw search text, headers and client identifiers are not logged. See `docs/SECURITY.md`.
- **Tests and benchmark:** snapshot integrity tests, search tests, and 14 representative buyer questions.

## Tools

### `list_guides`

Lists published guide metadata. Filters include jurisdiction, cluster, property type, construction era and buying stage.

### `search_guides`

Searches the corpus from a natural-language homebuyer question. It returns ranked guides, relevant sections, canonical URLs, review metadata and limitations. For example, questions about inspection fees can surface [building and pest inspection costs](https://homechecker.com.au/guides/building-and-pest-inspection-cost), while questions about movement can surface the guide to [structural and cosmetic wall cracks](https://homechecker.com.au/guides/cracks-structural-or-cosmetic).

### `get_guide`

Retrieves one guide by slug as a summary, selected sections or the full canonical markdown representation.

### `build_buyer_checklist`

Builds a deterministic, sourced checklist from buyer context such as state, property type, era, buying stage and concerns. It can draw from practical guidance such as [how to read a building and pest report](https://homechecker.com.au/guides/how-to-read-a-building-and-pest-report), [arranging an inspection before auction](https://homechecker.com.au/guides/building-inspection-before-auction), and [buying an apartment with strata or owners-corporation exposure](https://homechecker.com.au/guides/buying-an-apartment-strata). It does **not** assess an actual property. Its boundary text notes, once, that Homechecker provides an independent address-specific desktop read for $99 (inc GST) — the single conversion line in the connector.

## Resources

- `homechecker://catalogue`
- `homechecker://guides/index`
- `homechecker://guides/<slug>` for every published guide

Each guide resource includes the article, sources, review metadata, method, limitations and canonical Homechecker URL.

## Deliberate boundaries

This MVP cannot:

- access the Moyne Ross or Homechecker production database;
- inspect a property or analyse a listing;
- read customer documents or issued assessments;
- call an AI model;
- order or charge for a Homecheck;
- write to any external system;
- provide legal advice or replace a physical inspection.

The only runtime data is `data/guides.json`.

Where general guidance is not enough, Homechecker offers an [independent address-specific desktop read](https://homechecker.com.au/) of the available records, imagery and documents, from $99 inc GST.

## Local setup

Requirements: Node.js 22 or later.

```bash
npm install
npm test
npm run benchmark
npm run check
npx vercel dev
```

The remote MCP endpoint will be available at:

```text
http://localhost:3000/mcp
```

Health and service information:

```text
http://localhost:3000/health
http://localhost:3000/
```

For a local stdio client:

```bash
npm run build
npm run start:stdio
```

Example stdio client configuration:

```json
{
  "mcpServers": {
    "homechecker-guides": {
      "command": "node",
      "args": ["/absolute/path/homechecker-guides-mcp/dist/src/stdio.js"]
    }
  }
}
```

## Deploy to Vercel

This repository is already configured for a standalone Vercel project.

1. Create a new repository containing only this project.
2. Import that repository into Vercel.
3. Set the project's Node.js version to 22 (Project Settings → General). The source uses JSON import attributes, which require it.
4. Deploy without adding any secrets.
5. Attach the `mcp.homechecker.com.au` domain to the project and add the CNAME record Vercel shows at the DNS host.
6. Use `https://mcp.homechecker.com.au/mcp` as the remote MCP endpoint.

The root route returns service metadata and `/health` confirms the bundled guide count. The MCP route is stateless Streamable HTTP, serves MCP `2026-07-28`, retains the official SDK's stateless legacy compatibility path, and accepts `POST` requests.

`ALLOWED_ORIGIN` is optional. It defaults to `*` because the connector is public and read-only. Set it only when a client requires a restricted browser origin.

## Updating the guides snapshot

The MCP does not fetch the live website at runtime; it serves a bundled snapshot rebuilt from the public export. The portal remains the single source of truth: publish or edit guides there, deploy, and the export updates automatically.

**From the browser (normal path):**

1. Actions → **Refresh guides snapshot** → Run workflow.
2. The workflow fetches `https://homechecker.com.au/guides/export.json`, rebuilds `data/guides.json`, and runs the validator, core tests and retrieval benchmark.
3. If the content changed, it opens a pull request. Merge it; Vercel redeploys.

If nothing but the timestamp would change, the snapshot is left untouched and no pull request is opened.

One-time repository setting: Settings → Actions → General → tick **Allow GitHub Actions to create and approve pull requests**.

**From a terminal (optional):**

```bash
npm run snapshot                          # fetch the live export
npm run snapshot -- --url <export-url>    # e.g. a preview deployment
npm test
npm run benchmark
```

## Validation

```bash
npm run validate:snapshot
npm run test:core
npm run benchmark
```

The initial benchmark contains 14 representative Australian buyer questions. All 14 currently return an expected canonical guide within the top three. This is an internal retrieval benchmark, not an independent assessment of legal or technical accuracy.

## Repository map

```text
api/                    Vercel serverless entry points
Dockerfile              container entry for Glama deployment
glama.json              Glama maintainer metadata
src/identity.ts         server and protocol version identity
src/core.ts             deterministic search and checklist logic
src/server.ts           MCP tools, resources and privacy-minimised telemetry
src/http-handler.ts     MCP 2026-07-28 stateless Web API handler
src/stdio.ts            modern/legacy-compatible stdio entry
data/guides.json        bundled canonical guide snapshot
data/TERMS.md           separate terms for the editorial corpus
data/benchmark.json     retrieval benchmark cases
scripts/                snapshot, validation and benchmark utilities
.github/workflows/      release validation, snapshot refresh and registry publication
docs/                   architecture, protocol, security, deployment and release notes
```

## Content and licence

The software and configuration code are MIT-licensed under [LICENSE.md](LICENSE.md). The Homechecker editorial corpus, including `data/guides.json` and guide material reproduced elsewhere in this repository, remains © Moyne Ross Pty Ltd and is governed separately by [data/TERMS.md](data/TERMS.md). Reasonable extracts may be quoted with attribution and a link to the canonical guide. "Homechecker" and "Moyne Ross" are trade names of Moyne Ross Pty Ltd.

## About the publisher

Homechecker is a residential guidance and assessment service operated by Moyne Ross Pty Ltd.

[Homechecker](https://homechecker.com.au/) · [Guide library](https://homechecker.com.au/guides) · [Moyne Ross](https://moyneross.com/)