mcp-swiss

Instructions

Implementation Reference

• src/modules/post.ts:212-264 (handler)

  The handler logic for the 'lookup_postcode' tool in `handlePost`. It validates the postcode, fetches the data from the swisstopo API, identifies the canton, and returns the result.

  case "lookup_postcode": {
    const postcode = String(args.postcode ?? "").trim();
    if (!/^\d{4}$/.test(postcode)) {
      throw new Error(`Invalid Swiss postcode: "${postcode}". Must be a 4-digit number.`);
    }
  
    // 1. Fetch PLZ record from the official registry
    const findUrl = buildUrl(`${BASE}/rest/services/api/MapServer/find`, {
      layer: PLZ_LAYER,
      searchText: postcode,
      searchField: "plz",
      returnGeometry: false,
      sr: 4326,
    });
    const findData = await fetchJSON<PlzFindResponse>(findUrl);
  
    if (!findData.results.length) {
      return JSON.stringify({ found: false, postcode, message: "Postcode not found." });
    }
  
    const record = findData.results[0];
    const attr = record.attributes;
  
    // 2. Get coordinates + confirm locality from SearchServer (zipcode origin)
    const searchUrl = buildUrl(`${BASE}/rest/services/api/SearchServer`, {
      searchText: postcode,
      type: "locations",
      origins: "zipcode",
      sr: 4326,
      limit: 1,
    });
    const searchData = await fetchJSON<SearchResponse>(searchUrl);
    const searchEntry =
      searchData.results.find((r) => r.attrs.origin === "zipcode") ?? null;
  
    const lat = searchEntry?.attrs.lat ?? null;
    const lon = searchEntry?.attrs.lon ?? null;
  
    // 3. Identify canton
    const canton =
      lat !== null && lon !== null ? await identifyCanton(lat, lon) : null;
  
    return JSON.stringify({
      found: true,
      postcode: attr.plz,
      locality: attr.langtext,
      canton: canton
        ? { code: canton.code, name: canton.name }
        : null,
      coordinates: lat !== null ? { lat, lon } : null,
      source: "swisstopo — Amtliches Ortschaftenverzeichnis",
    });
  }

• src/modules/post.ts:140-154 (schema)

  The tool registration definition for 'lookup_postcode', including the name, description, and input schema.

  {
    name: "lookup_postcode",
    description:
      "Look up a Swiss postcode (PLZ) to get locality name, canton, and coordinates. Source: Swiss federal geodata (swisstopo).",
    inputSchema: {
      type: "object",
      required: ["postcode"],
      properties: {
        postcode: {
          type: "string",
          description: "Swiss postal code (PLZ), e.g. \"8001\" or \"3000\"",
        },
      },
    },
  },