@shyzus/mcp-geocrafter 1.3.0 → 1.4.0

package/README.md

@@ -3,13 +3,14 @@
 GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Photon API (OpenStreetMap + Elasticsearch) with fuzzy matching support.
 
 [![CI](https://github.com/Shyzkanza/mcp-location/actions/workflows/ci.yml/badge.svg)](https://github.com/Shyzkanza/mcp-location/actions/workflows/ci.yml)
+[![Release](https://github.com/Shyzkanza/mcp-location/actions/workflows/release.yml/badge.svg)](https://github.com/Shyzkanza/mcp-location/actions/workflows/release.yml)
 [![npm version](https://img.shields.io/npm/v/@shyzus/mcp-geocrafter)](https://www.npmjs.com/package/@shyzus/mcp-geocrafter)
 [![npm downloads](https://img.shields.io/npm/dm/@shyzus/mcp-geocrafter?cacheSeconds=3600)](https://www.npmjs.com/package/@shyzus/mcp-geocrafter)
 [![Website Status](https://img.shields.io/website?url=https%3A%2F%2Fgeocrafter.rankorr.red%2Fhealth&label=API)](https://geocrafter.rankorr.red/health)
 ![Node](https://img.shields.io/badge/node-20%2B-green)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)
 ![MCP](https://img.shields.io/badge/MCP-2025--11--25-orange)
-![ChatGPT](https://img.shields.io/badge/ChatGPT-Apps%20SDK-purple)
+![ChatGPT](https://img.shields.io/badge/ChatGPT-MCP-purple)
 
 ---
 
@@ -32,31 +33,35 @@ This application allows **ChatGPT** and other MCP clients to access geocoding se
 
 ### ✨ Features
 
-- 🔍 **Address to GPS** - Convert addresses to coordinates
+- 🔍 **Address to GPS** - Convert addresses to coordinates (fuzzy matching)
 - 📍 **GPS to Address** - Convert coordinates to addresses
+- 🔗 **Geohash Encoding/Decoding** - Convert coordinates to geohash strings for location deduplication
+- 📏 **Distance Calculation** - Haversine formula to compute exact distance between two GPS points
 - 🏗️ **Modular Architecture** - Clean separation of concerns, reusable for future MCP servers
 - 🔌 **Dual Mode** - Works with ChatGPT (HTTP) and IDEs (stdio)
 - 🗺️ **GeoJSON Map Viewer** - Render interactive maps inside ChatGPT with fullscreen controls (Apps SDK)
 
-### 💬 Usage example
+### 💬 Usage examples
 
-In ChatGPT, simply ask:
+In ChatGPT or your IDE, simply ask:
 
 > "What are the coordinates of the Eiffel Tower?"
 
-Or:
-
 > "What is the address at coordinates 48.8566, 2.3522?"
 
-ChatGPT will use the MCP server to get the information.
+> "Encode the Eiffel Tower coordinates as a geohash"
+
+> "What's the distance between Paris and Marseille?"
+
+The LLM will use the MCP server to get the information.
 
 ---
 
-## 🏗️ Architecture: ChatGPT MCP App
+## 🏗️ Architecture: MCP Server
 
-### What is a ChatGPT App?
+### What is an MCP Server?
 
-**ChatGPT Apps** (via [Apps SDK](https://developers.openai.com/apps-sdk)) allow you to extend ChatGPT with:
+**MCP (Model Context Protocol)** servers allow you to extend ChatGPT and other LLMs with:
 - **Custom tools** (call external APIs)
 - **Real-time data** (up-to-date information)
 
@@ -171,10 +176,13 @@ npm test
 npm run test:watch
 ```
 
-63 tests across 3 suites:
+90 tests across 6 suites:
 - `errors.test.ts` — Error classes, formatting, network detection (17 tests)
 - `config.test.ts` — Environment variables, validation, singleton (20 tests)
 - `displayGeoJsonMap.test.ts` — GeoJSON parsing, viewport, colors, output (26 tests)
+- `geohash.test.ts` — Geohash encode/decode, roundtrip, precision (12 tests)
+- `haversine.test.ts` — Haversine distance formula, edge cases, symmetry (8 tests)
+- `calculateDistance.test.ts` — Distance tool validation, output format (7 tests)
 
 ---
 
@@ -357,9 +365,13 @@ mcp-location/
 │   ├── tools/
 │   │   ├── searchAddress.ts     # Tool: adresse → GPS
 │   │   ├── reverseGeocode.ts    # Tool: GPS → adresse
+│   │   ├── encodeGeohash.ts     # Tool: GPS → geohash
+│   │   ├── decodeGeohash.ts     # Tool: geohash → GPS
+│   │   ├── calculateDistance.ts # Tool: distance entre 2 points
 │   │   ├── displayGeoJsonMap.ts # Tool: GeoJSON → widget UI
 │   │   └── __tests__/
-│   │       └── displayGeoJsonMap.test.ts
+│   │       ├── displayGeoJsonMap.test.ts
+│   │       └── calculateDistance.test.ts
 │   ├── resources/
 │   │   └── mapViewerTemplate.ts # Template HTML pour ChatGPT
 │   ├── servers/
@@ -367,8 +379,12 @@ mcp-location/
 │   │   └── http.ts              # Serveur Streamable HTTP (ChatGPT)
 │   ├── utils/
 │   │   ├── errors.ts            # Gestion erreurs centralisée
+│   │   ├── geohash.ts           # Encode/decode geohash (zero deps)
+│   │   ├── haversine.ts         # Distance Haversine (zero deps)
 │   │   └── __tests__/
-│   │       └── errors.test.ts
+│   │       ├── errors.test.ts
+│   │       ├── geohash.test.ts
+│   │       └── haversine.test.ts
 │   ├── index.ts                 # Entry point stdio
 │   ├── http-server.ts           # Entry point HTTP
 │   └── http-client.ts           # Client npm
@@ -459,7 +475,7 @@ This project serves as a **template/base** for future MCP servers with a clean,
 - **`client/`**: External API abstraction (Photon)
 - **`tools/`**: Business logic (validation, transformation, formatting)
 - **`servers/`**: MCP implementation (stdio/Streamable HTTP), reuses tools
-- **`utils/errors.ts`**: Custom error classes, formatting
+- **`utils/`**: Custom error classes, geohash encode/decode, Haversine distance (zero dependencies)
 
 See [CONTEXT.md](CONTEXT.md) for detailed architecture documentation.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shyzus/mcp-geocrafter",
-  "version": "1.3.0",
-  "description": "GeoCrafter - MCP server for geocoding and reverse geocoding - Powered by Nominatim API",
+  "version": "1.4.0",
+  "description": "GeoCrafter - MCP server for geocoding, reverse geocoding, geohash and distance calculation - Powered by Photon API",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -14,7 +14,10 @@
   "keywords": [
     "mcp",
     "geocoding",
-    "nominatim",
+    "photon",
+    "geohash",
+    "distance",
+    "haversine",
     "location",
     "address",
     "gps",