openrouteservice-mcp 1.0.0 → 1.0.1

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 license key:
+
+* `osrm_route_steps`
+* `valhalla_mode_compare`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-openrouteservice-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -5,3 +5,26 @@ 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>;
+/** A road route from OSRM, with the turn-by-turn an OpenStreetMap router can give. */
+export declare function osrmRouteSteps(args: {
+    from_lat?: number;
+    from_lon?: number;
+    to_lat?: number;
+    to_lon?: number;
+    alternatives?: boolean;
+}): Promise<string>;
+/** The same trip by several modes, from Valhalla, which models them with different cost functions. */
+export declare function valhallaModeCompare(args: {
+    from_lat?: number;
+    from_lon?: number;
+    to_lat?: number;
+    to_lon?: number;
+    modes?: string;
+}): Promise<string>;

package/dist/api.js

@@ -57,3 +57,205 @@ 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");
+}
+/** A road route from OSRM, with the turn-by-turn an OpenStreetMap router can give. */
+export async function osrmRouteSteps(args) {
+    const nums = [args.from_lat, args.from_lon, args.to_lat, args.to_lon].map((v) => Number(v));
+    if (nums.some((n) => !Number.isFinite(n))) {
+        throw new OrsError("All four of from_lat, from_lon, to_lat and to_lon are required, for example 48.8584, 2.2945 to 48.8606, 2.3376.");
+    }
+    const [fromLat, fromLon, toLat, toLon] = nums;
+    if (Math.abs(fromLat) > 90 || Math.abs(toLat) > 90)
+        throw new OrsError("from_lat and to_lat must be between -90 and 90.");
+    if (Math.abs(fromLon) > 180 || Math.abs(toLon) > 180)
+        throw new OrsError("from_lon and to_lon must be between -180 and 180.");
+    // This OSRM build rejects any geometries parameter, including "none"; overview=false
+    // already suppresses the route geometry, and per-step geometry is not printed.
+    const params = new URLSearchParams({ overview: "false", steps: "true" });
+    if (args.alternatives !== false)
+        params.set("alternatives", "3");
+    const d = await orsFetch(`${ORS_OSRM}/route/v1/driving/${fromLon},${fromLat};${toLon},${toLat}?${params}`);
+    if (d.code !== "Ok" || !d.routes?.length)
+        throw new OrsError(`OSRM could not route between those points (status ${d.code ?? "unknown"}). Check that both points are on the road network.`);
+    const routes = d.routes;
+    return [
+        `OSRM road route, ${routes.length} option(s) found (OpenStreetMap road data)`,
+        `The demo OSRM instance is shared and not meant for production traffic, so treat the route as an indication rather than a navigation instruction.`,
+        "",
+        ...routes.map((r, ri) => {
+            const steps = r.legs?.flatMap((l) => l.steps ?? []) ?? [];
+            const named = steps.filter((s) => s.name && s.distance > 20);
+            return [
+                `Option ${ri + 1}: ${orsMetres(r.distance)}, ${orsDuration(r.duration)} estimated${ri === 0 ? " (the one OSRM prefers)" : ""}`,
+                `  via ${named.length} named road segment(s): ${[...new Set(named.map((s) => s.name))].slice(0, 8).join(", ") || "none recorded"}`,
+                `  turn-by-turn:`,
+                ...steps.slice(0, 10).map((s) => {
+                    const m = s.maneuver ?? {};
+                    const what = [m.modifier, m.type].filter(Boolean).join(" ");
+                    return `    ${String(Math.round(s.distance)).padStart(6)} m  ${s.name || "(unnamed road)"} — ${what}${m.instruction ? `: ${m.instruction}` : ""}`;
+                }),
+                steps.length > 10 ? `    ... ${steps.length - 10} further step(s) not shown` : "",
+            ].filter(Boolean).join("\n");
+        }),
+        "",
+        "The duration is a free-flow estimate with no traffic, no turn penalties beyond the model's own, and no time-of-day variation, so it is optimistic compared to what a navigation app will show you.",
+    ].join("\n");
+}
+/** The same trip by several modes, from Valhalla, which models them with different cost functions. */
+export async function valhallaModeCompare(args) {
+    const nums = [args.from_lat, args.from_lon, args.to_lat, args.to_lon].map((v) => Number(v));
+    if (nums.some((n) => !Number.isFinite(n))) {
+        throw new OrsError("All four of from_lat, from_lon, to_lat and to_lon are required.");
+    }
+    const [fromLat, fromLon, toLat, toLon] = nums;
+    const known = ["auto", "bicycle", "pedestrian", "multimodal", "truck", "taxi"];
+    const wanted = String(args?.modes ?? "auto,bicycle,pedestrian")
+        .split(",")
+        .map((m) => m.trim().toLowerCase())
+        .filter(Boolean)
+        .filter((m) => known.includes(m))
+        .slice(0, 4);
+    if (!wanted.length) {
+        throw new OrsError(`No usable mode in "${args.modes}". Valhalla costings here: ${known.join(", ")}.`);
+    }
+    const results = [];
+    for (const mode of wanted) {
+        try {
+            const d = await orsFetch(`${ORS_VALHALLA}/route?json=`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    locations: [{ lat: fromLat, lon: fromLon }, { lat: toLat, lon: toLon }],
+                    costing: mode,
+                    directions_options: { units: "kilometers" },
+                    ...(mode === "multimodal" ? { costings: [{ costing: "pedestrian" }, { costing: "bicycle" }] } : {}),
+                }),
+            });
+            if (d.error) {
+                results.push({ mode, ok: false, note: `${d.error_code ?? "error"}: ${d.error}` });
+                continue;
+            }
+            const s = d.trip?.summary ?? {};
+            const maneuvers = d.trip?.legs?.flatMap((l) => l.maneuvers ?? []) ?? [];
+            results.push({
+                mode,
+                ok: true,
+                note: [
+                    orsMetres((s.length ?? 0) * 1000),
+                    orsDuration(s.time ?? 0),
+                    `cost ${s.cost ?? "not reported"}`,
+                    s.has_toll ? "tolls" : "no tolls",
+                    s.has_ferry ? "includes a ferry" : "",
+                    s.has_highway ? "uses a motorway" : "",
+                    s.has_time_restrictions ? "has a time restriction" : "",
+                    s.energy_use?.value !== undefined ? `energy ${s.energy_use.value} ${s.energy_use.unit ?? ""}` : "",
+                    `${maneuvers.length} maneuver(s)`,
+                ].filter(Boolean).join(", "),
+            });
+            if (maneuvers.length) {
+                results[results.length - 1].note += `\n      first turns: ${maneuvers.slice(0, 3).map((m) => `${m.instruction ?? "?"}${m.street_names?.length ? ` (${m.street_names[0]})` : ""}`).join(" | ")}`;
+            }
+        }
+        catch (e) {
+            results.push({ mode, ok: false, note: errorMessage(e) });
+        }
+    }
+    return [
+        `Same trip by ${wanted.length} costing model(s), from Valhalla's public instance`,
+        `${fromLat}, ${fromLon} to ${toLat}, ${toLon}`,
+        "",
+        ...results.map((r) => `  ${r.ok ? "ok  " : "fail"} ${r.mode.padEnd(11)} ${r.note}`),
+        "",
+        "The costing models disagree on purpose: a bicycle and a pedestrian route on the same two points are different journeys, and the fast car route is often the one you cannot walk. Compare them before assuming one mode is the right one.",
+        "Valhalla's public instance is a shared demo, so a routing failure here is not evidence the trip is unroutable.",
+    ].join("\n");
+}

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/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "openrouteservice-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "osrm_route_steps",
+    "valhalla_mode_compare",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * 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 async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

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, osrmRouteSteps, valhallaModeCompare } from "./api.js";
+import { premiumRequired } from "./license.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,71 @@ 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 ----
+        const paywallMessage = await premiumRequired("osrm_route_steps");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await osrmRouteSteps(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 ----
+        const paywallMessage = await premiumRequired("valhalla_mode_compare");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await valhallaModeCompare(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.1",
+  "description": "Query OpenRouteService (free key; set OPENROUTESERVICE_API_KEY): geocode, reverse geocode, driving directions.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/openrouteservice-mcp",
   "repository": {