@shyzus/mcp-geocrafter 1.2.3 → 1.4.0

package/README.md

@@ -1,15 +1,16 @@
 # 🗺️ GeoCrafter - Geocoding Server for ChatGPT
 
-GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Nominatim API (OpenStreetMap).
+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)
 
 ---
 
@@ -17,12 +18,12 @@ GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding -
 
 **This project is independent and unofficial.**
 
-- ❌ **Not affiliated** with OpenStreetMap or Nominatim
+- ❌ **Not affiliated** with OpenStreetMap, Photon or Komoot
 - ❌ **Not sponsored** by these organizations
-- ✅ Uses **public data** from the [Nominatim API](https://nominatim.openstreetmap.org/)
+- ✅ Uses **public data** from the [Photon API](https://photon.komoot.io/) (OpenStreetMap)
 - ✅ Educational and practical purpose project
 
-Geocoding data comes from the Nominatim API, which uses OpenStreetMap data.
+Geocoding data comes from the Photon API (by Komoot), which uses OpenStreetMap data with Elasticsearch-powered fuzzy matching.
 
 ---
 
@@ -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)
 
@@ -64,13 +69,13 @@ ChatGPT will use the MCP server to get the information.
 
 ```
 ┌─────────────┐         ┌──────────────┐         ┌──────────────┐
-│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │  Nominatim   │
-│             │  HTTP   │  (Node.js)   │  HTTP   │  API         │
+│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │   Photon     │
+│             │  HTTP   │  (Node.js)   │  HTTP   │   API        │
 └─────────────┘         └──────────────┘         └──────────────┘
 ```
 
 1. **ChatGPT** calls your MCP server via the [Model Context Protocol](https://modelcontextprotocol.io/)
-2. **The MCP server** fetches data from the Nominatim API
+2. **The MCP server** fetches data from the Photon API (OpenStreetMap + Elasticsearch)
 3. **The results** are returned to ChatGPT
 
 ### MCP Protocol
@@ -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)
 
 ---
 
@@ -353,13 +361,17 @@ mcp-location/
 │   ├── __tests__/
 │   │   └── config.test.ts       # Tests config
 │   ├── client/
-│   │   └── nominatimClient.ts   # Client API Nominatim
+│   │   └── photonClient.ts      # Client API Photon (fuzzy matching)
 │   ├── 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
@@ -435,16 +451,16 @@ Create a `.env` file:
 ```bash
 PORT=3000                          # HTTP server port
 NODE_ENV=production                # Environment
-NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org  # Optional
-NOMINATIM_USER_AGENT=MyApp/1.0    # Optional (recommended by Nominatim)
+PHOTON_BASE_URL=https://photon.komoot.io  # Optional (default: Komoot's public instance)
+USER_AGENT=MyApp/1.0              # Optional
 CORS_ORIGIN=*                      # CORS origin (default: * in dev, https://chatgpt.com in prod)
 ```
 
-### Customize the Nominatim API
+### Customize the Photon API
 
-The Nominatim API is public but you can:
-1. Use a custom instance (set `NOMINATIM_BASE_URL`)
-2. Set a custom User-Agent (recommended, set `NOMINATIM_USER_AGENT`)
+The Photon API is public but you can:
+1. Use a self-hosted Photon instance (set `PHOTON_BASE_URL`)
+2. Set a custom User-Agent (set `USER_AGENT`)
 
 ---
 
@@ -456,10 +472,10 @@ This project serves as a **template/base** for future MCP servers with a clean,
 
 - **`config.ts`**: Environment variables, constants, validation
 - **`types.ts`**: Shared TypeScript interfaces
-- **`client/`**: External API abstraction (Nominatim)
+- **`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.
 
@@ -479,7 +495,7 @@ See [CONTEXT.md](CONTEXT.md) for detailed architecture documentation.
 - [Apps SDK - MCP Server](https://developers.openai.com/apps-sdk/build/mcp-server) - Server config
 - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP spec
 - [MCP SDK TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) - Node.js SDK
-- [Nominatim API](https://nominatim.org/release-docs/develop/api/Overview/) - Geocoding API docs
+- [Photon API](https://photon.komoot.io/) - Geocoding API (OpenStreetMap + Elasticsearch)
 
 ### Community
 
@@ -535,7 +551,7 @@ This project is a **complete template** for creating your own ChatGPT apps with
 ### To create your own app:
 
 1. **Duplicate this project**
-2. **Replace the Nominatim API** with your API
+2. **Replace the Photon API** with your API
 3. **Modify the tools** in `src/tools/`
 4. **Customize the configuration** in `src/config.ts`
 5. **Deploy**!
@@ -562,13 +578,13 @@ MIT - Use freely for your personal or commercial projects.
 
 ## 🙏 Credits & Attributions
 
-- **Geocoding Data** - [Nominatim API](https://nominatim.openstreetmap.org/) - OpenStreetMap data
+- **Geocoding Data** - [Photon API](https://photon.komoot.io/) by [Komoot](https://www.komoot.com/) - OpenStreetMap data
 - **MCP Protocol** - [Anthropic](https://www.anthropic.com/)
 - **Apps SDK** - [OpenAI](https://openai.com/)
 
 ### Data & Licenses
 
-Geocoding data comes from the Nominatim API which uses OpenStreetMap data. This data is provided under the Open Database License (ODbL).
+Geocoding data comes from the Photon API (by Komoot) which uses OpenStreetMap data. This data is provided under the Open Database License (ODbL).
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shyzus/mcp-geocrafter",
-  "version": "1.2.3",
-  "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",