mcp-swiss 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikram Gorla
+
+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,175 @@
+# mcp-swiss 🏔️
+
+[![CI](https://github.com/vikramgorla/mcp-swiss/actions/workflows/ci.yml/badge.svg)](https://github.com/vikramgorla/mcp-swiss/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/mcp-swiss.svg)](https://www.npmjs.com/package/mcp-swiss)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)
+
+Swiss open data MCP server for AI assistants. Zero API keys. Zero config. Just works.
+
+## What is this?
+
+`mcp-swiss` is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants (Claude, Cursor, Cline, etc.) direct access to Swiss open data:
+
+- 🚆 **Transport** — SBB trains, PostBus, trams, live departures, journey planning
+- 🌤️ **Weather** — MeteoSwiss live conditions + historical data
+- 🌊 **Hydrology** — BAFU river and lake levels (great for Aare swimming!)
+- 🗺️ **Geodata** — swisstopo geocoding, solar potential, geographic layers
+- 🏢 **Companies** — ZEFIX federal registry, all 700K+ Swiss companies
+
+**22 tools. No API keys. No registration. No server to run.**
+
+---
+
+## Install
+
+```bash
+npx mcp-swiss
+```
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "swiss": {
+      "command": "npx",
+      "args": ["mcp-swiss"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Cursor
+
+Create or edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "swiss": {
+      "command": "npx",
+      "args": ["mcp-swiss"]
+    }
+  }
+}
+```
+
+### Cline (VSCode)
+
+Open `settings.json` and add:
+
+```json
+{
+  "cline.mcpServers": {
+    "swiss": {
+      "command": "npx",
+      "args": ["mcp-swiss"]
+    }
+  }
+}
+```
+
+---
+
+## Demo Prompts
+
+Once connected, try asking your AI:
+
+- *"Next 5 trains from Zürich HB to Geneva right now"*
+- *"Is the Aare in Bern warm enough to swim? What's the water level?"*
+- *"Weather in Lugano vs Zürich today"*
+- *"Find all companies with 'blockchain' in their name registered in Zug"*
+- *"What's the solar potential of Bundesplatz 3, Bern?"*
+- *"Live departures from Bern HB in the next 30 minutes"*
+- *"Plan my Saturday: train to Interlaken, check weather, find the nearest SBB station"*
+- *"What rivers are near Thun and what are their current water levels?"*
+
+---
+
+## Tools
+
+Full specifications for all tools: [`docs/tool-specs.md`](docs/tool-specs.md) | Machine-readable: [`docs/tools.schema.json`](docs/tools.schema.json)
+
+### 🚆 Transport (5 tools)
+| Tool | Description |
+|------|-------------|
+| `search_stations` | Find stations/stops by name or location |
+| `get_connections` | Journey planner between any two points |
+| `get_departures` | Live departures from a station |
+| `get_arrivals` | Live arrivals at a station |
+| `get_nearby_stations` | Stations near coordinates |
+
+### 🌤️ Weather & Hydrology (6 tools)
+| Tool | Description |
+|------|-------------|
+| `get_weather` | Current conditions at a MeteoSwiss station |
+| `list_weather_stations` | All ~160 MeteoSwiss stations with metadata |
+| `get_weather_history` | Historical weather data (up to 32 days) |
+| `get_water_level` | River/lake level + temperature (BAFU) |
+| `list_hydro_stations` | All 400+ hydrological monitoring stations |
+| `get_water_history` | Historical hydrology data |
+
+### 🗺️ Geodata / swisstopo (6 tools)
+| Tool | Description |
+|------|-------------|
+| `geocode` | Swiss address → coordinates |
+| `reverse_geocode` | Coordinates → Swiss address |
+| `search_places` | Swiss place names, mountains, lakes, features |
+| `get_solar_potential` | Rooftop solar irradiation at a location |
+| `identify_location` | All geographic data layers at a point |
+| `get_municipality` | Municipality info by name |
+
+### 🏢 Companies / ZEFIX (5 tools)
+| Tool | Description |
+|------|-------------|
+| `search_companies` | Search by name, canton, legal form |
+| `get_company` | Full company details by ZEFIX `ehraid` (from search results) |
+| `search_companies_by_address` | Companies registered at an address |
+| `list_cantons` | All 26 Swiss cantons |
+| `list_legal_forms` | AG, GmbH, and all Swiss legal forms |
+
+---
+
+## Data Sources
+
+All official Swiss open data — no API keys required:
+
+| Source | Data | API |
+|--------|------|-----|
+| [transport.opendata.ch](https://transport.opendata.ch) | SBB, PostBus, trams | REST |
+| [api.existenz.ch](https://api.existenz.ch) | MeteoSwiss weather + BAFU hydrology | REST |
+| [api3.geo.admin.ch](https://api3.geo.admin.ch) | swisstopo federal geodata | REST |
+| [zefix.admin.ch](https://www.zefix.admin.ch) | Federal company registry | REST |
+
+---
+
+## For contributors
+
+mcp-swiss uses [Speckit](https://github.com/jmanhype/speckit) — a spec-driven development workflow.
+Every new tool or module starts with a spec in `specs/`, not code.
+
+See [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the full workflow including:
+- How to add a new tool (spec → plan → implement → test)
+- Testing requirements (unit + integration + MCP protocol)
+- Code style and ESLint rules
+- Branch naming and PR process
+
+---
+
+## Requirements
+
+- Node.js 18+
+- No API keys or accounts needed
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const transport_js_1 = require("./modules/transport.js");
+const weather_js_1 = require("./modules/weather.js");
+const geodata_js_1 = require("./modules/geodata.js");
+const companies_js_1 = require("./modules/companies.js");
+const server = new index_js_1.Server({ name: "mcp-swiss", version: "0.1.0" }, { capabilities: { tools: {} } });
+const allTools = [
+    ...transport_js_1.transportTools,
+    ...weather_js_1.weatherTools,
+    ...geodata_js_1.geodataTools,
+    ...companies_js_1.companiesTools,
+];
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: allTools,
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const safeArgs = (args ?? {});
+    try {
+        let result;
+        if (transport_js_1.transportTools.some((t) => t.name === name)) {
+            result = await (0, transport_js_1.handleTransport)(name, safeArgs);
+        }
+        else if (weather_js_1.weatherTools.some((t) => t.name === name)) {
+            result = await (0, weather_js_1.handleWeather)(name, safeArgs);
+        }
+        else if (geodata_js_1.geodataTools.some((t) => t.name === name)) {
+            result = await (0, geodata_js_1.handleGeodata)(name, safeArgs);
+        }
+        else if (companies_js_1.companiesTools.some((t) => t.name === name)) {
+            result = await (0, companies_js_1.handleCompanies)(name, safeArgs);
+        }
+        else {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: result }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("mcp-swiss running on stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/modules/companies.d.ts

@@ -0,0 +1,83 @@
+export declare const companiesTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            canton: {
+                type: string;
+                description: string;
+            };
+            legal_form: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            ehraid?: undefined;
+            address?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            ehraid: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            canton?: undefined;
+            legal_form?: undefined;
+            limit?: undefined;
+            address?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            canton?: undefined;
+            legal_form?: undefined;
+            ehraid?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            canton?: undefined;
+            legal_form?: undefined;
+            limit?: undefined;
+            ehraid?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+export declare function handleCompanies(name: string, args: Record<string, unknown>): Promise<string>;

package/dist/modules/companies.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.companiesTools = void 0;
+exports.handleCompanies = handleCompanies;
+const http_js_1 = require("../utils/http.js");
+const BASE = "https://www.zefix.admin.ch/ZefixREST/api/v1";
+exports.companiesTools = [
+    {
+        name: "search_companies",
+        description: "Search Swiss company registry (ZEFIX) by name, canton, or legal form",
+        inputSchema: {
+            type: "object",
+            required: ["name"],
+            properties: {
+                name: { type: "string", description: "Company name or partial name to search" },
+                canton: { type: "string", description: "Canton abbreviation (e.g. ZH, BE, GE, ZG)" },
+                legal_form: { type: "string", description: "Legal form code (e.g. 0106=GmbH, 0101=AG)" },
+                limit: { type: "number", description: "Max results (default: 20)" },
+            },
+        },
+    },
+    {
+        name: "get_company",
+        description: "Get full details of a Swiss company by its ZEFIX internal ID (ehraid). Use search_companies first to find the ehraid — it is returned in company search results.",
+        inputSchema: {
+            type: "object",
+            required: ["ehraid"],
+            properties: {
+                ehraid: { type: "number", description: "Company internal ZEFIX ID (ehraid integer, e.g. 119283). Returned by search_companies." },
+            },
+        },
+    },
+    {
+        name: "search_companies_by_address",
+        description: "Search Swiss companies registered at a specific address or locality",
+        inputSchema: {
+            type: "object",
+            required: ["address"],
+            properties: {
+                address: { type: "string", description: "Address or locality name" },
+                limit: { type: "number", description: "Max results (default: 20)" },
+            },
+        },
+    },
+    {
+        name: "list_cantons",
+        description: "List all Swiss cantons with their codes",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "list_legal_forms",
+        description: "List all Swiss company legal forms (AG, GmbH, etc.)",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+];
+async function handleCompanies(name, args) {
+    switch (name) {
+        case "search_companies": {
+            const body = {
+                name: args.name,
+                maxEntries: args.limit ?? 20,
+                languageKey: "en",
+            };
+            if (args.canton)
+                body.cantonAbbreviation = [args.canton];
+            if (args.legal_form)
+                body.legalFormCode = args.legal_form;
+            const response = await fetch(`${BASE}/firm/search.json`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "Accept": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (response.status === 404) {
+                return JSON.stringify({ companies: [], hasMoreResults: false }, null, 2);
+            }
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            const data = await response.json();
+            if (data.error)
+                return JSON.stringify({ companies: [], hasMoreResults: false }, null, 2);
+            return JSON.stringify({ companies: data.list ?? [], hasMoreResults: data.hasMoreResults ?? false }, null, 2);
+        }
+        case "get_company": {
+            // ZEFIX firm/{id}.json uses the internal ehraid integer (not CHE uid)
+            const ehraid = args.ehraid;
+            const url = `${BASE}/firm/${ehraid}.json`;
+            const data = await (0, http_js_1.fetchJSON)(url);
+            return JSON.stringify(data, null, 2);
+        }
+        case "search_companies_by_address": {
+            const body = {
+                name: args.address,
+                maxEntries: args.limit ?? 20,
+                languageKey: "en",
+            };
+            const response = await fetch(`${BASE}/firm/search.json`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "Accept": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (response.status === 404)
+                return JSON.stringify({ companies: [], hasMoreResults: false }, null, 2);
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            const data = await response.json();
+            if (data.error)
+                return JSON.stringify({ companies: [], hasMoreResults: false }, null, 2);
+            return JSON.stringify({ companies: data.list ?? [], hasMoreResults: data.hasMoreResults ?? false }, null, 2);
+        }
+        case "list_cantons": {
+            // ZEFIX /cantons and /legalForms endpoints require authentication (403).
+            // Return hardcoded authoritative list instead.
+            const cantons = [
+                { code: "AG", name: "Aargau" }, { code: "AI", name: "Appenzell Innerrhoden" },
+                { code: "AR", name: "Appenzell Ausserrhoden" }, { code: "BE", name: "Bern" },
+                { code: "BL", name: "Basel-Landschaft" }, { code: "BS", name: "Basel-Stadt" },
+                { code: "FR", name: "Fribourg" }, { code: "GE", name: "Geneva" },
+                { code: "GL", name: "Glarus" }, { code: "GR", name: "Graubünden" },
+                { code: "JU", name: "Jura" }, { code: "LU", name: "Lucerne" },
+                { code: "NE", name: "Neuchâtel" }, { code: "NW", name: "Nidwalden" },
+                { code: "OW", name: "Obwalden" }, { code: "SG", name: "St. Gallen" },
+                { code: "SH", name: "Schaffhausen" }, { code: "SO", name: "Solothurn" },
+                { code: "SZ", name: "Schwyz" }, { code: "TG", name: "Thurgau" },
+                { code: "TI", name: "Ticino" }, { code: "UR", name: "Uri" },
+                { code: "VD", name: "Vaud" }, { code: "VS", name: "Valais" },
+                { code: "ZG", name: "Zug" }, { code: "ZH", name: "Zürich" },
+            ];
+            return JSON.stringify(cantons, null, 2);
+        }
+        case "list_legal_forms": {
+            // ZEFIX /legalForms requires authentication (403). Return common Swiss legal forms.
+            const forms = [
+                { code: "0101", name: "Einzelunternehmen", nameEn: "Sole proprietorship" },
+                { code: "0103", name: "Kollektivgesellschaft", nameEn: "General partnership" },
+                { code: "0104", name: "Kommanditgesellschaft", nameEn: "Limited partnership" },
+                { code: "0105", name: "Aktiengesellschaft (AG)", nameEn: "Corporation (AG)" },
+                { code: "0106", name: "Gesellschaft mit beschränkter Haftung (GmbH)", nameEn: "Limited liability company (GmbH)" },
+                { code: "0107", name: "Genossenschaft", nameEn: "Cooperative" },
+                { code: "0108", name: "Verein", nameEn: "Association" },
+                { code: "0109", name: "Stiftung", nameEn: "Foundation" },
+                { code: "0110", name: "Kommanditaktiengesellschaft", nameEn: "Partnership limited by shares" },
+                { code: "0113", name: "Filiale ausländischer Gesellschaft", nameEn: "Branch of foreign company" },
+                { code: "0114", name: "Institut des öffentlichen Rechts", nameEn: "Public law institution" },
+            ];
+            return JSON.stringify(forms, null, 2);
+        }
+        default:
+            throw new Error(`Unknown companies tool: ${name}`);
+    }
+}

package/dist/modules/geodata.d.ts

@@ -0,0 +1,109 @@
+export declare const geodataTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
+            lat?: undefined;
+            lng?: undefined;
+            query?: undefined;
+            type?: undefined;
+            layers?: undefined;
+            name?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            lat: {
+                type: string;
+                description: string;
+            };
+            lng: {
+                type: string;
+                description: string;
+            };
+            address?: undefined;
+            query?: undefined;
+            type?: undefined;
+            layers?: undefined;
+            name?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+            };
+            address?: undefined;
+            lat?: undefined;
+            lng?: undefined;
+            layers?: undefined;
+            name?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            lat: {
+                type: string;
+                description: string;
+            };
+            lng: {
+                type: string;
+                description: string;
+            };
+            layers: {
+                type: string;
+                description: string;
+            };
+            address?: undefined;
+            query?: undefined;
+            type?: undefined;
+            name?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        required: string[];
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            address?: undefined;
+            lat?: undefined;
+            lng?: undefined;
+            query?: undefined;
+            type?: undefined;
+            layers?: undefined;
+        };
+    };
+})[];
+export declare function handleGeodata(name: string, args: Record<string, unknown>): Promise<string>;