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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode-mcp
-Version: 0.2.4
+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
@@ -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.4 → 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.4 → ng_postcode_mcp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode-mcp"
-version = "0.2.4"
+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"

{ng_postcode_mcp-0.2.4 → 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.4",
+  "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.4",
+      "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.4 → 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
@@ -79,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:
@@ -90,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),
     )
 
 
@@ -470,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.4 → ng_postcode_mcp-0.3.0}/tests/test_tools.py

@@ -224,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"}) == (