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

{ng_postcode_mcp-0.3.0 → ng_postcode_mcp-0.4.1}/.gitignore

@@ -6,3 +6,4 @@ dist/
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
+*.mcpb

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode-mcp
-Version: 0.3.0
+Version: 0.4.1
 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
@@ -95,6 +95,10 @@ Most clients take this entry in their MCP settings:
 | VS Code | The same server object in `.vscode/mcp.json`, under a top-level `"servers"` key instead of `"mcpServers"` |
 | Others | Any client that launches stdio servers: use the command, arguments and environment above |
 
+### As a bundle
+
+[`bundle/`](bundle) holds an MCPB manifest for clients that install `.mcpb` files, such as Claude Desktop. It runs the published package with uv and asks for the API key in the client's own settings. Build it with `npx @anthropic-ai/mcpb pack mcp/bundle ng-postcode.mcpb` from the repository root. [`bundle-python/`](bundle-python) is the same bundle for hosts that only run Python bundles, such as Smithery; it starts the server with `uvx`, so uv must be installed. `scripts/smithery_bundle.py` builds the copy Smithery accepts, which also carries each tool's input schema.
+
 ## Configuration
 
 | Variable | Default | Purpose |
@@ -116,10 +120,13 @@ NG_POSTCODE_TRANSPORT=http uvx ng-postcode-mcp        # http://127.0.0.1:8000/mc
 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.
+Over HTTP a caller can send its own NIPOST key in the `X-NIPOST-API-Key` header, and that key is used for that caller's requests only. A caller that sends none uses the server's key, if `NG_POSTCODE_API_KEY` is set.
+
+To host the server for other people, leave `NG_POSTCODE_API_KEY` unset so every caller brings a key, and serve it over HTTPS so the header is encrypted. Callers are trusting the host with their key, and all of them share the host's geocoder, which answers one search a second. Validation still works without any key. If you do set a server key, anyone who can reach the server spends its credits, so keep it on loopback or behind your own authentication. `NG_POSTCODE_MAX_LEVEL` caps every caller either way.
 
 ## Safety
 
+- The key is read from the environment or the `X-NIPOST-API-Key` header, never from tool arguments, and never appears in results or logs.
 - Lookups default to level 1, which is free. A model cannot spend credits unless you raise `NG_POSTCODE_MAX_LEVEL`.
 - A mistyped code is never corrected and sent to the API silently. The server returns the suggestion and asks the model to confirm it with the user.
 - Levels 2 and up return house addresses. Treat them as personal data under the Nigeria Data Protection Act.

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

@@ -67,6 +67,10 @@ Most clients take this entry in their MCP settings:
 | VS Code | The same server object in `.vscode/mcp.json`, under a top-level `"servers"` key instead of `"mcpServers"` |
 | Others | Any client that launches stdio servers: use the command, arguments and environment above |
 
+### As a bundle
+
+[`bundle/`](bundle) holds an MCPB manifest for clients that install `.mcpb` files, such as Claude Desktop. It runs the published package with uv and asks for the API key in the client's own settings. Build it with `npx @anthropic-ai/mcpb pack mcp/bundle ng-postcode.mcpb` from the repository root. [`bundle-python/`](bundle-python) is the same bundle for hosts that only run Python bundles, such as Smithery; it starts the server with `uvx`, so uv must be installed. `scripts/smithery_bundle.py` builds the copy Smithery accepts, which also carries each tool's input schema.
+
 ## Configuration
 
 | Variable | Default | Purpose |
@@ -88,10 +92,13 @@ NG_POSTCODE_TRANSPORT=http uvx ng-postcode-mcp        # http://127.0.0.1:8000/mc
 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.
+Over HTTP a caller can send its own NIPOST key in the `X-NIPOST-API-Key` header, and that key is used for that caller's requests only. A caller that sends none uses the server's key, if `NG_POSTCODE_API_KEY` is set.
+
+To host the server for other people, leave `NG_POSTCODE_API_KEY` unset so every caller brings a key, and serve it over HTTPS so the header is encrypted. Callers are trusting the host with their key, and all of them share the host's geocoder, which answers one search a second. Validation still works without any key. If you do set a server key, anyone who can reach the server spends its credits, so keep it on loopback or behind your own authentication. `NG_POSTCODE_MAX_LEVEL` caps every caller either way.
 
 ## Safety
 
+- The key is read from the environment or the `X-NIPOST-API-Key` header, never from tool arguments, and never appears in results or logs.
 - Lookups default to level 1, which is free. A model cannot spend credits unless you raise `NG_POSTCODE_MAX_LEVEL`.
 - A mistyped code is never corrected and sent to the API silently. The server returns the suggestion and asks the model to confirm it with the user.
 - Levels 2 and up return house addresses. Treat them as personal data under the Nigeria Data Protection Act.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode-mcp"
-version = "0.3.0"
+version = "0.4.1"
 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"
@@ -36,7 +36,7 @@ Repository = "https://github.com/Adeniyikayodee/ng-postcode"
 Issues = "https://github.com/Adeniyikayodee/ng-postcode/issues"
 
 [dependency-groups]
-dev = ["jsonschema>=4.20", "mypy>=1.13", "pytest>=8", "ruff>=0.8"]
+dev = ["jsonschema>=4.20", "mypy>=1.13", "pytest>=8", "ruff>=0.8", "types-jsonschema>=4.20"]
 
 # Inside the repository, build against the local packages so they never drift.
 [tool.uv.sources]

{ng_postcode_mcp-0.3.0 → ng_postcode_mcp-0.4.1}/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.3.0",
+  "version": "0.4.1",
   "repository": {
     "url": "https://github.com/Adeniyikayodee/ng-postcode",
     "source": "github",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "ng-postcode-mcp",
-      "version": "0.3.0",
+      "version": "0.4.1",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

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

@@ -4,7 +4,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. Over stdio, stdout carries the protocol, so nothing else may
-print to it. Over HTTP, every caller shares the server's key.
+print to it. Over HTTP, a caller may send its own key in the X-NIPOST-API-Key
+header; without one it uses the server's key, if the server has one.
 """
 
 from __future__ import annotations
@@ -34,12 +35,14 @@ from ng_postcode.api import (
     lookup,
     reverse,
 )
-from ng_postcode.client import AsyncClient, TransportError
+from ng_postcode.client import TIMEOUT, AsyncClient, TransportError
 from pydantic import BaseModel, ConfigDict, Field
 
 T = TypeVar("T")
 
 KEY_URL = "https://dashboard.postcode.gov.ng"
+KEY_HEADER = "x-nipost-api-key"
+MAX_KEY_LENGTH = 256
 
 INSTRUCTIONS = """\
 Tools for Nigeria's 11-character building postcode, e.g. EK-01-A03-FK-01 \
@@ -60,8 +63,8 @@ READ_ONLY_OFFLINE = ToolAnnotations(
 READ_ONLY_ONLINE = ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=True)
 
 HINTS = {
-    "auth_required": f"Set NG_POSTCODE_API_KEY to a key from {KEY_URL}.",
-    "invalid_api_key": f"NG_POSTCODE_API_KEY is invalid or revoked; create a new key at {KEY_URL}.",
+    "auth_required": f"Supply a NIPOST API key from {KEY_URL}.",
+    "invalid_api_key": f"The NIPOST API key is invalid or revoked; create a new key at {KEY_URL}.",
     "insufficient_credits": "The NIPOST account is out of credits; top up or use level 1.",
     "level_not_granted": "The key is not granted this lookup level; use a lower level or "
     f"request more access at {KEY_URL}.",
@@ -201,8 +204,11 @@ class Location(FromLibrary):
 
 @dataclass(frozen=True, slots=True)
 class State:
-    """What the tools share for the life of the server. Either part may be unconfigured."""
+    """What the tools share for the life of the server. `nipost` and `geocoder` may be
+    unconfigured."""
 
+    http: httpx.AsyncClient
+    base_url: str
     nipost: AsyncClient | None
     geocoder: Nominatim | None
 
@@ -217,17 +223,18 @@ def create_server(
 
     @asynccontextmanager
     async def lifespan(_: MCPServer[State]) -> AsyncIterator[State]:
+        shared = http if http is not None else httpx.AsyncClient(timeout=TIMEOUT)
         nipost = (
-            AsyncClient(settings.api_key, base_url=settings.base_url, http=http)
+            AsyncClient(settings.api_key, base_url=settings.base_url, http=shared)
             if settings.api_key
             else None
         )
         geocoder = geocoder_for(settings, geocoder_http)
         try:
-            yield State(nipost, geocoder)
+            yield State(shared, settings.base_url, nipost, geocoder)
         finally:
-            if nipost:
-                await nipost.aclose()
+            if http is None:
+                await shared.aclose()
             if geocoder:
                 await geocoder.aclose()
 
@@ -304,8 +311,12 @@ def create_server(
         structured_output=True,
     )
     async def find_postcode_at_location(
-        latitude: Annotated[float, Field(ge=-90, le=90)],
-        longitude: Annotated[float, Field(ge=-180, le=180)],
+        latitude: Annotated[
+            float, Field(ge=-90, le=90, description="Latitude in decimal degrees, e.g. 7.6211.")
+        ],
+        longitude: Annotated[
+            float, Field(ge=-180, le=180, description="Longitude in decimal degrees, e.g. 5.2214.")
+        ],
         ctx: Context[State, Any],
         max_distance_m: Annotated[
             float | None,
@@ -346,9 +357,13 @@ def create_server(
             ),
         ] = None,
         latitude: Annotated[
-            float | None, Field(ge=-90, le=90, description="A location pin the user shared.")
+            float | None,
+            Field(ge=-90, le=90, description="Latitude of a location pin the user shared."),
+        ] = None,
+        longitude: Annotated[
+            float | None,
+            Field(ge=-180, le=180, description="Longitude of that pin. Give it with latitude."),
         ] = None,
-        longitude: Annotated[float | None, Field(ge=-180, le=180)] = None,
     ) -> Resolution:
         """Turn a described Nigerian address into a postcode, only as precisely as the
         evidence allows.
@@ -366,8 +381,8 @@ def create_server(
             if latitude is not None and longitude is not None
             else None
         )
-        state = ctx.request_context.lifespan_context
-        resolver = Resolver(nipost=state.nipost, geocoder=state.geocoder)
+        geocoder = ctx.request_context.lifespan_context.geocoder
+        resolver = Resolver(nipost=nipost_for(ctx), geocoder=geocoder)
         return await resolver.resolve(address, location, reading(landmarks, geocode_queries))
 
     return server
@@ -461,10 +476,25 @@ def checked(text: str) -> Postcode:
             raise ToolError(f"{text!r} is not a valid postcode: {error}.{maybe}")
 
 
+def nipost_for(ctx: Context[State, Any]) -> AsyncClient | None:
+    """The caller's own client when an HTTP request carries a key, else the server's."""
+    state = ctx.request_context.lifespan_context
+    sent = (v for k, v in (ctx.headers or {}).items() if k.lower() == KEY_HEADER)
+    key = next(sent, "").strip()
+    if not key:
+        return state.nipost
+    if not (key.isascii() and key.isprintable() and " " not in key and len(key) <= MAX_KEY_LENGTH):
+        raise ToolError("The X-NIPOST-API-Key header does not hold a usable NIPOST API key.")
+    return AsyncClient(key, base_url=state.base_url, http=state.http)
+
+
 def api(ctx: Context[State, Any]) -> AsyncClient:
-    client = ctx.request_context.lifespan_context.nipost
+    client = nipost_for(ctx)
     if client is None:
-        raise ToolError(f"This tool needs NG_POSTCODE_API_KEY. {HINTS['auth_required']}")
+        raise ToolError(
+            "This tool needs a NIPOST API key: set NG_POSTCODE_API_KEY on the server, or over "
+            f"HTTP send your own in the X-NIPOST-API-Key header. Get one at {KEY_URL}."
+        )
     return client
 
 

ng_postcode_mcp-0.4.1/tests/test_caller_key.py

@@ -0,0 +1,94 @@
+"""A caller's own NIPOST key over HTTP, against an in-process server with NIPOST mocked."""
+
+from __future__ import annotations
+
+import socket
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import httpx
+import httpx2
+import pytest
+import uvicorn
+from mcp import Client
+from mcp.client.streamable_http import streamable_http_client
+from mcp.types import CallToolResult
+
+from ng_postcode_mcp import Settings, create_server
+
+LOOKUP = {"postcode": "EK-01-A03-FK-01"}
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+@contextmanager
+def serving(server_key: str | None, keys_seen: list[str]) -> Iterator[str]:
+    """Run the server over HTTP on a loopback port; yields its URL."""
+
+    def nipost(request: httpx.Request) -> httpx.Response:
+        keys_seen.append(request.headers["X-API-Key"])
+        return httpx.Response(200, json={"data": {"postcode": "EK-01-A03-FK-01", "valid": True}})
+
+    upstream = httpx.AsyncClient(transport=httpx.MockTransport(nipost))
+    app = create_server(Settings(api_key=server_key), http=upstream).streamable_http_app()
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        port = int(probe.getsockname()[1])
+    server = uvicorn.Server(uvicorn.Config(app, host="127.0.0.1", port=port, log_level="error"))
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+    deadline = time.monotonic() + 20
+    while not server.started and time.monotonic() < deadline:
+        time.sleep(0.05)
+    try:
+        yield f"http://127.0.0.1:{port}/mcp"
+    finally:
+        server.should_exit = True
+        thread.join(timeout=10)
+
+
+async def lookup(url: str, caller_key: str | bytes | None) -> CallToolResult:
+    sent = caller_key.encode() if isinstance(caller_key, str) else caller_key
+    headers = {b"X-NIPOST-API-Key": sent} if sent else {}
+    async with (
+        httpx2.AsyncClient(headers=headers) as http,
+        Client(streamable_http_client(url, http_client=http)) as client,
+    ):
+        return await client.call_tool("lookup_postcode", LOOKUP)
+
+
+@pytest.mark.anyio
+async def test_a_callers_key_is_used_for_its_own_requests() -> None:
+    seen: list[str] = []
+    with serving(None, seen) as url:
+        own = await lookup(url, "caller-key")
+        none = await lookup(url, None)
+    assert not own.is_error
+    assert seen == ["caller-key"]
+    assert none.is_error
+    assert "X-NIPOST-API-Key" in str(none.content)
+
+
+@pytest.mark.anyio
+async def test_the_servers_key_is_the_fallback() -> None:
+    seen: list[str] = []
+    with serving("server-key", seen) as url:
+        await lookup(url, None)
+        await lookup(url, "caller-key")
+    assert seen == ["server-key", "caller-key"]
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("key", ["k\xe9y".encode("latin-1"), b"two words", b"k" * 300])
+async def test_an_unusable_key_is_refused_before_nipost(key: bytes) -> None:
+    seen: list[str] = []
+    with serving("server-key", seen) as url:
+        result = await lookup(url, key)
+    assert result.is_error
+    assert "does not hold a usable" in str(result.content)
+    assert seen == []

{ng_postcode_mcp-0.3.0 → ng_postcode_mcp-0.4.1}/tests/test_metadata.py

@@ -29,3 +29,23 @@ def test_readme_proves_registry_ownership() -> None:
 
 def test_registry_description_fits() -> None:
     assert len(server_json()["description"]) <= 100
+
+
+def test_the_bundle_pins_this_version() -> None:
+    bundle = ROOT / "bundle"
+    if not bundle.exists():  # the bundle lives in the repository, not the sdist
+        return
+    released = version("ng-postcode-mcp")
+    manifest: dict[str, Any] = json.loads((bundle / "manifest.json").read_text(encoding="utf-8"))
+    assert manifest["version"] == released
+    assert f'"ng-postcode-mcp=={released}"' in (bundle / "pyproject.toml").read_text()
+
+
+def test_the_python_bundle_pins_this_version() -> None:
+    bundle = ROOT / "bundle-python"
+    if not bundle.exists():  # the bundle lives in the repository, not the sdist
+        return
+    released = version("ng-postcode-mcp")
+    manifest: dict[str, Any] = json.loads((bundle / "manifest.json").read_text(encoding="utf-8"))
+    assert manifest["version"] == released
+    assert f'"ng-postcode-mcp=={released}"' in (bundle / "server" / "main.py").read_text()

ng_postcode_mcp-0.4.1/tests/test_reference_schema.py

@@ -0,0 +1,74 @@
+"""The shared postcode reference schema, and that resolve_address answers fit it."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+from jsonschema import Draft202012Validator
+from ng_address.models import Resolution
+from ng_postcode import Postcode, Segment
+
+SCHEMA_FILE = Path(__file__).resolve().parents[2] / "docs/schemas/postcode-reference.schema.json"
+
+pytestmark = pytest.mark.skipif(
+    not SCHEMA_FILE.exists(), reason="the schema lives in the repository, not the sdist"
+)
+
+
+def loaded() -> dict[str, Any]:
+    document: dict[str, Any] = json.loads(SCHEMA_FILE.read_text(encoding="utf-8"))
+    return document
+
+
+@pytest.fixture(scope="module")
+def schema() -> Draft202012Validator:
+    Draft202012Validator.check_schema(loaded())
+    return Draft202012Validator(loaded())
+
+
+def test_its_own_examples_are_valid(schema: Draft202012Validator) -> None:
+    for example in loaded()["examples"]:
+        schema.validate(example)
+
+
+@pytest.mark.parametrize(
+    "reference",
+    [
+        {"code": "EK-01-A03-FK-01"},
+        {"code": "EK-01-A03-FK-01", "level": "area"},
+        {"code": "EK-01-A03-FK", "level": "building"},
+        {"code": "EK01A03FK01", "level": "building"},
+        {"code": "ek-01-a03-fk-01", "level": "building"},
+        {"code": "EK-00", "level": "lga"},
+        {"code": "EK-01", "level": "street"},
+        {"code": "EK-01", "level": "lga", "confidence": "certain"},
+    ],
+)
+def test_rejects_malformed_references(
+    schema: Draft202012Validator, reference: dict[str, str]
+) -> None:
+    assert not schema.is_valid(reference)
+
+
+def test_every_prefix_of_a_code_fits_its_level(schema: Draft202012Validator) -> None:
+    code = Postcode("EK01A03FK01")
+    levels = {"state": Segment.STATE, "lga": Segment.LGA, "district": Segment.DISTRICT}
+    levels |= {"area": Segment.AREA, "building": Segment.UNIT}
+    for level, segment in levels.items():
+        schema.validate({"code": code.prefix(segment), "level": level})
+
+
+def test_a_resolution_is_a_reference(schema: Draft202012Validator) -> None:
+    answer = Resolution(
+        status="partial",
+        code="EK-01-A03-FK",
+        level="area",
+        confidence="medium",
+        method="geocoded",
+        question="Which building is it?",
+        evidence=[],
+    )
+    schema.validate(answer.model_dump())

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

@@ -161,7 +161,7 @@ async def test_lookup_never_autocorrects_before_spending() -> None:
 async def test_online_tools_explain_a_missing_or_rejected_key() -> None:
     missing = await call("lookup_postcode", {"postcode": "EK-01-A03-FK-01"}, key=None)
     assert missing.is_error
-    assert "needs NG_POSTCODE_API_KEY" in text(missing)
+    assert "needs a NIPOST API key" in text(missing)
 
     secret = "nipost_test_never_echo_me"
     rejected = await call("lookup_postcode", {"postcode": "EK-01-A03-FK-01"}, key=secret)