opplevagent-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Fredriksen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Opplevagent MCP Server
+
+MCP server for **[Opplevagent](https://opplevagent.no)** — discover Norwegian experiences and activities from Claude Desktop, Cursor, or any MCP client.
+
+Search tours, courses and things to do across Norway and filter by **county, municipality, category, weather, season, group size, age and price**. Every result links straight to a booking page.
+
+[![npm](https://img.shields.io/npm/v/opplevagent-mcp)](https://www.npmjs.com/package/opplevagent-mcp)
+
+## Install
+
+### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "opplevagent": {
+      "command": "npx",
+      "args": ["opplevagent-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. No API key required.
+
+### Run directly
+
+```bash
+npx opplevagent-mcp
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `opplev_discover` | Search experiences by structured filters: `fylke` (county), `kommune` (municipality), `category`, `indoor_outdoor`, `weather`, `season`, `group_size`, `age`, `max_price`, `duration_max`, `language`, `limit`. Returns ranked experiences with place, category, duration, price and a booking link. |
+| `opplev_info` | Get the full profile for one experience by `id` (UUID) — description, place, season, duration, group size, age suitability, price, languages, accessibility, meeting point and booking link. |
+| `opplev_categories` | List all experience categories with the count of published experiences in each. |
+
+All tools are **read-only** and query the public Opplevagent API. No authentication.
+
+## Example prompts
+
+- *"Hva kan vi finne på i Oslo når det regner?"*
+- *"Hvalsafari i Tromsø"*
+- *"Familievennlige aktiviteter utendørs i Bergen om sommeren"*
+- *"Things to do in Trondheim under 500 kr"*
+
+## Categories
+
+`kultur_historie` · `sightseeing_transport` · `adrenalin_action` · `dyreliv_safari` · `vinter_sno` · `natur_friluft` · `overnatting_opplevelse` · `velvaere_spa` · `mat_drikke`
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `OPPLEVAGENT_URL` | `https://opplevagent.no` | Base URL of the Opplevagent API. Override to point at a staging instance. |
+
+## How it works
+
+Opplevagent is an **A2A (Agent-to-Agent) marketplace** for Norwegian experiences. This MCP server is a thin, read-only wrapper over the public discovery API:
+
+- REST: `https://opplevagent.no/api/opplevelser`
+- Discover: `https://opplevagent.no/api/opplevelser/discover`
+- Agent card: `https://opplevagent.no/.well-known/agent-card.json`
+- OpenAPI: `https://opplevagent.no/openapi.json`
+- Remote MCP (Streamable HTTP): `https://opplevagent.no/mcp`
+
+## Links
+
+- Website: <https://opplevagent.no>
+- npm: <https://www.npmjs.com/package/opplevagent-mcp>
+- Issues: <https://github.com/slookisen/opplevagent-mcp/issues>
+
+## License
+
+MIT © Daniel Fredriksen

package/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+/**
+ * Opplevagent MCP Server — Discover Norwegian experiences & activities via Claude Desktop
+ *
+ * Install:
+ *   npx opplevagent-mcp
+ *
+ * Or add to Claude Desktop config (~/.claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "opplevagent": {
+ *         "command": "npx",
+ *         "args": ["opplevagent-mcp"]
+ *       }
+ *     }
+ *   }
+ *
+ * Backed by the public Opplevagent A2A marketplace: https://opplevagent.no
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BASE_URL = process.env.OPPLEVAGENT_URL || "https://opplevagent.no";
+const UA = "opplevagent-mcp/0.1.0";
+
+// ── Helpers ──────────────────────────────────────────────────
+
+async function fetchJSON(url) {
+  const res = await fetch(url, {
+    headers: { Accept: "application/json", "User-Agent": UA },
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+  return res.json();
+}
+
+// Norwegian labels for the fixed category vocabulary.
+const CATEGORY_LABELS = {
+  kultur_historie: "Kultur & historie",
+  sightseeing_transport: "Sightseeing & transport",
+  adrenalin_action: "Adrenalin & action",
+  dyreliv_safari: "Dyreliv & safari",
+  vinter_sno: "Vinter & snø",
+  natur_friluft: "Natur & friluft",
+  overnatting_opplevelse: "Overnatting & opplevelse",
+  velvaere_spa: "Velvære & spa",
+  mat_drikke: "Mat & drikke",
+};
+
+function categoryLabel(c) {
+  return CATEGORY_LABELS[c] || c;
+}
+
+function profileUrl(slug) {
+  return slug ? `${BASE_URL}/opplevelse/${slug}` : undefined;
+}
+
+function priceText(exp) {
+  if (exp.price_from != null) {
+    const unit = exp.price_unit ? ` ${exp.price_unit}` : "";
+    return `fra ${exp.price_from} kr${unit}`;
+  }
+  if (exp.price_band) return String(exp.price_band);
+  return null;
+}
+
+function durationText(exp) {
+  const d = exp.duration_min ?? exp.duration_max;
+  if (d == null) return null;
+  if (d >= 1440) return `${Math.round((d / 1440) * 10) / 10} dager`;
+  if (d >= 60) return `${Math.round((d / 60) * 10) / 10} t`;
+  return `${d} min`;
+}
+
+// Format one experience from the /discover result list.
+function formatExperience(exp, idx) {
+  const lines = [`**${idx}. ${exp.title}**`];
+
+  const meta = [];
+  const place = [exp.kommune, exp.fylke].filter(Boolean).join(", ");
+  if (place) meta.push(`📍 ${place}`);
+  if (exp.category) meta.push(`🏷️ ${categoryLabel(exp.category)}`);
+  if (exp.indoor_outdoor) {
+    const io = { indoor: "innendørs", outdoor: "utendørs", both: "inne/ute" }[exp.indoor_outdoor] || exp.indoor_outdoor;
+    meta.push(io);
+  }
+  const dur = durationText(exp);
+  if (dur) meta.push(`⏱ ${dur}`);
+  const price = priceText(exp);
+  if (price) meta.push(`💰 ${price}`);
+  if (meta.length) lines.push(`   ${meta.join("  ·  ")}`);
+
+  const links = [];
+  const url = profileUrl(exp.slug);
+  if (url) links.push(`🔗 ${url}`);
+  if (exp.booking_url) links.push(`🎟️ Book: ${exp.booking_url}`);
+  if (links.length) lines.push(`   ${links.join("  ·  ")}`);
+
+  return lines.join("\n");
+}
+
+// ── MCP Server ───────────────────────────────────────────────
+
+const server = new McpServer({
+  name: "opplevagent",
+  version: "0.1.0",
+});
+
+// Tool 1: Discover experiences by structured filters
+// Annotations: read-only, safe, idempotent, open-world (queries a public registry).
+server.registerTool(
+  "opplev_discover",
+  {
+    title: "Discover Norwegian experiences",
+    description:
+      "Search Norwegian experiences and activities (tours, courses, things to do) by structured filters. " +
+      "Use this when a user asks what to do somewhere — e.g. 'hva kan vi finne på i Oslo når det regner', " +
+      "'family-friendly outdoor activities in Tromsø in winter', 'things to do in Trondheim under 500 kr'. " +
+      "Translate the user's natural-language request into the filters below. Returns ranked experiences with " +
+      "place, category, duration, price and a booking link.",
+    inputSchema: {
+      fylke: z.string().optional().describe("County / region, e.g. 'Oslo', 'Troms', 'Vestland'"),
+      kommune: z.string().optional().describe("Municipality, e.g. 'Tromsø', 'Bergen'"),
+      category: z
+        .enum([
+          "kultur_historie",
+          "sightseeing_transport",
+          "adrenalin_action",
+          "dyreliv_safari",
+          "vinter_sno",
+          "natur_friluft",
+          "overnatting_opplevelse",
+          "velvaere_spa",
+          "mat_drikke",
+        ])
+        .optional()
+        .describe("Experience category. Use opplev_categories to list valid values with counts."),
+      indoor_outdoor: z.enum(["indoor", "outdoor", "both"]).optional().describe("Indoor, outdoor, or both"),
+      weather: z
+        .enum(["rain", "snow", "clear", "any"])
+        .optional()
+        .describe("Current/expected weather. 'rain' and 'snow' prefer indoor & weather-independent activities."),
+      season: z.enum(["spring", "summer", "autumn", "winter"]).optional().describe("Season"),
+      group_size: z.number().int().optional().describe("Number of people in the group"),
+      age: z.number().int().optional().describe("Age of participant (for age-suitability filtering)"),
+      max_price: z.number().optional().describe("Maximum price per person in NOK"),
+      duration_max: z.number().int().optional().describe("Maximum duration in minutes"),
+      language: z.string().optional().describe("Preferred language for the experience, e.g. 'en', 'no'"),
+      limit: z.number().min(1).max(50).default(10).describe("Max results"),
+    },
+    annotations: {
+      title: "Discover Norwegian experiences",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async (args) => {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(args)) {
+      if (v !== undefined && v !== null && v !== "") params.set(k, String(v));
+    }
+    if (!params.has("limit")) params.set("limit", "10");
+
+    const data = await fetchJSON(`${BASE_URL}/api/opplevelser/discover?${params}`);
+
+    if (!data.results?.length) {
+      return {
+        content: [
+          { type: "text", text: "Ingen opplevelser funnet med disse filtrene. Prøv et bredere søk (færre filtre)." },
+        ],
+      };
+    }
+
+    const applied = Object.entries(data.query || {})
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    const header = `🎒 **Opplevelser i Norge** — ${data.count} treff${applied ? ` (${applied})` : ""}:\n`;
+    const results = data.results.map((exp, i) => formatExperience(exp, i + 1)).join("\n\n");
+
+    return { content: [{ type: "text", text: header + "\n" + results }] };
+  }
+);
+
+// Tool 2: Full detail for a single experience by id
+server.registerTool(
+  "opplev_info",
+  {
+    title: "Experience details",
+    description:
+      "Get the full profile for one experience by its id (UUID from opplev_discover results): " +
+      "title, description, category, county/municipality, indoor/outdoor, season, duration, group size, " +
+      "age suitability, price, languages, accessibility, meeting point and booking link.",
+    inputSchema: {
+      id: z.string().describe("Experience id (UUID). Get this from opplev_discover results."),
+    },
+    annotations: {
+      title: "Experience details",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ id }) => {
+    const data = await fetchJSON(`${BASE_URL}/api/opplevelser/${id}`);
+    const exp = data.experience || data;
+
+    const sections = [`# ${exp.title}`];
+
+    const place = [exp.kommune, exp.fylke].filter(Boolean).join(", ");
+    const head = [];
+    if (place) head.push(`📍 ${place}`);
+    if (exp.category) head.push(categoryLabel(exp.category));
+    if (exp.confidence) head.push(`tillit: ${exp.confidence}`);
+    if (head.length) sections.push(head.join("  ·  "));
+
+    if (exp.description) sections.push(`\n${exp.description}`);
+
+    // Quick facts
+    const facts = [];
+    if (exp.indoor_outdoor) {
+      const io = { indoor: "Innendørs", outdoor: "Utendørs", both: "Inne/ute" }[exp.indoor_outdoor] || exp.indoor_outdoor;
+      facts.push(`- **Inne/ute:** ${io}`);
+    }
+    if (Array.isArray(exp.season) && exp.season.length) facts.push(`- **Sesong:** ${exp.season.join(", ")}`);
+    const dur = durationText(exp);
+    if (dur) facts.push(`- **Varighet:** ${dur}`);
+    if (exp.group_min != null || exp.group_max != null)
+      facts.push(`- **Gruppe:** ${[exp.group_min, exp.group_max].filter((x) => x != null).join("–")} personer`);
+    if (exp.min_age != null) facts.push(`- **Min. alder:** ${exp.min_age}`);
+    if (exp.age_suitability) facts.push(`- **Passer for:** ${exp.age_suitability}`);
+    const price = priceText(exp);
+    if (price) facts.push(`- **Pris:** ${price}`);
+    if (Array.isArray(exp.languages) && exp.languages.length) facts.push(`- **Språk:** ${exp.languages.join(", ")}`);
+    if (Array.isArray(exp.accessibility) && exp.accessibility.length)
+      facts.push(`- **Tilgjengelighet:** ${exp.accessibility.join(", ")}`);
+    if (Array.isArray(exp.activity_tags) && exp.activity_tags.length)
+      facts.push(`- **Stikkord:** ${exp.activity_tags.join(", ")}`);
+    if (facts.length) sections.push(`\n## Fakta\n${facts.join("\n")}`);
+
+    if (exp.meeting_point) sections.push(`\n📌 **Oppmøte:** ${exp.meeting_point}`);
+
+    const links = [];
+    if (exp.slug) links.push(`🔗 [Profil](${profileUrl(exp.slug)})`);
+    if (exp.booking_url) links.push(`🎟️ [Book / mer info](${exp.booking_url})`);
+    if (exp.evidence_url && exp.evidence_url !== exp.booking_url) links.push(`📄 [Kilde](${exp.evidence_url})`);
+    if (links.length) sections.push(`\n${links.join("  ·  ")}`);
+
+    return { content: [{ type: "text", text: sections.join("\n") }] };
+  }
+);
+
+// Tool 3: List categories with counts
+server.registerTool(
+  "opplev_categories",
+  {
+    title: "List experience categories",
+    description:
+      "List all experience categories on Opplevagent with the count of published experiences in each. " +
+      "Useful when the user asks 'what kinds of experiences are available?' or to pick a valid category " +
+      "value for opplev_discover.",
+    inputSchema: {},
+    annotations: {
+      title: "List experience categories",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async () => {
+    const data = await fetchJSON(`${BASE_URL}/api/opplevelser/categories`);
+    const cats = data.categories || [];
+    if (!cats.length) {
+      return { content: [{ type: "text", text: "Ingen kategorier registrert ennå." }] };
+    }
+    const total = cats.reduce((sum, c) => sum + (c.count || 0), 0);
+    const lines = [`🗂️ **Kategorier på Opplevagent** — ${total} opplevelser totalt:\n`];
+    for (const c of cats) {
+      lines.push(`- **${categoryLabel(c.category)}** (\`${c.category}\`) — ${c.count}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+// ── Start ────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "opplevagent-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.slookisen/opplevagent-mcp",
+  "description": "MCP server for Opplevagent — discover Norwegian experiences and activities from Claude Desktop. Search tours, courses and things to do by county, category, weather, season, group size, age and price.",
+  "main": "index.js",
+  "bin": {
+    "opplevagent-mcp": "index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node test-smoke.mjs"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "claude",
+    "opplevagent",
+    "experiences",
+    "activities",
+    "things-to-do",
+    "tourism",
+    "norway",
+    "a2a",
+    "opplevelser"
+  ],
+  "author": "Daniel Fredriksen",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slookisen/opplevagent-mcp.git"
+  },
+  "homepage": "https://opplevagent.no",
+  "bugs": {
+    "url": "https://github.com/slookisen/opplevagent-mcp/issues"
+  }
+}