ng-postcode-mcp 0.1.0__tar.gz → 0.2.1__tar.gz

ng_postcode_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: ng-postcode-mcp
+Version: 0.2.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
+Author: Kayode Adeniyi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,geocoding,mcp,mcp-server,model-context-protocol,ndaps,nigeria,nipost,postcode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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
+Requires-Dist: ng-postcode[client]<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# ng-postcode-mcp
+
+MCP server for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. It lets AI assistants validate postcodes offline, look them up, autocomplete them and find them by location through the [postcode.gov.ng](https://docs.postcode.gov.ng) API, and resolve described addresses to postcodes.
+
+Built on the [`ng-postcode`](https://pypi.org/project/ng-postcode/) and [`ng-address-resolver`](https://pypi.org/project/ng-address-resolver/) libraries.
+
+<!-- mcp-name: io.github.Adeniyikayodee/ng-postcode -->
+
+## Tools
+
+| Tool | What it does | Needs a key | Cost |
+| --- | --- | --- | --- |
+| `validate_postcode` | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free |
+| `lookup_postcode` | Confirms a code is assigned; level 2 adds the address, level 3 building use | Yes | Level 1 free, 2+ uses credits |
+| `autocomplete_postcode` | Suggests the next segment of a partly typed code | Yes | Free tier |
+| `find_postcode_at_location` | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |
+| `resolve_address` | Turns a described address ("back of Fabian Hotel, off NTA Road") or a location pin into a postcode, only as precisely as the evidence allows | Yes, plus a geocoder for text | Free tier |
+
+All tools are read-only. Errors come back as messages the model can act on, such as a missing key or an exhausted credit balance.
+
+### How `resolve_address` answers
+
+The assistant reads the address and passes its landmarks and map searches to the tool; the server makes no model calls of its own. The answer is never more precise than its evidence:
+
+| Evidence | Answer |
+| --- | --- |
+| A postcode written in the address, or a location pin on a building | Building code |
+| A landmark the address *is* | Building code, medium confidence |
+| A building near a landmark ("behind", "opposite") | Area code, plus a question for the user |
+| A street only | District code, low confidence |
+| A town only, or nothing found | No code, plus a question |
+
+Text alone rarely identifies a building, so ask users for a location pin when the exact building matters. This tool is pre-release: its NIPOST steps have not yet been run against the live API.
+
+## Install
+
+Works with any MCP client. The server runs over stdio:
+
+| Setting | Value |
+| --- | --- |
+| Command | `uvx` |
+| Arguments | `ng-postcode-mcp` |
+| Environment | `NG_POSTCODE_API_KEY` (optional for `validate_postcode`) |
+
+It needs [uv](https://docs.astral.sh/uv/) installed. Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng).
+
+Most clients take this entry in their MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ng-postcode": {
+      "command": "uvx",
+      "args": ["ng-postcode-mcp"],
+      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
+    }
+  }
+}
+```
+
+| Client | How to add it |
+| --- | --- |
+| Claude Code | `claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp` |
+| Claude Desktop | The entry above, in its MCP server settings |
+| Codex | `codex mcp add ng-postcode --env NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp` |
+| Cursor | The entry above, in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
+| 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 |
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `NG_POSTCODE_API_KEY` | none | NIPOST API key. Read from the environment only; never passed through tools. |
+| `NG_POSTCODE_MAX_LEVEL` | `1` | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. |
+| `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. |
+
+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.
+
+## Safety
+
+- 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.
+- `resolve_address` sends the search strings to the geocoder you configure. With a third-party geocoder, that shares address text with it.
+
+## License
+
+MIT

ng_postcode_mcp-0.2.1/README.md

@@ -0,0 +1,91 @@
+# ng-postcode-mcp
+
+MCP server for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. It lets AI assistants validate postcodes offline, look them up, autocomplete them and find them by location through the [postcode.gov.ng](https://docs.postcode.gov.ng) API, and resolve described addresses to postcodes.
+
+Built on the [`ng-postcode`](https://pypi.org/project/ng-postcode/) and [`ng-address-resolver`](https://pypi.org/project/ng-address-resolver/) libraries.
+
+<!-- mcp-name: io.github.Adeniyikayodee/ng-postcode -->
+
+## Tools
+
+| Tool | What it does | Needs a key | Cost |
+| --- | --- | --- | --- |
+| `validate_postcode` | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free |
+| `lookup_postcode` | Confirms a code is assigned; level 2 adds the address, level 3 building use | Yes | Level 1 free, 2+ uses credits |
+| `autocomplete_postcode` | Suggests the next segment of a partly typed code | Yes | Free tier |
+| `find_postcode_at_location` | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |
+| `resolve_address` | Turns a described address ("back of Fabian Hotel, off NTA Road") or a location pin into a postcode, only as precisely as the evidence allows | Yes, plus a geocoder for text | Free tier |
+
+All tools are read-only. Errors come back as messages the model can act on, such as a missing key or an exhausted credit balance.
+
+### How `resolve_address` answers
+
+The assistant reads the address and passes its landmarks and map searches to the tool; the server makes no model calls of its own. The answer is never more precise than its evidence:
+
+| Evidence | Answer |
+| --- | --- |
+| A postcode written in the address, or a location pin on a building | Building code |
+| A landmark the address *is* | Building code, medium confidence |
+| A building near a landmark ("behind", "opposite") | Area code, plus a question for the user |
+| A street only | District code, low confidence |
+| A town only, or nothing found | No code, plus a question |
+
+Text alone rarely identifies a building, so ask users for a location pin when the exact building matters. This tool is pre-release: its NIPOST steps have not yet been run against the live API.
+
+## Install
+
+Works with any MCP client. The server runs over stdio:
+
+| Setting | Value |
+| --- | --- |
+| Command | `uvx` |
+| Arguments | `ng-postcode-mcp` |
+| Environment | `NG_POSTCODE_API_KEY` (optional for `validate_postcode`) |
+
+It needs [uv](https://docs.astral.sh/uv/) installed. Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng).
+
+Most clients take this entry in their MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ng-postcode": {
+      "command": "uvx",
+      "args": ["ng-postcode-mcp"],
+      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
+    }
+  }
+}
+```
+
+| Client | How to add it |
+| --- | --- |
+| Claude Code | `claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp` |
+| Claude Desktop | The entry above, in its MCP server settings |
+| Codex | `codex mcp add ng-postcode --env NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp` |
+| Cursor | The entry above, in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
+| 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 |
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `NG_POSTCODE_API_KEY` | none | NIPOST API key. Read from the environment only; never passed through tools. |
+| `NG_POSTCODE_MAX_LEVEL` | `1` | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. |
+| `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. |
+
+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.
+
+## Safety
+
+- 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.
+- `resolve_address` sends the search strings to the geocoder you configure. With a third-party geocoder, that shares address text with it.
+
+## License
+
+MIT

{ng_postcode_mcp-0.1.0 → ng_postcode_mcp-0.2.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode-mcp"
-version = "0.1.0"
-description = "MCP server for Nigeria's NIPOST digital postcode (NDAPS): validate, look up and reverse-geocode postcodes."
+version = "0.2.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"
 license = "MIT"
@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: GIS",
     "Typing :: Typed",
 ]
-dependencies = ["mcp>=2.3,<3", "ng-postcode[client]>=0.1,<0.2"]
+dependencies = ["mcp>=2.3,<3", "ng-address-resolver>=0.1,<0.2", "ng-postcode[client]>=0.1,<0.2"]
 
 [project.scripts]
 ng-postcode-mcp = "ng_postcode_mcp.server:main"
@@ -38,8 +38,9 @@ Issues = "https://github.com/Adeniyikayodee/ng-postcode/issues"
 [dependency-groups]
 dev = ["jsonschema>=4.20", "mypy>=1.13", "pytest>=8", "ruff>=0.8"]
 
-# Inside the repository, build against the local library so the two never drift.
+# Inside the repository, build against the local packages so they never drift.
 [tool.uv.sources]
+ng-address-resolver = { path = "../agent", editable = true }
 ng-postcode = { path = "../python", editable = true }
 
 [tool.hatch.build.targets.sdist]

{ng_postcode_mcp-0.1.0 → ng_postcode_mcp-0.2.1}/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.Adeniyikayodee/ng-postcode",
   "title": "Nigeria Postcode",
-  "description": "Validate, look up and reverse-geocode Nigeria's NIPOST digital postcodes (NDAPS).",
-  "version": "0.1.0",
+  "description": "Validate, look up and resolve addresses to Nigeria's NIPOST digital postcodes (NDAPS).",
+  "version": "0.2.1",
   "repository": {
     "url": "https://github.com/Adeniyikayodee/ng-postcode",
     "source": "github",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "ng-postcode-mcp",
-      "version": "0.1.0",
+      "version": "0.2.1",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"
@@ -29,7 +29,21 @@
           "name": "NG_POSTCODE_MAX_LEVEL",
           "description": "Highest lookup level tools may request. Levels 2 and up consume NIPOST credits.",
           "default": "1",
-          "choices": ["1", "2", "3", "4", "5"]
+          "choices": [
+            "1",
+            "2",
+            "3",
+            "4",
+            "5"
+          ]
+        },
+        {
+          "name": "NG_GEOCODER_URL",
+          "description": "Nominatim server used by resolve_address to place described addresses. Ideally your own instance."
+        },
+        {
+          "name": "NG_GEOCODER_CONTACT",
+          "description": "URL or email identifying you to the geocoder. Required for the public Nominatim."
         }
       ]
     }

{ng_postcode_mcp-0.1.0 → ng_postcode_mcp-0.2.1}/src/ng_postcode_mcp/server.py

@@ -2,8 +2,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. stdout carries the protocol, so nothing else may
-print to it.
+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.
 """
 
 from __future__ import annotations
@@ -21,6 +21,8 @@ import httpx
 from mcp.server.mcpserver import Context, MCPServer
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.types import ToolAnnotations
+from ng_address import Landmark, Nominatim, ParsedAddress, Resolution, Resolver
+from ng_address.geocode import PUBLIC_NOMINATIM
 from ng_postcode import Corrected, Postcode, parse, parse_lenient
 from ng_postcode.api import (
     BASE_URL,
@@ -45,6 +47,9 @@ Tools for Nigeria's 11-character building postcode, e.g. EK-01-A03-FK-01 \
 - lookup_postcode level 1 only confirms a code exists. Levels 2 and up add the \
 address and building details, consume NIPOST credits, and are capped by the \
 server's NG_POSTCODE_MAX_LEVEL.
+- resolve_address turns a described address into a code. It answers only as \
+precisely as its evidence allows: pass on its level and confidence, and ask the \
+user its question instead of guessing. A location pin is the most reliable input.
 - Never substitute a suggested correction without confirming it with the user.
 - Addresses returned are personal data: use them only for the user's request."""
 
@@ -69,6 +74,8 @@ class Settings:
     api_key: str | None
     max_level: int = 1
     base_url: str = BASE_URL
+    geocoder_url: str | None = None
+    geocoder_contact: str | None = None
 
 
 def settings_from_env(env: Mapping[str, str]) -> Settings | str:
@@ -76,10 +83,16 @@ def settings_from_env(env: Mapping[str, str]) -> Settings | str:
     raw_level = env.get("NG_POSTCODE_MAX_LEVEL", "1").strip()
     if raw_level not in {"1", "2", "3", "4", "5"}:
         return f"NG_POSTCODE_MAX_LEVEL must be 1 to 5, got {raw_level!r}"
+    geocoder_url = env.get("NG_GEOCODER_URL", "").strip().rstrip("/") or None
+    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"
     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,
     )
 
 
@@ -163,24 +176,39 @@ class Location(FromLibrary):
     radius_m: float | None = Field(description="The radius the API actually applied.")
 
 
-Api = AsyncClient | None
+@dataclass(frozen=True, slots=True)
+class State:
+    """What the tools share for the life of the server. Either part may be unconfigured."""
+
+    nipost: AsyncClient | None
+    geocoder: Nominatim | None
 
 
-def create_server(settings: Settings, http: httpx.AsyncClient | None = None) -> MCPServer[Api]:
-    """Build the server. Pass `http` to route API calls through your own client, as tests do."""
+def create_server(
+    settings: Settings,
+    http: httpx.AsyncClient | None = None,
+    geocoder_http: httpx.AsyncClient | None = None,
+) -> MCPServer[State]:
+    """Build the server. Pass `http` and `geocoder_http` to route calls through your own
+    clients, as tests do."""
 
     @asynccontextmanager
-    async def lifespan(_: MCPServer[Api]) -> AsyncIterator[Api]:
-        if settings.api_key is None:
-            yield None
-            return
-        client = AsyncClient(settings.api_key, base_url=settings.base_url, http=http)
+    async def lifespan(_: MCPServer[State]) -> AsyncIterator[State]:
+        nipost = (
+            AsyncClient(settings.api_key, base_url=settings.base_url, http=http)
+            if settings.api_key
+            else None
+        )
+        geocoder = geocoder_for(settings, geocoder_http)
         try:
-            yield client
+            yield State(nipost, geocoder)
         finally:
-            await client.aclose()
+            if nipost:
+                await nipost.aclose()
+            if geocoder:
+                await geocoder.aclose()
 
-    server: MCPServer[Api] = MCPServer(
+    server: MCPServer[State] = MCPServer(
         name="ng-postcode",
         title="Nigeria Postcode",
         instructions=INSTRUCTIONS,
@@ -210,7 +238,7 @@ def create_server(settings: Settings, http: httpx.AsyncClient | None = None) ->
     )
     async def lookup_postcode(
         postcode: Annotated[str, Field(description="Code in any style, e.g. EK-01-A03-FK-01.")],
-        ctx: Context[Api, Any],
+        ctx: Context[State, Any],
         level: Annotated[
             int,
             Field(
@@ -237,7 +265,7 @@ def create_server(settings: Settings, http: httpx.AsyncClient | None = None) ->
     )
     async def autocomplete_postcode(
         partial: Annotated[str, Field(description="The start of a code, e.g. 'EK 01 A'.")],
-        ctx: Context[Api, Any],
+        ctx: Context[State, Any],
     ) -> Completions:
         """Suggest completions for the next segment of a partly typed postcode."""
         result = await api(ctx).send(autocomplete(partial))
@@ -251,7 +279,7 @@ def create_server(settings: Settings, http: httpx.AsyncClient | None = None) ->
     async def find_postcode_at_location(
         latitude: Annotated[float, Field(ge=-90, le=90)],
         longitude: Annotated[float, Field(ge=-180, le=180)],
-        ctx: Context[Api, Any],
+        ctx: Context[State, Any],
         max_distance_m: Annotated[
             float | None,
             Field(ge=0, le=250, description="Search radius in metres. Defaults to 25."),
@@ -263,9 +291,85 @@ def create_server(settings: Settings, http: httpx.AsyncClient | None = None) ->
         )
         return Location.model_validate(unwrap(result))
 
+    @server.tool(
+        title="Resolve a Nigerian address to a postcode",
+        annotations=READ_ONLY_ONLINE,
+        structured_output=True,
+    )
+    async def resolve_address(
+        address: Annotated[str, Field(description="The address exactly as the user gave it.")],
+        ctx: Context[State, Any],
+        landmarks: Annotated[
+            list[Landmark] | None,
+            Field(
+                description="Landmarks named in the address, each with how the address relates "
+                "to it. Use 'at' only when the address is the landmark itself."
+            ),
+        ] = None,
+        geocode_queries: Annotated[
+            list[str] | None,
+            Field(
+                max_length=3,
+                description="Up to three map search strings you derive from the address: named "
+                "places and streets with the town and state, most specific first, without "
+                "directional words like 'back of'.",
+            ),
+        ] = None,
+        latitude: Annotated[
+            float | None, Field(ge=-90, le=90, description="A location pin the user shared.")
+        ] = 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.
+
+        A full building code comes only from a postcode written in the address, a location
+        pin, or a landmark that is the address itself. Otherwise the result is an area or
+        district prefix with a `question` for the user. Read the address yourself and fill
+        `landmarks` and `geocode_queries`; the address text is sent to the configured
+        geocoder.
+        """
+        if (latitude is None) != (longitude is None):
+            raise ToolError("Give both latitude and longitude, or neither.")
+        location = (
+            Coordinate(lat=latitude, lng=longitude)
+            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)
+        return await resolver.resolve(address, location, reading(landmarks, geocode_queries))
+
     return server
 
 
+def reading(landmarks: list[Landmark] | None, queries: list[str] | None) -> ParsedAddress | None:
+    """The host model's reading of the address, in the resolver's terms."""
+    if not landmarks and not queries:
+        return None
+    return ParsedAddress(
+        house_number=None,
+        street=None,
+        landmarks=landmarks or [],
+        locality=None,
+        lga=None,
+        state=None,
+        geocode_queries=queries or [],
+        question=None,
+    )
+
+
+def geocoder_for(settings: Settings, http: httpx.AsyncClient | None) -> Nominatim | None:
+    if settings.geocoder_url is None:
+        return None
+    contact = settings.geocoder_contact or "unknown"
+    return Nominatim(
+        settings.geocoder_url,
+        f"ng-postcode-mcp/{version('ng-postcode-mcp')} ({contact})",
+        http=http,
+    )
+
+
 def completions(found: Autocomplete) -> Completions:
     return Completions(
         segment=None if found.segment is None else found.segment.value,
@@ -319,8 +423,8 @@ def checked(text: str) -> Postcode:
             raise ToolError(f"{text!r} is not a valid postcode: {error}.{maybe}")
 
 
-def api(ctx: Context[Api, Any]) -> AsyncClient:
-    client = ctx.request_context.lifespan_context
+def api(ctx: Context[State, Any]) -> AsyncClient:
+    client = ctx.request_context.lifespan_context.nipost
     if client is None:
         raise ToolError(f"This tool needs NG_POSTCODE_API_KEY. {HINTS['auth_required']}")
     return client

ng_postcode_mcp-0.2.1/tests/test_resolve_tool.py

@@ -0,0 +1,144 @@
+"""resolve_address through a real MCP client, with NIPOST and the geocoder mocked."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+from mcp import Client
+from mcp.types import CallToolResult
+
+from ng_postcode_mcp import Settings, create_server, settings_from_env
+
+PLACES = {"Fabian Hotel, Ado Ekiti, Ekiti": 30, "NTA Road, Ado Ekiti, Ekiti": 26}
+BEHIND_FABIAN = {
+    "address": "back of Fabian Hotel, off NTA Road, Ado Ekiti",
+    "landmarks": [{"name": "Fabian Hotel", "relation": "behind"}],
+    "geocode_queries": ["Fabian Hotel, Ado Ekiti, Ekiti", "NTA Road, Ado Ekiti, Ekiti"],
+}
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+def nipost(request: httpx.Request) -> httpx.Response:
+    if request.url.path == "/v1/lookup":
+        return httpx.Response(200, json={"data": {"postcode": "EK-01-A03-FK-01", "valid": True}})
+    unit = {"postcode": "EK-01-A03-FK-01", "display": "EK 01 A03 FK 01", "distance_m": 8.0}
+    data = {"found": True, "unit": unit, "area": "EK-01-A03-FK", "district": "EK-01-A03"}
+    return httpx.Response(200, json={"data": data})
+
+
+async def call(
+    arguments: dict[str, Any],
+    *,
+    geocoder: bool = True,
+    searched: list[httpx.Request] | None = None,
+) -> CallToolResult:
+    def geocode(request: httpx.Request) -> httpx.Response:
+        if searched is not None:
+            searched.append(request)
+        query = request.url.params["q"]
+        rank = PLACES.get(query)
+        hit = {"lat": "7.62", "lon": "5.19", "place_rank": rank, "display_name": query}
+        return httpx.Response(200, json=[hit] if rank else [])
+
+    settings = Settings(
+        api_key="good",
+        geocoder_url="https://geo.example" if geocoder else None,
+        geocoder_contact="ops@example.com",
+    )
+    nipost_http = httpx.AsyncClient(transport=httpx.MockTransport(nipost))
+    geocoder_http = httpx.AsyncClient(transport=httpx.MockTransport(geocode))
+    server = create_server(settings, http=nipost_http, geocoder_http=geocoder_http)
+    async with Client(server) as client:
+        result = await client.call_tool("resolve_address", arguments)
+    await nipost_http.aclose()
+    await geocoder_http.aclose()
+    return result
+
+
+@pytest.mark.anyio
+async def test_the_host_models_reading_drives_the_answer() -> None:
+    searched: list[httpx.Request] = []
+    result = await call(BEHIND_FABIAN, searched=searched)
+    assert not result.is_error
+    answer = result.structured_content
+    assert (answer["status"], answer["level"], answer["code"]) == (
+        "partial",
+        "area",
+        "EK-01-A03-FK",
+    )
+    assert "behind Fabian Hotel" in answer["question"]
+    assert [r.url.params["q"] for r in searched] == ["Fabian Hotel, Ado Ekiti, Ekiti"]
+    assert searched[0].headers["User-Agent"].startswith("ng-postcode-mcp/")
+    assert "ops@example.com" in searched[0].headers["User-Agent"]
+
+
+@pytest.mark.anyio
+async def test_a_typed_postcode_needs_no_geocoder() -> None:
+    searched: list[httpx.Request] = []
+    result = await call({"address": "deliver to ek01a03fk01"}, searched=searched)
+    answer = result.structured_content
+    assert (answer["status"], answer["code"], answer["confidence"]) == (
+        "resolved",
+        "EK-01-A03-FK-01",
+        "high",
+    )
+    assert searched == []
+
+
+@pytest.mark.anyio
+async def test_a_location_pin_gives_the_building() -> None:
+    result = await call({"address": "my house", "latitude": 7.62, "longitude": 5.19})
+    answer = result.structured_content
+    assert (answer["level"], answer["method"], answer["code"]) == (
+        "building",
+        "location",
+        "EK-01-A03-FK-01",
+    )
+
+
+@pytest.mark.anyio
+async def test_without_a_geocoder_it_explains_and_asks() -> None:
+    result = await call(BEHIND_FABIAN, geocoder=False)
+    assert not result.is_error
+    answer = result.structured_content
+    assert (answer["status"], answer["code"]) == ("unresolved", None)
+    assert any("NG_GEOCODER_URL" in line for line in answer["evidence"])
+    assert answer["question"]
+
+
+@pytest.mark.anyio
+async def test_half_a_coordinate_is_an_error_the_model_can_fix() -> None:
+    result = await call({"address": "my house", "latitude": 7.62})
+    assert result.is_error
+
+
+@pytest.mark.anyio
+async def test_schemas_guide_the_host_model() -> None:
+    async with Client(create_server(Settings(api_key=None))) as client:
+        tools = {tool.name: tool for tool in (await client.list_tools()).tools}
+    tool = tools["resolve_address"]
+    assert tool.input_schema["required"] == ["address"]
+    relations = tool.input_schema["$defs"]["Landmark"]["properties"]["relation"]["enum"]
+    assert {"at", "behind", "opposite"} <= set(relations)
+    assert tool.input_schema["properties"]["geocode_queries"]["anyOf"][0]["maxItems"] == 3
+    assert tool.output_schema is not None
+    assert {"status", "code", "level", "confidence", "question", "evidence"} <= set(
+        tool.output_schema["properties"]
+    )
+
+
+def test_geocoder_settings() -> None:
+    public = {"NG_GEOCODER_URL": "https://nominatim.openstreetmap.org/"}
+    assert settings_from_env(public) == (
+        "the public Nominatim requires NG_GEOCODER_CONTACT, a URL or email identifying you"
+    )
+    configured = settings_from_env(public | {"NG_GEOCODER_CONTACT": "https://example.com"})
+    assert isinstance(configured, Settings)
+    assert configured.geocoder_url == "https://nominatim.openstreetmap.org"
+    assert settings_from_env({}) == Settings(api_key=None)

{ng_postcode_mcp-0.1.0 → ng_postcode_mcp-0.2.1}/tests/test_tools.py

@@ -86,7 +86,7 @@ def text(result: CallToolResult) -> str:
 
 
 @pytest.mark.anyio
-async def test_lists_four_read_only_tools_with_schemas() -> None:
+async def test_lists_five_read_only_tools_with_schemas() -> None:
     async with Client(create_server(Settings(api_key=None))) as client:
         tools = {tool.name: tool for tool in (await client.list_tools()).tools}
     assert set(tools) == {
@@ -94,6 +94,7 @@ async def test_lists_four_read_only_tools_with_schemas() -> None:
         "lookup_postcode",
         "autocomplete_postcode",
         "find_postcode_at_location",
+        "resolve_address",
     }
     for tool in tools.values():
         assert tool.annotations is not None

ng_postcode_mcp-0.1.0/PKG-INFO

@@ -1,87 +0,0 @@
-Metadata-Version: 2.5
-Name: ng-postcode-mcp
-Version: 0.1.0
-Summary: MCP server for Nigeria's NIPOST digital postcode (NDAPS): validate, look up and reverse-geocode postcodes.
-Project-URL: Repository, https://github.com/Adeniyikayodee/ng-postcode
-Project-URL: Issues, https://github.com/Adeniyikayodee/ng-postcode/issues
-Author: Kayode Adeniyi
-License-Expression: MIT
-License-File: LICENSE
-Keywords: ai-agents,geocoding,mcp,mcp-server,model-context-protocol,ndaps,nigeria,nipost,postcode
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering :: GIS
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: mcp<3,>=2.3
-Requires-Dist: ng-postcode[client]<0.2,>=0.1
-Description-Content-Type: text/markdown
-
-# ng-postcode-mcp
-
-MCP server for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. It lets AI assistants validate postcodes offline and look them up, autocomplete them and find them by location through the [postcode.gov.ng](https://docs.postcode.gov.ng) API.
-
-Built on the [`ng-postcode`](https://pypi.org/project/ng-postcode/) library.
-
-<!-- mcp-name: io.github.Adeniyikayodee/ng-postcode -->
-
-## Tools
-
-| Tool | What it does | Needs a key | Cost |
-| --- | --- | --- | --- |
-| `validate_postcode` | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free |
-| `lookup_postcode` | Confirms a code is assigned; level 2 adds the address, level 3 building use | Yes | Level 1 free, 2+ uses credits |
-| `autocomplete_postcode` | Suggests the next segment of a partly typed code | Yes | Free tier |
-| `find_postcode_at_location` | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |
-
-All tools are read-only. Errors come back as messages the model can act on, such as a missing key or an exhausted credit balance.
-
-## Install
-
-Requires [uv](https://docs.astral.sh/uv/). Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng); `validate_postcode` works without one.
-
-**Claude Code**
-
-```sh
-claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
-```
-
-**Claude Desktop, Cursor and other clients** that use an `mcpServers` config:
-
-```json
-{
-  "mcpServers": {
-    "ng-postcode": {
-      "command": "uvx",
-      "args": ["ng-postcode-mcp"],
-      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
-    }
-  }
-}
-```
-
-## Configuration
-
-| Variable | Default | Purpose |
-| --- | --- | --- |
-| `NG_POSTCODE_API_KEY` | none | NIPOST API key. Read from the environment only; never passed through tools. |
-| `NG_POSTCODE_MAX_LEVEL` | `1` | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. |
-| `NG_POSTCODE_BASE_URL` | `https://api.postcode.gov.ng` | Alternative API host, such as a staging stack. |
-
-## Safety
-
-- 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.
-
-## License
-
-MIT

ng_postcode_mcp-0.1.0/README.md

@@ -1,60 +0,0 @@
-# ng-postcode-mcp
-
-MCP server for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. It lets AI assistants validate postcodes offline and look them up, autocomplete them and find them by location through the [postcode.gov.ng](https://docs.postcode.gov.ng) API.
-
-Built on the [`ng-postcode`](https://pypi.org/project/ng-postcode/) library.
-
-<!-- mcp-name: io.github.Adeniyikayodee/ng-postcode -->
-
-## Tools
-
-| Tool | What it does | Needs a key | Cost |
-| --- | --- | --- | --- |
-| `validate_postcode` | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free |
-| `lookup_postcode` | Confirms a code is assigned; level 2 adds the address, level 3 building use | Yes | Level 1 free, 2+ uses credits |
-| `autocomplete_postcode` | Suggests the next segment of a partly typed code | Yes | Free tier |
-| `find_postcode_at_location` | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |
-
-All tools are read-only. Errors come back as messages the model can act on, such as a missing key or an exhausted credit balance.
-
-## Install
-
-Requires [uv](https://docs.astral.sh/uv/). Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng); `validate_postcode` works without one.
-
-**Claude Code**
-
-```sh
-claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
-```
-
-**Claude Desktop, Cursor and other clients** that use an `mcpServers` config:
-
-```json
-{
-  "mcpServers": {
-    "ng-postcode": {
-      "command": "uvx",
-      "args": ["ng-postcode-mcp"],
-      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
-    }
-  }
-}
-```
-
-## Configuration
-
-| Variable | Default | Purpose |
-| --- | --- | --- |
-| `NG_POSTCODE_API_KEY` | none | NIPOST API key. Read from the environment only; never passed through tools. |
-| `NG_POSTCODE_MAX_LEVEL` | `1` | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. |
-| `NG_POSTCODE_BASE_URL` | `https://api.postcode.gov.ng` | Alternative API host, such as a staging stack. |
-
-## Safety
-
-- 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.
-
-## License
-
-MIT