Skip to content

Commit 15f6d14

Browse files
feat(mcp): add ng-postcode MCP server
Agents had no postcode tool. Python over Rust: uvx runs it with no toolchain. Credits are capped at the free level by default and typos are never auto-corrected into paid calls.
1 parent ca2cf30 commit 15f6d14

13 files changed

Lines changed: 2215 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
Rust library for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. Parse, validate and format postcodes offline, and call the [postcode.gov.ng](https://docs.postcode.gov.ng) API for lookup, autocomplete and reverse geocoding.
77

8-
A Python package with the same behaviour lives in [`python/`](python). Both pass the shared cases in [`spec/vectors.json`](spec/vectors.json).
8+
A Python package with the same behaviour lives in [`python/`](python). Both pass the shared cases in [`spec/vectors.json`](spec/vectors.json). An MCP server for AI assistants, built on the Python package, lives in [`mcp/`](mcp).
99

1010
## Format
1111

‎mcp/LICENSE‎

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

‎mcp/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ng-postcode-mcp
2+
3+
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.
4+
5+
Built on the [`ng-postcode`](https://pypi.org/project/ng-postcode/) library.
6+
7+
<!-- mcp-name: io.github.Adeniyikayodee/ng-postcode -->
8+
9+
## Tools
10+
11+
| Tool | What it does | Needs a key | Cost |
12+
| --- | --- | --- | --- |
13+
| `validate_postcode` | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free |
14+
| `lookup_postcode` | Confirms a code is assigned; level 2 adds the address, level 3 building use | Yes | Level 1 free, 2+ uses credits |
15+
| `autocomplete_postcode` | Suggests the next segment of a partly typed code | Yes | Free tier |
16+
| `find_postcode_at_location` | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |
17+
18+
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.
19+
20+
## Install
21+
22+
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.
23+
24+
**Claude Code**
25+
26+
```sh
27+
claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
28+
```
29+
30+
**Claude Desktop, Cursor and other clients** that use an `mcpServers` config:
31+
32+
```json
33+
{
34+
"mcpServers": {
35+
"ng-postcode": {
36+
"command": "uvx",
37+
"args": ["ng-postcode-mcp"],
38+
"env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
39+
}
40+
}
41+
}
42+
```
43+
44+
## Configuration
45+
46+
| Variable | Default | Purpose |
47+
| --- | --- | --- |
48+
| `NG_POSTCODE_API_KEY` | none | NIPOST API key. Read from the environment only; never passed through tools. |
49+
| `NG_POSTCODE_MAX_LEVEL` | `1` | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. |
50+
| `NG_POSTCODE_BASE_URL` | `https://api.postcode.gov.ng` | Alternative API host, such as a staging stack. |
51+
52+
## Safety
53+
54+
- Lookups default to level 1, which is free. A model cannot spend credits unless you raise `NG_POSTCODE_MAX_LEVEL`.
55+
- 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.
56+
- Levels 2 and up return house addresses. Treat them as personal data under the Nigeria Data Protection Act.
57+
58+
## License
59+
60+
MIT

‎mcp/pyproject.toml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
[build-system]
2+
requires = ["hatchling>=1.27"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "ng-postcode-mcp"
7+
version = "0.1.0"
8+
description = "MCP server for Nigeria's NIPOST digital postcode (NDAPS): validate, look up and reverse-geocode postcodes."
9+
readme = "README.md"
10+
requires-python = ">=3.10"
11+
license = "MIT"
12+
license-files = ["LICENSE"]
13+
authors = [{ name = "Kayode Adeniyi" }]
14+
keywords = ["mcp", "mcp-server", "model-context-protocol", "ai-agents", "nigeria", "postcode", "nipost", "ndaps", "geocoding"]
15+
classifiers = [
16+
"Development Status :: 3 - Alpha",
17+
"Intended Audience :: Developers",
18+
"Operating System :: OS Independent",
19+
"Programming Language :: Python :: 3",
20+
"Programming Language :: Python :: 3 :: Only",
21+
"Programming Language :: Python :: 3.10",
22+
"Programming Language :: Python :: 3.11",
23+
"Programming Language :: Python :: 3.12",
24+
"Programming Language :: Python :: 3.13",
25+
"Programming Language :: Python :: 3.14",
26+
"Topic :: Scientific/Engineering :: GIS",
27+
"Typing :: Typed",
28+
]
29+
dependencies = ["mcp>=2.3,<3", "ng-postcode[client]>=0.1,<0.2"]
30+
31+
[project.scripts]
32+
ng-postcode-mcp = "ng_postcode_mcp.server:main"
33+
34+
[project.urls]
35+
Repository = "https://github.com/Adeniyikayodee/ng-postcode"
36+
Issues = "https://github.com/Adeniyikayodee/ng-postcode/issues"
37+
38+
[dependency-groups]
39+
dev = ["jsonschema>=4.20", "mypy>=1.13", "pytest>=8", "ruff>=0.8"]
40+
41+
# Inside the repository, build against the local library so the two never drift.
42+
[tool.uv.sources]
43+
ng-postcode = { path = "../python", editable = true }
44+
45+
[tool.hatch.build.targets.sdist]
46+
only-include = ["src", "tests", "README.md", "LICENSE", "server.json"]
47+
48+
[tool.ruff]
49+
line-length = 100
50+
target-version = "py310"
51+
52+
[tool.ruff.lint]
53+
select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PT"]
54+
55+
[tool.mypy]
56+
strict = true
57+
files = ["src", "tests"]
58+
59+
[tool.pytest.ini_options]
60+
testpaths = ["tests"]

‎mcp/server.json‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3+
"name": "io.github.Adeniyikayodee/ng-postcode",
4+
"title": "Nigeria Postcode",
5+
"description": "Validate, look up and reverse-geocode Nigeria's NIPOST digital postcodes (NDAPS).",
6+
"version": "0.1.0",
7+
"repository": {
8+
"url": "https://github.com/Adeniyikayodee/ng-postcode",
9+
"source": "github",
10+
"subfolder": "mcp"
11+
},
12+
"packages": [
13+
{
14+
"registryType": "pypi",
15+
"identifier": "ng-postcode-mcp",
16+
"version": "0.1.0",
17+
"runtimeHint": "uvx",
18+
"transport": {
19+
"type": "stdio"
20+
},
21+
"environmentVariables": [
22+
{
23+
"name": "NG_POSTCODE_API_KEY",
24+
"description": "NIPOST Postcode API key from dashboard.postcode.gov.ng. Validation works without it.",
25+
"isRequired": false,
26+
"isSecret": true
27+
},
28+
{
29+
"name": "NG_POSTCODE_MAX_LEVEL",
30+
"description": "Highest lookup level tools may request. Levels 2 and up consume NIPOST credits.",
31+
"default": "1",
32+
"choices": ["1", "2", "3", "4", "5"]
33+
}
34+
]
35+
}
36+
]
37+
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""MCP server for Nigeria's NIPOST digital postcode (NDAPS)."""
2+
3+
from .server import Settings, create_server, main, settings_from_env
4+
5+
__all__ = ["Settings", "create_server", "main", "settings_from_env"]
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from .server import main
2+
3+
main()

‎mcp/src/ng_postcode_mcp/py.typed‎

Whitespace-only changes.

0 commit comments

Comments
 (0)