@shyzus/mcp-geocrafter 1.4.0 → 1.5.0

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)
@@ -18,13 +18,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 +32,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 +77,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
 
@@ -99,12 +112,18 @@ MCP (Model Context Protocol) is an open standard created by Anthropic that allow
   "mcpServers": {
     "mcp-geocrafter": {
       "command": "npx",
-      "args": ["-y", "@shyzus/mcp-geocrafter"]
+      "args": ["-y", "@shyzus/mcp-geocrafter"],
+      "env": {
+        "GOOGLE_API_KEY": "your-google-api-key",
+        "GEOCODING_PROVIDER": "google"
+      }
     }
   }
 }
 ```
 
+> `GOOGLE_API_KEY` enables the Google provider. `GEOCODING_PROVIDER` sets the default (optional, defaults to `photon` if omitted). The LLM can override the provider per request.
+
 **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)
@@ -176,7 +195,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)
@@ -361,7 +381,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 +476,18 @@ 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**: Set `GOOGLE_API_KEY` to enable. Get a key from [Google Cloud Console](https://console.cloud.google.com) → APIs & Services → Credentials. Enable "Geocoding API" first.
+- **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.
 
 ---
 
@@ -472,7 +499,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 +605,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/package.json

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