ng-postcode-mcp 0.2.0__tar.gz → 0.2.2__tar.gz

{ng_postcode_mcp-0.2.0 → ng_postcode_mcp-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode-mcp
-Version: 0.2.0
+Version: 0.2.2
 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,8 +22,8 @@ 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
+Requires-Dist: ng-address-resolver<0.2,>=0.1.1
+Requires-Dist: ng-postcode[client]<0.3,>=0.2
 Description-Content-Type: text/markdown
 
 # ng-postcode-mcp
@@ -58,19 +58,21 @@ The assistant reads the address and passes its landmarks and map searches to the
 | 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.
+Text alone rarely identifies a building, so ask users for a location pin when the exact building matters. This tool is pre-release: it works against the live API, but its accuracy on real addresses is unmeasured.
 
 ## 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.
+Works with any MCP client. The server runs over stdio:
 
-**Claude Code**
+| Setting | Value |
+| --- | --- |
+| Command | `uvx` |
+| Arguments | `ng-postcode-mcp` |
+| Environment | `NG_POSTCODE_API_KEY` (optional for `validate_postcode`) |
 
-```sh
-claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
-```
+It needs [uv](https://docs.astral.sh/uv/) installed. Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng).
 
-**Claude Desktop, Cursor and other clients** that use an `mcpServers` config:
+Most clients take this entry in their MCP settings:
 
 ```json
 {
@@ -84,6 +86,15 @@ claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-post
 }
 ```
 
+| 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_mcp-0.2.0 → ng_postcode_mcp-0.2.2}/README.md

@@ -30,19 +30,21 @@ The assistant reads the address and passes its landmarks and map searches to the
 | 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.
+Text alone rarely identifies a building, so ask users for a location pin when the exact building matters. This tool is pre-release: it works against the live API, but its accuracy on real addresses is unmeasured.
 
 ## 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.
+Works with any MCP client. The server runs over stdio:
 
-**Claude Code**
+| Setting | Value |
+| --- | --- |
+| Command | `uvx` |
+| Arguments | `ng-postcode-mcp` |
+| Environment | `NG_POSTCODE_API_KEY` (optional for `validate_postcode`) |
 
-```sh
-claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
-```
+It needs [uv](https://docs.astral.sh/uv/) installed. Get an API key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng).
 
-**Claude Desktop, Cursor and other clients** that use an `mcpServers` config:
+Most clients take this entry in their MCP settings:
 
 ```json
 {
@@ -56,6 +58,15 @@ claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-post
 }
 ```
 
+| 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_mcp-0.2.0 → ng_postcode_mcp-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode-mcp"
-version = "0.2.0"
+version = "0.2.2"
 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,<0.2", "ng-postcode[client]>=0.1,<0.2"]
+dependencies = ["mcp>=2.3,<3", "ng-address-resolver>=0.1.1,<0.2", "ng-postcode[client]>=0.2,<0.3"]
 
 [project.scripts]
 ng-postcode-mcp = "ng_postcode_mcp.server:main"

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

{ng_postcode_mcp-0.2.0 → ng_postcode_mcp-0.2.2}/src/ng_postcode_mcp/server.py

@@ -62,6 +62,8 @@ 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}.",
     "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}.",
 }
 STATUS_HINTS = {
     403: "The key lacks the scope or access level for this request.",
@@ -136,6 +138,10 @@ class Address(FromLibrary):
 class PostcodeDetails(FromLibrary):
     postcode: str
     valid: bool = Field(description="Whether the code is assigned to a building.")
+    status: str | None = Field(
+        default=None, description="valid, not_found, or invalid for a malformed code."
+    )
+    verified: bool | None = None
     administrative_address: Address | None = Field(description="Level 2 and up.")
     recent_house_address: str | None = Field(description="Level 2 and up. Personal data.")
     building_use_status: str | None = Field(description="Level 3 and up, e.g. residential.")
@@ -144,8 +150,10 @@ class PostcodeDetails(FromLibrary):
 
 
 class Completion(FromLibrary):
-    code: str
-    label: str
+    code: str = Field(description="The value of the next segment, e.g. A03, not a full prefix.")
+    label: str | None = Field(
+        default=None, description="A name for the code, when NIPOST sends one."
+    )
 
 
 class Completions(BaseModel):
@@ -174,6 +182,7 @@ class Location(FromLibrary):
     state: str | None
     message: str | None
     radius_m: float | None = Field(description="The radius the API actually applied.")
+    depth: str | None = Field(default=None, description="How deep the match goes, e.g. unit.")
 
 
 @dataclass(frozen=True, slots=True)
@@ -264,10 +273,14 @@ def create_server(
         structured_output=True,
     )
     async def autocomplete_postcode(
-        partial: Annotated[str, Field(description="The start of a code, e.g. 'EK 01 A'.")],
+        partial: Annotated[
+            str, Field(min_length=1, description="The start of a code, e.g. 'EK 01 A'.")
+        ],
         ctx: Context[State, Any],
     ) -> Completions:
         """Suggest completions for the next segment of a partly typed postcode."""
+        if not partial.strip():
+            raise ToolError("Give at least the first characters of a postcode.")
         result = await api(ctx).send(autocomplete(partial))
         return completions(unwrap(result))
 

{ng_postcode_mcp-0.2.0 → ng_postcode_mcp-0.2.2}/tests/test_tools.py

@@ -9,8 +9,10 @@ from typing import Any
 import httpx
 import pytest
 from mcp import Client
+from mcp.server.mcpserver.exceptions import ToolError
 from mcp.types import CallToolResult, TextContent
 from ng_postcode import api
+from ng_postcode.api import ApiError
 from pydantic import BaseModel
 
 from ng_postcode_mcp import Settings, create_server, settings_from_env
@@ -20,6 +22,7 @@ from ng_postcode_mcp.server import (
     Location,
     NearestBuilding,
     PostcodeDetails,
+    unwrap,
 )
 
 Handler = Callable[[httpx.Request], httpx.Response]
@@ -208,3 +211,17 @@ def test_settings_from_env() -> None:
     assert settings_from_env({"NG_POSTCODE_MAX_LEVEL": "9"}) == (
         "NG_POSTCODE_MAX_LEVEL must be 1 to 5, got '9'"
     )
+
+
+@pytest.mark.anyio
+async def test_a_blank_autocomplete_never_reaches_the_api() -> None:
+    seen: list[httpx.Request] = []
+    result = await call("autocomplete_postcode", {"partial": "  "}, seen=seen)
+    assert result.is_error
+    assert seen == []
+
+
+def test_a_level_the_key_lacks_gets_a_specific_hint() -> None:
+    error = ApiError(403, "level_not_granted", "this key is granted up to lookup level 1")
+    with pytest.raises(ToolError, match="request more access"):
+        unwrap(error)