@shyzus/mcp-geocrafter 1.5.0 → 1.5.2

package/README.md

@@ -11,6 +11,8 @@ GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding wi
 ![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)
 
 ---
 
@@ -32,9 +34,9 @@ This application allows **ChatGPT** and other MCP clients to access geocoding se
 
 ### ✨ Features
 
-- 🔍 **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
+- 🔍 **Address to GPS** - `search_address_google` (recommended) + `search_address_photon` (fuzzy matching)
+- 📍 **GPS to Address** - `reverse_geocode_google` (recommended) + `reverse_geocode_photon`
+- 🔄 **Multi-Provider** - Dedicated tools per provider — the LLM picks the right one automatically
 - 🔗 **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
@@ -48,7 +50,7 @@ This application allows **ChatGPT** and other MCP clients to access geocoding se
 | **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").
+Each provider has its own dedicated tools — the LLM sees both options and picks the right one. Users can also force a provider (e.g. "use Google", "use Photon").
 
 ### 💬 Usage examples
 
@@ -105,24 +107,20 @@ 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
 {
   "mcpServers": {
     "mcp-geocrafter": {
       "command": "npx",
-      "args": ["-y", "@shyzus/mcp-geocrafter"],
-      "env": {
-        "GOOGLE_API_KEY": "your-google-api-key",
-        "GEOCODING_PROVIDER": "google"
-      }
+      "args": ["-y", "@shyzus/mcp-geocrafter"]
     }
   }
 }
 ```
 
-> `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.
+> 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)
@@ -131,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!
@@ -296,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": {
@@ -303,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"
+      }
     }
   }
 }
@@ -485,9 +520,12 @@ CORS_ORIGIN=*                      # CORS origin (default: * in dev, https://cha
 
 ### Providers configuration
 
-- **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.
+- **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.
+- Each provider has **dedicated tools** (`search_address_google`, `search_address_photon`, etc.) — no `provider` parameter needed.
+- The `apiKey` parameter on Google tools is never logged, never stored, never returned in responses.
 
 ---
 

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.5.0",
+  "version": "1.5.2",
   "description": "GeoCrafter - MCP server for geocoding, reverse geocoding, geohash and distance calculation - Powered by Photon API",
   "type": "module",
   "main": "dist/index.js",