@thehikingworld/mcp 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @thehikingworld/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only access to [The Hiking World](https://www.thehikingworld.com): sourced, dated trail and permit records. A figure is returned only when the catalog stored it. Unverified fees stay labelled unverified. Null means not recorded.
+
+Geometry is OpenStreetMap, ODbL. Editorial text is The Hiking World. Permit tariffs stay the issuer's. Cite the trail URL and the verified date.
+
+## Install
+
+```bash
+npx -y @thehikingworld/mcp
+```
+
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "thehikingworld": {
+      "command": "npx",
+      "args": ["-y", "@thehikingworld/mcp"]
+    }
+  }
+}
+```
+
+The process speaks MCP on stdin/stdout. `THW_API_BASE` overrides the default origin `https://www.thehikingworld.com`.
+
+## Hosted
+
+`https://www.thehikingworld.com/api/mcp` is the same tool set over Streamable HTTP. No install. No API key. Read-only.
+
+## Tools
+
+`get_trail`, `search_trails`, `get_permit`, `plan_permits`, `get_updates`, `list_regions`, `list_countries`, `get_geojson`, `get_provenance`.
+
+`plan_permits` takes one or more trail slugs and returns the stored permit rows for each, summing only confident same-currency official figures; a mixed or unverified set keeps a null total. It is a reference, not a route planner or a booking step.
+
+`get_updates` returns confirmed fee changes, newest first, each with a citation. `get_permit` and `get_trail` carry the citation string when a fee is citeable.
+
+If the feed is down, the tool returns an error and the process stays up.

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { pathToFileURL } from "node:url";
+import { registerTools } from "./tools.js";
+export { filterSummaries, matchPermits, registerTools } from "./tools.js";
+async function main() {
+    const server = new McpServer({ name: "thehikingworld", version: "1.1.1" });
+    registerTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+const invokedDirectly = process.argv[1] != null && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : "MCP server failed";
+        process.stderr.write(`${message}\n`);
+        process.exit(1);
+    });
+}

package/dist/tools.js

@@ -0,0 +1,268 @@
+import { z } from "zod";
+const DEFAULT_BASE = "https://www.thehikingworld.com";
+const HONESTY = "Figures are sourced and dated. They may be provisional. Cite the trail URL and the verifiedDate. Permit status is verified-official, reported-secondary, or unverified, or null when the feed has none. Null means not recorded. This server does not invent figures.";
+const VERIFY_NOTE = " A returned figure can be verified with get_provenance and the record signature.";
+function baseUrl() {
+    return (process.env.THW_API_BASE || DEFAULT_BASE).replace(/\/$/, "");
+}
+async function getJson(path) {
+    // TODO perf: direct lib calls
+    const url = `${baseUrl()}${path}`;
+    try {
+        const response = await fetch(url, { headers: { Accept: "application/json" } });
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            body = null;
+        }
+        if (!response.ok) {
+            return { status: response.status, body, error: `Feed returned ${response.status} for ${path}` };
+        }
+        return { status: response.status, body };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : "network error";
+        return { status: 0, body: null, error: `The Hiking World feed is unreachable (${message}).` };
+    }
+}
+async function postJson(path, payload) {
+    const url = `${baseUrl()}${path}`;
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            body = null;
+        }
+        if (!response.ok)
+            return { status: response.status, body, error: `Feed returned ${response.status} for ${path}` };
+        return { status: response.status, body };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : "network error";
+        return { status: 0, body: null, error: `The Hiking World feed is unreachable (${message}).` };
+    }
+}
+function text(value, isError = false) {
+    return {
+        isError,
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+function km(summary) {
+    const value = summary.distanceKm?.value;
+    return typeof value === "number" ? value : null;
+}
+export function filterSummaries(rows, query) {
+    const country = query.country?.trim().toLowerCase();
+    const region = query.region?.trim().toLowerCase();
+    const sac = query.sacScale?.trim().toLowerCase();
+    return rows.filter((row) => {
+        if (country && row.country.toLowerCase() !== country)
+            return false;
+        if (region && row.region.toLowerCase() !== region)
+            return false;
+        if (sac && (row.sacScale ?? "").toLowerCase() !== sac)
+            return false;
+        if (query.permitRequired != null && row.permitRequired !== query.permitRequired)
+            return false;
+        if (query.maxTypicalDays != null && (row.typicalDays == null || row.typicalDays > query.maxTypicalDays)) {
+            return false;
+        }
+        const distance = km(row);
+        if (query.minDistanceKm != null && (distance == null || distance < query.minDistanceKm))
+            return false;
+        if (query.maxDistanceKm != null && (distance == null || distance > query.maxDistanceKm))
+            return false;
+        return true;
+    });
+}
+function norm(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+export function matchPermits(rows, query) {
+    const needle = norm(query);
+    const slugNeedle = needle.replace(/ /g, "-");
+    const exactSlug = rows.filter((row) => row.trailSlug === slugNeedle || row.trailSlug === query.trim());
+    if (exactSlug.length)
+        return { match: "rows", rows: exactSlug };
+    const exactName = rows.filter((row) => norm(row.trailName) === needle);
+    if (exactName.length)
+        return { match: "rows", rows: exactName };
+    const fuzzy = rows.filter((row) => norm(row.trailName).includes(needle) || row.trailSlug.includes(slugNeedle));
+    const slugs = [...new Set(fuzzy.map((row) => row.trailSlug))];
+    if (slugs.length === 1)
+        return { match: "rows", rows: fuzzy };
+    if (slugs.length > 1) {
+        const candidates = slugs.map((slug) => fuzzy.find((row) => row.trailSlug === slug));
+        return { match: "candidates", rows: candidates };
+    }
+    return { match: "none", rows: [] };
+}
+export function registerTools(server) {
+    server.registerTool("plan_permits", {
+        description: `Structured permit plan from stored rows only. The model does not author fees. A missing total means no confident total. ${HONESTY}`,
+        inputSchema: { query: z.string().describe("Trail name or permit question. No fee figures.") },
+    }, async ({ query }) => {
+        const result = await postJson("/api/agent/permit-planner", { query });
+        if (result.error || !result.body)
+            return text({ error: result.error ?? "Planner unavailable" }, true);
+        return text({ caveat: "permit facts and issuer links, not legal/visa advice.", plan: result.body });
+    });
+    server.registerTool("get_trail", {
+        description: `Full sourced trail record from /api/v1/trails/{slug}, including permits, provenance, and geometryUrl. Unknown slug returns not found. ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: { slug: z.string().describe("Trail slug, for example inca-trail") },
+    }, async ({ slug }) => {
+        const aliases = {
+            "makalu-basecamp": "makalu-base-camp",
+            "makalu-base-camp-trek-with-arun-valley": "makalu-base-camp",
+            "tsum-valley-trek": "tsum-valley",
+            gosaikunda: "gosainkunda-trek",
+            "mardi-himal-base-camp-trail": "mardi-himal-trek",
+        };
+        const canonicalSlug = aliases[slug];
+        const result = await getJson(`/api/v1/trails/${encodeURIComponent(canonicalSlug ?? slug)}`);
+        if (result.error && result.status === 0)
+            return text({ error: result.error }, true);
+        if (result.status === 404 || result.body?.data == null) {
+            return text({ error: "not found", slug });
+        }
+        return text(canonicalSlug ? { ...result.body, canonicalSlug } : result.body);
+    });
+    server.registerTool("search_trails", {
+        description: `Filter trail summaries from /api/v1/trails. Each distance and elevation stays the feed object (value, source, verifiedDate, provisional). ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: {
+            country: z.string().optional(),
+            region: z.string().optional(),
+            maxDistanceKm: z.number().optional(),
+            minDistanceKm: z.number().optional(),
+            sacScale: z.string().optional().describe("SAC grade such as T3"),
+            permitRequired: z.boolean().optional(),
+            maxTypicalDays: z.number().optional(),
+        },
+    }, async (query) => {
+        const result = await getJson("/api/v1/trails");
+        if (result.error || !result.body?.data)
+            return text({ error: result.error ?? "Empty trail feed" }, true);
+        const data = filterSummaries(result.body.data, query);
+        return text({
+            schemaVersion: result.body.schemaVersion,
+            generatedAt: result.body.generatedAt,
+            license: result.body.license,
+            data,
+        });
+    });
+    server.registerTool("get_permit", {
+        description: `Permit rows from /api/v1/permits for a slug or a name ("Manaslu", "EBC"). Ambiguous names return candidates instead of a guess. Every row keeps status and verifiedDate. ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: { trail: z.string().describe("Slug or trail name") },
+    }, async ({ trail }) => {
+        const result = await getJson("/api/v1/permits");
+        if (result.error || !result.body?.data)
+            return text({ error: result.error ?? "Empty permit feed" }, true);
+        const found = matchPermits(result.body.data, trail);
+        if (found.match === "none")
+            return text({ error: "not found", trail });
+        if (found.match === "candidates") {
+            return text({
+                ambiguous: true,
+                candidates: found.rows.map((row) => ({
+                    trailSlug: row.trailSlug,
+                    trailName: row.trailName,
+                    country: row.country,
+                    status: row.status,
+                    verifiedDate: row.verifiedDate,
+                })),
+            });
+        }
+        return text({
+            schemaVersion: result.body.schemaVersion,
+            generatedAt: result.body.generatedAt,
+            license: result.body.license,
+            data: found.rows,
+        });
+    });
+    server.registerTool("list_regions", {
+        description: `Distinct region and country names on /api/v1/trails, so an agent can see coverage. ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: {},
+    }, async () => {
+        const result = await getJson("/api/v1/trails");
+        if (result.error || !result.body?.data)
+            return text({ error: result.error ?? "Empty trail feed" }, true);
+        const seen = new Map();
+        for (const row of result.body.data) {
+            seen.set(`${row.country}\t${row.region}`, { region: row.region, country: row.country });
+        }
+        return text({
+            schemaVersion: result.body.schemaVersion,
+            generatedAt: result.body.generatedAt,
+            license: result.body.license,
+            data: [...seen.values()].sort((a, b) => a.country.localeCompare(b.country) || a.region.localeCompare(b.region)),
+        });
+    });
+    server.registerTool("list_countries", {
+        description: `Distinct countries on /api/v1/trails. ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: {},
+    }, async () => {
+        const result = await getJson("/api/v1/trails");
+        if (result.error || !result.body?.data)
+            return text({ error: result.error ?? "Empty trail feed" }, true);
+        const counts = new Map();
+        for (const row of result.body.data)
+            counts.set(row.country, (counts.get(row.country) ?? 0) + 1);
+        return text({
+            schemaVersion: result.body.schemaVersion,
+            generatedAt: result.body.generatedAt,
+            license: result.body.license,
+            data: [...counts.entries()]
+                .map(([country, trails]) => ({ country, trails }))
+                .sort((a, b) => a.country.localeCompare(b.country)),
+        });
+    });
+    server.registerTool("get_geojson", {
+        description: `Trail line from /api/v1/trails/{slug}/geojson. A schematic line has schematic: true and is not a GPS track. ${HONESTY}${VERIFY_NOTE}`,
+        inputSchema: { slug: z.string() },
+    }, async ({ slug }) => {
+        const result = await getJson(`/api/v1/trails/${encodeURIComponent(slug)}/geojson`);
+        if (result.error && result.status === 0)
+            return text({ error: result.error }, true);
+        if (result.status === 404 || result.body?.data == null)
+            return text({ error: "not found", slug });
+        return text(result.body);
+    });
+    server.registerTool("get_provenance", {
+        description: `Published public key, signing policy, and the verification recipe from /api/v1/provenance. ${HONESTY}`,
+        inputSchema: {},
+    }, async () => {
+        const result = await getJson("/api/v1/provenance");
+        if (result.error || !result.body)
+            return text({ error: result.error ?? "Empty provenance feed" }, true);
+        return text(result.body);
+    });
+    server.registerTool("get_updates", {
+        description: `Confirmed permit-fee changes from /updates.json, newest first. Each row has the old figure, the new figure, the issuer, the source URL, and a citation. ${HONESTY}`,
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).optional().describe("How many changes to return. Default 20."),
+        },
+    }, async ({ limit }) => {
+        const result = await getJson("/updates.json");
+        if (result.error || !result.body?.changes)
+            return text({ error: result.error ?? "Empty updates feed" }, true);
+        const cap = limit ?? 20;
+        const changes = [...result.body.changes]
+            .sort((a, b) => b.date.localeCompare(a.date))
+            .slice(0, cap)
+            .map((change) => ({
+            ...change,
+            citation: change.citation ?? `${change.sentence ?? `${change.trail} fee change`} Source: ${change.sourceUrl}`,
+        }));
+        return text({ data: changes });
+    });
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@thehikingworld/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "MCP server for The Hiking World sourced trail catalog.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/ravitejarx/the-hiking-world.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "thehikingworld-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}