🗺️ GeoCrafter - Geocoding Server for ChatGPT

GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Photon API (OpenStreetMap + Elasticsearch) with fuzzy matching support.

⚠️ Disclaimer

This project is independent and unofficial.

• ❌ Not affiliated with OpenStreetMap, Photon or Komoot
• ❌ Not sponsored by these organizations
• ✅ Uses public data from the Photon API (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?

This application allows ChatGPT and other MCP clients to access geocoding services with a clean, modular architecture that serves as a template for future MCP servers.

✨ Features

• 🔍 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 examples

In ChatGPT or your IDE, simply ask:

"What are the coordinates of the Eiffel Tower?"

"What is the address at coordinates 48.8566, 2.3522?"

"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: MCP Server

What is an MCP Server?

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)

How does it work?

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │   Photon     │
│             │  HTTP   │  (Node.js)   │  HTTP   │   API        │
└─────────────┘         └──────────────┘         └──────────────┘

1. ChatGPT calls your MCP server via the Model Context Protocol
2. The MCP server fetches data from the Photon API (OpenStreetMap + Elasticsearch)
3. The results are returned to ChatGPT

MCP Protocol

MCP (Model Context Protocol) is an open standard created by Anthropic that allows LLMs to access external data and tools securely. It is used by:

• ChatGPT (via Apps SDK)
• Claude Desktop
• Cursor
• Other MCP clients

🚀 Quick Start

Use with Cursor / Claude Desktop / Warp

The easiest way - Install the npm client that connects to the remote server:

{
  "mcpServers": {
    "mcp-geocrafter": {
      "command": "npx",
      "args": ["-y", "@shyzus/mcp-geocrafter"]
    }
  }
}

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)
• Warp: In Warp AI settings

Use with ChatGPT

A production server is available and ready to use!

Server URL: https://geocrafter.rankorr.red/mcp

ChatGPT Configuration

1. Have a ChatGPT account with subscription (ChatGPT Plus, Team, or Enterprise)
2. Open ChatGPT in your browser → Go to Settings (⚙️)
3. Go to "Apps & Connectors"
4. Enable developer mode:
   • In "Advanced Settings", enable developer mode
   • Go back
5. Create a new application:
   • The "Create" button now appears in the top right
   • Click on it
   • Fill in the form:
     • Name: "GeoCrafter" (or another name)
     • Image: Add an icon/image (optional)
     • Server URL: https://geocrafter.rankorr.red/mcp
     • Authentication: Select "None"
   • Click "Create"
6. The application is now available in ChatGPT and will activate automatically when you ask ChatGPT to use it

Test it!

Ask a question in ChatGPT:

"What are the coordinates of Paris, France?"

Or to test directly:

"Use GeoCrafter to find the address at coordinates 48.8566, 2.3522"

For developers - Local installation

# 1. Clone the project
git clone https://github.com/rankorr/mcp-location.git
cd mcp-location

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Use locally
npx @modelcontextprotocol/inspector node dist/index.js

🧪 Tests

# Run tests
npm test

# Watch mode
npm run test:watch

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)

📱 Deployment and Development

💡 To use the application in ChatGPT, see the 🚀 Quick Start section above for complete instructions.

Option 1: Local Testing with ngrok (For development)

1. Start the HTTP server

npm run start:http

The server starts on http://localhost:3000

2. Expose with ngrok

In a new terminal:

# Install ngrok if necessary
brew install ngrok  # macOS
# or download from https://ngrok.com/download

# Expose port 3000
ngrok http 3000

You get a public URL like:

https://abc123.ngrok-free.dev

Important:

• Note the complete URL: https://abc123.ngrok-free.dev/mcp (or just https://abc123.ngrok-free.dev/ - both work)
• The server uses Streamable HTTP transport (modern MCP standard, replaces deprecated SSE)

3. Configure the application in ChatGPT

Follow the configuration instructions in the 🚀 Quick Start section, using your ngrok URL (https://your-url.ngrok-free.dev/mcp) instead of the production URL.

Option 2: Deploy your own server (For developers)

Note: If you just want to use the application, see the 🚀 Quick Start section which uses the production server already available.

CI/CD Pipelines

Two GitHub Actions workflows:

• ci.yml — Runs on push/PR to main: type check, tests, build
• release.yml — Runs on tag push (*.*.*): tests → GHCR image → Docker Swarm deploy → health check → npm publish

Release Process

# 1. Bump version
npm version patch   # 1.0.5 → 1.0.6

# 2. Push with tags
git push origin main --tags

The tag push triggers release.yml which automatically:

• Builds & pushes the Docker image to GHCR
• Deploys to VPS via SSH + docker stack deploy
• Runs health check
• Publishes to npm (if version not already published)

Configure your server in ChatGPT

Once deployed:

1. Note your server URL: https://your-domain.com/mcp (or / - both endpoints work)
2. The server uses Streamable HTTP transport (modern MCP standard)
3. Follow the instructions in 🚀 Quick Start

🧪 Local Testing (without ChatGPT)

With Cursor (the IDE you're using)

The MCP server already works in Cursor! Ask me a question about locations and I'll use the server.

With Claude Desktop

1. Install Claude Desktop

2. Configure in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-geocrafter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-location/dist/index.js"
      ]
    }
  }
}

3. Restart Claude Desktop
4. The MCP icon 🔌 appears in the bottom left

With the MCP inspector

npx @modelcontextprotocol/inspector node dist/index.js

Opens a web interface to test all tools.

🗺️ GeoJSON Map Viewer (ChatGPT UI Tool)

display_geojson_map is a ChatGPT-only tool that returns an interactive Leaflet map embedded inside the conversation. It leverages the OpenAI Apps SDK widget runtime (text/html+skybridge) and ships with a dedicated template bundled in this repository.

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | geojson | object | string | ✅ | GeoJSON FeatureCollection to render. Accepts either a parsed object (recommended) or a JSON string for compatibility with ChatGPT prompts. | | title | string | ❌ | Custom title displayed above the map. Defaults to Carte GeoJSON. | | description | string | ❌ | Caption shown next to the title (e.g., context or instructions). | | highlightColor | string | ❌ | Hex color (e.g., #2563eb) applied to outlines, fills and markers. |

Output

• Inline widget rendered directly in ChatGPT with:
  • OpenStreetMap tiles + Leaflet overlay
  • Computed bounding box & auto-fit
  • Recentrer button
  • Agrandir button (toggles fullscreen inside ChatGPT, matching the requirement “option de l’ouvrir en grand”)
• Lightweight structuredContent summary exposed to the model (feature count, geometry types, bounds)
• Full GeoJSON stays inside _meta, so it is only consumed by the widget (keeps the model prompt small)

Example call

{
  "name": "display_geojson_map",
  "arguments": {
    "title": "Stations autour de Lyon",
    "description": "Résultats de places_nearby sur 5 km",
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [4.8357, 45.7640] },
          "properties": { "label": "Lyon Part-Dieu" }
        }
      ]
    }
  }
}

ℹ️ The stdio server (Cursor/Claude Desktop) ignores this tool, which is fine: it is explicitly designed for ChatGPT with UI widgets.

📂 Project Structure

mcp-location/
├── src/
│   ├── config.ts                # Configuration centralisée
│   ├── types.ts                 # Types TypeScript partagés
│   ├── __tests__/
│   │   └── config.test.ts       # Tests config
│   ├── client/
│   │   └── 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
│   │       └── calculateDistance.test.ts
│   ├── resources/
│   │   └── mapViewerTemplate.ts # Template HTML pour ChatGPT
│   ├── servers/
│   │   ├── stdio.ts             # Serveur stdio (IDEs)
│   │   └── 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
│   │       ├── geohash.test.ts
│   │       └── haversine.test.ts
│   ├── index.ts                 # Entry point stdio
│   ├── http-server.ts           # Entry point HTTP
│   └── http-client.ts           # Client npm
├── .github/workflows/
│   ├── ci.yml                   # CI: tests on push/PR
│   └── release.yml              # Release: GHCR + deploy + npm
├── Dockerfile                   # Multi-stage Docker (node:20-alpine)
├── docker-compose.yml           # Docker Swarm stack
├── vitest.config.ts             # Vitest configuration
├── package.json
├── tsconfig.json
└── README.md

🛠️ Available Commands

📖 Full documentation: COMMANDS.md

Quick Reference

# 🌟 Recommended for ChatGPT development (2 terminals)
npm run tunnel           # Terminal 1: ngrok (keep running)
npm run dev              # Terminal 2: Dev server with hot-reload

# Alternative: All-in-one
npm run dev:tunnel       # Dev + ngrok in parallel

# Testing
npm run inspect          # Launch MCP Inspector
npm run health           # Health check

# Build & Production
npm run build            # Compile TypeScript
npm run rebuild          # Clean + Build
npm run build:start      # Build then start

# Utilities
npm run kill             # Kill process on port 3000
npm run kill:tunnel      # Kill ngrok

Cursor Commands

Available via Cmd+Shift+P:

• dev-server - Dev with hot-reload (recommended)
• tunnel-only - Launch ngrok (keep running)
• mcp-inspector - Launch MCP Inspector
• build / rebuild / clean
• kill-server / kill-tunnel

See COMMANDS.md for the complete list.

🔧 Advanced Configuration

Environment variables

Create a .env file:

PORT=3000                          # HTTP server port
NODE_ENV=production                # Environment
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

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)

🏗️ Architecture Details

This project serves as a template/base for future MCP servers with a clean, modular architecture:

Separation of Concerns

• config.ts: Environment variables, constants, validation
• types.ts: Shared TypeScript interfaces
• client/: External API abstraction (Photon)
• 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)

See CONTEXT.md for detailed architecture documentation.

📚 Resources & Documentation

Project Documentation

• CONTEXT.md - Project memory (status, decisions, changelog)
• COMMANDS.md - All npm scripts and Cursor commands
• OPENAI_APPS_SDK_REFERENCE.md - Complete SDK reference guide

Official documentation

• OpenAI Apps SDK - Complete ChatGPT Apps guide
• Apps SDK - MCP Server - Server config
• Model Context Protocol - MCP spec
• MCP SDK TypeScript - Node.js SDK
• Photon API - Geocoding API (OpenStreetMap + Elasticsearch)

Community

• MCP Servers Repository - Official examples
• OpenAI Apps Examples - App examples

🐛 Debugging & Troubleshooting

Server won't start

# Check that Node.js is installed
node --version  # Must be 20+

# Check that dependencies are installed
npm install

# Full rebuild
npm run build

UI doesn't display in ChatGPT

1. Check ngrok logs - See if ChatGPT is making requests
2. Check the server - http://localhost:3000/health must respond
3. Refresh the connector in ChatGPT (Settings → Apps → Refresh)
4. Check the CORS - Allowed domains in src/servers/http.ts

CORS errors

The server allows all origins in dev. In production, restrict in src/servers/http.ts:

res.setHeader('Access-Control-Allow-Origin', 'https://chatgpt.com');

Logs

Server logs display in the terminal. For more details:

console.log('MCP Request:', jsonRpcRequest.method);

🚀 Use This Project as a Template

This project is a complete template for creating your own ChatGPT apps with a clean architecture.

To create your own app:

1. Duplicate this project
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!

Possible app examples

• 🎬 Cinema - Movie search and showtimes
• 🍽️ Restaurants - Reservations with menu
• 🏨 Hotels - Search and availability
• 📦 Delivery - Package tracking
• 📰 News - Articles with integrated reader
• 🎵 Music - Audio player in ChatGPT
• 📊 Analytics - Charts and dashboards

The possibilities are endless! 🚀

📝 License

MIT - Use freely for your personal or commercial projects.

🙏 Credits & Attributions

• Geocoding Data - Photon API by Komoot - OpenStreetMap data
• MCP Protocol - Anthropic
• Apps SDK - OpenAI

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).

📞 Support

For any questions:

• 📖 Check the Apps SDK documentation
• 💬 Open an issue on GitHub
• 📧 Contact the team

Have fun with your ChatGPT app! 📍✨