@shyzus/mcp-geocrafter 1.0.0

package/README.md

@@ -0,0 +1,530 @@
+# 🗺️ GeoCrafter - Geocoding Server for ChatGPT
+
+GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Nominatim API (OpenStreetMap).
+
+[![Deploy Status](https://github.com/rankorr/mcp-location/actions/workflows/deploy.yml/badge.svg)](https://github.com/rankorr/mcp-location/actions/workflows/deploy.yml)
+[![npm version](https://img.shields.io/badge/npm-v1.0.0-blue)](https://www.npmjs.com/package/@shyzus/mcp-geocrafter)
+[![npm downloads](https://img.shields.io/npm/dm/@shyzus/mcp-geocrafter)](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-18%2B-green)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)
+![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange)
+![ChatGPT](https://img.shields.io/badge/ChatGPT-Apps%20SDK-purple)
+
+---
+
+## ⚠️ Disclaimer
+
+**This project is independent and unofficial.**
+
+- ❌ **Not affiliated** with OpenStreetMap or Nominatim
+- ❌ **Not sponsored** by these organizations
+- ✅ Uses **public data** from the [Nominatim API](https://nominatim.openstreetmap.org/)
+- ✅ Educational and practical purpose project
+
+Geocoding data comes from the Nominatim API, which uses OpenStreetMap data.
+
+---
+
+## 🎯 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
+- 📍 **GPS to Address** - Convert coordinates to addresses
+- 🏗️ **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
+
+In ChatGPT, 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.
+
+---
+
+## 🏗️ Architecture: ChatGPT MCP App
+
+### What is a ChatGPT App?
+
+**ChatGPT Apps** (via [Apps SDK](https://developers.openai.com/apps-sdk)) allow you to extend ChatGPT with:
+- **Custom tools** (call external APIs)
+- **Real-time data** (up-to-date information)
+
+### How does it work?
+
+```
+┌─────────────┐         ┌──────────────┐         ┌──────────────┐
+│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │  Nominatim   │
+│             │  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
+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:
+
+```json
+{
+  "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
+
+```bash
+# 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
+```
+
+---
+
+## 📱 Deployment and Development
+
+> **🔒 CI/CD secrets configuration:** To automatically deploy to a VPS with GitHub Actions and Portainer, see [SECRETS.md](SECRETS.md) for GitHub secrets configuration.
+
+> **💡 To use the application in ChatGPT**, see the [🚀 Quick Start](#-quick-start) section above for complete instructions.
+
+### Option 1: Local Testing with ngrok (For development)
+
+#### 1. Start the HTTP server
+
+```bash
+npm run start:http
+```
+
+The server starts on `http://localhost:3000`
+
+#### 2. Expose with ngrok
+
+In a **new terminal**:
+
+```bash
+# 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 with `/mcp` at the end: `https://abc123.ngrok-free.dev/mcp`
+
+#### 3. Configure the application in ChatGPT
+
+Follow the configuration instructions in the [🚀 Quick Start](#-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](#-quick-start) section which uses the production server already available.
+
+This project includes a GitHub Actions workflow that automatically deploys to a VPS with Docker and Portainer.
+
+#### **VPS Deployment with GitHub Actions**
+
+1. **Configure GitHub secrets** according to [SECRETS.md](SECRETS.md)
+2. **Push to the `main` branch**
+3. GitHub Actions will automatically:
+   - ✅ Test TypeScript code
+   - ✅ Deploy to your VPS via Portainer
+   - ✅ Check health status
+
+**Benefits**:
+- Automatic deployment on each push
+- Free SSL with Traefik + Let's Encrypt
+- Integrated health monitoring
+- Centralized logs
+
+#### **Other cloud platforms**
+
+You can also deploy on:
+- **Railway** - Automatic deployment from GitHub
+- **Render** - Managed service with free SSL
+- **Fly.io** - Edge computing with global deployment
+- **Google Cloud Run** - Serverless with automatic scaling
+
+See the [Apps SDK deployment guide](https://developers.openai.com/apps-sdk/deploy) for more details.
+
+#### **Configure your server in ChatGPT**
+
+Once deployed:
+1. Note your server URL: `https://your-domain.com/mcp`
+2. Follow the instructions in [🚀 Quick Start](#-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](https://claude.ai/download)
+
+2. Configure in `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```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
+
+```bash
+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
+
+```json
+{
+  "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
+│   ├── client/
+│   │   └── nominatimClient.ts # Client API Nominatim
+│   ├── tools/
+│   │   ├── searchAddress.ts   # Tool: adresse → GPS
+│   │   ├── reverseGeocode.ts  # Tool: GPS → adresse
+│   │   └── displayGeoJsonMap.ts # Tool: GeoJSON → widget UI
+│   ├── resources/
+│   │   └── mapViewerTemplate.ts # Template HTML (text/html+skybridge) pour ChatGPT
+│   ├── servers/
+│   │   ├── stdio.ts           # Serveur stdio (IDEs)
+│   │   └── http.ts             # Serveur HTTP (ChatGPT)
+│   ├── utils/
+│   │   └── errors.ts           # Gestion erreurs centralisée
+│   ├── index.ts                # Entry point stdio
+│   ├── http-server.ts          # Entry point HTTP
+│   └── http-client.ts          # Client npm
+├── dist/                       # Compiled code (generated)
+├── Dockerfile                  # Multi-stage Docker image
+├── docker-compose.yml          # Stack with Traefik labels
+├── .github/workflows/deploy.yml # CI/CD pipeline
+├── package.json                # Server dependencies
+├── tsconfig.json               # TypeScript config
+└── README.md                   # This file
+```
+
+---
+
+## 🛠️ Available Commands
+
+```bash
+# Development
+npm run dev              # Dev mode with hot-reload (stdio)
+npm run dev:http         # Dev mode HTTP server
+
+# Production
+npm run build            # Compile TypeScript
+npm run start            # Start stdio server
+npm run start:http       # Start HTTP server (port 3000)
+```
+
+---
+
+## 🔧 Advanced Configuration
+
+### Environment variables
+
+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)
+CORS_ORIGIN=*                      # CORS origin (default: * in dev, https://chatgpt.com in prod)
+```
+
+### Customize the Nominatim 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`)
+
+---
+
+## 🏗️ 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 (Nominatim)
+- **`tools/`**: Business logic (validation, transformation, formatting)
+- **`servers/`**: MCP implementation (stdio/HTTP), reuses tools
+- **`utils/errors.ts`**: Custom error classes, formatting
+
+See [CONTEXT.md](CONTEXT.md) for detailed architecture documentation.
+
+---
+
+## 📚 Resources & Documentation
+
+### Official documentation
+
+- [OpenAI Apps SDK](https://developers.openai.com/apps-sdk) - Complete ChatGPT Apps guide
+- [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
+
+### Community
+
+- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Official examples
+- [OpenAI Apps Examples](https://github.com/openai/chatgpt-apps-examples) - App examples
+
+---
+
+## 🐛 Debugging & Troubleshooting
+
+### Server won't start
+
+```bash
+# Check that Node.js is installed
+node --version  # Must be 18+
+
+# 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`:
+
+```typescript
+res.setHeader('Access-Control-Allow-Origin', 'https://chatgpt.com');
+```
+
+### Logs
+
+Server logs display in the terminal. For more details:
+
+```typescript
+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 Nominatim 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** - [Nominatim API](https://nominatim.openstreetmap.org/) - 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).
+
+---
+
+## 📞 Support
+
+For any questions:
+- 📖 Check the [Apps SDK documentation](https://developers.openai.com/apps-sdk)
+- 💬 Open an issue on GitHub
+- 📧 Contact the team
+
+---
+
+**Have fun with your ChatGPT app! 📍✨**

package/dist/http-client.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * HTTP Client pour installation npm
+ *
+ * Point d'entrée pour npx @shyzus/mcp-geocrafter
+ * Démarre le serveur HTTP
+ */
+import { startHttpServer } from './servers/http.js';
+startHttpServer().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=http-client.js.map

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Entry point pour GeoCrafter stdio Server (IDEs)
+ *
+ * Délègue à src/servers/stdio.ts
+ */
+import { startStdioServer } from './servers/stdio.js';
+startStdioServer().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@shyzus/mcp-geocrafter",
+  "version": "1.0.0",
+  "description": "GeoCrafter - MCP server for geocoding and reverse geocoding - Powered by Nominatim API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-geocrafter": "dist/http-client.js"
+  },
+  "files": [
+    "dist/http-client.js",
+    "README.md"
+  ],
+  "keywords": ["mcp", "geocoding", "nominatim", "location", "address", "gps", "chatgpt"],
+  "author": "Rankorr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rankorr/mcp-location"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "dev:http": "tsx watch src/http-server.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http-server.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}
+