openrouteservice-mcp 1.0.0 → 1.0.2

package/README.md

@@ -4,10 +4,29 @@ Query OpenRouteService (free key; set OPENROUTESERVICE_API_KEY): geocode, revers
 
 ## Tools
 
-- `geocode` — Forward geocode a place name.
-- `reverse` — Place name for coordinates.
-- `directions` — Car route between two points.
+- `geocode` — Coordinates for a place name, e.g. Berlin.
+- `reverse` — Nearest place name for latitude and longitude.
+- `directions` — Driving route between two points, with distance and time.
 
 ## Source
 
 [openrouteservice-mcp](https://github.com/mrfentmen/premium-mcps/tree/main/servers/openrouteservice-mcp)
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a licence key:
+
+* `osrm_route_steps`
+* `valhalla_mode_compare`
+
+The tool bodies run on our gateway, not inside this package, so the key is what buys access. Buy one at https://buy.polar.sh/polar_cl_mrO7rS5LZxpqM7oAFFEA10i9121J240U40IIj4JRZO4 and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "polar_..." }
+```
+
+The gateway checks the key against Polar and gives every key 1,000 free premium
+calls a month before per-call billing starts. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -5,3 +5,10 @@ export declare function errorMessage(e: unknown): string;
 export declare function geocode(query: string, limit?: string): Promise<string>;
 export declare function reverse(lat: string, lon: string): Promise<string>;
 export declare function directions(fromLon: string, fromLat: string, toLon: string, toLat: string): Promise<string>;
+/** Geocode against OpenStreetMap itself, so you can see how the answer moves between geocoders. */
+export declare function nominatimLookup(args: {
+    query?: string;
+    lat?: number;
+    lon?: number;
+    limit?: number;
+}): Promise<string>;

package/dist/api.js

@@ -57,3 +57,93 @@ export async function directions(fromLon, fromLat, toLon, toLat) {
         throw new OrsError(`HTTP ${res.status}: ${text.slice(0, 300)}`);
     return text.slice(0, 8000);
 }
+// ---- muxG tools:
+const ORS_NOMINATIM = "https://nominatim.openstreetmap.org";
+const ORS_OSRM = "https://router.project-osrm.org";
+const ORS_VALHALLA = "https://valhalla1.openstreetmap.de";
+const ORS_UA = "awesome-mcps/1.0 (mcp routing)";
+const ORS_LIST_CAP = 8;
+async function orsFetch(url, init = {}) {
+    const res = await fetch(url, {
+        ...init,
+        headers: { "User-Agent": ORS_UA, Accept: "application/json", ...(init.headers ?? {}) },
+        signal: AbortSignal.timeout(30000),
+    });
+    if (res.status === 429)
+        throw new OrsError("OpenStreetMap Nominatim is rate limiting this IP. Its public instance allows at most one request a second, so wait a moment and try again.");
+    if (res.status === 404)
+        throw new OrsError("The routing backend has no answer for that point.");
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 200);
+        throw new OrsError(`Returned ${res.status}: ${body}`);
+    }
+    return (await res.json());
+}
+function orsBound(value, min, max, fallback) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(Math.floor(n), max));
+}
+function orsMetres(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(2)} km` : `${Math.round(n)} m`;
+}
+function orsDuration(seconds) {
+    const m = Math.round(seconds / 60);
+    if (m < 60)
+        return `${m} min`;
+    return `${Math.floor(m / 60)} h ${m % 60} min`;
+}
+/** Geocode against OpenStreetMap itself, so you can see how the answer moves between geocoders. */
+export async function nominatimLookup(args) {
+    const limit = orsBound(args?.limit, 1, ORS_LIST_CAP, 5);
+    const hasCoords = args?.lat !== undefined && args.lon !== undefined;
+    const hasQuery = String(args?.query ?? "").trim().length > 0;
+    if (!hasCoords && !hasQuery)
+        throw new OrsError("Give a query to look up, or a lat and lon to reverse geocode.");
+    let url;
+    let direction;
+    if (hasCoords) {
+        const lat = Number(args.lat);
+        const lon = Number(args.lon);
+        if (!Number.isFinite(lat) || Math.abs(lat) > 90)
+            throw new OrsError(`"${args.lat}" is not a latitude between -90 and 90.`);
+        if (!Number.isFinite(lon) || Math.abs(lon) > 180)
+            throw new OrsError(`"${args.lon}" is not a longitude between -180 and 180.`);
+        const zoom = orsBound(args.limit, 1, 18, 18);
+        url = `${ORS_NOMINATIM}/reverse?format=jsonv2&lat=${lat}&lon=${lon}&zoom=${zoom}&addressdetails=1&namedetails=1`;
+        direction = `Reverse geocode of ${lat}, ${lon} at zoom ${zoom}`;
+    }
+    else {
+        url = `${ORS_NOMINATIM}/search?format=jsonv2&addressdetails=1&namedetails=1&limit=${limit}&q=${encodeURIComponent(String(args.query).trim())}`;
+        direction = `Forward geocode of "${String(args.query).trim()}" in OpenStreetMap`;
+    }
+    const raw = await orsFetch(url);
+    const rows = Array.isArray(raw) ? raw : [raw];
+    if (!rows.length || !rows[0]?.display_name) {
+        return [
+            `${direction}`,
+            "OpenStreetMap returned nothing.",
+            "No match usually means the name is missing from OSM, is spelled differently, or is a building rather than an address. Try a coarser place name, or the postcode.",
+        ].join("\n");
+    }
+    return [
+        direction,
+        `${rows.length} result(s) from Nominatim, OpenStreetMap's own geocoder`,
+        "",
+        ...rows.map((r, i) => {
+            const addr = r.address ?? {};
+            const named = Object.entries(addr).filter(([k]) => !["country_code", "country", "state", "county", "municipality", "city_district", "ISO3166-2-lvl4"].includes(k)).slice(0, 6);
+            return [
+                `${i + 1}. ${r.name ?? "(no name)"} — ${r.display_name}`,
+                `   ${r.lat}, ${r.lon} | OSM ${r.osm_type ?? "?"}/${r.osm_id ?? "?"} | place id ${r.place_id ?? "not reported"}`,
+                `   classified as ${r.category ?? "not reported"}/${r.type ?? "not reported"} (address type ${r.addresstype ?? "not reported"})`,
+                r.importance !== undefined ? `   importance ${Number(r.importance).toFixed(4)}` : "",
+                named.length ? `   address parts: ${named.map(([k, v]) => `${k}=${v}`).join(", ")}` : "   address parts: not reported",
+                r.boundingbox ? `   bounding box: ${r.boundingbox.join(", ")}` : "",
+            ].filter(Boolean).join("\n");
+        }),
+        "",
+        "This is a different geocoder from the one this server's other tools use, and they will disagree: Nominatim ranks by OpenStreetMap importance, while a commercial geocoder ranks by its own address database. A pin that moves between them is usually a boundary or a duplicated feature, not a bug in either.",
+    ].filter(Boolean).join("\n");
+}

package/dist/gateway.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export declare class GatewayError extends Error {
+    readonly refused: boolean;
+    constructor(message: string, refused: boolean);
+}
+export declare function premiumTool(tool: string, args: Record<string, unknown>): Promise<string>;

package/dist/gateway.js

@@ -0,0 +1,85 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+const DEFAULT_GATEWAY_URL = 'https://mcp-gateway.contactae2000.workers.dev/mcp';
+const DEFAULT_TIMEOUT_MS = 25000;
+const USER_AGENT = 'mrfentmen-mcp/1.0';
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export class GatewayError extends Error {
+    refused;
+    constructor(message, refused) {
+        super(message);
+        this.refused = refused;
+        this.name = 'GatewayError';
+    }
+}
+export async function premiumTool(tool, args) {
+    const key = (process.env.MCP_LICENSE_KEY ?? '').trim();
+    if (!key) {
+        throw new GatewayError(`"${tool}" is a premium tool and no licence key is set. Set MCP_LICENSE_KEY in your MCP client config.`, true);
+    }
+    const url = (process.env.MCP_GATEWAY_URL ?? DEFAULT_GATEWAY_URL).trim();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+                authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: { name: tool, arguments: args },
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway. Check your connection and try again.`, false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway (HTTP ${response.status}).`, false);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new GatewayError(`"${tool}" got an unreadable answer from the licence gateway.`, false);
+    }
+    if (body.error) {
+        throw new GatewayError(`"${tool}" was refused by the licence gateway: ${body.error.message ?? 'unknown error'}`, false);
+    }
+    const result = body.result ?? {};
+    const text = (result.content ?? [])
+        .map((part) => part.text ?? '')
+        .join('\n')
+        .trim();
+    if (result.isError) {
+        // The gateway marks a licence refusal structurally, so a missing or rejected
+        // key is told apart from a tool that failed after the gate let it through.
+        if (result.structuredContent?.licenceRefusal) {
+            throw new GatewayError(text || `"${tool}" needs a valid licence key.`, true);
+        }
+        throw new GatewayError(text || `"${tool}" failed on the licence gateway.`, false);
+    }
+    if (!text)
+        throw new GatewayError(`"${tool}" returned no data.`, false);
+    return text;
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { errorMessage, geocode, reverse, directions, } from "./api.js";
+import { errorMessage, geocode, reverse, directions, nominatimLookup } from "./api.js";
+import { premiumTool } from "./gateway.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -11,7 +12,7 @@ export function createServer() {
     });
     server.registerTool("geocode", {
         title: "Geocode",
-        description: "Forward geocode a place name.",
+        description: "Coordinates for a place name, e.g. Berlin.",
         inputSchema: z.object({
             query: z.string().describe("Place name, e.g. Berlin."),
             limit: z.string().describe("Max results (default 5, max 20).").optional()
@@ -27,10 +28,10 @@ export function createServer() {
     });
     server.registerTool("reverse", {
         title: "Reverse geocode",
-        description: "Place name for coordinates.",
+        description: "Nearest place name for latitude and longitude.",
         inputSchema: z.object({
-            lat: z.string().describe("Latitude."),
-            lon: z.string().describe("Longitude.")
+            lat: z.string().describe("Latitude, e.g. 48.86"),
+            lon: z.string().describe("Longitude, e.g. 2.35")
         }),
         annotations: READ_ONLY,
     }, async ({ lat, lon }) => {
@@ -43,7 +44,7 @@ export function createServer() {
     });
     server.registerTool("directions", {
         title: "Driving directions",
-        description: "Car route between two points.",
+        description: "Driving route between two points, with distance and time.",
         inputSchema: z.object({
             from_lon: z.string().describe("Origin longitude."),
             from_lat: z.string().describe("Origin latitude."),
@@ -59,5 +60,67 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("nominatim_lookup", {
+        title: "Nominatim lookup",
+        description: "Geocode against OpenStreetMap's own Nominatim instead of the commercial geocoder, forward or reverse: display name, coordinates, OSM object type and id, place id, how Nominatim classifies the feature, importance score, address parts and bounding box, so you can see how the answer differs from another geocoder.",
+        inputSchema: z.object({
+            query: z.string().describe("What to look up, e.g. 'Eiffel Tower' or a postcode.").optional(),
+            lat: z.number().describe("Latitude, for a reverse lookup.").optional(),
+            lon: z.number().describe("Longitude, for a reverse lookup.").optional(),
+            limit: z.number().describe("Results to show, 1-8. For a reverse lookup this is the zoom level.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await nominatimLookup(args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("osrm_route_steps", {
+        title: "OSRM route steps",
+        description: "A road route from OSRM over OpenStreetMap data with turn-by-turn instructions and alternatives: distance, estimated time, the named roads used, and each manoeuvre with its modifier, type and instruction. A different router on different data from this server's directions tool.",
+        inputSchema: z.object({
+            from_lat: z.number().describe("Origin latitude."),
+            from_lon: z.number().describe("Origin longitude."),
+            to_lat: z.number().describe("Destination latitude."),
+            to_lon: z.number().describe("Destination longitude."),
+            alternatives: z.boolean().describe("Ask for alternative routes, default true.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: osrm_route_steps ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_openrouteservice_osrm_route_steps", args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("valhalla_mode_compare", {
+        title: "Valhalla mode compare",
+        description: "The same origin and destination costed by several Valhalla modes (auto, bicycle, pedestrian, multimodal, truck, taxi) side by side: distance, time, cost, tolls, ferries, motorway use, energy estimate and the opening manoeuvres, so the right mode for a journey can be compared rather than assumed.",
+        inputSchema: z.object({
+            from_lat: z.number().describe("Origin latitude."),
+            from_lon: z.number().describe("Origin longitude."),
+            to_lat: z.number().describe("Destination latitude."),
+            to_lon: z.number().describe("Destination longitude."),
+            modes: z.string().describe("Comma separated costings, default 'auto,bicycle,pedestrian'.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: valhalla_mode_compare ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_openrouteservice_valhalla_mode_compare", args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openrouteservice-mcp",
-  "version": "1.0.0",
-  "description": "OpenRouteService geocoding and routing. Free key.",
+  "version": "1.0.2",
+  "description": "Query OpenRouteService (free key; set OPENROUTESERVICE_API_KEY): geocode, reverse geocode, driving directions.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/openrouteservice-mcp",
   "repository": {