ng-postcode-mcp 0.2.3__tar.gz → 0.3.0__tar.gz

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode-mcp
-Version: 0.2.3
+Version: 0.3.0
 Summary: MCP server for Nigeria's NIPOST digital postcode (NDAPS): validate, look up, reverse-geocode and resolve addresses to postcodes.
 Project-URL: Repository, https://github.com/Adeniyikayodee/ng-postcode
 Project-URL: Issues, https://github.com/Adeniyikayodee/ng-postcode/issues
@@ -22,7 +22,7 @@ Classifier: Topic :: Scientific/Engineering :: GIS
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: mcp<3,>=2.3
-Requires-Dist: ng-address-resolver<0.2,>=0.1.3
+Requires-Dist: ng-address-resolver<0.2,>=0.1.4
 Requires-Dist: ng-postcode[client]<0.3,>=0.2.1
 Description-Content-Type: text/markdown
 
@@ -104,9 +104,20 @@ Most clients take this entry in their MCP settings:
 | `NG_POSTCODE_BASE_URL` | `https://api.postcode.gov.ng` | Alternative API host, such as a staging stack. |
 | `NG_GEOCODER_URL` | none | A Nominatim server `resolve_address` uses to place described addresses. Without it, only typed postcodes and location pins resolve. |
 | `NG_GEOCODER_CONTACT` | none | A URL or email sent in the User-Agent. Required for the public Nominatim. |
+| `NG_POSTCODE_TRANSPORT` | `stdio` | `http` serves streamable HTTP at `/mcp` instead. |
+| `NG_POSTCODE_HOST`, `NG_POSTCODE_PORT` | `127.0.0.1`, `8000` | Where the HTTP transport listens. |
 
 The public Nominatim at `https://nominatim.openstreetmap.org` allows light personal use only; a service whose main job is geocoding must run its own instance. Map data © OpenStreetMap contributors.
 
+## HTTP and Docker
+
+```sh
+NG_POSTCODE_TRANSPORT=http uvx ng-postcode-mcp        # http://127.0.0.1:8000/mcp
+docker build -t ng-postcode-mcp . && docker run --rm -i ng-postcode-mcp   # from the repository root
+```
+
+Over HTTP every caller uses the server's own NIPOST key and credits, and the server adds no authentication. It listens on loopback by default; put it behind your own authentication before setting `NG_POSTCODE_HOST` to a public address.
+
 ## Safety
 
 - Lookups default to level 1, which is free. A model cannot spend credits unless you raise `NG_POSTCODE_MAX_LEVEL`.

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/README.md

@@ -76,9 +76,20 @@ Most clients take this entry in their MCP settings:
 | `NG_POSTCODE_BASE_URL` | `https://api.postcode.gov.ng` | Alternative API host, such as a staging stack. |
 | `NG_GEOCODER_URL` | none | A Nominatim server `resolve_address` uses to place described addresses. Without it, only typed postcodes and location pins resolve. |
 | `NG_GEOCODER_CONTACT` | none | A URL or email sent in the User-Agent. Required for the public Nominatim. |
+| `NG_POSTCODE_TRANSPORT` | `stdio` | `http` serves streamable HTTP at `/mcp` instead. |
+| `NG_POSTCODE_HOST`, `NG_POSTCODE_PORT` | `127.0.0.1`, `8000` | Where the HTTP transport listens. |
 
 The public Nominatim at `https://nominatim.openstreetmap.org` allows light personal use only; a service whose main job is geocoding must run its own instance. Map data © OpenStreetMap contributors.
 
+## HTTP and Docker
+
+```sh
+NG_POSTCODE_TRANSPORT=http uvx ng-postcode-mcp        # http://127.0.0.1:8000/mcp
+docker build -t ng-postcode-mcp . && docker run --rm -i ng-postcode-mcp   # from the repository root
+```
+
+Over HTTP every caller uses the server's own NIPOST key and credits, and the server adds no authentication. It listens on loopback by default; put it behind your own authentication before setting `NG_POSTCODE_HOST` to a public address.
+
 ## Safety
 
 - Lookups default to level 1, which is free. A model cannot spend credits unless you raise `NG_POSTCODE_MAX_LEVEL`.

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode-mcp"
-version = "0.2.3"
+version = "0.3.0"
 description = "MCP server for Nigeria's NIPOST digital postcode (NDAPS): validate, look up, reverse-geocode and resolve addresses to postcodes."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: GIS",
     "Typing :: Typed",
 ]
-dependencies = ["mcp>=2.3,<3", "ng-address-resolver>=0.1.3,<0.2", "ng-postcode[client]>=0.2.1,<0.3"]
+dependencies = ["mcp>=2.3,<3", "ng-address-resolver>=0.1.4,<0.2", "ng-postcode[client]>=0.2.1,<0.3"]
 
 [project.scripts]
 ng-postcode-mcp = "ng_postcode_mcp.server:main"

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Adeniyikayodee/ng-postcode",
   "title": "Nigeria Postcode",
   "description": "Validate, look up and resolve addresses to Nigeria's NIPOST digital postcodes (NDAPS).",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "repository": {
     "url": "https://github.com/Adeniyikayodee/ng-postcode",
     "source": "github",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "ng-postcode-mcp",
-      "version": "0.2.3",
+      "version": "0.3.0",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"
@@ -44,6 +44,15 @@
         {
           "name": "NG_GEOCODER_CONTACT",
           "description": "URL or email identifying you to the geocoder. Required for the public Nominatim."
+        },
+        {
+          "name": "NG_POSTCODE_TRANSPORT",
+          "description": "stdio (default), or http to serve streamable HTTP at /mcp on NG_POSTCODE_HOST and NG_POSTCODE_PORT.",
+          "default": "stdio",
+          "choices": [
+            "stdio",
+            "http"
+          ]
         }
       ]
     }

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/src/ng_postcode_mcp/server.py

@@ -3,7 +3,8 @@
 Validation runs offline. Lookup, autocomplete and reverse geocoding call the
 postcode.gov.ng API with the key in NG_POSTCODE_API_KEY, which never appears in
 tool arguments or results. Address resolution also searches the geocoder in
-NG_GEOCODER_URL. stdout carries the protocol, so nothing else may print to it.
+NG_GEOCODER_URL. Over stdio, stdout carries the protocol, so nothing else may
+print to it. Over HTTP, every caller shares the server's key.
 """
 
 from __future__ import annotations
@@ -65,6 +66,7 @@ HINTS = {
     "level_not_granted": "The key is not granted this lookup level; use a lower level or "
     f"request more access at {KEY_URL}.",
 }
+LEVEL_2_FIELDS = ("state_name", "lga_name", "locality_name", "address")
 STATUS_HINTS = {
     403: "The key lacks the scope or access level for this request.",
     429: "NIPOST rate limit reached; wait before retrying.",
@@ -78,6 +80,9 @@ class Settings:
     base_url: str = BASE_URL
     geocoder_url: str | None = None
     geocoder_contact: str | None = None
+    transport: Literal["stdio", "http"] = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8000
 
 
 def settings_from_env(env: Mapping[str, str]) -> Settings | str:
@@ -89,12 +94,21 @@ def settings_from_env(env: Mapping[str, str]) -> Settings | str:
     geocoder_contact = env.get("NG_GEOCODER_CONTACT", "").strip() or None
     if geocoder_url == PUBLIC_NOMINATIM and geocoder_contact is None:
         return "the public Nominatim requires NG_GEOCODER_CONTACT, a URL or email identifying you"
+    transport = env.get("NG_POSTCODE_TRANSPORT", "stdio").strip().lower()
+    if transport not in ("stdio", "http"):
+        return f"NG_POSTCODE_TRANSPORT must be stdio or http, got {transport!r}"
+    raw_port = env.get("NG_POSTCODE_PORT", "8000").strip()
+    if not (raw_port.isdecimal() and 0 < int(raw_port) < 65536):
+        return f"NG_POSTCODE_PORT must be 1 to 65535, got {raw_port!r}"
     return Settings(
         api_key=env.get("NG_POSTCODE_API_KEY", "").strip() or None,
         max_level=int(raw_level),
         base_url=env.get("NG_POSTCODE_BASE_URL", "").strip() or BASE_URL,
         geocoder_url=geocoder_url,
         geocoder_contact=geocoder_contact,
+        transport="http" if transport == "http" else "stdio",
+        host=env.get("NG_POSTCODE_HOST", "").strip() or "127.0.0.1",
+        port=int(raw_port),
     )
 
 
@@ -298,11 +312,14 @@ def create_server(
             Field(ge=0, le=250, description="Search radius in metres. Defaults to 25."),
         ] = None,
     ) -> Location:
-        """Return the postcode of the nearest building to a coordinate in Nigeria."""
+        """Return the postcode of the nearest building to a coordinate in Nigeria.
+
+        Names and the house address are withheld unless NG_POSTCODE_MAX_LEVEL is 2 or more.
+        """
         result = await api(ctx).send(
             reverse(Coordinate(lat=latitude, lng=longitude), max_distance_m)
         )
-        return Location.model_validate(unwrap(result))
+        return capped(Location.model_validate(unwrap(result)), settings.max_level)
 
     @server.tool(
         title="Resolve a Nigerian address to a postcode",
@@ -383,6 +400,14 @@ def geocoder_for(settings: Settings, http: httpx.AsyncClient | None) -> Nominati
     )
 
 
+def capped(location: Location, max_level: int) -> Location:
+    """The location without the fields a level 2 key adds, unless the cap allows them."""
+    if max_level >= 2 or location.unit is None:
+        return location
+    unit = location.unit.model_copy(update=dict.fromkeys(LEVEL_2_FIELDS))
+    return location.model_copy(update={"unit": unit})
+
+
 def completions(found: Autocomplete) -> Completions:
     return Completions(
         segment=None if found.segment is None else found.segment.value,
@@ -458,4 +483,8 @@ def main() -> None:
         sys.exit(f"ng-postcode-mcp: {settings}")
     # httpx logs every request URL at INFO, which would copy postcodes into client logs.
     logging.getLogger("httpx").setLevel(logging.WARNING)
-    create_server(settings).run()
+    server = create_server(settings)
+    if settings.transport == "http":
+        server.run("streamable-http", host=settings.host, port=settings.port)
+    else:
+        server.run()

ng_postcode_mcp-0.3.0/tests/test_http.py

@@ -0,0 +1,49 @@
+"""The real entry point over HTTP, on a loopback port."""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+
+import pytest
+from mcp import Client
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+def free_port() -> int:
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        return int(probe.getsockname()[1])
+
+
+def wait_until_listening(port: int, seconds: float = 20.0) -> None:
+    deadline = time.monotonic() + seconds
+    while time.monotonic() < deadline:
+        with socket.socket() as probe:
+            if probe.connect_ex(("127.0.0.1", port)) == 0:
+                return
+        time.sleep(0.1)
+    raise TimeoutError(f"nothing listening on port {port}")
+
+
+@pytest.mark.anyio
+async def test_serves_over_http() -> None:
+    port = free_port()
+    env = {k: v for k, v in os.environ.items() if not k.startswith("NG_POSTCODE_")}
+    env |= {"NG_POSTCODE_TRANSPORT": "http", "NG_POSTCODE_PORT": str(port)}
+    server = subprocess.Popen([sys.executable, "-m", "ng_postcode_mcp"], env=env)
+    try:
+        wait_until_listening(port)
+        async with Client(f"http://127.0.0.1:{port}/mcp") as client:
+            result = await client.call_tool("validate_postcode", {"postcode": "LA11W06TC10"})
+    finally:
+        server.terminate()
+        server.wait(timeout=10)
+    assert result.structured_content["postcode"] == "LA-11-W06-TC-10"

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/tests/test_resolve_tool.py

@@ -61,6 +61,13 @@ async def call(
     return result
 
 
+@pytest.mark.anyio
+async def test_queries_without_landmarks_never_give_a_building() -> None:
+    queries = {k: v for k, v in BEHIND_FABIAN.items() if k != "landmarks"}
+    answer = (await call(queries)).structured_content
+    assert (answer["status"], answer["level"]) == ("partial", "area")
+
+
 @pytest.mark.anyio
 async def test_the_host_models_reading_drives_the_answer() -> None:
     searched: list[httpx.Request] = []

{ng_postcode_mcp-0.2.3 → ng_postcode_mcp-0.3.0}/tests/test_tools.py

@@ -22,6 +22,7 @@ from ng_postcode_mcp.server import (
     Location,
     NearestBuilding,
     PostcodeDetails,
+    capped,
     unwrap,
 )
 
@@ -181,6 +182,26 @@ async def test_autocomplete_and_reverse() -> None:
     assert (near.structured_content["found"], near.structured_content["radius_m"]) == (False, 25.0)
 
 
+def test_the_level_cap_withholds_names_and_addresses() -> None:
+    unit = NearestBuilding(
+        postcode="EK-01-A03-FK-01",
+        display="EK 01 A03 FK 01",
+        distance_m=8.0,
+        confidence="high",
+        state_name="EKITI",
+        lga_name="ADO EKITI",
+        locality_name="ADO EKITI",
+        address="NTA ROAD",
+    )
+    found = Location(
+        found=True, unit=unit, area=None, district=None, state=None, message=None, radius_m=25.0
+    )
+    assert capped(found, 2) == found
+    held = capped(found, 1).unit
+    assert held is not None
+    assert (held.postcode, held.address, held.state_name) == ("EK-01-A03-FK-01", None, None)
+
+
 @pytest.mark.anyio
 async def test_rejects_out_of_range_arguments() -> None:
     result = await call("find_postcode_at_location", {"latitude": 95, "longitude": 5.22})
@@ -203,6 +224,14 @@ def test_output_models_only_use_fields_the_library_has(
     assert set(model.model_fields) <= {field.name for field in dataclasses.fields(source)}
 
 
+def test_transport_settings() -> None:
+    served = settings_from_env({"NG_POSTCODE_TRANSPORT": "HTTP", "NG_POSTCODE_PORT": "9000"})
+    assert isinstance(served, Settings)
+    assert (served.transport, served.host, served.port) == ("http", "127.0.0.1", 9000)
+    assert isinstance(settings_from_env({"NG_POSTCODE_TRANSPORT": "sse"}), str)
+    assert isinstance(settings_from_env({"NG_POSTCODE_PORT": "0"}), str)
+
+
 def test_settings_from_env() -> None:
     assert settings_from_env({}) == Settings(api_key=None)
     assert settings_from_env({"NG_POSTCODE_API_KEY": " k ", "NG_POSTCODE_MAX_LEVEL": "3"}) == (