clevertech-mcp-server 0.1.0__py3-none-any.whl

clevertech_mcp/auth.py

@@ -0,0 +1,69 @@
+"""
+Authentication helpers for the CleverTech MCP server.
+
+Handles extraction of client IP, user API keys from request headers,
+and resolution of the upstream API key.
+"""
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+
+# MCP tools receive a *context* object (starlette Request or similar).
+# We use duck-typing to support both Starlette's Request and MCP's
+# RequestContext / MiddlewareContext.
+
+
+def _extract_client_ip(context) -> str:
+    """Extract the client IP address from an MCP/starlette context.
+
+    Prefers X-Forwarded-For (first entry) when present; falls back to
+    ``context.request.client.host`` or ``"unknown"``.
+    """
+    # Starlette-style request
+    request: Optional["Request"] = getattr(context, "request", None)
+    if request is not None:
+        forwarded = request.headers.get("X-Forwarded-For")
+        if forwarded:
+            # X-Forwarded-For can contain a comma-separated list
+            return forwarded.split(",")[0].strip()
+        if request.client is not None:
+            return request.client.host
+    return "unknown"
+
+
+def _get_user_api_key(context) -> Optional[str]:
+    """Extract a user-supplied API key from the request context.
+
+    Looks for an ``Authorization: Bearer <token>`` header.  Returns
+    ``None`` if no key is present.
+    """
+    import os
+
+    request = getattr(context, "request", None)
+    if request is not None:
+        auth_header: Optional[str] = request.headers.get("Authorization", "")
+        if auth_header.startswith("Bearer "):
+            return auth_header[7:]  # strip "Bearer "
+    return os.getenv("CLEVERTECH_API_KEY")
+
+
+def get_upstream_key(
+    user_api_key: Optional[str],
+    server_api_key: Optional[str],
+) -> Optional[str]:
+    """Return the API key to use for upstream CleverTech API calls.
+
+    Prefers the user-provided key (authenticated user) over the server-
+    wide key (anonymous / default).  Returns ``None`` if neither is set.
+    """
+    if user_api_key:
+        return user_api_key
+    return server_api_key
+
+
+def is_authenticated(user_api_key: Optional[str]) -> bool:
+    """Check if a user API key was provided."""
+    return bool(user_api_key)  # Empty string is not authenticated

clevertech_mcp/client.py

@@ -0,0 +1,54 @@
+"""
+CleverTech API client — async httpx wrapper.
+"""
+
+from typing import Any, Optional
+import httpx
+
+
+class CleverTechClient:
+    """Async HTTP client for the CleverTech API."""
+
+    def __init__(self, base_url: str, api_key: Optional[str] = None) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Lazily initialise and return the underlying httpx.AsyncClient."""
+        if self._client is None:
+            headers: dict[str, str] = {
+                "Accept": "application/json",
+            }
+            if self._api_key:
+                headers["Authorization"] = f"Bearer {self._api_key}"
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=headers,
+                timeout=30.0,
+            )
+        return self._client
+
+    async def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """Perform an async GET request and return the parsed JSON body."""
+        client = self._get_client()
+        response = await client.get(path, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    async def post(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Perform an async POST request and return the parsed JSON body."""
+        client = self._get_client()
+        response = await client.post(path, json=json)
+        response.raise_for_status()
+        return response.json()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client, if initialised."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None

clevertech_mcp/config.py

@@ -0,0 +1,35 @@
+"""
+CleverTech MCP Server — configuration loader.
+
+Loads settings from environment variables via python-dotenv.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def load_config() -> dict:
+    """Load and return the server configuration as a dict.
+
+    Environment variables read:
+        CLEVERTECH_API_URL      — base URL for the CleverTech API
+        CLEVERTECH_API_KEY      — API key for authenticated requests
+        PORT                    — port for SSE transport
+        TRANSPORT               — transport mode (stdio or sse)
+        LOG_LEVEL               — logging level
+        RATE_LIMIT_ANON_DAILY   — max anonymous requests per day
+        RATE_LIMIT_ANON_BURST   — max anonymous requests per minute
+        SENTRY_DSN              — Sentry DSN for error tracking
+    """
+    return {
+        "api_url": os.getenv("CLEVERTECH_API_URL", "https://clevertech.ca"),
+        "api_key": os.getenv("CLEVERTECH_API_KEY"),
+        "port": int(os.getenv("PORT", "8001")),
+        "transport": os.getenv("TRANSPORT", "stdio"),
+        "log_level": os.getenv("LOG_LEVEL", "INFO"),
+        "rate_limit_anon_daily": int(os.getenv("RATE_LIMIT_ANON_DAILY", "50")),
+        "rate_limit_anon_burst": int(os.getenv("RATE_LIMIT_ANON_BURST", "10")),
+        "sentry_dsn": os.getenv("SENTRY_DSN"),
+    }

clevertech_mcp/rate_limit.py

@@ -0,0 +1,100 @@
+"""
+Local in-memory rate limiter for anonymous users.
+
+Tracks requests per source IP using a sliding-window approach:
+- Daily limit (24-hour sliding window)
+- Burst limit (1-minute sliding window)
+"""
+
+import time
+import threading
+from typing import Optional
+
+
+class LocalRateLimiter:
+    """Thread-safe in-memory rate limiter keyed by source IP."""
+
+    def __init__(
+        self,
+        daily_limit: int = 50,
+        burst_per_minute: int = 10,
+    ) -> None:
+        self._daily_limit = daily_limit
+        self._burst_per_minute = burst_per_minute
+        self._storage: dict[str, list[tuple[float, int]]] = {}
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    #  Internal helpers
+    # ------------------------------------------------------------------
+
+    def _prune(self, key: str, now: float) -> None:
+        """Remove entries older than 24 hours from *key*'s history."""
+        if key not in self._storage:
+            return
+        cutoff = now - 86400.0  # 24 hours
+        self._storage[key] = [
+            (ts, cost) for ts, cost in self._storage[key] if ts > cutoff
+        ]
+        if not self._storage[key]:
+            del self._storage[key]
+
+    def _daily_usage(self, key: str) -> int:
+        """Total cost accumulated by *key* in the last 24 hours."""
+        return sum(cost for _, cost in self._storage.get(key, []))
+
+    def _burst_usage(self, key: str, now: float) -> int:
+        """Total cost accumulated by *key* in the last 60 seconds."""
+        cutoff = now - 60.0
+        return sum(
+            cost
+            for ts, cost in self._storage.get(key, [])
+            if ts > cutoff
+        )
+
+    # ------------------------------------------------------------------
+    #  Public API
+    # ------------------------------------------------------------------
+
+    def check(self, source_ip: str, cost: int = 1) -> tuple[bool, str]:
+        """Check whether *source_ip* is allowed to proceed.
+
+        Returns ``(True, "")`` if allowed, or ``(False, message)`` if
+        the request would exceed a rate limit.
+        """
+        now = time.time()
+        with self._lock:
+            self._prune(source_ip, now)
+
+            daily = self._daily_usage(source_ip)
+            if daily + cost > self._daily_limit:
+                remaining = self._daily_limit - daily
+                return False, (
+                    f"Daily rate limit exceeded. "
+                    f"{max(0, remaining)} of {self._daily_limit} requests remaining."
+                )
+
+            burst = self._burst_usage(source_ip, now)
+            if burst + cost > self._burst_per_minute:
+                return False, (
+                    f"Burst rate limit exceeded. "
+                    f"Max {self._burst_per_minute} requests per minute."
+                )
+
+            # Record the request
+            self._storage.setdefault(source_ip, []).append((now, cost))
+            return True, ""
+
+    def remaining(self, source_ip: str) -> dict[str, int]:
+        """Return a summary of remaining capacity for *source_ip*."""
+        now = time.time()
+        with self._lock:
+            self._prune(source_ip, now)
+            daily = self._daily_usage(source_ip)
+            burst = self._burst_usage(source_ip, now)
+            return {
+                "daily_used": daily,
+                "daily_remaining": max(0, self._daily_limit - daily),
+                "daily_limit": self._daily_limit,
+                "burst_remaining": max(0, self._burst_per_minute - burst),
+            }

clevertech_mcp/server.py

@@ -0,0 +1,81 @@
+"""
+CleverTech MCP Server — main entry point.
+"""
+
+import os
+import sys
+import argparse
+import json
+from mcp.server.fastmcp import FastMCP
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from clevertech_mcp.config import load_config
+from clevertech_mcp.client import CleverTechClient
+from clevertech_mcp.tools import register_all_tools
+
+
+async def health_endpoint(request):
+    """Health check endpoint for Railway deployment."""
+    return JSONResponse({"status": "ok", "service": "clevertech-mcp"})
+
+
+def create_server(config: dict) -> FastMCP:
+    """Build and return a fully-configured FastMCP server instance."""
+    mcp = FastMCP("clevertech-mcp")
+
+    client = CleverTechClient(
+        base_url=config["api_url"],
+        api_key=config.get("api_key"),
+    )
+
+    register_all_tools(mcp, client, config)
+    return mcp
+
+
+def main():
+    """CLI entry point for the CleverTech MCP server."""
+    parser = argparse.ArgumentParser(
+        description="CleverTech MCP Server — Canadian government data APIs"
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default=os.getenv("TRANSPORT", "stdio"),
+        help="Transport mode (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.getenv("HOST", "0.0.0.0"),
+        help="Host to bind when using SSE transport (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.getenv("PORT", "8001")),
+        help="Port to bind when using SSE transport (default: %(default)s)",
+    )
+    args = parser.parse_args()
+
+    config = load_config()
+    config["host"] = args.host
+    config["port"] = args.port
+
+    mcp = create_server(config)
+
+    if args.transport == "sse":
+        # Register /health endpoint for Railway health checks
+        sse_app = mcp.sse_app()
+        if not any(
+            getattr(r, "path", "") == "/health"
+            for r in getattr(sse_app, "routes", [])
+        ):
+            sse_app.router.routes.insert(0, Route("/health", endpoint=health_endpoint))
+        import uvicorn
+        uvicorn.run(sse_app, host=args.host, port=args.port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

clevertech_mcp/tools/__init__.py

@@ -0,0 +1,53 @@
+"""
+Aggregate all tool registrations onto a single FastMCP instance.
+"""
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_all_tools(mcp: FastMCP, client: CleverTechClient, config: dict) -> None:
+    """Wire up every tool category to the FastMCP server."""
+    # Lazy imports so that individual tool modules can be worked on in
+    # parallel without one missing module breaking the whole scaffold.
+    try:
+        from clevertech_mcp.tools.property import register_property_tools
+        register_property_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.dls import register_dls_tools
+        register_dls_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.building import register_building_tools
+        register_building_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.zoning import register_zoning_tools
+        register_zoning_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.business import register_business_tools
+        register_business_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.geo import register_geo_tools
+        register_geo_tools(mcp, client, config)
+    except ImportError:
+        pass
+
+    try:
+        from clevertech_mcp.tools.meta import register_meta_tools
+        register_meta_tools(mcp, client, config)
+    except ImportError:
+        pass

clevertech_mcp/tools/building.py

@@ -0,0 +1,95 @@
+"""Building permit MCP tools."""
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_building_tools(mcp: FastMCP, client: CleverTechClient, config: dict):
+    """Register building permit tools."""
+
+    @mcp.tool(
+        name="building_permit_search",
+        description="Search building permits by address, contractor, applicant, or permit number across 13+ Canadian cities. Returns permit details including type, value, status, and dates.",
+    )
+    async def building_permit_search(
+        city: str,
+        q: str,
+        permit_type: str = None,
+        limit: int = 20,
+    ) -> str:
+        """Search building permits.
+
+        Args:
+            city: City slug
+            q: Search query (address, contractor, applicant, or permit number)
+            permit_type: Filter by permit type (e.g., 'Building', 'Demolition', 'Electrical')
+            limit: Max results (1-200, default 20)
+        """
+        params = {"q": q, "limit": min(limit, 200)}
+        if permit_type:
+            params["permit_type"] = permit_type
+
+        data = await client.get(f"/api/{city}/building/search", params=params)
+
+        results = data.get("results", [])
+        total = data.get("total", 0)
+        message = data.get("_message", "")
+
+        lines = [f"Found {len(results)} of {total} building permits"]
+        if message:
+            lines.append(f"\n{message}")
+
+        for r in results:
+            lines.extend([
+                "",
+                "---",
+                f"Permit: {r.get('permit_number', 'N/A')}",
+                f"Type: {r.get('permit_type', 'N/A')}",
+                f"Status: {r.get('status', 'N/A')}",
+                f"Address: {r.get('address', 'N/A')}",
+                f"Applicant: {r.get('applicant', 'N/A')}",
+                f"Value: ${r.get('job_value', 0):,.0f}" if r.get('job_value') is not None else "Value: N/A",
+                f"Issued: {r.get('issued_date', 'N/A')}",
+            ])
+
+        return "\n".join(lines)
+
+    @mcp.tool(
+        name="building_permit_recent",
+        description="Get the most recently issued building permits for a city. Useful for monitoring new construction activity.",
+    )
+    async def building_permit_recent(
+        city: str,
+        limit: int = 20,
+    ) -> str:
+        """Get recently issued permits.
+
+        Args:
+            city: City slug
+            limit: Max results (1-100, default 20)
+        """
+        data = await client.get(
+            f"/api/{city}/building/recent",
+            params={"limit": min(limit, 100)},
+        )
+
+        results = data.get("results", [])
+        message = data.get("_message", "")
+
+        lines = [f"Recent building permits ({len(results)})"]
+        if message:
+            lines.append(f"\n{message}")
+
+        for r in results:
+            lines.extend([
+                "",
+                "---",
+                f"Permit: {r.get('permit_number', 'N/A')}",
+                f"Type: {r.get('permit_type', 'N/A')}",
+                f"Status: {r.get('status', 'N/A')}",
+                f"Address: {r.get('address', 'N/A')}",
+                f"Value: ${r.get('job_value', 0):,.0f}" if r.get('job_value') is not None else "Value: N/A",
+                f"Issued: {r.get('issued_date', 'N/A')}",
+            ])
+
+        return "\n".join(lines)

clevertech_mcp/tools/business.py

@@ -0,0 +1,60 @@
+"""Business registry MCP tools."""
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_business_tools(mcp: FastMCP, client: CleverTechClient, config: dict):
+    """Register business registry tools."""
+
+    @mcp.tool(
+        name="business_registry_search",
+        description="Search the Canadian federal business registry. Find corporations by name, province, city, status, or industry act.",
+    )
+    async def business_registry_search(
+        q: str,
+        province: str = None,
+        city: str = None,
+        status: str = None,
+        limit: int = 25,
+    ) -> str:
+        """Search the business registry.
+
+        Args:
+            q: Corporation name or keyword
+            province: Two-letter province code (AB, BC, ON, QC, etc.)
+            city: City name
+            status: Corporation status (Active, Dissolved, etc.)
+            limit: Max results (1-100, default 25)
+        """
+        params = {"q": q, "limit": min(limit, 100)}
+        if province:
+            params["province"] = province
+        if city:
+            params["city"] = city
+        if status:
+            params["status"] = status
+
+        data = await client.get("/api/registry/search", params=params)
+
+        results = data.get("results", [])
+        total = data.get("total", len(results))
+        message = data.get("_message", "")
+
+        lines = [f"Found {len(results)} of {total} corporations"]
+        if message:
+            lines.append(f"\n{message}")
+
+        for r in results:
+            lines.extend([
+                "",
+                "---",
+                f"Name: {r.get('corporation_name', r.get('name', 'N/A'))}",
+                f"Number: {r.get('corporation_number', r.get('number', 'N/A'))}",
+                f"Status: {r.get('status', 'N/A')}",
+                f"Jurisdiction: {r.get('jurisdiction', r.get('province', 'N/A'))}",
+            ])
+            if r.get('registered_address'):
+                lines.append(f"Address: {r['registered_address']}")
+
+        return "\n".join(lines)

clevertech_mcp/tools/dls.py

@@ -0,0 +1,119 @@
+"""DLS conversion MCP tools.
+
+Provides GPS ↔ Dominion Land Survey (DLS) coordinate conversion for Western
+Canadian provinces (Alberta, Saskatchewan, Manitoba).
+"""
+
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_dls_tools(mcp: FastMCP, client: CleverTechClient, config: dict) -> None:
+    """Register DLS conversion tools on the FastMCP server."""
+
+    @mcp.tool(
+        name="dls_convert",
+        description=(
+            "Convert between GPS coordinates and Dominion Land Survey (DLS) "
+            "grid system used in Western Canada. Supports GPS→DLS and "
+            "DLS→GPS directions."
+        ),
+    )
+    async def dls_convert(
+        direction: str,
+        lat: Optional[float] = None,
+        lon: Optional[float] = None,
+        dls_string: Optional[str] = None,
+        province: Optional[str] = None,
+    ) -> str:
+        """Convert a single coordinate between GPS and DLS.
+
+        Args:
+            direction: 'gps_to_dls' or 'dls_to_gps'.
+            lat: Latitude (required for gps_to_dls).
+            lon: Longitude (required for gps_to_dls).
+            dls_string: DLS grid reference (required for dls_to_gps).
+            province: Province code AB/SK/MB (optional, auto-detected).
+        """
+        if direction == "gps_to_dls":
+            if lat is None or lon is None:
+                return "Error: lat and lon are required for gps_to_dls direction."
+            payload: dict = {"lat": lat, "lon": lon}
+            if province:
+                payload["province"] = province
+            data = await client.post("/api/v1/convert/gps-to-dls", json=payload)
+        else:
+            if not dls_string:
+                return "Error: dls_string is required for dls_to_gps direction."
+            payload = {"dls_string": dls_string}
+            if province:
+                payload["province"] = province
+            data = await client.post("/api/v1/convert/dls-to-gps", json=payload)
+
+        lines: list[str] = []
+        if data.get("dls"):
+            lines.append(f"DLS: {data['dls']}")
+        if data.get("province"):
+            lines.append(f"Province: {data['province']}")
+        if "lat" in data and "lon" in data:
+            lines.append(f"GPS: {data['lat']}, {data['lon']}")
+        if data.get("confidence"):
+            lines.append(f"Confidence: {data['confidence']}")
+        if data.get("distance_km"):
+            lines.append(f"Distance to grid center: {data['distance_km']} km")
+        if data.get("_message"):
+            lines.append(f"\n{data['message']}")
+
+        return "\n".join(lines) if lines else "No result returned."
+
+    @mcp.tool(
+        name="dls_batch",
+        description=(
+            "Convert multiple GPS coordinates to DLS or multiple DLS strings "
+            "to GPS in a single batch request. Up to 100 items per batch."
+        ),
+    )
+    async def dls_batch(
+        direction: str,
+        items: list[dict],
+        province: Optional[str] = None,
+    ) -> str:
+        """Batch convert coordinates.
+
+        Args:
+            direction: 'gps_to_dls' or 'dls_to_gps'.
+            items: List of coordinate objects.
+                   gps_to_dls: [{"lat": 51.0, "lon": -114.0}, ...]
+                   dls_to_gps: [{"dls_string": "NW-16-24-1-W5"}, ...]
+            province: Province code (optional).
+        """
+        if not items:
+            return "Error: items list is empty."
+        if len(items) > 100:
+            return "Error: batch limited to 100 items."
+
+        payload: dict = {"direction": direction, "items": items}
+        if province:
+            payload["province"] = province
+
+        data = await client.post("/api/v1/convert/batch", json=payload)
+
+        results = data.get("results", [])
+        lines: list[str] = [f"Batch result: {data.get('count', 0)} conversions"]
+
+        for i, r in enumerate(results[:20]):
+            if r.get("dls"):
+                line = f"{i + 1}. {r['dls']}"
+                if "lat" in r and "lon" in r:
+                    line += f" → ({r['lat']}, {r['lon']})"
+                lines.append(line)
+
+        if len(results) > 20:
+            lines.append(f"\n... and {len(results) - 20} more")
+
+        if data.get("_message"):
+            lines.append(f"\n{data['message']}")
+
+        return "\n".join(lines)

clevertech_mcp/tools/geo.py

@@ -0,0 +1,43 @@
+"""Geocoding MCP tools."""
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_geo_tools(mcp: FastMCP, client: CleverTechClient, config: dict):
+    """Register geocoding tools."""
+
+    @mcp.tool(
+        name="reverse_geocode",
+        description="Convert GPS coordinates to a human-readable address, city, neighborhood, province, and DLS grid reference. Works across all Canadian cities in the CleverTech database.",
+    )
+    async def reverse_geocode(lat: float, lon: float) -> str:
+        """Reverse geocode GPS coordinates.
+
+        Args:
+            lat: Latitude
+            lon: Longitude
+        """
+        data = await client.get(
+            "/api/v1/geocode/reverse",
+            params={"lat": lat, "lon": lon},
+        )
+
+        lines = [
+            f"Address: {data.get('address', 'N/A')}",
+            f"City: {data.get('city', 'N/A')}",
+            f"Province: {data.get('province', 'N/A')}",
+            f"Postal Code: {data.get('postal_code', data.get('postcode', 'N/A'))}",
+            f"Neighborhood: {data.get('neighborhood', data.get('neighbourhood', 'N/A'))}",
+        ]
+
+        if data.get("dls"):
+            lines.append(f"DLS: {data['dls']}")
+        if data.get("lat") and data.get("lon"):
+            lines.append(f"GPS: {data['lat']}, {data['lon']}")
+        if data.get("confidence"):
+            lines.append(f"Confidence: {data['confidence']}")
+        if data.get("_message"):
+            lines.append(f"\n{data['_message']}")
+
+        return "\n".join(lines)

clevertech_mcp/tools/meta.py

@@ -0,0 +1,49 @@
+"""Meta MCP tools — server info, capabilities, city listing.
+
+Discovery endpoints so callers can learn which cities and services are
+available before making domain-specific calls.
+"""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_meta_tools(mcp: FastMCP, client: CleverTechClient, config: dict) -> None:
+    """Register meta-discovery tools on the FastMCP server."""
+
+    @mcp.tool(
+        name="list_cities",
+        description=(
+            "List all available cities with their slugs, API capabilities, "
+            "and property counts. Use this first to discover which cities are "
+            "available and what services each supports."
+        ),
+    )
+    async def list_cities() -> str:
+        """List available cities and their capabilities."""
+        data = await client.get("/api/cities")
+
+        cities = data.get("cities", data.get("results", []))
+        if not cities:
+            return json.dumps(data, indent=2, default=str)
+
+        lines: list[str] = ["# Available Cities\n"]
+        for city in cities:
+            name = city.get("name", city.get("city", "Unknown"))
+            slug = city.get("slug", city.get("city_slug", "?"))
+            props = city.get("property_count", city.get("count", "?"))
+            services = city.get("services", city.get("capabilities", []))
+
+            lines.append(f"## {name}")
+            lines.append(f"- Slug: {slug}")
+            if isinstance(props, int):
+                lines.append(f"- Properties: {props:,}")
+            else:
+                lines.append(f"- Properties: {props}")
+            if services:
+                lines.append(f"- Services: {', '.join(services)}")
+            lines.append("")
+
+        return "\n".join(lines)

clevertech_mcp/tools/property.py

@@ -0,0 +1,167 @@
+"""Property-related MCP tools.
+
+Search, lookup, and report on properties across Canadian cities.
+Provides assessment data, building permits, zoning, and DLS coordinates.
+"""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_property_tools(
+    mcp: FastMCP, client: CleverTechClient, config: dict
+) -> None:
+    """Register property search, by-roll, and report tools."""
+
+    @mcp.tool(
+        name="property_search",
+        description=(
+            "Search for properties by address across 13+ Canadian cities. "
+            "Returns assessment data including value, lot size, year built, "
+            "and DLS coordinates."
+        ),
+    )
+    async def property_search(
+        city: str,
+        address: str,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> str:
+        """Search for properties by address.
+
+        Args:
+            city: City slug (calgary, toronto, vancouver, montreal, edmonton,
+                  etc.).
+            address: Street address to search (partial matches supported).
+            limit: Max results (1-200, default 10).
+            offset: Pagination offset.
+        """
+        data = await client.get(
+            f"/api/{city}/property/search",
+            params={
+                "address": address,
+                "limit": min(limit, 200),
+                "offset": offset,
+            },
+        )
+
+        results = data.get("results", [])
+        total = data.get("total", 0)
+        message = data.get("_message", "")
+
+        lines: list[str] = [f"Found {len(results)} of {total} properties"]
+        if message:
+            lines.append(f"\n{message}")
+
+        for r in results:
+            lines.extend(
+                [
+                    "",
+                    "---",
+                    f"Address: {r.get('address', 'N/A')}",
+                    f"Roll: {r.get('roll_number', 'N/A')}",
+                ]
+            )
+            if r.get("assessed_value") is not None:
+                lines.append(f"Assessed Value: ${r['assessed_value']:,.0f}")
+            else:
+                lines.append("Assessed Value: N/A")
+            lines.append(f"Type: {r.get('property_type', 'N/A')}")
+            if r.get("dls"):
+                lines.append(f"DLS: {r['dls']}")
+
+        return "\n".join(lines)
+
+    @mcp.tool(
+        name="property_report",
+        description=(
+            "Get a consolidated property report — assessment data, building "
+            "permits at this address, zoning information, and DLS coordinates "
+            "in a single response."
+        ),
+    )
+    async def property_report(city: str, roll_number: str) -> str:
+        """Get a consolidated property report.
+
+        Args:
+            city: City slug.
+            roll_number: Property roll number.
+        """
+        data = await client.get(f"/api/{city}/property/report/{roll_number}")
+
+        message = data.get("_message", "")
+        lines: list[str] = [
+            "# Property Report",
+            f"**Address:** {data.get('address', 'N/A')}",
+            f"**Roll:** {data.get('roll_number', 'N/A')}",
+            f"**DLS:** {data.get('dls', 'N/A')}",
+            f"**Generated:** {data.get('generated_at', 'N/A')}",
+        ]
+
+        prop = data.get("property", {})
+        if prop:
+            lines.append("")
+            lines.append("## Assessment")
+            if prop.get("assessed_value") is not None:
+                lines.append(f"- Assessed Value: ${prop['assessed_value']:,.0f}")
+            else:
+                lines.append("- Assessed Value: N/A")
+            if prop.get("land_value") is not None:
+                lines.append(f"- Land: ${prop['land_value']:,.0f}")
+            else:
+                lines.append("- Land: N/A")
+            if prop.get("improvement_value") is not None:
+                lines.append(f"- Building: ${prop['improvement_value']:,.0f}")
+            else:
+                lines.append("- Building: N/A")
+            lines.append(f"- Year Built: {prop.get('year_built', 'N/A')}")
+            lines.append(f"- Lot Size: {prop.get('lot_size_sqm', 'N/A')} m²")
+
+        permits = data.get("permits", [])
+        if permits:
+            lines.append(f"\n## Building Permits ({len(permits)})")
+            for p in permits[:10]:
+                job_value = (
+                    f"${p.get('job_value', 0):,.0f}"
+                    if p.get("job_value") is not None
+                    else "N/A"
+                )
+                lines.append(
+                    f"- {p.get('permit_number', 'N/A')}: "
+                    f"{p.get('permit_type', 'N/A')} — {job_value}"
+                )
+
+        zoning = data.get("zoning")
+        if zoning:
+            lines.extend(
+                [
+                    "",
+                    "## Zoning",
+                    f"- Zone: {zoning.get('zone_code', 'N/A')}",
+                    f"- Description: {zoning.get('description', 'N/A')}",
+                ]
+            )
+
+        if message:
+            lines.append(f"\n{message}")
+
+        return "\n".join(lines)
+
+    @mcp.tool(
+        name="property_by_roll",
+        description=(
+            "Get a single property assessment record by its roll number. "
+            "Faster than search when you already know the roll number."
+        ),
+    )
+    async def property_by_roll(city: str, roll_number: str) -> str:
+        """Get a property by its roll number.
+
+        Args:
+            city: City slug.
+            roll_number: Property roll number.
+        """
+        data = await client.get(f"/api/{city}/property/by-roll/{roll_number}")
+        return json.dumps(data, indent=2, default=str)

clevertech_mcp/tools/zoning.py

@@ -0,0 +1,58 @@
+"""Zoning MCP tools."""
+
+from mcp.server.fastmcp import FastMCP
+from clevertech_mcp.client import CleverTechClient
+
+
+def register_zoning_tools(mcp: FastMCP, client: CleverTechClient, config: dict):
+    """Register zoning lookup tools."""
+
+    @mcp.tool(
+        name="zoning_lookup",
+        description="Look up zoning district information for a GPS point or address in a Canadian city. Returns zone code, description, and district boundaries.",
+    )
+    async def zoning_lookup(
+        city: str,
+        lat: float = None,
+        lon: float = None,
+        address: str = None,
+    ) -> str:
+        """Get zoning information.
+
+        Args:
+            city: City slug
+            lat: Latitude (alternative to address)
+            lon: Longitude (alternative to address)
+            address: Street address (alternative to lat/lon)
+        """
+        if lat is not None and lon is not None:
+            params = {"lat": lat, "lon": lon}
+            data = await client.get(f"/api/{city}/zoning/by-gps", params=params)
+        elif address:
+            data = await client.get(f"/api/{city}/zoning/by-gps", params={"address": address})
+        else:
+            return "Error: Provide either lat+lon or address."
+
+        message = data.get("_message", "")
+        zoning = data.get("zoning", data)
+        if isinstance(zoning, list):
+            zoning = zoning[0] if zoning else {}
+
+        lines = [
+            f"Zone: {zoning.get('zone_code', zoning.get('zone', 'N/A'))}",
+            f"Description: {zoning.get('description', 'N/A')}",
+        ]
+
+        if zoning.get("district_name"):
+            lines.append(f"District: {zoning['district_name']}")
+        if zoning.get("land_use"):
+            lines.append(f"Land Use: {zoning['land_use']}")
+
+        bounds = zoning.get("boundaries", zoning.get("geometry"))
+        if bounds:
+            lines.append(f"Boundaries: Available ({type(bounds).__name__})")
+
+        if message:
+            lines.append(f"\n{message}")
+
+        return "\n".join(lines)

clevertech_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: clevertech-mcp-server
+Version: 0.1.0
+Summary: MCP Server for CleverTech Canadian government data APIs
+Author-email: CleverTech <dev@clevertech.ca>
+License: MIT
+License-File: LICENSE
+Keywords: canada,dls,gis,land-survey,mcp,property
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: starlette>=0.36.0
+Requires-Dist: uvicorn>=0.27.0
+Description-Content-Type: text/markdown
+
+# CleverTech MCP Server
+
+**Canadian government data for AI agents.** Property assessments, building permits, zoning, business registry, DLS grid conversion — 50 free queries/day, no signup.
+
+```bash
+npx @clevertech/mcp-server
+```
+
+[![PyPI version](https://badge.fury.io/py/clevertech-mcp-server.svg)](https://pypi.org/project/clevertech-mcp-server/)
+[![npm version](https://badge.fury.io/npm/%40clevertech%2Fmcp-server.svg)](https://www.npmjs.com/package/@clevertech/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Quick Start
+
+### Claude Code
+
+Add to your `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clevertech": {
+      "command": "npx",
+      "args": ["-y", "@clevertech/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor / Cline
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "clevertech": {
+      "command": "uvx",
+      "args": ["clevertech-mcp-server"]
+    }
+  }
+}
+```
+
+### GitHub Copilot
+
+```json
+{
+  "mcpServers": {
+    "clevertech": {
+      "command": "npx",
+      "args": ["-y", "@clevertech/mcp-server"]
+    }
+  }
+}
+```
+
+### Direct CLI
+
+```bash
+# npm (Node.js)
+npx @clevertech/mcp-server
+
+# uv / PyPI
+uvx clevertech-mcp-server
+```
+
+---
+
+## Available Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `dls_convert` | GPS ↔ Dominion Land Survey (DLS) coordinate conversion for Western Canada |
+| `dls_batch` | Batch GPS ↔ DLS conversion — up to 100 coordinates at once |
+| `property_search` | Property assessment search by address across 13+ Canadian cities |
+| `property_report` | Consolidated property report — assessment, permits, zoning, and DLS in one call |
+| `property_by_roll` | Direct property lookup by roll number — faster than address search |
+| `building_permit_search` | Building permit search by address, contractor, applicant, or permit number |
+| `building_permit_recent` | Recently issued building permits feed — monitor new construction activity |
+| `zoning_lookup` | Zoning district lookup by GPS coordinates or street address |
+| `business_registry_search` | Federal corporation search — find Canadian businesses by name, province, or city |
+| `reverse_geocode` | GPS → address, city, neighborhood, province, and DLS grid reference |
+| `list_cities` | Discover available cities, their API capabilities, and property counts |
+
+### What Agents Can Do
+
+- **Ask**: *"What's 1532 14 Ave SW in Calgary worth?"* — Gets assessed value, land value, building value, year built, lot size, and DLS coordinates.
+- **Ask**: *"Show me recent building permits in Vancouver"* — Returns the latest construction permits with type, value, status, and issue dates.
+- **Ask**: *"What zone is this GPS point in?"* — Looks up zoning district, land use, and boundary info.
+- **Ask**: *"Convert these 50 GPS points to DLS"* — Batch converts in a single API call.
+- **Ask**: *"Is Shopify still an active corporation?"* — Searches the federal business registry.
+
+---
+
+## Cities Supported
+
+**20 cities** across Canada — and growing:
+
+| Province | Cities |
+|----------|--------|
+| Alberta | Calgary, Edmonton, High River |
+| British Columbia | Vancouver, Victoria |
+| Ontario | Toronto, Ottawa, Hamilton, Kitchener, London, Mississauga, Markham, Vaughan |
+| Quebec | Montreal, Quebec City |
+| Manitoba | Winnipeg |
+| Saskatchewan | Saskatoon, Regina |
+| Nova Scotia | Halifax |
+| Newfoundland | St. John's |
+
+Use `list_cities` to see live availability, API capabilities per city, and property counts.
+
+---
+
+## Pricing
+
+No signup required to start. Free tier gives you 50 queries/day out of the box.
+
+| Tier | Queries/Day | Price | API Key |
+|------|-------------|-------|---------|
+| **Free** | 50 | $0 | Not required |
+| **Developer** | 200 | Free | [Sign up →](https://clevertech.ca/keys) |
+| **Pro** | 2,000 | $10/mo | [Sign up →](https://clevertech.ca/keys) |
+| **Enterprise** | 10,000 | $40/mo | [Sign up →](https://clevertech.ca/keys) |
+
+[Get your API key →](https://clevertech.ca/keys)
+
+### Using an API Key
+
+```bash
+npx @clevertech/mcp-server --api-key YOUR_KEY
+```
+
+Or via environment variable:
+
+```bash
+export CLEVERTECH_API_KEY=your_key_here
+npx @clevertech/mcp-server
+```
+
+---
+
+## Features
+
+- **No signup required** — 50 free queries/day out of the box
+- **11 MCP tools** covering property, permits, zoning, business registry, and DLS
+- **Batch DLS conversion** — convert up to 100 coordinates in one call
+- **Consolidated property reports** — assessment + permits + zoning + DLS in a single response
+- **stdio + SSE transport** — works with Claude Code, Cursor, Cline, GitHub Copilot, and any MCP-compatible agent
+- **Clean text output** — formatted for easy LLM parsing and reformatting
+- **20 Canadian cities** — urban and rural coverage with regular additions
+- **MIT licensed** — use it anywhere, no restrictions
+
+---
+
+## Development
+
+```bash
+# Clone and set up
+git clone https://github.com/anteriorclever/clevertech-mcp-server.git
+cd clevertech-mcp-server
+uv sync
+
+# Run locally (stdio transport)
+uv run clevertech-mcp-server --transport stdio
+
+# Run with SSE transport (for HTTP-based agents)
+uv run clevertech-mcp-server --transport sse --port 8000
+```
+
+### Run Tests
+
+```bash
+uv run pytest
+```
+
+### Project Structure
+
+```
+src/clevertech_mcp/
+├── tools/
+│   ├── property.py    # property_search, property_report, property_by_roll
+│   ├── building.py    # building_permit_search, building_permit_recent
+│   ├── zoning.py      # zoning_lookup
+│   ├── dls.py         # dls_convert, dls_batch
+│   ├── business.py    # business_registry_search
+│   ├── geo.py         # reverse_geocode
+│   └── meta.py        # list_cities
+├── server.py          # FastMCP server entry point
+├── client.py          # HTTP client for CleverTech API
+├── auth.py            # API key authentication
+├── rate_limit.py      # Rate limiting
+└── config.py          # Configuration management
+```
+
+---
+
+## Documentation
+
+- [Tool Reference](docs/tools.md)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [CleverTech API Keys](https://clevertech.ca/keys)
+
+---
+
+## License
+
+MIT © 2026 CleverTech — see [LICENSE](LICENSE) for details.

clevertech_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+clevertech_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clevertech_mcp/auth.py,sha256=xgmWMnBfqB5Mf2AbAeM4L1G0URj2rYT29UCiH8UFyFA,2247
+clevertech_mcp/client.py,sha256=THID5xn-1yCC6dDIK9GZab94Q37Qfw1K-wZEQzNOCGw,1823
+clevertech_mcp/config.py,sha256=XOnv9AZxSfIhDo16k8CSES0_TmNXXqu3Jdiqvf6rI-Q,1331
+clevertech_mcp/rate_limit.py,sha256=9qmAqNwK9hprNpvTAYlI8BIBehhuaygoYojM5WKxmPg,3567
+clevertech_mcp/server.py,sha256=JhRpKOT5ImJauzpW8mf6CGk8t8MRgpsDBsw0qt3esCQ,2280
+clevertech_mcp/tools/__init__.py,sha256=oC66yJC3AwG7VFsFW7mWLNlIJ-frPh3FzmwKCVL9GeE,1624
+clevertech_mcp/tools/building.py,sha256=fHToQxUsZbiS1xlXyPwbTo0SCh2qcUY-VY_TpOqsjYg,3331
+clevertech_mcp/tools/business.py,sha256=dPESy1X7fotYVr8zyzpt2_5FHlQ5JjlQYtcloVrvLwc,2069
+clevertech_mcp/tools/dls.py,sha256=RaqxRy3zLfAz5n4hQUm2rvpCy5a6HWS2vMvBbJicXJc,4356
+clevertech_mcp/tools/geo.py,sha256=8BNg8HH2R37XKZoLKqg_TChmzGXs3djrwdN4zVOvHss,1555
+clevertech_mcp/tools/meta.py,sha256=K9WeOmYPoQpqEvw1KQ8bJa8r0eyiP8vJM_sON1HAz9w,1788
+clevertech_mcp/tools/property.py,sha256=r9vYZBvKUN90xf4PQldgJ_9pJNj-a4ZdeEH6zXr2upI,5677
+clevertech_mcp/tools/zoning.py,sha256=rwKYt1BhCgHRR18th2hhY8vI2koIG6rb05-cOscNmHA,2020
+clevertech_mcp_server-0.1.0.dist-info/METADATA,sha256=z-lxFnN2LGXQYZq0yi93MnI1t-mKZFW27nBpgG8oThU,7039
+clevertech_mcp_server-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+clevertech_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=5DBsT1PeZ75Kwp2MCi6RFU4_704NTddkpXqyO85hWyo,69
+clevertech_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=nm-6Sfd2weKWBQsLq4qTjKEzdAKVIA4Y11gUniTqcIg,1067
+clevertech_mcp_server-0.1.0.dist-info/RECORD,,

clevertech_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

clevertech_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clevertech-mcp-server = clevertech_mcp.server:main

clevertech_mcp_server-0.1.0.dist-info/licenses/LICENSE

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