scotlis-mcp 1.0.0__tar.gz

scotlis_mcp-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+venv
+
+# MCPB build output
+*.mcpb

scotlis_mcp-1.0.0/.mcpbignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.git/
+.gitignore
+.python-version
+uv.lock
+pyproject.toml
+scotlis-mcp.mcpb
+venv/**/__pycache__/

scotlis_mcp-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

scotlis_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dart120
+
+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.

scotlis_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: scotlis-mcp
+Version: 1.0.0
+Summary: MCP server exposing ScotLIS (Registers of Scotland) property price search
+Project-URL: Repository, https://github.com/Dart120/scotlis-mcp
+Author-email: Dart120 <irenitemi81@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: mcp[cli]<2,>=1.6.0
+Description-Content-Type: text/markdown
+
+# scotlis-mcp
+
+An MCP server exposing [ScotLIS](https://scotlis.ros.gov.uk) (Registers of Scotland) property price search as a tool Claude can call directly.
+
+Given a UK postcode, it returns every registered title at that address with its sale date, price (or non-monetary reason, e.g. a gift between family members), and a link to the property summary.
+
+Only covers Scotland, and only titles on the Land Register — older properties still on the Sasine Register may show no price.
+
+## Use as a standalone CLI
+
+```bash
+python3 scotlis_prices.py "EH1 1RE"
+python3 scotlis_prices.py "EH1 1RE" --sort price --desc
+python3 scotlis_prices.py "EH1 1RE" --format csv > prices.csv
+python3 scotlis_prices.py "EH1 1RE" --format json
+```
+
+## Install as a Claude Desktop extension (one click, macOS only for now)
+
+Download `scotlis-mcp.mcpb` from the [latest release](https://github.com/Dart120/scotlis-mcp/releases/latest), then double-click it, or drag it into the Claude Desktop window, or use **Settings > Extensions > Advanced settings > Install Extension…**.
+
+This bundle embeds its own Python 3.13 runtime, so it works even if your Mac's system Python is older. It's currently built for macOS only — see [Build the extension bundle](#build-the-extension-bundle) to build one for another platform.
+
+## Use as an MCP server in Claude Desktop (manual config)
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/Dart120/scotlis-mcp.git
+cd scotlis-mcp
+uv sync
+```
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "scotlis-prices": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/scotlis-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, and Claude will be able to call `search_property_prices` for any UK postcode.
+
+## Build the extension bundle
+
+```bash
+uv sync
+npm install -g @anthropic-ai/mcpb
+cp -R .venv venv   # bundles a real, self-contained interpreter — not a symlink
+mcpb pack . scotlis-mcp.mcpb
+```
+
+## Disclaimer
+
+Unofficial tool, not affiliated with Registers of Scotland. Queries ScotLIS's public search form directly — be a good citizen and don't hammer it.

scotlis_mcp-1.0.0/README.md

@@ -0,0 +1,60 @@
+# scotlis-mcp
+
+An MCP server exposing [ScotLIS](https://scotlis.ros.gov.uk) (Registers of Scotland) property price search as a tool Claude can call directly.
+
+Given a UK postcode, it returns every registered title at that address with its sale date, price (or non-monetary reason, e.g. a gift between family members), and a link to the property summary.
+
+Only covers Scotland, and only titles on the Land Register — older properties still on the Sasine Register may show no price.
+
+## Use as a standalone CLI
+
+```bash
+python3 scotlis_prices.py "EH1 1RE"
+python3 scotlis_prices.py "EH1 1RE" --sort price --desc
+python3 scotlis_prices.py "EH1 1RE" --format csv > prices.csv
+python3 scotlis_prices.py "EH1 1RE" --format json
+```
+
+## Install as a Claude Desktop extension (one click, macOS only for now)
+
+Download `scotlis-mcp.mcpb` from the [latest release](https://github.com/Dart120/scotlis-mcp/releases/latest), then double-click it, or drag it into the Claude Desktop window, or use **Settings > Extensions > Advanced settings > Install Extension…**.
+
+This bundle embeds its own Python 3.13 runtime, so it works even if your Mac's system Python is older. It's currently built for macOS only — see [Build the extension bundle](#build-the-extension-bundle) to build one for another platform.
+
+## Use as an MCP server in Claude Desktop (manual config)
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/Dart120/scotlis-mcp.git
+cd scotlis-mcp
+uv sync
+```
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "scotlis-prices": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/scotlis-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, and Claude will be able to call `search_property_prices` for any UK postcode.
+
+## Build the extension bundle
+
+```bash
+uv sync
+npm install -g @anthropic-ai/mcpb
+cp -R .venv venv   # bundles a real, self-contained interpreter — not a symlink
+mcpb pack . scotlis-mcp.mcpb
+```
+
+## Disclaimer
+
+Unofficial tool, not affiliated with Registers of Scotland. Queries ScotLIS's public search form directly — be a good citizen and don't hammer it.

scotlis_mcp-1.0.0/manifest.json

@@ -0,0 +1,39 @@
+{
+  "manifest_version": "0.2",
+  "name": "scotlis-mcp",
+  "version": "1.0.0",
+  "description": "Search Scottish property sale prices (ScotLIS) by postcode",
+  "long_description": "Queries ScotLIS (Registers of Scotland's public land register) for every registered title at a UK postcode and returns the sale date, price, and consideration for each. Covers Scotland only, and only titles on the Land Register.",
+  "author": {
+    "name": "Dart120",
+    "email": "irenitemi81@gmail.com",
+    "url": "https://github.com/Dart120"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Dart120/scotlis-mcp"
+  },
+  "license": "MIT",
+  "server": {
+    "type": "python",
+    "entry_point": "server.py",
+    "mcp_config": {
+      "command": "${__dirname}/venv/bin/python3",
+      "args": [
+        "${__dirname}/server.py"
+      ]
+    }
+  },
+  "tools": [
+    {
+      "name": "search_property_prices",
+      "description": "Search registered property sale prices in Scotland by postcode"
+    }
+  ],
+  "compatibility": {
+    "platforms": ["darwin"],
+    "runtimes": {
+      "python": ">=3.13"
+    }
+  }
+}

scotlis_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "scotlis-mcp"
+version = "1.0.0"
+description = "MCP server exposing ScotLIS (Registers of Scotland) property price search"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+    { name = "Dart120", email = "irenitemi81@gmail.com" },
+]
+dependencies = [
+    "mcp[cli]>=1.6.0,<2",
+]
+
+[project.urls]
+Repository = "https://github.com/Dart120/scotlis-mcp"
+
+[project.scripts]
+scotlis-mcp = "server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["server.py", "scotlis_prices.py"]

scotlis_mcp-1.0.0/scotlis_prices.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Search Scottish property prices from ScotLIS (Registers of Scotland).
+
+ScotLIS renders its results server-side with Next.js, so the search results are
+embedded in the page as a JSON blob (``__NEXT_DATA__``). This script submits the
+same query the public search form does and reads that blob, which avoids both
+HTML scraping and a browser.
+
+Usage:
+    python3 scotlis_prices.py "EH1 1RE"
+    python3 scotlis_prices.py "EH1 1RE" --sort price --desc
+    python3 scotlis_prices.py "EH1 1RE" --format csv > prices.csv
+    python3 scotlis_prices.py "EH1 1RE" --format json
+
+Price searches are postcode-only; title numbers are not accepted by ScotLIS for
+this search type.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime as dt
+import json
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, asdict
+from typing import Iterable
+
+BASE_URL = "https://scotlis.ros.gov.uk"
+RESULTS_URL = f"{BASE_URL}/results"
+PROPERTY_URL = f"{BASE_URL}/property-summary/{{title}}"
+
+USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+)
+
+# ScotLIS only populates the price/date fields when sortBy is one of these.
+# Anything else (including "price") silently returns results with those fields
+# stripped out, so we always request a safe value and sort locally.
+_SAFE_SORT_BY = "address"
+
+_NEXT_DATA_RE = re.compile(
+    r'<script id="__NEXT_DATA__" type="application/json">(.*?)</script>', re.S
+)
+_POSTCODE_RE = re.compile(
+    r"^(?P<out>[A-Z]{1,2}\d[A-Z\d]?)\s*(?P<in>\d[A-Z]{2})$", re.I
+)
+_PRICE_RE = re.compile(r"£\s*([\d,]+)")
+
+
+class ScotLISError(RuntimeError):
+    """Raised when ScotLIS cannot be queried or its response is unusable."""
+
+
+@dataclass
+class Sale:
+    """One registered title and its most recent recorded consideration."""
+
+    title_number: str
+    address: str
+    date: dt.date | None
+    price: int | None
+    consideration: str
+    explanation: str | None
+    url: str
+
+    @property
+    def price_display(self) -> str:
+        return f"£{self.price:,}" if self.price is not None else "—"
+
+    def as_dict(self) -> dict:
+        d = asdict(self)
+        d["date"] = self.date.isoformat() if self.date else None
+        return d
+
+
+def normalise_postcode(raw: str) -> str:
+    """Return a postcode as ``EH1 1RE``, or raise ValueError."""
+    compact = re.sub(r"\s+", "", raw.upper())
+    m = _POSTCODE_RE.match(compact)
+    if not m:
+        raise ValueError(f"{raw!r} does not look like a UK postcode")
+    return f"{m.group('out')} {m.group('in')}".upper()
+
+
+def _fetch(url: str, timeout: float, retries: int) -> str:
+    """GET a URL, retrying transient failures with a short backoff."""
+    last_error: Exception | None = None
+    for attempt in range(retries + 1):
+        req = urllib.request.Request(
+            url,
+            headers={
+                "User-Agent": USER_AGENT,
+                "Accept": "text/html,application/xhtml+xml",
+                "Accept-Language": "en-GB,en;q=0.9",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")[:200]
+            if exc.code in (403, 429) and "captcha" in body.lower():
+                raise ScotLISError(
+                    "ScotLIS served a CAPTCHA challenge (AWS WAF). Slow down or "
+                    "run the search in a browser."
+                ) from exc
+            if exc.code < 500 and exc.code != 429:
+                raise ScotLISError(f"ScotLIS returned HTTP {exc.code}: {body}") from exc
+            last_error = exc
+        except (urllib.error.URLError, TimeoutError) as exc:
+            last_error = exc
+        if attempt < retries:
+            time.sleep(2 ** attempt)
+    raise ScotLISError(f"Could not reach ScotLIS: {last_error}")
+
+
+def _extract_page_props(html: str) -> dict:
+    m = _NEXT_DATA_RE.search(html)
+    if not m:
+        raise ScotLISError(
+            "No __NEXT_DATA__ block in the response — the ScotLIS page layout "
+            "has probably changed."
+        )
+    try:
+        return json.loads(m.group(1))["props"]["pageProps"]
+    except (ValueError, KeyError) as exc:
+        raise ScotLISError(f"Could not parse the ScotLIS page data: {exc}") from exc
+
+
+def _parse_price(consideration: str | None) -> int | None:
+    """Pull an integer out of '£340,000'; non-monetary entries return None."""
+    if not consideration:
+        return None
+    m = _PRICE_RE.search(consideration)
+    return int(m.group(1).replace(",", "")) if m else None
+
+
+def _parse_date(value: str | None) -> dt.date | None:
+    if not value:
+        return None
+    try:
+        return dt.date.fromisoformat(value[:10])
+    except ValueError:
+        return None
+
+
+def _tidy_address(pretty: str, postcode: str) -> str:
+    """ScotLIS prints the postcode unspaced ('EH11RE') at the end; fix that."""
+    compact = postcode.replace(" ", "")
+    if pretty.upper().endswith(compact):
+        return pretty[: -len(compact)] + postcode
+    return pretty
+
+
+def search_prices(
+    postcode: str, *, timeout: float = 30.0, retries: int = 2
+) -> list[Sale]:
+    """Return the registered sales ScotLIS holds for a postcode."""
+    postcode = normalise_postcode(postcode)
+    query = urllib.parse.urlencode(
+        {
+            "searchType": "prices",
+            "postcode": postcode,
+            "sortBy": _SAFE_SORT_BY,
+            "sortDir": "asc",
+        }
+    )
+    props = _extract_page_props(_fetch(f"{RESULTS_URL}?{query}", timeout, retries))
+
+    sales = []
+    for entry in props.get("addresses") or []:
+        title = entry.get("titleNumber", "")
+        consideration = entry.get("consideration") or "No price available"
+        sales.append(
+            Sale(
+                title_number=title,
+                address=_tidy_address(entry.get("prettyPrint", ""), postcode),
+                date=_parse_date(entry.get("entryDate")),
+                price=_parse_price(consideration),
+                consideration=consideration,
+                explanation=entry.get("considerationExplanation"),
+                url=PROPERTY_URL.format(title=title),
+            )
+        )
+    return sales
+
+
+def sort_sales(sales: list[Sale], key: str, descending: bool) -> list[Sale]:
+    """Sort locally — ScotLIS returns results in a fixed order regardless of sortBy."""
+    # Rows with no price or date sort last in either direction.
+    if key == "price":
+        ranked = sorted(
+            (s for s in sales if s.price is not None),
+            key=lambda s: s.price,
+            reverse=descending,
+        )
+        return ranked + [s for s in sales if s.price is None]
+    if key == "date":
+        ranked = sorted(
+            (s for s in sales if s.date is not None),
+            key=lambda s: s.date,
+            reverse=descending,
+        )
+        return ranked + [s for s in sales if s.date is None]
+    return sorted(sales, key=lambda s: s.address, reverse=descending)
+
+
+def print_table(sales: Iterable[Sale], postcode: str) -> None:
+    sales = list(sales)
+    priced = [s.price for s in sales if s.price is not None]
+    addr_width = min(max((len(s.address) for s in sales), default=10), 60)
+
+    print(f"\n{len(sales)} result(s) for {postcode}\n")
+    header = f"{'DATE':<12} {'PRICE':>10}  {'TITLE':<10} ADDRESS"
+    print(header)
+    print("-" * (len(header) + addr_width - 7))
+    for s in sales:
+        date = s.date.strftime("%d %b %Y") if s.date else "—"
+        # Non-monetary considerations are free text, so they trail the address
+        # rather than blowing out the price column.
+        note = f"  · {s.consideration}" if s.price is None else ""
+        print(f"{date:<12} {s.price_display:>10}  {s.title_number:<10} {s.address}{note}")
+
+    if priced:
+        priced.sort()
+        mid = len(priced) // 2
+        median = priced[mid] if len(priced) % 2 else (priced[mid - 1] + priced[mid]) // 2
+        print(
+            f"\n{len(priced)} with a recorded price — "
+            f"median £{median:,}, range £{min(priced):,}–£{max(priced):,}"
+        )
+    unpriced = len(sales) - len(priced)
+    if unpriced:
+        print(f"{unpriced} without a monetary price (gifts, transfers, pre-2003 titles).")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Search property prices on ScotLIS by postcode."
+    )
+    parser.add_argument("postcode", help="e.g. 'EH1 1RE'")
+    parser.add_argument(
+        "--sort", choices=("address", "date", "price"), default="address"
+    )
+    parser.add_argument("--desc", action="store_true", help="sort descending")
+    parser.add_argument(
+        "--format", choices=("table", "json", "csv"), default="table"
+    )
+    parser.add_argument("--timeout", type=float, default=30.0)
+    args = parser.parse_args(argv)
+
+    try:
+        postcode = normalise_postcode(args.postcode)
+        sales = sort_sales(search_prices(postcode, timeout=args.timeout), args.sort, args.desc)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except ScotLISError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if not sales:
+        print(
+            f"No registered titles found for {postcode}. ScotLIS only covers "
+            "Scotland, and only properties on the Land Register.",
+            file=sys.stderr,
+        )
+        return 0
+
+    if args.format == "json":
+        json.dump([s.as_dict() for s in sales], sys.stdout, indent=2)
+        print()
+    elif args.format == "csv":
+        writer = csv.DictWriter(
+            sys.stdout,
+            fieldnames=["title_number", "address", "date", "price", "consideration", "explanation", "url"],
+        )
+        writer.writeheader()
+        writer.writerows(s.as_dict() for s in sales)
+    else:
+        print_table(sales, postcode)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scotlis_mcp-1.0.0/server.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""MCP server exposing ScotLIS property-price search as tools for Claude Desktop.
+
+Wraps scotlis_prices.py (the standalone CLI) so Claude can call it directly
+instead of a human running it in a terminal.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from scotlis_prices import (
+    ScotLISError,
+    search_prices,
+    sort_sales,
+    normalise_postcode,
+)
+
+mcp = FastMCP("scotlis-prices")
+
+
+@mcp.tool()
+def search_property_prices(
+    postcode: str,
+    sort_by: str = "address",
+    descending: bool = False,
+) -> dict:
+    """Search registered property sale prices in Scotland by postcode.
+
+    Queries ScotLIS (Registers of Scotland's public land register) for every
+    registered title at a postcode and returns, for each, the title number,
+    address, sale date, and consideration (sale price, or a non-monetary
+    reason such as a gift between family members).
+
+    Only covers Scotland, and only titles on the Land Register (older
+    properties still on the Sasine Register, or recently transferred for
+    non-monetary consideration, may show no price).
+
+    Args:
+        postcode: A UK postcode, e.g. "EH1 1RE" (spacing/case don't matter).
+        sort_by: One of "address", "date", "price". Defaults to "address".
+        descending: Sort highest/latest/Z-first when true.
+
+    Returns:
+        A dict with the normalised postcode, result count, a list of sales
+        (title_number, address, date, price, consideration, explanation,
+        url), and summary stats (count with a price, median/min/max price)
+        when at least one sale has a recorded price.
+    """
+    try:
+        postcode_norm = normalise_postcode(postcode)
+        sales = sort_sales(search_prices(postcode_norm), sort_by, descending)
+    except ValueError as exc:
+        return {"error": str(exc)}
+    except ScotLISError as exc:
+        return {"error": str(exc)}
+
+    priced = sorted(s.price for s in sales if s.price is not None)
+    summary = {}
+    if priced:
+        mid = len(priced) // 2
+        median = priced[mid] if len(priced) % 2 else (priced[mid - 1] + priced[mid]) // 2
+        summary = {
+            "priced_count": len(priced),
+            "median_price": median,
+            "min_price": priced[0],
+            "max_price": priced[-1],
+        }
+
+    return {
+        "postcode": postcode_norm,
+        "result_count": len(sales),
+        "summary": summary,
+        "sales": [s.as_dict() for s in sales],
+    }
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()