map-mcp 0.1.0__py3-none-any.whl

map_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""map-mcp — drive and perceive an existing live MapLibre GL map from an agent or a human CLI.
+
+A map app opts in with a small JS hook that registers its live map and connects out to a
+local WebSocket this process runs. The MCP tools (for agents) and the CLI (for humans) are
+thin frontends over one shared core-operations layer, so any operation one can do, the other
+can too (parity by construction). v1 is MapLibre-only and drives *existing* maps — it does not
+generate maps.
+"""
+
+__version__ = "0.1.0"

map_mcp/bridge.py

@@ -0,0 +1,202 @@
+"""The local WebSocket bridge between this process and the in-browser map hook.
+
+``call(method, params)`` sends a request to the connected hook and blocks until the matching
+reply arrives (correlated by id). The correlation logic is synchronous and unit-testable
+without a socket — feed replies via ``_on_message``. The live WebSocket server is gated on the
+``websockets`` library, binds loopback only, and (with U6) requires a per-session token.
+
+Sync-over-async: the ws server runs in a daemon thread with its own event loop; ``call`` (on
+the MCP/CLI thread) waits on a threading event the receive coroutine sets. This keeps core-ops
+and the MCP tools synchronous, matching streamlit-mcp's engine.
+"""
+
+from __future__ import annotations
+
+import secrets
+import threading
+from typing import Any, Callable, Optional
+
+from .protocol import decode, encode, make_request
+
+
+class BridgeError(RuntimeError):
+    """Raised when no map is connected, a call times out, or the hook returns an error."""
+
+
+def ws_available() -> bool:
+    try:
+        import websockets  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def authenticate(first_message: str, expected_token: Optional[str]) -> bool:
+    """Validate the hook's opening ``{type:"hello", token}`` frame against the session token.
+
+    Pure (no I/O), so the handshake rule is unit-testable. When no token is configured
+    (``expected_token`` falsy) the gate is open — but the CLI always issues a token."""
+    if not expected_token:
+        return True
+    try:
+        msg = decode(first_message)
+    except Exception:
+        return False
+    if msg.get("type") != "hello":
+        return False
+    # constant-time compare so token validation leaks no timing signal
+    return secrets.compare_digest(str(msg.get("token") or ""), str(expected_token))
+
+
+class _Pending:
+    __slots__ = ("event", "result", "error")
+
+    def __init__(self) -> None:
+        self.event = threading.Event()
+        self.result: Any = None
+        self.error: Optional[str] = None
+
+
+class Bridge:
+    """Correlates outbound requests with inbound replies by id. Transport-agnostic."""
+
+    def __init__(self) -> None:
+        self._pending: dict[Any, _Pending] = {}
+        self._lock = threading.Lock()
+        self._sender: Optional[Callable[[str], None]] = None
+        self._thread: Optional[threading.Thread] = None
+        self.port: Optional[int] = None
+        self._loop: Any = None
+
+    @property
+    def connected(self) -> bool:
+        return self._sender is not None
+
+    def attach_sender(self, sender: Callable[[str], None]) -> None:
+        """Bind the function that writes a frame to the connected hook (last writer wins —
+        a reconnect/new tab replaces the old; the old's in-flight calls then time out)."""
+        self._sender = sender
+
+    def detach(self, sender: Optional[Callable[[str], None]] = None) -> None:
+        """Clear the sender on disconnect. Identity-guarded: a stale connection's teardown
+        only clears the sender if it is still the *current* one — so a page reload (new
+        socket attaches, then the old socket's close fires) can't null the live sender.
+        Draining lets in-flight calls fail fast with 'map disconnected' instead of timing out."""
+        if sender is None or self._sender is sender:
+            self._sender = None
+            self._drain_pending("map disconnected")
+
+    def _drain_pending(self, message: str) -> None:
+        with self._lock:
+            waiting = list(self._pending.values())
+        for pend in waiting:
+            if pend.error is None and pend.result is None:
+                pend.error = message
+                pend.event.set()
+
+    def call(self, method: str, params: Optional[dict] = None, *, timeout: float = 10.0) -> Any:
+        """Send a request and block for its reply. Raises BridgeError on no-connection,
+        send failure, timeout, disconnect, or an error reply — never leaks another exception."""
+        sender = self._sender
+        if sender is None:
+            raise BridgeError("no map connected — open a hooked map and try again")
+        req = make_request(method, params)
+        pend = _Pending()
+        with self._lock:
+            self._pending[req["id"]] = pend
+        try:
+            try:
+                sender(encode(req))
+            except Exception as e:  # closed loop / dropped socket -> clean BridgeError, not a leak
+                raise BridgeError(f"send failed: {e}") from e
+            if not pend.event.wait(timeout):
+                raise BridgeError(f"timeout after {timeout}s waiting for {method!r}")
+            if pend.error is not None:
+                raise BridgeError(pend.error)
+            return pend.result
+        finally:
+            with self._lock:
+                self._pending.pop(req["id"], None)
+
+    def _on_message(self, text: str) -> None:
+        """Resolve the pending call matching this reply's id. Unknown/stale ids are ignored."""
+        try:
+            msg = decode(text)
+        except Exception:
+            return
+        with self._lock:
+            pend = self._pending.get(msg.get("id"))
+        if pend is None:
+            return
+        if msg.get("ok"):
+            pend.result = msg.get("result")
+        else:
+            pend.error = msg.get("error") or "unknown error from hook"
+        pend.event.set()
+
+    # ------------------------------------------------------------- live server
+    def serve_ws(self, host: str = "127.0.0.1", port: int = 8765,
+                 token: Optional[str] = None) -> None:
+        """Start the loopback WebSocket server in a daemon thread (non-blocking).
+
+        Gated on ``websockets``. Binds loopback only. The token handshake is layered in U6;
+        v1 here wires connect -> sender, and routes inbound frames to ``_on_message``.
+        """
+        if not ws_available():
+            raise BridgeError("websockets not installed — `pip install map-mcp` includes it")
+        if host not in ("127.0.0.1", "::1", "localhost"):
+            raise BridgeError(f"refusing to bind non-loopback host {host!r} (local-only)")
+
+        import asyncio
+
+        import websockets
+
+        loop = asyncio.new_event_loop()
+        self._loop = loop
+        ready = threading.Event()
+        startup: dict[str, BaseException] = {}
+
+        async def handler(ws):
+            # Token handshake (local-only security): require a valid hello before accepting
+            # commands, so a stray page on the loopback port can't drive the operator's map.
+            if token:
+                try:
+                    first = await asyncio.wait_for(ws.recv(), timeout=10)
+                except Exception:
+                    return
+                if not authenticate(first, token):
+                    await ws.close(code=4001, reason="bad token")
+                    return
+            send = lambda text: asyncio.run_coroutine_threadsafe(ws.send(text), loop)
+            self.attach_sender(send)
+            try:
+                async for message in ws:
+                    self._on_message(message)
+            finally:
+                self.detach(send)  # identity-guarded: only clears if still the current sender
+
+        async def main():
+            async with websockets.serve(handler, host, port) as server:
+                try:
+                    self.port = server.sockets[0].getsockname()[1]
+                except Exception:
+                    self.port = port
+                ready.set()
+                await asyncio.Future()  # serve forever
+
+        def run():
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_until_complete(main())
+            except BaseException as e:  # bind failure (port in use), etc.
+                startup["error"] = e
+                ready.set()  # unblock the waiter so it can surface the error
+
+        self._thread = threading.Thread(target=run, daemon=True, name="map-mcp-bridge")
+        self._thread.start()
+        # Don't return until the server is actually listening — and surface startup failure
+        # (a port-in-use bind error would otherwise die silently in the thread).
+        if not ready.wait(timeout=5):
+            raise BridgeError("bridge did not start within 5s")
+        if "error" in startup:
+            raise BridgeError(f"bridge failed to start: {startup['error']}")

map_mcp/cli.py

@@ -0,0 +1,153 @@
+"""map-mcp CLI — the human-first surface.
+
+`serve` starts the bridge + the MCP server (for agents) and prints the opt-in snippet + token.
+`call` lets a human drive the live map from the terminal. Both paths go through the same
+``CoreOps`` an agent uses over MCP, so parity holds by construction — ``run_op`` accepts exactly
+the operations the MCP tools expose.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+import sys
+import time
+from typing import Any, Optional
+
+from .bridge import Bridge, BridgeError
+from .coreops import OP_NAMES, CoreOps
+
+
+def _force_utf8_output() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def run_op(ops: CoreOps, op: str, params: Optional[dict] = None) -> dict:
+    """Dispatch one operation by name through core-ops. Fail-closed, like the MCP tools.
+
+    This is the parity seam: it accepts exactly ``OP_NAMES`` — the same surface the agent has."""
+    if op not in OP_NAMES:
+        return {"error": f"unknown operation {op!r}; expected one of {list(OP_NAMES)}"}
+    try:
+        result = getattr(ops, op)(**(params or {}))
+    except (BridgeError, ValueError, TypeError) as e:
+        return {"error": str(e)}
+    return result if isinstance(result, dict) else {"result": result}
+
+
+def _snippet(ws_port: int, token: str) -> str:
+    url = f"ws://127.0.0.1:{ws_port}"
+    return (
+        "Add this to your MapLibre page (the map is your existing maplibregl.Map):\n"
+        '  <script src="map-mcp-hook.js"></script>\n'
+        "  <script>\n"
+        f'    mapMcp.register(map, {{ url: "{url}", token: "{token}" }});\n'
+        "  </script>\n"
+        f"  bridge: {url}   token: {token}"
+    )
+
+
+# --------------------------------------------------------------------- commands
+def _start_bridge(ws_port: int) -> tuple[Bridge, str]:
+    """Start the loopback bridge with a fresh per-session token. Raises BridgeError on
+    startup failure (e.g. port in use). Shared by serve and call."""
+    token = secrets.token_urlsafe(16)
+    bridge = Bridge()
+    bridge.serve_ws(host="127.0.0.1", port=ws_port, token=token)
+    return bridge, token
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from .server import run_server, validate_transport
+    try:
+        validate_transport(args.transport)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    try:
+        bridge, token = _start_bridge(args.ws_port)
+    except Exception as e:
+        print(f"could not start the map bridge: {e}", file=sys.stderr)
+        return 1
+    print(_snippet(bridge.port, token), file=sys.stderr)
+    try:
+        run_server(bridge, transport=args.transport, host=args.host, port=args.port)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    return 0
+
+
+def _wait_for_map(bridge: Bridge, timeout: float) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if bridge.connected:
+            return True
+        time.sleep(0.1)
+    return bridge.connected
+
+
+def cmd_call(args: argparse.Namespace) -> int:
+    try:
+        params = json.loads(args.params) if args.params else {}
+    except json.JSONDecodeError as e:
+        print(f"bad --params JSON: {e}", file=sys.stderr)
+        return 1
+    try:
+        bridge, token = _start_bridge(args.ws_port)
+    except Exception as e:
+        print(f"could not start the map bridge: {e}", file=sys.stderr)
+        return 1
+    print(_snippet(bridge.port, token), file=sys.stderr)
+    if not _wait_for_map(bridge, args.wait):
+        print("no map connected — open your hooked map, then retry", file=sys.stderr)
+        return 1
+    result = run_op(CoreOps(bridge), args.op, params)
+    print(json.dumps(result, indent=2, default=str))
+    return 1 if "error" in result else 0
+
+
+# --------------------------------------------------------------------- parser
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="map-mcp",
+        description="Drive and perceive an existing live MapLibre GL map (agent via MCP, or here).")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_serve = sub.add_parser("serve", help="serve the live map over MCP (for agents)")
+    p_serve.add_argument("--transport", choices=["stdio", "http", "sse"], default="stdio")
+    p_serve.add_argument("--host", default="127.0.0.1")
+    p_serve.add_argument("--port", type=int, default=8000, help="MCP HTTP/SSE port")
+    p_serve.add_argument("--ws-port", dest="ws_port", type=int, default=8765,
+                         help="bridge WebSocket port the hook connects to")
+    p_serve.set_defaults(func=cmd_serve)
+
+    p_call = sub.add_parser("call", help="run one operation against the live map (same ops agents use)")
+    p_call.add_argument("op", choices=list(OP_NAMES))
+    p_call.add_argument("--params", help="JSON params, e.g. '{\"point\":[12.5,41.9]}'")
+    p_call.add_argument("--ws-port", dest="ws_port", type=int, default=8765)
+    p_call.add_argument("--wait", type=float, default=30.0,
+                        help="seconds to wait for the hooked map to connect")
+    p_call.set_defaults(func=cmd_call)
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    _force_utf8_output()
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+def _cli() -> None:
+    """Console-script entry point — propagate the exit code."""
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    _cli()

map_mcp/coreops.py

@@ -0,0 +1,114 @@
+"""Core operations — the single implementation each frontend (MCP server + CLI) calls.
+
+Every op issues one bridge call and returns the hook's structured result. The bridge is
+injected, so a fake bridge makes this layer fully unit-testable without a browser. Input
+validation lives here (geographic inputs are ``[lng, lat]``); the hook does the MapLibre work.
+A bridge error (no map connected, timeout, hook error) propagates as ``BridgeError`` — the
+frontends turn it into a clean tool/CLI error.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# The canonical operation surface. The MCP tool set and the CLI command set both cover exactly
+# these — the parity contract (asserted in the scenario test).
+OP_NAMES = (
+    "get_viewport",
+    "query_rendered_features",
+    "get_features_at",
+    "click_at",
+    "read_popup",
+    "set_view",
+    "list_layers",
+    "set_layer_visibility",
+    "screenshot",
+)
+
+
+class CoreOps:
+    def __init__(self, bridge: Any) -> None:
+        self.bridge = bridge
+
+    def get_viewport(self) -> dict:
+        return self.bridge.call("get_viewport")
+
+    def query_rendered_features(
+        self,
+        point: Optional[list] = None,
+        bbox: Optional[list] = None,
+        layers: Optional[list] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        params: dict = {}
+        if point is not None:
+            params["point"] = _point(point)
+        if bbox is not None:
+            params["bbox"] = _bbox(bbox)
+        if layers:
+            params["layers"] = list(layers)
+        if limit is not None:
+            params["limit"] = int(limit)
+        return self.bridge.call("query_rendered_features", params)
+
+    def get_features_at(self, point: list, layers: Optional[list] = None) -> dict:
+        params: dict = {"point": _point(point)}
+        if layers:
+            params["layers"] = list(layers)
+        return self.bridge.call("get_features_at", params)
+
+    def click_at(self, point: list, layers: Optional[list] = None) -> dict:
+        params: dict = {"point": _point(point)}
+        if layers:
+            params["layers"] = list(layers)
+        return self.bridge.call("click_at", params)
+
+    def read_popup(self) -> dict:
+        return self.bridge.call("read_popup")
+
+    def set_view(
+        self,
+        center: Optional[list] = None,
+        zoom: Optional[float] = None,
+        bbox: Optional[list] = None,
+        bearing: Optional[float] = None,
+        pitch: Optional[float] = None,
+    ) -> dict:
+        params: dict = {}
+        if center is not None:
+            params["center"] = _point(center)
+        if zoom is not None:
+            params["zoom"] = float(zoom)
+        if bbox is not None:
+            params["bbox"] = _bbox(bbox)
+        if bearing is not None:
+            params["bearing"] = float(bearing)
+        if pitch is not None:
+            params["pitch"] = float(pitch)
+        if not params:
+            raise ValueError("set_view needs at least one of center/zoom/bbox/bearing/pitch")
+        return self.bridge.call("set_view", params)
+
+    def list_layers(self) -> dict:
+        return self.bridge.call("list_layers")
+
+    def set_layer_visibility(self, layer: str, visible: bool) -> dict:
+        if not layer:
+            raise ValueError("set_layer_visibility needs a layer id")
+        return self.bridge.call("set_layer_visibility",
+                                {"layer": layer, "visible": bool(visible)})
+
+    def screenshot(self) -> dict:
+        return self.bridge.call("screenshot")
+
+
+def _point(p: Any) -> list:
+    if not (isinstance(p, (list, tuple)) and len(p) == 2):
+        raise ValueError(f"point must be [lng, lat], got {p!r}")
+    return [float(p[0]), float(p[1])]
+
+
+def _bbox(b: Any) -> list:
+    if not (isinstance(b, (list, tuple)) and len(b) == 2):
+        raise ValueError(f"bbox must be [[lng,lat],[lng,lat]], got {b!r}")
+    return [_point(b[0]), _point(b[1])]

map_mcp/protocol.py

@@ -0,0 +1,46 @@
+"""Pure wire protocol for the bridge: request/response envelopes + id correlation.
+
+No I/O — fully unit-testable. Both the live socket (``bridge.py``) and the in-browser hook
+speak this. A request is ``{id, method, params}``; a reply is ``{id, ok, result}`` on success
+or ``{id, ok=false, error}`` on failure.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+from typing import Any, Optional
+
+_counter = itertools.count(1)
+
+
+def next_id() -> int:
+    """Monotonic request id (process-local)."""
+    return next(_counter)
+
+
+def make_request(method: str, params: Optional[dict] = None, *, id: Optional[int] = None) -> dict:
+    if not method:
+        raise ValueError("request needs a method")
+    return {
+        "id": id if id is not None else next_id(),
+        "method": method,
+        "params": params or {},
+    }
+
+
+def make_response(id: Any, *, result: Any = None, error: Optional[str] = None) -> dict:
+    if error is not None:
+        return {"id": id, "ok": False, "error": error}
+    return {"id": id, "ok": True, "result": result}
+
+
+def encode(msg: dict) -> str:
+    return json.dumps(msg)
+
+
+def decode(text: str) -> dict:
+    msg = json.loads(text)
+    if not isinstance(msg, dict):
+        raise ValueError("envelope must be a JSON object")
+    return msg

map_mcp/server.py

@@ -0,0 +1,129 @@
+"""FastMCP server: exposes the core operations as MCP tools over stdio and HTTP/SSE.
+
+Tool bodies are thin — they call the shared ``CoreOps`` (the same layer the CLI uses, so parity
+holds). A no-map-connected / hook error / bad input is failed closed into a clean ``{"error":
+...}`` result rather than a raised exception, so an agent gets a message it can act on. HTTP/SSE
+refuses non-loopback binds (the bridge is local-only).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from fastmcp import FastMCP
+
+from .bridge import BridgeError
+from .coreops import OP_NAMES, CoreOps
+
+TOOL_NAMES = OP_NAMES
+VALID_TRANSPORTS = ("stdio", "http", "sse")
+
+
+def _guard(fn: Callable) -> Callable:
+    """Fail closed: turn a no-connection/hook/input error into a clean error result.
+
+    Matches the CLI's run_op catch set (BridgeError, ValueError, TypeError) so the two
+    frontends fail closed identically. The bridge converts transport faults (closed loop,
+    dropped socket) into BridgeError at the source, so nothing else should escape here."""
+    def wrapped(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except (BridgeError, ValueError, TypeError) as e:
+            return {"error": str(e)}
+    return wrapped
+
+
+def core_tool_handlers(ops: CoreOps) -> dict[str, Callable]:
+    """The tool implementations bound to one CoreOps — directly unit-testable."""
+    return {
+        "get_viewport": _guard(lambda: ops.get_viewport()),
+        "query_rendered_features": _guard(
+            lambda point=None, bbox=None, layers=None, limit=None:
+            ops.query_rendered_features(point, bbox, layers, limit)),
+        "get_features_at": _guard(lambda point, layers=None: ops.get_features_at(point, layers)),
+        "click_at": _guard(lambda point, layers=None: ops.click_at(point, layers)),
+        "read_popup": _guard(lambda: ops.read_popup()),
+        "set_view": _guard(lambda center=None, zoom=None, bbox=None, bearing=None, pitch=None:
+                           ops.set_view(center, zoom, bbox, bearing, pitch)),
+        "list_layers": _guard(lambda: ops.list_layers()),
+        "set_layer_visibility": _guard(lambda layer, visible: ops.set_layer_visibility(layer, visible)),
+        "screenshot": _guard(lambda: ops.screenshot()),
+    }
+
+
+def build_server(bridge: Any, app_name: str = "map-mcp"):
+    """Construct a FastMCP server exposing the core tools, bound to one bridge."""
+    mcp = FastMCP(app_name)
+    H = core_tool_handlers(CoreOps(bridge))
+
+    @mcp.tool
+    def get_viewport() -> dict:
+        """Current viewport: center [lng,lat], zoom, bearing, pitch, bounds."""
+        return H["get_viewport"]()
+
+    @mcp.tool
+    def query_rendered_features(point: Optional[list] = None, bbox: Optional[list] = None,
+                                layers: Optional[list] = None, limit: Optional[int] = None) -> dict:
+        """Features currently rendered, optionally at a [lng,lat] point or within a [[lng,lat],[lng,lat]] bbox."""
+        return H["query_rendered_features"](point=point, bbox=bbox, layers=layers, limit=limit)
+
+    @mcp.tool
+    def get_features_at(point: list, layers: Optional[list] = None) -> dict:
+        """Features rendered at a [lng,lat] point."""
+        return H["get_features_at"](point, layers)
+
+    @mcp.tool
+    def click_at(point: list, layers: Optional[list] = None) -> dict:
+        """Fire the map's click at a [lng,lat] point (runs app popup handlers) and return features + popup."""
+        return H["click_at"](point, layers)
+
+    @mcp.tool
+    def read_popup() -> dict:
+        """Text of any open map popup(s)."""
+        return H["read_popup"]()
+
+    @mcp.tool
+    def set_view(center: Optional[list] = None, zoom: Optional[float] = None,
+                 bbox: Optional[list] = None, bearing: Optional[float] = None,
+                 pitch: Optional[float] = None) -> dict:
+        """Move the map: center+zoom (and bearing/pitch), or fit a bbox. Returns the new viewport."""
+        return H["set_view"](center=center, zoom=zoom, bbox=bbox, bearing=bearing, pitch=pitch)
+
+    @mcp.tool
+    def list_layers() -> dict:
+        """The style's layers with id, type, source, and visibility."""
+        return H["list_layers"]()
+
+    @mcp.tool
+    def set_layer_visibility(layer: str, visible: bool) -> dict:
+        """Show or hide a layer by id."""
+        return H["set_layer_visibility"](layer, visible)
+
+    @mcp.tool
+    def screenshot() -> dict:
+        """A PNG data URL of the current map (needs preserveDrawingBuffer:true on the map)."""
+        return H["screenshot"]()
+
+    return mcp
+
+
+def validate_transport(transport: str) -> str:
+    if transport not in VALID_TRANSPORTS:
+        raise ValueError(f"transport must be one of {VALID_TRANSPORTS}, got {transport!r}")
+    return transport
+
+
+def run_server(bridge: Any, transport: str = "stdio", host: str = "127.0.0.1",
+               port: int = 8000) -> None:
+    """Build and run the MCP server (blocking). The bridge's ws server is started separately."""
+    validate_transport(transport)
+    if transport in ("http", "sse") and host not in ("127.0.0.1", "::1", "localhost"):
+        raise ValueError(
+            f"Refusing to serve {transport} on non-loopback host {host!r}: the map bridge is "
+            "local-only. Bind 127.0.0.1, or use stdio."
+        )
+    mcp = build_server(bridge)
+    if transport == "stdio":
+        mcp.run()
+    else:
+        mcp.run(transport=transport, host=host, port=port)

map_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: map-mcp
+Version: 0.1.0
+Summary: Drive and perceive an existing live MapLibre GL map from an AI agent (MCP) or a human CLI — no test code, no browser automation.
+Project-URL: Homepage, https://github.com/dkedar7/map-mcp
+Project-URL: Source, https://github.com/dkedar7/map-mcp
+Project-URL: Bug Tracker, https://github.com/dkedar7/map-mcp/issues
+Author: Kedar Dabhadkar
+License: MIT License
+        
+        Copyright (c) 2026 Kedar Dabhadkar
+        
+        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.
+License-File: LICENSE
+Keywords: agent,geospatial,llm,map,maplibre,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4,>=3
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# map-mcp
+
+Drive and perceive an **existing, live MapLibre GL map** from an AI agent (over MCP) or a human
+CLI — query the rendered features, read the viewport, click and read popups, navigate, toggle
+layers. The agent and the CLI act on the **same map a person is looking at**, with parity by
+construction.
+
+It does **not** generate maps. Other geo-MCP servers (gis-mcp, Mapbox, CARTO) create maps or
+call GIS operations; map-mcp reaches into a map that's *already on screen*. Think of it as the
+agent-native counterpart to [MapGrab](https://github.com/maxlapides/mapgrab): same live-map
+access, but conversational over MCP instead of written as test code.
+
+> **Status:** v1, MapLibre GL only. Cooperation-required (your app adds a one-line hook). A
+> no-cooperation path and other map libraries are future work.
+
+## Install
+
+```
+uvx map-mcp --help          # or: pip install map-mcp
+```
+
+## Quickstart
+
+1. **Start the bridge + MCP server.** It prints a WebSocket URL and a per-session token.
+   ```
+   map-mcp serve
+   ```
+2. **Add the hook to your MapLibre page** (`map` is your existing `maplibregl.Map`):
+   ```html
+   <script src="map-mcp-hook.js"></script>
+   <script>
+     mapMcp.register(map, { url: "ws://127.0.0.1:8765", token: "PASTE_TOKEN" });
+   </script>
+   ```
+3. **Point your agent at the MCP server** (stdio by default; `--transport http` for HTTP/SSE).
+   Or drive it yourself from the terminal:
+   ```
+   map-mcp call get_viewport
+   map-mcp call query_rendered_features --params '{"point":[12.5,41.9]}'
+   ```
+
+There's a runnable example in [`examples/sample_app/`](examples/sample_app/).
+
+## Tools (the operation surface)
+
+The agent's MCP tools and the CLI's `call` operations are exactly the same set:
+
+| Operation | What it does |
+|---|---|
+| `get_viewport` | center `[lng,lat]`, zoom, bearing, pitch, bounds |
+| `query_rendered_features` | features currently rendered (optionally at a point or within a bbox) |
+| `get_features_at` | features rendered at a `[lng,lat]` point |
+| `click_at` | fire the map's click at a point (runs your popup handlers), return features + popup |
+| `read_popup` | text of any open popup(s) |
+| `set_view` | center+zoom (and bearing/pitch), or fit a bbox |
+| `list_layers` | the style's layers + visibility |
+| `set_layer_visibility` | show/hide a layer |
+| `screenshot` | a PNG data URL of the current map* |
+
+Perception returns **structured feature properties** (GeoJSON-shaped) — agents reason over
+properties, not pixels. `screenshot` is optional.
+
+\* needs the map created with `preserveDrawingBuffer: true` (see [`hook/snippet.md`](hook/snippet.md)).
+
+## How it works
+
+The hook connects *out* to a loopback WebSocket the `map-mcp` process runs. The MCP tools and
+the CLI are thin frontends over one shared core-operations layer, so any operation one can do,
+the other can too.
+
+**Security model (local-only).** The bridge binds `127.0.0.1` only, so nothing off your machine
+can reach it. Browsers do *not* apply same-origin policy to WebSocket connections, so the
+**per-session token is the security boundary**: only a page that presents it can drive your map.
+Treat the token like a secret — the convenience `?token=` pattern in the example leaks it via
+browser history and server logs, so for anything sensitive paste the token into the page rather
+than the URL. A hardened Origin allowlist is future work.
+
+## Scope (v1)
+
+- **In:** MapLibre GL; the operations above; stdio + HTTP/SSE; a human CLI with parity.
+- **Out:** generating maps; a hosted service; non-map visualizations; other map libraries
+  (Leaflet/deck.gl) and a no-cooperation (Playwright) path are future work.
+
+## License
+
+MIT

map_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+map_mcp/__init__.py,sha256=ibEmgPip9FsO2DtyPz6vDwy-wGIiiovMgrrN_Z-7mdg,510
+map_mcp/bridge.py,sha256=073eNQ4ucVAeNgMJapok8VJlWEBZvI8z8DZXMEGkjk8,8355
+map_mcp/cli.py,sha256=OBSZrSGGB5w-hKkpCldHU3isPE-xR7AO4gO6IIonsOQ,5618
+map_mcp/coreops.py,sha256=7Cl7sm92FqjrnINDMN0OI9FQFkXrs46zSknVYuwZQ7Q,3938
+map_mcp/protocol.py,sha256=2hNGFUXuYPWvn9szRQCcszDVOq1_e1Ei-R1f4oAhykw,1293
+map_mcp/server.py,sha256=_27L-DxCFvzkZYf7RnHDyGrxfYsRcj3B_AZHNEifGPA,5493
+map_mcp-0.1.0.dist-info/METADATA,sha256=GJQvG7TcQjO5UGZGiY8I155hz7qz2QoBCh9IjcFW7gI,5980
+map_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+map_mcp-0.1.0.dist-info/entry_points.txt,sha256=uviG52jhZepoabiz5QZLdz3kgugXzmEyThkNp0MJklY,45
+map_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=68VkOZUTE_Q_g8vf9largzAs5-Z9lXBNy3EMH-z_Gw4,1072
+map_mcp-0.1.0.dist-info/RECORD,,

map_mcp-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

map_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+map-mcp = map_mcp.cli:_cli

map_mcp-0.1.0.dist-info/licenses/LICENSE

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