plannexus-mcp 0.1.0__tar.gz

plannexus_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/

plannexus_mcp-0.1.0/LICENSE

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

plannexus_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: plannexus-mcp
+Version: 0.1.0
+Summary: MCP server for PlanNexus — query UK planning-application data from Claude, ChatGPT or any MCP client.
+Project-URL: Homepage, https://plannexus.io
+Project-URL: Documentation, https://plannexus.io/mcp
+Author: PlanNexus
+License: MIT
+License-File: LICENSE
+Keywords: claude,llm,mcp,plannexus,planning,planning-applications,uk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# plannexus-mcp
+
+Put **UK planning data inside your AI.** `plannexus-mcp` is an [MCP](https://modelcontextprotocol.io)
+server that lets Claude, ChatGPT or any MCP client query [PlanNexus](https://plannexus.io) —
+planning applications across ~363 UK local planning authorities — in plain English.
+
+Ask things like *"what's been applied for within 500m of SW1A 1AA this month?"* and your
+assistant calls PlanNexus directly.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_applications` | Search by free text, postcode, council, or lat/lng + radius, with type/status/date filters |
+| `get_application` | Full detail for one application — status, decision, dates, and (on a paid plan) **agent / applicant / case-officer contacts** |
+| `get_constraints` | Planning constraints at a postcode or point — conservation area, listed building, Article 4, TPO, flood, green belt, … |
+| `find_authority` | Look up a council's id by name |
+
+## Setup (Claude Desktop)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "plannexus": {
+      "command": "uvx",
+      "args": ["plannexus-mcp"],
+      "env": { "PLANNEXUS_API_KEY": "pn_live_..." }
+    }
+  }
+}
+```
+
+Restart Claude and ask away. **Search works without a key** (public preview); add a
+[PlanNexus API key](https://plannexus.io) to unlock applicant/agent contacts on a paid plan.
+
+## Run directly
+
+```bash
+PLANNEXUS_API_KEY=pn_live_... uvx plannexus-mcp
+```
+
+`PLANNEXUS_BASE_URL` overrides the API base (defaults to `https://api.plannexus.io/v1`).
+
+## Licence
+
+MIT

plannexus_mcp-0.1.0/README.md

@@ -0,0 +1,48 @@
+# plannexus-mcp
+
+Put **UK planning data inside your AI.** `plannexus-mcp` is an [MCP](https://modelcontextprotocol.io)
+server that lets Claude, ChatGPT or any MCP client query [PlanNexus](https://plannexus.io) —
+planning applications across ~363 UK local planning authorities — in plain English.
+
+Ask things like *"what's been applied for within 500m of SW1A 1AA this month?"* and your
+assistant calls PlanNexus directly.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_applications` | Search by free text, postcode, council, or lat/lng + radius, with type/status/date filters |
+| `get_application` | Full detail for one application — status, decision, dates, and (on a paid plan) **agent / applicant / case-officer contacts** |
+| `get_constraints` | Planning constraints at a postcode or point — conservation area, listed building, Article 4, TPO, flood, green belt, … |
+| `find_authority` | Look up a council's id by name |
+
+## Setup (Claude Desktop)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "plannexus": {
+      "command": "uvx",
+      "args": ["plannexus-mcp"],
+      "env": { "PLANNEXUS_API_KEY": "pn_live_..." }
+    }
+  }
+}
+```
+
+Restart Claude and ask away. **Search works without a key** (public preview); add a
+[PlanNexus API key](https://plannexus.io) to unlock applicant/agent contacts on a paid plan.
+
+## Run directly
+
+```bash
+PLANNEXUS_API_KEY=pn_live_... uvx plannexus-mcp
+```
+
+`PLANNEXUS_BASE_URL` overrides the API base (defaults to `https://api.plannexus.io/v1`).
+
+## Licence
+
+MIT

plannexus_mcp-0.1.0/plannexus_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""PlanNexus MCP server — query UK planning data from any MCP client."""
+
+from plannexus_mcp.server import http_app, main, mcp
+
+__all__ = ["http_app", "main", "mcp"]

plannexus_mcp-0.1.0/plannexus_mcp/server.py

@@ -0,0 +1,210 @@
+"""PlanNexus MCP server — query UK planning data from any MCP client.
+
+A thin wrapper over the public PlanNexus REST API that exposes planning search,
+application detail, point-constraints and authority lookup as MCP tools, so a
+user can ask their AI assistant (Claude Desktop, Claude Code, ChatGPT, …) things
+like "what's been applied for within 500m of SW1A 1AA this month?" and have it
+call PlanNexus directly.
+
+Auth: set ``PLANNEXUS_API_KEY``. The key is forwarded on every call, so paid
+features (applicant/agent/case-officer contacts) appear automatically for a paid
+key and are redacted for a free key — identical gating to the API. Search works
+even with no key (public preview), so it's useful before sign-up.
+
+Two transports from one codebase:
+- ``main()`` — stdio, for a *local* client (the ``plannexus-mcp`` console script).
+  The key comes from ``PLANNEXUS_API_KEY``.
+- ``http_app()`` — a streamable-HTTP ASGI app for the *hosted* PlanNexus MCP
+  endpoint, where auth middleware calls ``set_request_key()`` per request so one
+  process serves many users' keys.
+
+Local setup (Claude Desktop ``claude_desktop_config.json``)::
+
+    {
+      "mcpServers": {
+        "plannexus": {
+          "command": "uvx",
+          "args": ["plannexus-mcp"],
+          "env": {"PLANNEXUS_API_KEY": "pn_live_..."}
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import contextvars
+import os
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("PlanNexus")
+
+_DEFAULT_BASE = "https://api.plannexus.io/v1"
+_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+# The caller's API key. The local (stdio) server reads PLANNEXUS_API_KEY; the
+# hosted (HTTP) server sets it per-request via this context var (one process,
+# many users). _key() prefers the per-request value, else the env var.
+_request_key: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "plannexus_api_key", default=None
+)
+
+
+def set_request_key(key: str | None) -> None:
+    """Set the PlanNexus API key for the current request context (hosted server)."""
+    _request_key.set(key)
+
+
+def _base_url() -> str:
+    return os.environ.get("PLANNEXUS_BASE_URL", _DEFAULT_BASE).rstrip("/")
+
+
+def _key() -> str:
+    return _request_key.get() or os.environ.get("PLANNEXUS_API_KEY", "")
+
+
+def _get(path: str, params: dict[str, Any]) -> Any:
+    """GET a PlanNexus endpoint, forwarding the API key, with LLM-friendly errors."""
+    clean = {k: v for k, v in params.items() if v not in (None, "", [])}
+    headers = {"Accept": "application/json", "User-Agent": "plannexus-mcp/0.1"}
+    key = _key()
+    if key:
+        headers["X-API-Key"] = key
+    try:
+        with httpx.Client(base_url=_base_url(), headers=headers, timeout=_TIMEOUT) as client:
+            r = client.get(path, params=clean)
+    except httpx.HTTPError as exc:
+        return {"error": f"request_failed: {exc}"}
+
+    if r.status_code == 401:
+        return {
+            "error": "Unauthorised — set a valid PlanNexus API key (get one at https://plannexus.io)."
+        }
+    if r.status_code == 402:
+        return {"error": "This is a paid PlanNexus feature — upgrade your plan to access it."}
+    if r.status_code == 404:
+        return {"error": "Not found."}
+    if r.status_code == 429:
+        return {"error": "Rate limit or monthly quota reached for your plan."}
+    if r.status_code >= 400:
+        return {"error": f"api_error {r.status_code}", "detail": r.text[:300]}
+    try:
+        return r.json()
+    except ValueError:
+        return {"error": "non_json_response", "detail": r.text[:300]}
+
+
+@mcp.tool()
+def search_applications(
+    query: str = "",
+    postcode: str = "",
+    authority_id: str = "",
+    lat: float | None = None,
+    lng: float | None = None,
+    radius_m: int = 1000,
+    application_type: str = "",
+    status: str = "",
+    date_received_from: str = "",
+    date_received_to: str = "",
+    limit: int = 20,
+) -> Any:
+    """Search UK planning applications across ~363 local planning authorities.
+
+    Combine any of:
+    - query: free text matched against description + address
+    - postcode: full or partial UK postcode (prefix match, e.g. "SW1A" or "SW1A 1AA")
+    - authority_id: a council UUID — use find_authority to look one up by name
+    - lat + lng + radius_m: everything within radius_m metres of a point
+    - application_type: e.g. "householder", "full", "outline", "listed_building"
+    - status: e.g. "approved", "refused", "pending"
+    - date_received_from / date_received_to: ISO dates (YYYY-MM-DD)
+
+    Returns a page of application summaries (id, reference, address, type, status,
+    dates, council, coordinates). Pass an id to get_application for full detail.
+    """
+    return _get(
+        "/applications",
+        {
+            "q": query,
+            "postcode": postcode,
+            "authority_id": authority_id,
+            "lat": lat,
+            "lng": lng,
+            "radius": radius_m,
+            "application_type": application_type,
+            "status": status,
+            "date_received_from": date_received_from,
+            "date_received_to": date_received_to,
+            "per_page": min(max(limit, 1), 100),
+        },
+    )
+
+
+@mcp.tool()
+def get_application(application_id: str) -> Any:
+    """Full detail for one planning application by id.
+
+    Returns address, description, type, status, decision, all dates, ward/parish,
+    coordinates, EPC (where matched) and — on a paid PlanNexus plan — the
+    applicant, agent and case-officer contact details (redacted on the free tier,
+    with a ``redacted_fields`` list). Get the id from search_applications.
+    """
+    return _get(f"/applications/{application_id}", {})
+
+
+@mcp.tool()
+def get_constraints(postcode: str = "", lat: float | None = None, lng: float | None = None) -> Any:
+    """Planning constraints at a point — by UK postcode, or by lat + lng.
+
+    Returns which designations apply at that location: conservation area, listed
+    building, Article 4 direction, tree preservation order (TPO), flood risk zone,
+    green belt, scheduled monument, AONB, SSSI, world heritage site, and more.
+    Answers "what would affect a development at this address?".
+    """
+    return _get("/constraints", {"postcode": postcode, "lat": lat, "lng": lng})
+
+
+@mcp.tool()
+def find_authority(name: str = "") -> Any:
+    """Find UK local planning authorities (councils) and their ids.
+
+    Pass a name or partial name (e.g. "camden", "north lincolnshire") to filter,
+    or omit to list all active councils. Use the returned id as ``authority_id``
+    in search_applications to scope a search to one council.
+    """
+    data = _get("/authorities", {})
+    if isinstance(data, dict) and isinstance(data.get("data"), list):
+        rows = data["data"]
+        if name:
+            needle = name.lower()
+            rows = [r for r in rows if needle in (r.get("name") or "").lower()]
+        return {
+            "authorities": [
+                {"id": r.get("id"), "name": r.get("name"), "gss_code": r.get("gss_code")}
+                for r in rows
+            ],
+            "total": len(rows),
+        }
+    return data
+
+
+def main() -> None:
+    """Console entry point (``plannexus-mcp``) — serves the tools over stdio."""
+    mcp.run()
+
+
+def http_app():
+    """Streamable-HTTP ASGI app for the hosted PlanNexus MCP endpoint.
+
+    The hosted deployment wraps this with middleware that reads the caller's
+    PlanNexus API key from the request and calls ``set_request_key()``, so a
+    single instance serves many users. (The local server uses ``main()`` instead.)
+    """
+    return mcp.streamable_http_app()
+
+
+if __name__ == "__main__":
+    main()

plannexus_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "plannexus-mcp"
+version = "0.1.0"
+description = "MCP server for PlanNexus — query UK planning-application data from Claude, ChatGPT or any MCP client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "PlanNexus" }]
+keywords = ["mcp", "planning", "uk", "planning-applications", "plannexus", "llm", "claude"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://plannexus.io"
+Documentation = "https://plannexus.io/mcp"
+
+[project.scripts]
+plannexus-mcp = "plannexus_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["plannexus_mcp"]