@shyzus/mcp-geocrafter 1.4.1 → 1.5.1

package/README.md

@@ -1,6 +1,6 @@
-# 🗺️ GeoCrafter - Geocoding Server for ChatGPT
+# 🗺️ GeoCrafter - Multi-Provider Geocoding MCP Server
 
-GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Photon API (OpenStreetMap + Elasticsearch) with fuzzy matching support.
+GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding with **multi-provider support** — Google Geocoding API and Photon API (OpenStreetMap). The LLM intelligently picks the best provider per query, or the user can force one.
 
 [![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)
@@ -11,6 +11,8 @@ GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding -
 ![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-MCP-purple)
+![Google](https://img.shields.io/badge/Google%20Geocoding-supported-4285F4)
+![Photon](https://img.shields.io/badge/Photon%20OSM-supported-7EB900)
 
 ---
 
@@ -18,13 +20,12 @@ GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding -
 
 **This project is independent and unofficial.**
 
-- ❌ **Not affiliated** with OpenStreetMap, Photon or Komoot
+- ❌ **Not affiliated** with Google, OpenStreetMap, Photon or Komoot
 - ❌ **Not sponsored** by these organizations
+- ✅ Uses [Google Geocoding API](https://developers.google.com/maps/documentation/geocoding) (10k free requests/month)
 - ✅ Uses **public data** from the [Photon API](https://photon.komoot.io/) (OpenStreetMap)
 - ✅ Educational and practical purpose project
 
-Geocoding data comes from the Photon API (by Komoot), which uses OpenStreetMap data with Elasticsearch-powered fuzzy matching.
-
 ---
 
 ## 🎯 What is it?
@@ -33,14 +34,24 @@ This application allows **ChatGPT** and other MCP clients to access geocoding se
 
 ### ✨ Features
 
-- 🔍 **Address to GPS** - Convert addresses to coordinates (fuzzy matching)
+- 🔍 **Address to GPS** - Convert addresses to coordinates with multi-provider support
 - 📍 **GPS to Address** - Convert coordinates to addresses
+- 🔄 **Multi-Provider** - Google Geocoding API + Photon API (OpenStreetMap), selectable per request
 - 🔗 **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)
 
+### 🔄 Providers
+
+| Provider | Best for | Limitations |
+|----------|----------|-------------|
+| **Google** (recommended) | POIs, businesses, intent-based queries ("gare ales france") | Requires API key, 10k free/month |
+| **Photon** | Typo-tolerant search on place/street names, no API key needed | Less accurate on POI resolution |
+
+The LLM automatically picks the best provider based on query type, or the user can force one (e.g. "use Google", "use Photon").
+
 ### 💬 Usage examples
 
 In ChatGPT or your IDE, simply ask:
@@ -68,15 +79,19 @@ The LLM will use the MCP server to get the information.
 ### How does it work?
 
 ```
-┌─────────────┐         ┌──────────────┐         ┌──────────────┐
-│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │   Photon     │
-│             │  HTTP   │  (Node.js)   │  HTTP   │   API        │
-└─────────────┘         └──────────────┘         └──────────────┘
+                                                  ┌──────────────┐
+                                           ┌────► │   Google     │
+┌─────────────┐         ┌──────────────┐   │      │   Geocoding  │
+│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─┤      └──────────────┘
+│   / IDE     │  MCP    │  (Node.js)   │   │      ┌──────────────┐
+└─────────────┘         └──────────────┘   └────► │   Photon     │
+                                                  │   API (OSM)  │
+                                                  └──────────────┘
 ```
 
-1. **ChatGPT** calls your MCP server via the [Model Context Protocol](https://modelcontextprotocol.io/)
-2. **The MCP server** fetches data from the Photon API (OpenStreetMap + Elasticsearch)
-3. **The results** are returned to ChatGPT
+1. **ChatGPT/IDE** calls your MCP server via the [Model Context Protocol](https://modelcontextprotocol.io/)
+2. **The MCP server** routes the request to the selected geocoding provider (Google or Photon)
+3. **The results** are returned in a unified format
 
 ### MCP Protocol
 
@@ -92,7 +107,7 @@ MCP (Model Context Protocol) is an open standard created by Anthropic that allow
 
 ### Use with Cursor / Claude Desktop / Warp
 
-**The easiest way** - Install the npm client that connects to the remote server:
+**The easiest way** - Install the npm client that connects to the remote server (Google + Photon providers are both available server-side):
 
 ```json
 {
@@ -105,6 +120,8 @@ MCP (Model Context Protocol) is an open standard created by Anthropic that allow
 }
 ```
 
+> This connects to the hosted server at `https://geocrafter.rankorr.red/mcp` which has both Google and Photon providers configured. The LLM picks the best provider per query, or the user can force one.
+
 **Config file locations:**
 - **Cursor**: `~/.cursor/mcp.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp.json` (Windows)
 - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
@@ -112,6 +129,26 @@ MCP (Model Context Protocol) is an open standard created by Anthropic that allow
 
 ---
 
+### Google API Key Setup
+
+To use the Google provider, you need a Google API key. There are **two ways** to provide it:
+
+**Option A — Server-side (env var):** Set `GOOGLE_API_KEY` on the server. All clients benefit automatically.
+
+**Option B — Per-request (tool parameter):** Pass `apiKey` in the tool call. Useful for N8N, automation workflows, or when you don't control the server. The key is never logged or returned in responses.
+
+**To get a key:**
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create or select a project
+3. **APIs & Services** → **Library** → search **"Geocoding API"** → **Enable**
+4. **APIs & Services** → **Credentials** → **Create Credentials** → **API Key**
+5. Copy the key
+
+> **Pricing**: First 10,000 requests/month are **free**. Beyond that, ~4.34€/1k requests. [Details](https://developers.google.com/maps/documentation/geocoding/usage-and-billing)
+
+---
+
 ### Use with ChatGPT
 
 A production server is available and ready to use!
@@ -176,7 +213,8 @@ npm test
 npm run test:watch
 ```
 
-90 tests across 6 suites:
+113 tests across 7 suites:
+- `googleClient.test.ts` — Google Geocoding API client, mapping, error handling (23 tests)
 - `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)
@@ -276,6 +314,19 @@ The MCP server already works in Cursor! Ask me a question about locations and I'
 
 2. Configure in `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
+**Option A — Use the remote server (recommended, no API key needed):**
+```json
+{
+  "mcpServers": {
+    "mcp-geocrafter": {
+      "command": "npx",
+      "args": ["-y", "@shyzus/mcp-geocrafter"]
+    }
+  }
+}
+```
+
+**Option B — Run locally with your own Google API key:**
 ```json
 {
   "mcpServers": {
@@ -283,7 +334,11 @@ The MCP server already works in Cursor! Ask me a question about locations and I'
       "command": "node",
       "args": [
         "/absolute/path/to/mcp-location/dist/index.js"
-      ]
+      ],
+      "env": {
+        "GOOGLE_API_KEY": "your-google-api-key",
+        "GEOCODING_PROVIDER": "google"
+      }
     }
   }
 }
@@ -361,7 +416,12 @@ mcp-location/
 │   ├── __tests__/
 │   │   └── config.test.ts       # Tests config
 │   ├── client/
-│   │   └── photonClient.ts      # Client API Photon (fuzzy matching)
+│   │   ├── types.ts             # GeocodingProvider interface
+│   │   ├── index.ts             # Provider factory/registry
+│   │   ├── googleClient.ts      # Google Geocoding API client
+│   │   ├── photonClient.ts      # Photon API client (OSM fuzzy matching)
+│   │   └── __tests__/
+│   │       └── googleClient.test.ts
 │   ├── tools/
 │   │   ├── searchAddress.ts     # Tool: adresse → GPS
 │   │   ├── reverseGeocode.ts    # Tool: GPS → adresse
@@ -451,16 +511,21 @@ Create a `.env` file:
 ```bash
 PORT=3000                          # HTTP server port
 NODE_ENV=production                # Environment
+GEOCODING_PROVIDER=google          # Default provider: "photon" (default) or "google"
+GOOGLE_API_KEY=AIzaSy...           # Required for Google provider (10k free requests/month)
 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 Photon API
+### Providers configuration
 
-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`)
+- **Google**: Two options to provide the API key:
+  - **Server-side**: Set `GOOGLE_API_KEY` environment variable — all clients benefit automatically
+  - **Per-request**: Pass `apiKey` parameter in the tool call — for N8N, automations, or when you don't control the server
+- **Photon**: Always available, no configuration needed. You can optionally self-host (set `PHOTON_BASE_URL`).
+- The `provider` parameter on `search_address` and `reverse_geocode` tools lets the LLM override the default per request.
+- The `apiKey` parameter is never logged, never stored, never returned in responses.
 
 ---
 
@@ -472,7 +537,7 @@ 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 (Photon)
+- **`client/`**: External API abstraction (Google, Photon) with provider interface + factory
 - **`tools/`**: Business logic (validation, transformation, formatting)
 - **`servers/`**: MCP implementation (stdio/Streamable HTTP), reuses tools
 - **`utils/`**: Custom error classes, geohash encode/decode, Haversine distance (zero dependencies)
@@ -578,13 +643,14 @@ MIT - Use freely for your personal or commercial projects.
 
 ## 🙏 Credits & Attributions
 
-- **Geocoding Data** - [Photon API](https://photon.komoot.io/) by [Komoot](https://www.komoot.com/) - OpenStreetMap data
+- **Geocoding Data** - [Google Geocoding API](https://developers.google.com/maps/documentation/geocoding) and [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 Photon API (by Komoot) which uses OpenStreetMap data. This data is provided under the Open Database License (ODbL).
+- Google Geocoding data is provided under [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms)
+- Photon/OpenStreetMap data is provided under the Open Database License (ODbL)
 
 ---
 

package/dist/http-client.js

@@ -6,7 +6,7 @@ const SERVER_URL = process.argv[2] || 'https://geocrafter.rankorr.red/mcp';
 // Proxy HTTP MCP server to stdio for Cursor
 const server = new McpServer({
     name: 'geocrafter-http-proxy',
-    version: '1.0.5',
+    version: '1.5.0',
 });
 // Forward all requests to HTTP server
 async function forwardRequest(method, params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shyzus/mcp-geocrafter",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "GeoCrafter - MCP server for geocoding, reverse geocoding, geohash and distance calculation - Powered by Photon API",
   "type": "module",
   "main": "dist/index.js",