@shyzus/mcp-geocrafter 1.0.3 → 1.0.4

package/README.md

@@ -3,8 +3,8 @@
 GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Nominatim API (OpenStreetMap).
 
 [![Deploy Status](https://github.com/Shyzkanza/mcp-location/actions/workflows/deploy.yml/badge.svg)](https://github.com/Shyzkanza/mcp-location/actions/workflows/deploy.yml)
-[![npm version](https://img.shields.io/badge/npm-v1.0.2-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)
+[![npm version](https://img.shields.io/badge/npm-v1.0.4-blue)](https://www.npmjs.com/package/@shyzus/mcp-geocrafter)
+[![npm downloads](https://img.shields.io/npm/dm/@shyzus/mcp-geocrafter?cacheSeconds=3600)](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)
@@ -195,7 +195,9 @@ 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`
+**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
 
@@ -276,8 +278,9 @@ See the [Apps SDK deployment guide](https://developers.openai.com/apps-sdk/deplo
 #### **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)
+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](#-quick-start)
 
 ---
 
@@ -385,7 +388,7 @@ mcp-location/
 │   │   └── mapViewerTemplate.ts # Template HTML (text/html+skybridge) pour ChatGPT
 │   ├── servers/
 │   │   ├── stdio.ts           # Serveur stdio (IDEs)
-│   │   └── http.ts             # Serveur HTTP (ChatGPT)
+│   │   └── http.ts             # Serveur Streamable HTTP (ChatGPT)
 │   ├── utils/
 │   │   └── errors.ts           # Gestion erreurs centralisée
 │   ├── index.ts                # Entry point stdio
@@ -404,17 +407,43 @@ mcp-location/
 
 ## 🛠️ Available Commands
 
+> 📖 **Full documentation**: [COMMANDS.md](./COMMANDS.md)
+
+### Quick Reference
+
 ```bash
-# Development
-npm run dev              # Dev mode with hot-reload (stdio)
-npm run dev:http         # Dev mode HTTP server
+# 🌟 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
 
-# Production
+# Testing
+npm run inspect          # Launch MCP Inspector
+npm run health           # Health check
+
+# Build & Production
 npm run build            # Compile TypeScript
-npm run start            # Start stdio server
-npm run start:http       # Start HTTP server (port 3000)
+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](./COMMANDS.md) for the complete list.
+
 ---
 
 ## 🔧 Advanced Configuration
@@ -449,7 +478,7 @@ This project serves as a **template/base** for future MCP servers with a clean,
 - **`types.ts`**: Shared TypeScript interfaces
 - **`client/`**: External API abstraction (Nominatim)
 - **`tools/`**: Business logic (validation, transformation, formatting)
-- **`servers/`**: MCP implementation (stdio/HTTP), reuses tools
+- **`servers/`**: MCP implementation (stdio/Streamable HTTP), reuses tools
 - **`utils/errors.ts`**: Custom error classes, formatting
 
 See [CONTEXT.md](CONTEXT.md) for detailed architecture documentation.
@@ -458,6 +487,12 @@ See [CONTEXT.md](CONTEXT.md) for detailed architecture documentation.
 
 ## 📚 Resources & Documentation
 
+### Project Documentation
+
+- [CONTEXT.md](./CONTEXT.md) - Project memory (status, decisions, changelog)
+- [COMMANDS.md](./COMMANDS.md) - All npm scripts and Cursor commands
+- [OPENAI_APPS_SDK_REFERENCE.md](./OPENAI_APPS_SDK_REFERENCE.md) - Complete SDK reference guide
+
 ### Official documentation
 
 - [OpenAI Apps SDK](https://developers.openai.com/apps-sdk) - Complete ChatGPT Apps guide

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shyzus/mcp-geocrafter",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "GeoCrafter - MCP server for geocoding and reverse geocoding - Powered by Nominatim API",
   "type": "module",
   "main": "dist/index.js",
@@ -23,17 +23,28 @@
   },
   "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",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "rebuild": "npm run clean && npm run build",
+    "dev": "npm run kill --silent; tsx watch src/http-server.ts",
+    "dev:http": "npm run dev",
+    "dev:tunnel": "npm run kill:tunnel --silent; npm-run-all --parallel dev tunnel",
+    "start": "npm run kill --silent; node dist/http-server.js",
+    "start:http": "npm run start",
+    "build:start": "npm run build && npm run start",
+    "kill": "lsof -ti:${PORT:-3000} | xargs kill -9 2>/dev/null || true",
+    "kill:tunnel": "pkill -f ngrok 2>/dev/null || true",
+    "tunnel": "ngrok http ${PORT:-3000}",
+    "inspect": "npx @modelcontextprotocol/inspector@latest http://localhost:${PORT:-3000}/mcp",
+    "health": "curl -s http://localhost:${PORT:-3000}/health | jq .",
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.23.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "npm-run-all": "^4.1.5",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
   }