ng-postcode-mcp 0.1.0__tar.gz

ng_postcode_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+target/
+Cargo.lock
+.venv/
+__pycache__/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

ng_postcode_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Adeniyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ng_postcode_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+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

@@ -0,0 +1,60 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+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."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kayode Adeniyi" }]
+keywords = ["mcp", "mcp-server", "model-context-protocol", "ai-agents", "nigeria", "postcode", "nipost", "ndaps", "geocoding"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+dependencies = ["mcp>=2.3,<3", "ng-postcode[client]>=0.1,<0.2"]
+
+[project.scripts]
+ng-postcode-mcp = "ng_postcode_mcp.server:main"
+
+[project.urls]
+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"]
+
+# Inside the repository, build against the local library so the two never drift.
+[tool.uv.sources]
+ng-postcode = { path = "../python", editable = true }
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "LICENSE", "server.json"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PT"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ng_postcode_mcp-0.1.0/server.json

@@ -0,0 +1,37 @@
+{
+  "$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",
+  "repository": {
+    "url": "https://github.com/Adeniyikayodee/ng-postcode",
+    "source": "github",
+    "subfolder": "mcp"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "ng-postcode-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "NG_POSTCODE_API_KEY",
+          "description": "NIPOST Postcode API key from dashboard.postcode.gov.ng. Validation works without it.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "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"]
+        }
+      ]
+    }
+  ]
+}

ng_postcode_mcp-0.1.0/src/ng_postcode_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for Nigeria's NIPOST digital postcode (NDAPS)."""
+
+from .server import Settings, create_server, main, settings_from_env
+
+__all__ = ["Settings", "create_server", "main", "settings_from_env"]

ng_postcode_mcp-0.1.0/src/ng_postcode_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

ng_postcode_mcp-0.1.0/src/ng_postcode_mcp/server.py

@@ -0,0 +1,344 @@
+"""MCP server for Nigeria's NIPOST digital postcode.
+
+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.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from importlib.metadata import version
+from typing import Annotated, Any, Literal, TypeVar
+
+import httpx
+from mcp.server.mcpserver import Context, MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from ng_postcode import Corrected, Postcode, parse, parse_lenient
+from ng_postcode.api import (
+    BASE_URL,
+    ApiError,
+    Autocomplete,
+    Coordinate,
+    autocomplete,
+    lookup,
+    reverse,
+)
+from ng_postcode.client import AsyncClient, TransportError
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+KEY_URL = "https://dashboard.postcode.gov.ng"
+
+INSTRUCTIONS = """\
+Tools for Nigeria's 11-character building postcode, e.g. EK-01-A03-FK-01 \
+(state, LGA, district, area, building unit).
+- validate_postcode is offline and free: use it first on any code a user typed.
+- 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.
+- Never substitute a suggested correction without confirming it with the user.
+- Addresses returned are personal data: use them only for the user's request."""
+
+READ_ONLY_OFFLINE = ToolAnnotations(
+    read_only_hint=True, idempotent_hint=True, open_world_hint=False
+)
+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}.",
+    "insufficient_credits": "The NIPOST account is out of credits; top up or use level 1.",
+}
+STATUS_HINTS = {
+    403: "The key lacks the scope or access level for this request.",
+    429: "NIPOST rate limit reached; wait before retrying.",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    api_key: str | None
+    max_level: int = 1
+    base_url: str = BASE_URL
+
+
+def settings_from_env(env: Mapping[str, str]) -> Settings | str:
+    """Read settings from the environment, or describe what is wrong with them."""
+    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}"
+    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,
+    )
+
+
+class Segments(BaseModel):
+    state: str
+    lga: str
+    district: str
+    area: str
+    unit: str
+
+
+class Validation(BaseModel):
+    valid: bool = Field(description="Whether the code is well formed. It may still be unassigned.")
+    postcode: str | None = Field(description="Canonical form, e.g. EK-01-A03-FK-01.")
+    compact: str | None = Field(description="Compact form for storage, e.g. EK01A03FK01.")
+    spaced: str | None = Field(description="Form shown to people, e.g. EK 01 A03 FK 01.")
+    segments: Segments | None
+    error: str | None = Field(description="Why the code is malformed.")
+    suggestion: str | None = Field(
+        description="A well-formed code if look-alike characters (O/0, I/1, S/5, B/8) were the "
+        "only problem. Confirm it with the user before using it."
+    )
+
+
+# Explicit output contracts. The SDK cannot derive schemas from the library's slotted
+# dataclasses, and named fields with descriptions serve agents better anyway.
+# tests/test_tools.py checks every field still exists in ng_postcode.api.
+
+
+class FromLibrary(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+
+class Address(FromLibrary):
+    state_name: str | None
+    lga_name: str | None
+    locality_name: str | None
+    zone: str | None = Field(description="Geopolitical zone, e.g. SOUTH WEST.")
+
+
+class PostcodeDetails(FromLibrary):
+    postcode: str
+    valid: bool = Field(description="Whether the code is assigned to a building.")
+    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.")
+    other_building_info: Any = Field(default=None, description="Level 4 and up, unstructured.")
+    point_geometry: Any = Field(default=None, description="Level 5, unstructured.")
+
+
+class Completion(FromLibrary):
+    code: str
+    label: str
+
+
+class Completions(BaseModel):
+    segment: Literal["state", "lga", "district", "area", "unit"] | None = Field(
+        description="The segment being completed."
+    )
+    suggestions: list[Completion]
+
+
+class NearestBuilding(FromLibrary):
+    postcode: str
+    display: str
+    distance_m: float | None
+    confidence: str | None = Field(description="high, medium or low, graded by distance.")
+    state_name: str | None = Field(description="Level 2 and up.")
+    lga_name: str | None = Field(description="Level 2 and up.")
+    locality_name: str | None = Field(description="Level 2 and up.")
+    address: str | None = Field(description="Recent house address. Level 2 and up.")
+
+
+class Location(FromLibrary):
+    found: bool = Field(description="False when no building is within the radius.")
+    unit: NearestBuilding | None
+    area: str | None = Field(description="Enclosing area code, e.g. EK-01-A03-FK.")
+    district: str | None
+    state: str | None
+    message: str | None
+    radius_m: float | None = Field(description="The radius the API actually applied.")
+
+
+Api = AsyncClient | 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."""
+
+    @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)
+        try:
+            yield client
+        finally:
+            await client.aclose()
+
+    server: MCPServer[Api] = MCPServer(
+        name="ng-postcode",
+        title="Nigeria Postcode",
+        instructions=INSTRUCTIONS,
+        version=version("ng-postcode-mcp"),
+        lifespan=lifespan,
+    )
+
+    @server.tool(
+        title="Validate a Nigerian postcode",
+        annotations=READ_ONLY_OFFLINE,
+        structured_output=True,
+    )
+    def validate_postcode(
+        postcode: Annotated[str, Field(description="Code in any style, e.g. 'ek 01 a03 fk 01'.")],
+    ) -> Validation:
+        """Check a postcode's structure offline and return its canonical forms and segments.
+
+        Free and instant. Does not confirm the code is assigned to a building; use
+        lookup_postcode for that.
+        """
+        return validation(postcode)
+
+    @server.tool(
+        title="Look up a Nigerian postcode",
+        annotations=READ_ONLY_ONLINE,
+        structured_output=True,
+    )
+    async def lookup_postcode(
+        postcode: Annotated[str, Field(description="Code in any style, e.g. EK-01-A03-FK-01.")],
+        ctx: Context[Api, Any],
+        level: Annotated[
+            int,
+            Field(
+                ge=1,
+                le=5,
+                description="1: validity only (free). 2: adds the administrative and recent "
+                "house address. 3: adds building use. Levels 2+ consume NIPOST credits.",
+            ),
+        ] = 1,
+    ) -> PostcodeDetails:
+        """Confirm a postcode is assigned and, at higher levels, return its address details."""
+        if level > settings.max_level:
+            raise ToolError(
+                f"Level {level} is above this server's cap of {settings.max_level}. Levels 2+ "
+                "consume NIPOST credits; the user can raise NG_POSTCODE_MAX_LEVEL to allow it."
+            )
+        result = await api(ctx).send(lookup(checked(postcode), level))
+        return PostcodeDetails.model_validate(unwrap(result))
+
+    @server.tool(
+        title="Autocomplete a Nigerian postcode",
+        annotations=READ_ONLY_ONLINE,
+        structured_output=True,
+    )
+    async def autocomplete_postcode(
+        partial: Annotated[str, Field(description="The start of a code, e.g. 'EK 01 A'.")],
+        ctx: Context[Api, Any],
+    ) -> Completions:
+        """Suggest completions for the next segment of a partly typed postcode."""
+        result = await api(ctx).send(autocomplete(partial))
+        return completions(unwrap(result))
+
+    @server.tool(
+        title="Find the postcode at a location",
+        annotations=READ_ONLY_ONLINE,
+        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)],
+        ctx: Context[Api, Any],
+        max_distance_m: Annotated[
+            float | None,
+            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."""
+        result = await api(ctx).send(
+            reverse(Coordinate(lat=latitude, lng=longitude), max_distance_m)
+        )
+        return Location.model_validate(unwrap(result))
+
+    return server
+
+
+def completions(found: Autocomplete) -> Completions:
+    return Completions(
+        segment=None if found.segment is None else found.segment.value,
+        suggestions=[Completion.model_validate(s) for s in found.suggestions],
+    )
+
+
+def validation(text: str) -> Validation:
+    match parse(text):
+        case Postcode() as code:
+            return Validation(
+                valid=True,
+                postcode=str(code),
+                compact=code.compact,
+                spaced=code.spaced,
+                segments=Segments(
+                    state=code.state,
+                    lga=code.lga,
+                    district=code.district,
+                    area=code.area,
+                    unit=code.unit,
+                ),
+                error=None,
+                suggestion=None,
+            )
+        case error:
+            return Validation(
+                valid=False,
+                postcode=None,
+                compact=None,
+                spaced=None,
+                segments=None,
+                error=str(error),
+                suggestion=suggestion(text),
+            )
+
+
+def suggestion(text: str) -> str | None:
+    fixed = parse_lenient(text)
+    return str(fixed.postcode) if isinstance(fixed, Corrected) else None
+
+
+def checked(text: str) -> Postcode:
+    """The parsed code, or a ToolError the model can act on. Never auto-corrects a paid call."""
+    match parse(text):
+        case Postcode() as code:
+            return code
+        case error:
+            hint = suggestion(text)
+            maybe = f" Did you mean {hint}? Confirm with the user first." if hint else ""
+            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
+    if client is None:
+        raise ToolError(f"This tool needs NG_POSTCODE_API_KEY. {HINTS['auth_required']}")
+    return client
+
+
+def unwrap(result: T | ApiError | TransportError) -> T:
+    if isinstance(result, TransportError):
+        raise ToolError(f"Could not reach the NIPOST API: {result}")
+    if isinstance(result, ApiError):
+        hint = HINTS.get(result.code) or STATUS_HINTS.get(result.status, "")
+        raise ToolError(f"NIPOST API error {result}. {hint}".strip())
+    return result
+
+
+def main() -> None:
+    settings = settings_from_env(os.environ)
+    if isinstance(settings, str):
+        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()

ng_postcode_mcp-0.1.0/tests/test_metadata.py

@@ -0,0 +1,31 @@
+"""Release metadata must agree, or the registry rejects the publish."""
+
+from __future__ import annotations
+
+import json
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def server_json() -> dict[str, Any]:
+    data: dict[str, Any] = json.loads((ROOT / "server.json").read_text(encoding="utf-8"))
+    return data
+
+
+def test_versions_and_names_agree() -> None:
+    server = server_json()
+    package = server["packages"][0]
+    assert package["identifier"] == "ng-postcode-mcp"
+    assert server["version"] == package["version"] == version("ng-postcode-mcp")
+
+
+def test_readme_proves_registry_ownership() -> None:
+    marker = f"<!-- mcp-name: {server_json()['name']} -->"
+    assert marker in (ROOT / "README.md").read_text(encoding="utf-8")
+
+
+def test_registry_description_fits() -> None:
+    assert len(server_json()["description"]) <= 100

ng_postcode_mcp-0.1.0/tests/test_stdio.py

@@ -0,0 +1,25 @@
+"""The real entry point over stdio: proves nothing but protocol reaches stdout."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+from mcp import Client, StdioServerParameters
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+@pytest.mark.anyio
+async def test_serves_over_stdio() -> None:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("NG_POSTCODE_")}
+    params = StdioServerParameters(command=sys.executable, args=["-m", "ng_postcode_mcp"], env=env)
+    async with Client(params) as client:
+        names = {tool.name for tool in (await client.list_tools()).tools}
+        result = await client.call_tool("validate_postcode", {"postcode": "LA11W06TC10"})
+    assert "validate_postcode" in names
+    assert result.structured_content["postcode"] == "LA-11-W06-TC-10"

ng_postcode_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,209 @@
+"""Tool behaviour through a real MCP client, in process, with the NIPOST API mocked."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+import pytest
+from mcp import Client
+from mcp.types import CallToolResult, TextContent
+from ng_postcode import api
+from pydantic import BaseModel
+
+from ng_postcode_mcp import Settings, create_server, settings_from_env
+from ng_postcode_mcp.server import (
+    Address,
+    Completion,
+    Location,
+    NearestBuilding,
+    PostcodeDetails,
+)
+
+Handler = Callable[[httpx.Request], httpx.Response]
+
+LOOKUP = {
+    "postcode": "EK-01-A03-FK-01",
+    "valid": True,
+    "administrative_address": {
+        "state_name": "EKITI",
+        "lga_name": "ADO EKITI",
+        "locality_name": "ADO EKITI",
+        "zone": "SOUTH WEST",
+    },
+    "recent_house_address": {"recent": "NTA ROAD, BACK OF FABIAN HOTEL, ADO EKITI"},
+    "building_use_status": "residential",
+}
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+def nipost(seen: list[httpx.Request]) -> Handler:
+    def handle(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        if request.headers.get("X-API-Key") != "good":
+            error = {"code": "invalid_api_key", "message": "the provided API key is invalid"}
+            return httpx.Response(401, json={"error": error})
+        if request.url.path == "/v1/lookup":
+            return httpx.Response(200, json={"data": LOOKUP})
+        if request.url.path == "/v1/search/reverse":
+            return httpx.Response(200, json={"data": {"found": False, "radius_m": 25}})
+        if request.url.path == "/v1/search/autocomplete":
+            suggestion = {"code": "EK-01", "label": "ADO EKITI"}
+            return httpx.Response(
+                200, json={"data": {"segment": "lga", "suggestions": [suggestion]}}
+            )
+        return httpx.Response(404, json={"error": {"code": "not_found", "message": "no route"}})
+
+    return handle
+
+
+async def call(
+    name: str,
+    arguments: dict[str, Any],
+    *,
+    key: str | None = "good",
+    max_level: int = 1,
+    seen: list[httpx.Request] | None = None,
+) -> CallToolResult:
+    http = httpx.AsyncClient(
+        transport=httpx.MockTransport(nipost(seen if seen is not None else []))
+    )
+    server = create_server(Settings(api_key=key, max_level=max_level), http=http)
+    async with Client(server) as client:
+        result = await client.call_tool(name, arguments)
+    await http.aclose()
+    return result
+
+
+def text(result: CallToolResult) -> str:
+    return " ".join(block.text for block in result.content if isinstance(block, TextContent))
+
+
+@pytest.mark.anyio
+async def test_lists_four_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) == {
+        "validate_postcode",
+        "lookup_postcode",
+        "autocomplete_postcode",
+        "find_postcode_at_location",
+    }
+    for tool in tools.values():
+        assert tool.annotations is not None
+        assert tool.annotations.read_only_hint is True
+        assert tool.description
+        assert tool.output_schema is not None
+    assert tools["validate_postcode"].annotations.open_world_hint is False  # type: ignore[union-attr]
+    level = tools["lookup_postcode"].input_schema["properties"]["level"]
+    assert (level["minimum"], level["maximum"], level["default"]) == (1, 5, 1)
+    assert "ctx" not in tools["lookup_postcode"].input_schema["properties"]
+
+
+@pytest.mark.anyio
+async def test_validate_works_offline_without_a_key() -> None:
+    result = await call("validate_postcode", {"postcode": "ek 01 a03 fk 01"}, key=None)
+    assert not result.is_error
+    assert result.structured_content["postcode"] == "EK-01-A03-FK-01"
+    assert result.structured_content["segments"]["district"] == "A03"
+
+
+@pytest.mark.anyio
+async def test_validate_suggests_but_does_not_apply_fixes() -> None:
+    result = await call("validate_postcode", {"postcode": "EK-O1-A03-FK-01"}, key=None)
+    assert not result.is_error
+    data = result.structured_content
+    assert (data["valid"], data["postcode"]) == (False, None)
+    assert (data["error"], data["suggestion"]) == ("invalid lga segment", "EK-01-A03-FK-01")
+
+
+@pytest.mark.anyio
+async def test_lookup_returns_the_address_within_the_cap() -> None:
+    seen: list[httpx.Request] = []
+    result = await call(
+        "lookup_postcode", {"postcode": "ek01a03fk01", "level": 2}, max_level=2, seen=seen
+    )
+    assert not result.is_error, text(result)
+    assert result.structured_content["administrative_address"]["zone"] == "SOUTH WEST"
+    assert dict(seen[0].url.params) == {"code": "EK-01-A03-FK-01", "level": "2"}
+
+
+@pytest.mark.anyio
+async def test_lookup_refuses_paid_levels_above_the_cap_without_calling_the_api() -> None:
+    seen: list[httpx.Request] = []
+    result = await call("lookup_postcode", {"postcode": "EK-01-A03-FK-01", "level": 3}, seen=seen)
+    assert result.is_error
+    assert "NG_POSTCODE_MAX_LEVEL" in text(result)
+    assert seen == []
+
+
+@pytest.mark.anyio
+async def test_lookup_never_autocorrects_before_spending() -> None:
+    seen: list[httpx.Request] = []
+    result = await call("lookup_postcode", {"postcode": "EK-O1-A03-FK-01"}, seen=seen)
+    assert result.is_error
+    assert "Did you mean EK-01-A03-FK-01? Confirm with the user first." in text(result)
+    assert seen == []
+
+
+@pytest.mark.anyio
+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)
+
+    secret = "nipost_test_never_echo_me"
+    rejected = await call("lookup_postcode", {"postcode": "EK-01-A03-FK-01"}, key=secret)
+    assert rejected.is_error
+    assert "invalid_api_key (401)" in text(rejected)
+    assert "create a new key" in text(rejected)
+    assert secret not in text(rejected)
+
+
+@pytest.mark.anyio
+async def test_autocomplete_and_reverse() -> None:
+    found = await call("autocomplete_postcode", {"partial": "EK"})
+    assert not found.is_error
+    assert found.structured_content["suggestions"][0]["code"] == "EK-01"
+
+    near = await call("find_postcode_at_location", {"latitude": 7.62, "longitude": 5.22})
+    assert not near.is_error
+    assert (near.structured_content["found"], near.structured_content["radius_m"]) == (False, 25.0)
+
+
+@pytest.mark.anyio
+async def test_rejects_out_of_range_arguments() -> None:
+    result = await call("find_postcode_at_location", {"latitude": 95, "longitude": 5.22})
+    assert result.is_error
+
+
+@pytest.mark.parametrize(
+    ("model", "source"),
+    [
+        (PostcodeDetails, api.Lookup),
+        (Address, api.AdministrativeAddress),
+        (Completion, api.Suggestion),
+        (NearestBuilding, api.NearestUnit),
+        (Location, api.Reverse),
+    ],
+)
+def test_output_models_only_use_fields_the_library_has(
+    model: type[BaseModel], source: type
+) -> None:
+    assert set(model.model_fields) <= {field.name for field in dataclasses.fields(source)}
+
+
+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"}) == (
+        Settings(api_key="k", max_level=3)
+    )
+    assert settings_from_env({"NG_POSTCODE_MAX_LEVEL": "9"}) == (
+        "NG_POSTCODE_MAX_LEVEL must be 1 to 5, got '9'"
+    )