@omnizoek/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# @omnizoek/mcp-server
+
+> **Model Context Protocol server** for OmniZoek — exposes 10 Dutch government data APIs as AI agent tools.
+
+Add this server to Claude Desktop, Cursor, or any MCP-compatible AI client and your agent can instantly look up Dutch addresses, validate IBANs, check vehicle ZE-zone compliance, look up energy labels, and more — all backed by live BAG, EP-Online, RDW, VIES, NS, and ENTSO-E data.
+
+[![npm version](https://img.shields.io/npm/v/@omnizoek/mcp-server)](https://www.npmjs.com/package/@omnizoek/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Available tools
+
+| Tool | Description |
+|---|---|
+| `omnizoek_address_enrich` | Validate and enrich a Dutch address — BAG ID, building year, surface area, coordinates, energy label |
+| `omnizoek_iban_to_bic` | Resolve an IBAN to BIC/SWIFT and bank name |
+| `omnizoek_vat_verify` | Verify a European VAT number via EU VIES |
+| `omnizoek_validate_finance` | Checksum-validate a Dutch BSN or IBAN |
+| `omnizoek_energy_label` | Look up the official EP-Online energy label for an address |
+| `omnizoek_emission_zone` | Check whether a vehicle (by kenteken) may enter Dutch ZE-zones |
+| `omnizoek_transit_disruptions` | Get current NS train disruptions, optionally filtered by station |
+| `omnizoek_grid_trigger` | Get current ENTSO-E electricity price and whether the negative-price trigger is active |
+| `omnizoek_minimum_wage` | Look up the Dutch statutory minimum wage for a given age |
+| `omnizoek_holiday_surcharge` | Check if a date is a Dutch public holiday and get the wage surcharge multiplier |
+
+---
+
+## Quick start
+
+You need an OmniZoek API key. [Get one free at omnizoek.nl →](https://omnizoek.nl/signup)
+
+Use an `omni_test_...` key during development — it returns fixture data and is never billed.
+
+---
+
+## Claude Desktop
+
+Add the following to your Claude Desktop config file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "omnizoek": {
+      "command": "npx",
+      "args": ["-y", "@omnizoek/mcp-server"],
+      "env": {
+        "OMNIZOEK_API_KEY": "omni_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the OmniZoek tools available in the tool panel.
+
+---
+
+## Cursor
+
+Add to your Cursor MCP config (`~/.cursor/mcp.json` or the workspace `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "omnizoek": {
+      "command": "npx",
+      "args": ["-y", "@omnizoek/mcp-server"],
+      "env": {
+        "OMNIZOEK_API_KEY": "omni_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Docker
+
+```bash
+docker run --rm -i \
+  -e OMNIZOEK_API_KEY=omni_live_YOUR_KEY_HERE \
+  omnizoek/mcp-server
+```
+
+To use via Docker in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "omnizoek": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "-e", "OMNIZOEK_API_KEY=omni_live_YOUR_KEY_HERE", "omnizoek/mcp-server"]
+    }
+  }
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `OMNIZOEK_API_KEY` | ✅ Yes | Your OmniZoek API key. Prefix `omni_test_` for sandbox mode. |
+
+---
+
+## Example prompts
+
+Once configured, you can ask your AI agent:
+
+- *"What street is postcode 1012LG house number 1?"*
+- *"Is IBAN NL91ABNA0417164300 valid, and what bank is it from?"*
+- *"Can a diesel Euro 4 van with kenteken AB123C drive through an Amsterdam ZE-zone?"*
+- *"What is the minimum wage for a 19-year-old in the Netherlands today?"*
+- *"Is 25 December 2025 a public holiday, and what is the retail surcharge multiplier?"*
+- *"What is the current electricity price in the Netherlands, and is the negative-price trigger active?"*
+
+---
+
+## Development
+
+```bash
+# Clone the monorepo
+git clone https://github.com/JakoRens/searchworks-nl.git
+cd searchworks-nl/omni-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally (requires OMNIZOEK_API_KEY)
+OMNIZOEK_API_KEY=omni_test_... npm start
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Set `OMNIZOEK_API_KEY` in the inspector's environment variable panel, then use the tool explorer to call any tool interactively.
+
+---
+
+## Links
+
+- [OmniZoek API docs](https://omnizoek.nl/docs)
+- [Sign up for an API key](https://omnizoek.nl/signup)
+- [JavaScript SDK — `@omnizoek/sdk`](https://www.npmjs.com/package/@omnizoek/sdk)
+- [React hooks — `@omnizoek/react`](https://www.npmjs.com/package/@omnizoek/react)
+- [Model Context Protocol](https://modelcontextprotocol.io)

package/dist/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { OmniClient } from "@omnizoek/sdk";
+
+// src/tools.ts
+import { z } from "zod";
+function errResponse(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true
+  };
+}
+function registerTools(server2, client) {
+  server2.tool(
+    "omnizoek_address_enrich",
+    "Enrich a Dutch address using postcode and house number. Returns the verified street name, city, municipality, province, BAG object ID, surface area (m\xB2), building year, usage function, and optionally the official EP-Online energy label. Use this when you need to validate or complete a Dutch address, or look up property details.",
+    {
+      postcode: z.string().describe(
+        "Dutch postcode without spaces, e.g. '1012LG'. Four digits followed by two uppercase letters."
+      ),
+      house_number: z.string().describe(
+        "House number as a string, e.g. '1', '23', or '4B'. Additions such as letters or 'bis' are included here."
+      ),
+      energy: z.boolean().optional().describe(
+        "Whether to include the EP-Online energy label in the response. Defaults to true. Set to false to speed up the call if the energy label is not needed."
+      )
+    },
+    async ({ postcode, house_number, energy }) => {
+      try {
+        const result = await client.geo.enrichAddress({
+          postcode,
+          houseNumber: house_number,
+          energy
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_iban_to_bic",
+    "Resolve a Dutch or European IBAN to its BIC/SWIFT code and bank name. Useful for payment processing, supplier onboarding, or any workflow that requires knowing which bank holds an account.",
+    {
+      iban: z.string().describe(
+        "Full IBAN number including country code, e.g. 'NL91ABNA0417164300'. Spaces are automatically stripped."
+      )
+    },
+    async ({ iban }) => {
+      try {
+        const result = await client.finance.ibanToBic({ iban });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_vat_verify",
+    "Verify a European VAT number (Dutch BTW-nummer or any EU member state) via the official EU VIES service. Returns whether the number is valid, the registered company name, and the registered address. Use during B2B onboarding or invoicing to confirm a customer is a registered VAT payer.",
+    {
+      country_code: z.string().length(2).describe(
+        "ISO 3166-1 alpha-2 country code for the VAT number, e.g. 'NL', 'DE', 'BE'. Required even when the country is already encoded in the vat_number."
+      ),
+      vat_number: z.string().describe(
+        "VAT number without the country prefix, e.g. '123456782B01' for NL123456782B01. Or pass the full number \u2014 the country prefix is stripped automatically."
+      )
+    },
+    async ({ country_code, vat_number }) => {
+      try {
+        const result = await client.finance.vatVerify({
+          countryCode: country_code,
+          vatNumber: vat_number
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_validate_finance",
+    "Validate a Dutch BSN (citizen service number) or IBAN using checksum algorithms. Returns whether the number is structurally valid, the algorithm used, and a human-readable detail message. Does NOT verify against live government registers \u2014 it is a format/checksum check only.",
+    {
+      type: z.enum(["bsn", "iban"]).describe(
+        "'bsn' to validate a Dutch citizen service number (Burgerservicenummer), or 'iban' to validate an IBAN checksum."
+      ),
+      number: z.string().describe(
+        "The number to validate. For BSN: 9 digits, e.g. '111222333'. For IBAN: full IBAN including country code, e.g. 'NL91ABNA0417164300'."
+      )
+    },
+    async ({ type, number }) => {
+      try {
+        const result = await client.compliance.validateFinance({ type, number });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_energy_label",
+    "Retrieve the official EP-Online energy label for a Dutch residential or commercial address. Returns the label class (A++++ through G), calculation type, registration date, and validity period. Use for real-estate listings, compliance checks, or sustainability reporting.",
+    {
+      postcode: z.string().describe("Dutch postcode without spaces, e.g. '1012LG'."),
+      house_number: z.string().describe("House number, e.g. '1' or '23B'.")
+    },
+    async ({ postcode, house_number }) => {
+      try {
+        const result = await client.realEstate.energyLabel({
+          postcode,
+          houseNumber: house_number
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_emission_zone",
+    "Check whether a Dutch-registered vehicle (by licence plate / kenteken) is allowed to enter zero-emission zones (ZE-zones). Returns whether the vehicle is ZE-compliant, its fuel types, Euro standard, emission category, and which zones were checked. Use for fleet management, delivery routing, or vehicle compliance checks.",
+    {
+      kenteken: z.string().describe(
+        "Dutch licence plate (kenteken) without hyphens and in uppercase, e.g. 'AB123C' or 'ABCD12'."
+      )
+    },
+    async ({ kenteken }) => {
+      try {
+        const result = await client.logistics.emissionZone({ kenteken });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_transit_disruptions",
+    "Retrieve current and upcoming NS (Dutch national railway) train disruptions and maintenance windows. Optionally filter by station code. Returns disruption type, title, cause, start/end time, and impact level. Use for travel planning assistants, commute notifications, or logistics coordination.",
+    {
+      station_code: z.string().optional().describe(
+        "Optional NS station code to filter disruptions, e.g. 'ASD' for Amsterdam Centraal, 'UT' for Utrecht Centraal. Omit to get all nationwide disruptions."
+      )
+    },
+    async ({ station_code }) => {
+      try {
+        const result = await client.logistics.transitDisruptions(
+          station_code ? { stationCode: station_code } : void 0
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_grid_trigger",
+    "Check the current Dutch electricity grid status from ENTSO-E. Returns the current day-ahead price (\u20AC/MWh), whether prices are negative, and whether a 'trigger' condition is active (useful for smart energy management systems, EV charging schedulers, or demand-response automation). The trigger fires when the price falls below zero.",
+    {
+      country_code: z.string().length(2).optional().describe(
+        "ISO 3166-1 alpha-2 country code. Defaults to 'NL' (Netherlands). Other supported values: 'BE', 'DE'."
+      )
+    },
+    async ({ country_code }) => {
+      try {
+        const result = await client.energy.gridTrigger(
+          country_code ? { countryCode: country_code } : void 0
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_minimum_wage",
+    "Look up the current Dutch statutory minimum wage (Wettelijk Minimumloon, WML) for a given age. Returns the hourly, daily, and monthly gross amounts in euros, plus the relevant law reference. Optionally pass a reference date to look up historical or future values.",
+    {
+      age: z.number().int().min(13).max(99).describe("Age of the employee in whole years, e.g. 21."),
+      date: z.string().optional().describe(
+        "Reference date in YYYY-MM-DD format. Defaults to today. Use a past date to look up historical minimum wages, or a future date if the next period's rates have been published."
+      )
+    },
+    async ({ age, date }) => {
+      try {
+        const result = await client.hr.minimumWage({ age, date });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+  server2.tool(
+    "omnizoek_holiday_surcharge",
+    "Check whether a given date is a Dutch public holiday and return the applicable wage surcharge multiplier for a given industry (e.g. retail, hospitality, healthcare). Returns the holiday name if applicable, the surcharge multiplier (e.g. 1.5 for time-and-a-half), and the legal basis. Use for HR systems, payroll calculations, or shift scheduling.",
+    {
+      date: z.string().describe(
+        "Date to check in YYYY-MM-DD format, e.g. '2025-12-25' for Christmas. Use today's date to check current surcharge applicability."
+      ),
+      industry: z.string().describe(
+        "Industry sector for the surcharge lookup. Common values: 'retail', 'horeca', 'healthcare', 'transport', 'construction'. Use 'general' if the specific industry is unknown."
+      )
+    },
+    async ({ date, industry }) => {
+      try {
+        const result = await client.hr.holidaySurcharge({ date, industry });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return errResponse(err);
+      }
+    }
+  );
+}
+
+// src/index.ts
+var apiKey = process.env.OMNIZOEK_API_KEY;
+if (!apiKey) {
+  process.stderr.write(
+    "[omnizoek-mcp] Error: OMNIZOEK_API_KEY environment variable is not set.\n  Set it to your OmniZoek API key: https://omnizoek.nl/signup\n  Use an 'omni_test_...' key for sandbox testing (free, never billed).\n"
+  );
+  process.exit(1);
+}
+var omni = new OmniClient({ apiKey });
+var server = new McpServer({
+  name: "omnizoek",
+  version: "0.1.0"
+});
+registerTools(server, omni);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@omnizoek/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server that exposes OmniZoek Dutch government data APIs as AI agent tools (Claude Desktop, Cursor, and any MCP-compatible client).",
+  "author": "OmniZoek <support@omnizoek.nl>",
+  "license": "MIT",
+  "homepage": "https://omnizoek.nl/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakoRens/searchworks-nl.git",
+    "directory": "omni-mcp"
+  },
+  "keywords": [
+    "omnizoek",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "dutch",
+    "netherlands",
+    "bag",
+    "postcode",
+    "iban",
+    "energy-label",
+    "rdw",
+    "ns"
+  ],
+  "type": "module",
+  "bin": {
+    "omnizoek-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "@omnizoek/sdk": "^0.1.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}