@heibergindustries/orakel-mcp 1.0.0

package/README.md

@@ -0,0 +1,131 @@
+# @heibergindustries/orakel-mcp
+
+MCP server for **Orakel** — Norwegian company data, financials, ownership, procurement, and prospecting tools. Works with Claude Code, Claude Desktop, and Gemini CLI.
+
+## Get Access
+
+Request an API key at [orakel.heiberg.co](https://orakel.heiberg.co).
+
+## Quick Start
+
+```bash
+ORAKEL_API_KEY=orakel_YOUR_KEY npx -y @heibergindustries/orakel-mcp
+```
+
+## Setup — Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "orakel": {
+      "command": "npx",
+      "args": ["-y", "@heibergindustries/orakel-mcp"],
+      "env": {
+        "ORAKEL_API_KEY": "orakel_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+## Setup — Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "orakel": {
+      "command": "npx",
+      "args": ["-y", "@heibergindustries/orakel-mcp"],
+      "env": {
+        "ORAKEL_API_KEY": "orakel_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+## Setup — Gemini CLI
+
+Add to your Gemini CLI MCP config:
+
+```json
+{
+  "mcpServers": {
+    "orakel": {
+      "command": "npx",
+      "args": ["-y", "@heibergindustries/orakel-mcp"],
+      "env": {
+        "ORAKEL_API_KEY": "orakel_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `lookup_company` | Look up a company by org number |
+| `search_companies` | Search by name, NACE, municipality, county, employees, revenue, tech stack, ad pixels |
+| `get_financials` | Get financial data (revenue, profit, assets, equity, debt, ratios) |
+| `find_prospects` | Find prospects by industry, location, size — formatted for sales |
+| `get_corporate_group` | Get parent company + subsidiaries hierarchy |
+| `get_shareholders` | Get shareholder register with ownership percentages |
+| `get_ownership_network` | Reverse lookup: what does a company/person own? |
+| `list_municipalities` | List Norwegian municipalities and county codes |
+| `search_inspections` | Search Mattilsynet food safety inspections (smilefjes) |
+| `search_licenses` | Search alcohol/tobacco licenses (TBR) |
+| `search_procurement` | Search public procurement notices (Doffin) |
+| `enrichment_status` | View domain enrichment pipeline results |
+| `push_to_destination` | Push companies to CRM (Attio, webhooks) |
+| `list_destinations` | List configured push destinations |
+| `manage_destination` | Create/update/delete push destinations |
+| `check_health` | Check API health, database status, sync progress |
+
+## Skills
+
+Pre-built guided workflows are included in the `skills/` directory of this package. Copy them to your `.claude/skills/` directory:
+
+```bash
+cp -r $(npm root -g)/@heibergindustries/orakel-mcp/skills/* ~/.claude/skills/
+```
+
+Available skills: `/prospect`, `/company-deep-dive`, `/push-to-crm`, `/market-scan`, `/ownership-map`.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORAKEL_API_KEY` | (required) | Your Orakel API key |
+| `ORAKEL_URL` | `https://orakel.heiberg.co` | API base URL (override for local dev) |
+
+## Examples
+
+Once configured, ask from any project:
+
+- "Look up Equinor" → `lookup_company`
+- "Find 15 bars in Oslo with over 10M revenue" → `find_prospects`
+- "What companies does Aker own?" → `get_ownership_network`
+- "Show me IT consulting companies in Bergen" → `search_companies`
+- "Push these prospects to my CRM" → `push_to_destination`
+
+## Data Sources
+
+All data sourced from Norwegian public registries under NLOD 2.0:
+
+- **Brønnøysundregistrene** — Company register, roles, financials
+- **Mattilsynet** — Food safety inspections
+- **Helsedirektoratet** — Alcohol/tobacco licenses
+- **Doffin** — Public procurement notices
+- **Aksjonærregisteret** — Shareholder data
+- **SSB** — Municipality reference data
+- **NORID** — Domain verification
+
+## License
+
+MIT

package/dist/server.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const ORAKEL_URL = process.env.ORAKEL_URL ?? "https://orakel.heiberg.co";
+const ORAKEL_API_KEY = process.env.ORAKEL_API_KEY ?? "";
+if (!ORAKEL_API_KEY) {
+    console.error("Error: ORAKEL_API_KEY environment variable is required.\n\n" +
+        "Request access at https://orakel.heiberg.co\n\n" +
+        "Then configure in Claude Code (~/.claude/settings.json):\n\n" +
+        '  "mcpServers": {\n' +
+        '    "orakel": {\n' +
+        '      "command": "npx",\n' +
+        '      "args": ["-y", "@heibergindustries/orakel-mcp"],\n' +
+        '      "env": { "ORAKEL_API_KEY": "orakel_YOUR_KEY" }\n' +
+        '    }\n' +
+        '  }\n');
+    process.exit(1);
+}
+async function orakelFetch(path, options) {
+    const url = `${ORAKEL_URL}${path}`;
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${ORAKEL_API_KEY}`,
+            "Content-Type": "application/json",
+            ...options?.headers,
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Orakel API error ${response.status}: ${text}`);
+    }
+    return response.json();
+}
+const server = new McpServer({
+    name: "orakel",
+    version: "1.0.0",
+});
+// ─── lookup_company ───────────────────────────────────────────
+server.tool("lookup_company", "Look up a Norwegian company by organization number. Returns full details including financials, roles, and sub-units.", { orgNumber: z.string().describe("9-digit Norwegian organization number") }, async ({ orgNumber }) => {
+    const company = await orakelFetch(`/api/companies/${orgNumber}`);
+    return { content: [{ type: "text", text: JSON.stringify(company, null, 2) }] };
+});
+// ─── search_companies ─────────────────────────────────────────
+server.tool("search_companies", "Search Norwegian companies by name, industry (NACE code), county, municipality, employee count, revenue, and more. Returns paginated results.", {
+    query: z.string().optional().describe("Search by company name"),
+    nace: z.string().optional().describe("NACE industry code prefix (e.g. '56.3' for bars/restaurants)"),
+    orgForm: z.string().optional().describe("Organization form code (AS, ASA, ENK, etc.)"),
+    county: z.string().optional().describe("2-digit county code (e.g. '39' for Vestfold, '03' for Oslo). Use list_municipalities to find codes."),
+    municipality: z.string().optional().describe("4-digit municipality number (e.g. '0301' for Oslo, '3905' for Tønsberg)"),
+    minEmployees: z.number().optional().describe("Minimum employee count"),
+    maxEmployees: z.number().optional().describe("Maximum employee count"),
+    minRevenue: z.number().optional().describe("Minimum revenue (NOK)"),
+    maxRevenue: z.number().optional().describe("Maximum revenue (NOK)"),
+    isBankrupt: z.boolean().optional().describe("Filter by bankruptcy status"),
+    isInGroup: z.boolean().optional().describe("Filter by whether company is part of a group"),
+    hasParent: z.boolean().optional().describe("Filter by whether company has a parent organization"),
+    hasTechnology: z.string().optional().describe("Filter by detected technology (e.g. 'WordPress', 'Shopify', 'HubSpot')"),
+    hasAnyAdPixel: z.boolean().optional().describe("Filter by companies running digital ads (Meta Pixel, Google Ads, etc.)"),
+    sort: z.string().optional().describe("Sort by: name, employeeCount, foundingDate, updatedAt"),
+    order: z.string().optional().describe("Sort order: asc or desc"),
+    limit: z.number().optional().describe("Max results (default 20, max 100)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.query)
+        searchParams.set("q", params.query);
+    if (params.nace)
+        searchParams.set("nace", params.nace);
+    if (params.orgForm)
+        searchParams.set("orgForm", params.orgForm);
+    if (params.county)
+        searchParams.set("county", params.county);
+    if (params.municipality)
+        searchParams.set("municipality", params.municipality);
+    if (params.minEmployees)
+        searchParams.set("minEmployees", String(params.minEmployees));
+    if (params.maxEmployees)
+        searchParams.set("maxEmployees", String(params.maxEmployees));
+    if (params.minRevenue)
+        searchParams.set("minRevenue", String(params.minRevenue));
+    if (params.maxRevenue)
+        searchParams.set("maxRevenue", String(params.maxRevenue));
+    if (params.isBankrupt !== undefined)
+        searchParams.set("isBankrupt", String(params.isBankrupt));
+    if (params.isInGroup !== undefined)
+        searchParams.set("isInGroup", String(params.isInGroup));
+    if (params.hasParent !== undefined)
+        searchParams.set("hasParent", String(params.hasParent));
+    if (params.hasTechnology)
+        searchParams.set("hasTechnology", params.hasTechnology);
+    if (params.hasAnyAdPixel !== undefined)
+        searchParams.set("hasAnyAdPixel", String(params.hasAnyAdPixel));
+    if (params.sort)
+        searchParams.set("sort", params.sort);
+    if (params.order)
+        searchParams.set("order", params.order);
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await orakelFetch(`/api/companies?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── get_financials ───────────────────────────────────────────
+server.tool("get_financials", "Get financial data (revenue, profit, assets, equity, debt) for a Norwegian company.", { orgNumber: z.string().describe("9-digit Norwegian organization number") }, async ({ orgNumber }) => {
+    const company = await orakelFetch(`/api/companies/${orgNumber}`);
+    const financials = company.financials ?? [];
+    return { content: [{ type: "text", text: JSON.stringify(financials, null, 2) }] };
+});
+// ─── find_prospects ───────────────────────────────────────────
+server.tool("find_prospects", "Find potential business prospects by industry, location, size, revenue, and technology. Returns a formatted list with financials and tech stack.", {
+    nace: z.string().optional().describe("NACE industry code prefix"),
+    county: z.string().optional().describe("2-digit county code (e.g. '39' for Vestfold). Use list_municipalities to find codes."),
+    municipality: z.string().optional().describe("4-digit municipality number"),
+    minEmployees: z.number().optional().describe("Minimum employees"),
+    maxEmployees: z.number().optional().describe("Maximum employees"),
+    minRevenue: z.number().optional().describe("Minimum revenue (NOK)"),
+    hasTechnology: z.string().optional().describe("Filter by detected technology (e.g. 'WordPress', 'Shopify')"),
+    hasAnyAdPixel: z.boolean().optional().describe("Only companies running digital ads"),
+    limit: z.number().optional().describe("Max results (default 20)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.nace)
+        searchParams.set("nace", params.nace);
+    if (params.county)
+        searchParams.set("county", params.county);
+    if (params.municipality)
+        searchParams.set("municipality", params.municipality);
+    if (params.minEmployees)
+        searchParams.set("minEmployees", String(params.minEmployees));
+    if (params.maxEmployees)
+        searchParams.set("maxEmployees", String(params.maxEmployees));
+    if (params.minRevenue)
+        searchParams.set("minRevenue", String(params.minRevenue));
+    if (params.hasTechnology)
+        searchParams.set("hasTechnology", params.hasTechnology);
+    if (params.hasAnyAdPixel !== undefined)
+        searchParams.set("hasAnyAdPixel", String(params.hasAnyAdPixel));
+    searchParams.set("limit", String(params.limit ?? 20));
+    searchParams.set("sort", "employeeCount");
+    searchParams.set("order", "desc");
+    const result = await orakelFetch(`/api/companies?${searchParams}`);
+    const companies = result.data ?? [];
+    const formatted = companies.map((c) => {
+        const financials = c.financials ?? [];
+        const latest = financials[0];
+        return {
+            orgNumber: c.orgNumber,
+            name: c.name,
+            employees: c.employeeCount,
+            city: c.businessAddressCity,
+            nace: c.naceCode1,
+            revenue: latest?.revenue,
+            netResult: latest?.netResult,
+        };
+    });
+    return { content: [{ type: "text", text: JSON.stringify(formatted, null, 2) }] };
+});
+// ─── list_municipalities ─────────────────────────────────────
+server.tool("list_municipalities", "List Norwegian municipalities and counties with their codes. Use this to find the right county or municipality code for search queries. For example, find that Vestfold = county code '39', or that Tønsberg = municipality '3905'.", {
+    county: z.string().optional().describe("2-digit county code to filter by (e.g. '39' for Vestfold)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.county)
+        searchParams.set("county", params.county);
+    const result = await orakelFetch(`/api/municipalities?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── push_to_destination ──────────────────────────────────────
+server.tool("push_to_destination", "Push company data to a configured destination (Attio CRM, webhook, etc.).", {
+    destinationName: z.string().describe("Name of the destination (e.g. 'zero7-attio')"),
+    orgNumbers: z.array(z.string()).describe("Array of 9-digit org numbers to push"),
+}, async ({ destinationName, orgNumbers }) => {
+    const result = await orakelFetch(`/api/push/${destinationName}`, {
+        method: "POST",
+        body: JSON.stringify({ orgNumbers }),
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── list_destinations ────────────────────────────────────────
+server.tool("list_destinations", "List all configured push destinations (Attio, webhooks, etc.).", {}, async () => {
+    const destinations = await orakelFetch("/api/destinations");
+    return { content: [{ type: "text", text: JSON.stringify(destinations, null, 2) }] };
+});
+// ─── manage_destination ───────────────────────────────────────
+server.tool("manage_destination", "Create, update, or delete a push destination.", {
+    action: z.enum(["create", "update", "delete"]).describe("Action to perform"),
+    name: z.string().describe("Destination name"),
+    type: z.string().optional().describe("Destination type (attio, webhook)"),
+    config: z.record(z.string(), z.unknown()).optional().describe("Configuration object"),
+    isActive: z.boolean().optional().describe("Whether the destination is active"),
+}, async ({ action, name, type, config, isActive }) => {
+    let result;
+    switch (action) {
+        case "create":
+            result = await orakelFetch("/api/destinations", {
+                method: "POST",
+                body: JSON.stringify({ name, type, config: config ?? {} }),
+            });
+            break;
+        case "update":
+            result = await orakelFetch(`/api/destinations/${name}`, {
+                method: "PUT",
+                body: JSON.stringify({ type, config, isActive }),
+            });
+            break;
+        case "delete":
+            await orakelFetch(`/api/destinations/${name}`, { method: "DELETE" });
+            result = { deleted: name };
+            break;
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── search_inspections ──────────────────────────────────────
+server.tool("search_inspections", "Search Mattilsynet food safety inspections (smilefjes). Filter by org number, rating (0=best, 3=worst), postal code, or date range.", {
+    orgNumber: z.string().optional().describe("Filter by 9-digit org number"),
+    minRating: z.number().optional().describe("Minimum overall rating (0=smiling, 3=very sad)"),
+    maxRating: z.number().optional().describe("Maximum overall rating"),
+    postnr: z.string().optional().describe("Postal code filter"),
+    fromDate: z.string().optional().describe("Inspections from this date (ISO format)"),
+    toDate: z.string().optional().describe("Inspections up to this date (ISO format)"),
+    limit: z.number().optional().describe("Max results (default 20)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.orgNumber)
+        searchParams.set("orgNumber", params.orgNumber);
+    if (params.minRating !== undefined)
+        searchParams.set("minRating", String(params.minRating));
+    if (params.maxRating !== undefined)
+        searchParams.set("maxRating", String(params.maxRating));
+    if (params.postnr)
+        searchParams.set("postnr", params.postnr);
+    if (params.fromDate)
+        searchParams.set("fromDate", params.fromDate);
+    if (params.toDate)
+        searchParams.set("toDate", params.toDate);
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await orakelFetch(`/api/inspections?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── search_licenses ─────────────────────────────────────────
+server.tool("search_licenses", "Search Norwegian alcohol and tobacco licenses (TBR). Filter by org number, license type, municipality, or active status.", {
+    orgNumber: z.string().optional().describe("Filter by org number"),
+    registerType: z.string().optional().describe("Alkoholsbevilling or Tobakksbevilling"),
+    licenseTypeCode: z.string().optional().describe("01SKJE (skjenke), 11ENGR (engros), 18TBIM (import), 19TBEK (export)"),
+    municipalityNo: z.string().optional().describe("Municipality number (e.g. '0301' for Oslo)"),
+    activeOnly: z.boolean().optional().describe("Only show currently valid licenses"),
+    limit: z.number().optional().describe("Max results (default 20)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.orgNumber)
+        searchParams.set("orgNumber", params.orgNumber);
+    if (params.registerType)
+        searchParams.set("registerType", params.registerType);
+    if (params.licenseTypeCode)
+        searchParams.set("licenseTypeCode", params.licenseTypeCode);
+    if (params.municipalityNo)
+        searchParams.set("municipalityNo", params.municipalityNo);
+    if (params.activeOnly !== undefined)
+        searchParams.set("activeOnly", String(params.activeOnly));
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await orakelFetch(`/api/licenses?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── search_procurement ──────────────────────────────────────
+server.tool("search_procurement", "Search Norwegian public procurement notices (Doffin). Filter by CPV code, contracting authority, value, status, or deadline.", {
+    query: z.string().optional().describe("Search in title"),
+    orgNumber: z.string().optional().describe("Contracting authority org number"),
+    cpvCode: z.string().optional().describe("CPV code (e.g. '72' for IT services)"),
+    status: z.string().optional().describe("Notice status: ACTIVE, EXPIRED"),
+    noticeType: z.string().optional().describe("Notice type: ANNOUNCEMENT_OF_COMPETITION, etc."),
+    minValue: z.number().optional().describe("Minimum estimated value (NOK)"),
+    deadlineAfter: z.string().optional().describe("Only notices with deadline after this date (ISO)"),
+    limit: z.number().optional().describe("Max results (default 20)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.query)
+        searchParams.set("q", params.query);
+    if (params.orgNumber)
+        searchParams.set("orgNumber", params.orgNumber);
+    if (params.cpvCode)
+        searchParams.set("cpvCode", params.cpvCode);
+    if (params.status)
+        searchParams.set("status", params.status);
+    if (params.noticeType)
+        searchParams.set("noticeType", params.noticeType);
+    if (params.minValue)
+        searchParams.set("minValue", String(params.minValue));
+    if (params.deadlineAfter)
+        searchParams.set("deadlineAfter", params.deadlineAfter);
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await orakelFetch(`/api/procurement?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── enrichment_status ────────────────────────────────────────
+server.tool("enrichment_status", "View domain enrichment results. Filter by status (confirmed, ambiguous, rejected) to review pipeline output. Shows company name, discovered domains, social handles, and confidence scores.", {
+    status: z.enum(["confirmed", "ambiguous", "rejected", "pending"]).optional().describe("Filter by enrichment status. Omit to see all non-pending results."),
+    minConfidence: z.number().optional().describe("Minimum confidence score (0-100)"),
+    limit: z.number().optional().describe("Max results (default 50, max 200)"),
+}, async (params) => {
+    const searchParams = new URLSearchParams();
+    if (params.status)
+        searchParams.set("status", params.status);
+    if (params.minConfidence)
+        searchParams.set("minConfidence", String(params.minConfidence));
+    if (params.limit)
+        searchParams.set("limit", String(params.limit));
+    const result = await orakelFetch(`/api/enrichment?${searchParams}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── get_corporate_group ─────────────────────────────────────
+server.tool("get_corporate_group", "Get the corporate group tree for a company. Shows parent company and all subsidiaries in a hierarchy.", { orgNumber: z.string().describe("9-digit Norwegian organization number") }, async ({ orgNumber }) => {
+    const result = await orakelFetch(`/api/companies/${orgNumber}/group`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── get_shareholders ────────────────────────────────────────
+server.tool("get_shareholders", "Get shareholders of a Norwegian company from the shareholder register (Aksjonærregisteret). Shows ownership percentages per share class.", {
+    orgNumber: z.string().describe("9-digit Norwegian organization number"),
+    year: z.number().optional().describe("Filter by snapshot year (e.g. 2024)"),
+    includePersons: z.boolean().optional().describe("Include individual (non-corporate) shareholders. Default: false for privacy."),
+}, async ({ orgNumber, year, includePersons }) => {
+    const params = new URLSearchParams();
+    if (year)
+        params.set("year", String(year));
+    if (includePersons)
+        params.set("includePersons", "true");
+    const result = await orakelFetch(`/api/companies/${orgNumber}/shareholders?${params}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── get_ownership_network ───────────────────────────────────
+server.tool("get_ownership_network", "Find all companies where a given company is a shareholder (reverse ownership lookup). Answer: 'What does company X own?'", {
+    shareholderOrgNumber: z.string().describe("Org number of the shareholder company"),
+    year: z.number().optional().describe("Filter by snapshot year"),
+}, async ({ shareholderOrgNumber, year }) => {
+    const params = new URLSearchParams({ shareholderOrgNumber });
+    if (year)
+        params.set("year", String(year));
+    const result = await orakelFetch(`/api/shareholders/by-owner?${params}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// ─── check_health ─────────────────────────────────────────────
+server.tool("check_health", "Check Orakel API health, database status, record counts, and sync status for all data sources.", {}, async () => {
+    const health = await orakelFetch("/api/health");
+    return { content: [{ type: "text", text: JSON.stringify(health, null, 2) }] };
+});
+// ─── Start server ─────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@heibergindustries/orakel-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Orakel — Norwegian company data, financials, and prospecting tools for Claude Code, Claude Desktop & Gemini CLI",
+  "type": "module",
+  "bin": {
+    "orakel-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bendikheiberg/orakel",
+    "directory": "mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "gemini",
+    "norway",
+    "company-data",
+    "business-intelligence"
+  ]
+}

package/skills/company-deep-dive/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: company-deep-dive
+description: >
+  Research a single Norwegian company in depth. Use when asked to look up,
+  analyze, or investigate a specific company.
+allowed-tools: mcp__orakel__lookup_company, mcp__orakel__get_financials, mcp__orakel__get_corporate_group, mcp__orakel__get_shareholders, mcp__orakel__get_ownership_network, mcp__orakel__search_companies, mcp__orakel__search_inspections, mcp__orakel__search_licenses
+---
+
+# Company Deep Dive
+
+Produce a comprehensive research report on a single Norwegian company.
+
+## Step 1: Identify the Company
+
+The user may provide:
+
+- **Organization number** (9 digits like 999888777): Use `lookup_company` directly.
+- **Company name**: Use `search_companies` with the `query` parameter to find it.
+
+If a name search returns multiple results, present the top matches and ask the user to confirm:
+
+> I found several companies matching that name:
+> 1. Example AS (999888777) - Oslo, IT consulting, 45 employees
+> 2. Example Norge AS (888777666) - Bergen, retail, 12 employees
+>
+> Which one did you mean?
+
+## Step 2: Gather All Data
+
+Once you have the org number, make these calls:
+
+1. `lookup_company` with the org number — this returns the core company data, roles, financials, sub-units, technologies, and enrichment data.
+2. `get_corporate_group` — to see parent company and subsidiaries.
+3. `get_shareholders` — to see ownership structure. Start without `includePersons` for privacy. Mention that personal shareholders can be included if needed.
+
+If the company's NACE code starts with 55 or 56 (hospitality/food service), also run:
+4. `search_inspections` with the org number — Mattilsynet food safety ratings.
+5. `search_licenses` with the org number — alcohol/tobacco licenses.
+
+## Step 3: Produce the Report
+
+Structure the report with these sections:
+
+### Overview
+- Full legal name and any brand names
+- Organization number
+- Organization form (AS, ASA, ENK, etc.)
+- Founding date and age
+- Registered address and business address
+- NACE industry code with plain-language description
+- Number of employees
+- Website and social media (from enrichment data if available)
+- Technologies detected (if any)
+
+### Financial Performance
+
+Present a multi-year table (most recent years first):
+
+| Year | Revenue (MNOK) | Net Result (MNOK) | Profit Margin | Assets (MNOK) | Equity Ratio |
+|------|---------------|-------------------|---------------|---------------|-------------|
+| 2023 | 32.5 | 4.1 | 12.6% | 28.0 | 42% |
+| 2022 | 28.9 | 3.2 | 11.1% | 24.5 | 38% |
+
+Calculate and highlight:
+- **Revenue trend:** Year-over-year growth percentage
+- **Profit margin:** Net result / revenue (as percentage)
+- **Equity ratio:** Equity / total assets (as percentage)
+
+#### Interpreting the Numbers
+
+Use these benchmarks to explain financial health in plain language:
+
+| Metric | Healthy | Moderate | Risky |
+|--------|---------|----------|-------|
+| Profit margin | > 10% | 3-10% | < 3% or negative |
+| Equity ratio | > 30% | 20-30% | < 20% |
+| Revenue growth | > 10% | 0-10% | Declining |
+| Debt-to-equity | < 2x | 2-4x | > 4x |
+
+Examples of plain-language interpretation:
+- "Revenue has grown 12% year-over-year, showing healthy expansion."
+- "The equity ratio of 18% is below the 20% threshold, which means the company is heavily leveraged."
+- "Profit margins have been declining for three consecutive years, from 15% to 8%."
+
+### Key People
+
+List board members, CEO, and other roles from the company data. Format as:
+
+- **Board Chair:** Name (since year)
+- **CEO / Daglig leder:** Name (since year)
+- **Board Members:** Name 1, Name 2, Name 3
+
+### Ownership Structure
+
+From `get_shareholders`:
+- List corporate shareholders with ownership percentages
+- Note majority shareholders (> 50%) and significant holders (> 10%)
+- If requested, include personal shareholders
+
+### Corporate Group
+
+From `get_corporate_group`:
+- Show parent company (if any)
+- List subsidiaries (if any)
+- Note the company's position in the hierarchy
+
+### Food Safety and Licenses (hospitality only)
+
+If the company is in NACE 55-56:
+
+**Inspections (Smilefjes):**
+- Most recent inspection date and rating
+- Rating scale: 0 = smiling face (best), 1 = neutral, 2 = sad, 3 = very sad (worst)
+- Any recent downgrades or improvements
+
+**Licenses:**
+- Active alcohol/tobacco licenses with type and validity period
+- License types: 01SKJE = serving license, 11ENGR = wholesale, 18TBIM = import, 19TBEK = export
+
+## Step 4: Closing Summary
+
+End the report with:
+- A one-paragraph plain-language summary of the company's health and position
+- The org number for reference: "Org number: 999888777"
+- Offer next steps: "Would you like me to check what this company owns, push it to your CRM, or compare it with competitors?"

package/skills/market-scan/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: market-scan
+description: >
+  Analyze a Norwegian market segment — size, top players, technology landscape,
+  procurement opportunities, regulatory status. Use for market research or
+  proposal preparation.
+allowed-tools: mcp__orakel__search_companies, mcp__orakel__find_prospects, mcp__orakel__search_procurement, mcp__orakel__search_licenses, mcp__orakel__search_inspections, mcp__orakel__list_municipalities
+---
+
+# Market Scan
+
+Produce a market analysis of a Norwegian industry segment, suitable for proposals, strategy documents, or competitive intelligence.
+
+## Step 1: Define the Market Segment
+
+Map the user's description to concrete filters. Ask clarifying questions if needed:
+
+- **What industry?** Map to NACE code(s).
+- **What geography?** Nationwide, specific county, or specific municipality.
+- **What size range?** All companies, or only above a certain threshold.
+
+### NACE Industry Codes
+
+| Code | Industry |
+|------|----------|
+| 01-03 | Agriculture, forestry, fishing |
+| 10-12 | Food, beverage, and tobacco manufacturing |
+| 41-43 | Construction (buildings, civil engineering, specialized) |
+| 46 | Wholesale trade |
+| 47 | Retail trade |
+| 50 | Shipping / water transport |
+| 55 | Hotels and accommodation |
+| 56.1 | Restaurants and cafes |
+| 56.3 | Bars and pubs |
+| 62.01 | Software development |
+| 62.02 | IT consulting |
+| 62.09 | Other IT services |
+| 64 | Financial services |
+| 69.1 | Accounting and auditing |
+| 69.2 | Legal services |
+| 70.22 | Management consulting |
+| 73.1 | Advertising agencies |
+| 85 | Education |
+| 86 | Health services |
+
+### County Codes
+
+| Code | County |
+|------|--------|
+| 03 | Oslo |
+| 11 | Rogaland |
+| 15 | More og Romsdal |
+| 18 | Nordland |
+| 30 | Viken |
+| 34 | Innlandet |
+| 38 | Vestfold og Telemark |
+| 42 | Agder |
+| 46 | Vestland |
+| 50 | Trondelag |
+| 54 | Troms og Finnmark |
+
+Use `list_municipalities` if the user names a specific city to find the municipality code.
+
+## Step 2: Market Overview
+
+Run `search_companies` with the NACE and region filters. Set `limit: 100` and `sort: employeeCount`, `order: desc` to get the biggest players first.
+
+Produce these metrics from the results:
+
+### Segment Size
+- Total number of companies matching the criteria
+- Total employees across the segment (sum of employeeCount)
+- Estimated total revenue (sum of latest revenue from financials, where available)
+
+### Size Distribution
+Categorize companies by employee count:
+
+| Size Class | Employees | Count |
+|------------|-----------|-------|
+| Micro | 1-4 | |
+| Small | 5-19 | |
+| Medium | 20-99 | |
+| Large | 100-249 | |
+| Enterprise | 250+ | |
+
+### Top 10 by Revenue
+
+| # | Company | Org Number | Location | Employees | Revenue (MNOK) |
+|---|---------|-----------|----------|-----------|----------------|
+| 1 | ... | ... | ... | ... | ... |
+
+Format revenue in millions NOK (MNOK), rounded to one decimal.
+
+## Step 3: Technology Landscape
+
+If tech stack data is available, summarize:
+- Most common technologies detected (WordPress, Shopify, HubSpot, etc.)
+- Percentage of companies running digital ads (hasAnyAdPixel)
+- This reveals the digital maturity of the segment.
+
+## Step 4: Procurement Opportunities
+
+Use `search_procurement` to find active public tenders relevant to the sector.
+
+Map NACE codes to CPV codes for procurement search:
+
+| NACE sector | CPV code prefix | Description |
+|-------------|----------------|-------------|
+| 62 (IT) | 72 | IT services |
+| 41-43 (Construction) | 45 | Construction work |
+| 85 (Education) | 80 | Education services |
+| 86 (Health) | 85 | Health services |
+| 73 (Advertising) | 79 | Business services |
+| 55-56 (Hospitality) | 55 | Hotel and restaurant services |
+
+Filter with `status: "ACTIVE"` and `deadlineAfter` set to today's date to show only open tenders.
+
+Present as:
+
+### Active Tenders
+| Title | Contracting Authority | Deadline | Est. Value (MNOK) |
+|-------|-----------------------|----------|-------------------|
+
+If no active tenders are found, say so explicitly — that's useful information too.
+
+## Step 5: Regulatory Landscape (Hospitality and Food Sectors Only)
+
+For NACE 55-56 segments, add:
+
+### Food Safety Overview
+Use `search_inspections` to get recent inspections in the region. Summarize:
+- Distribution of ratings (how many 0/1/2/3)
+- Average rating for the segment
+- Rating scale: 0 = best (smiling face), 3 = worst (very sad face)
+
+### License Landscape
+Use `search_licenses` to check the segment. Summarize:
+- Number of active alcohol serving licenses (01SKJE)
+- Number of wholesale licenses (11ENGR)
+- Import/export licenses (18TBIM / 19TBEK)
+
+## Step 6: Format for Output
+
+Structure the final report under clear headings. Use tables wherever possible. The output should be ready to copy-paste into a proposal or strategy document.
+
+### Suggested Report Structure
+
+```
+# Market Analysis: [Industry] in [Region]
+
+## Executive Summary
+[2-3 sentence overview of the market]
+
+## Market Size
+[Segment size metrics and size distribution table]
+
+## Top Players
+[Top 10 table by revenue]
+
+## Technology Adoption
+[Tech landscape summary]
+
+## Public Procurement
+[Active tenders or note that none exist]
+
+## Regulatory Landscape (if applicable)
+[Inspection and license summary]
+
+## Key Takeaways
+[3-5 bullet points summarizing the most important findings]
+```
+
+If the user mentions this is for a specific proposal or client, adapt the framing accordingly.

package/skills/ownership-map/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ownership-map
+description: >
+  Trace ownership networks and corporate hierarchies for Norwegian companies.
+  Use for due diligence, competitive intelligence, or compliance research.
+allowed-tools: mcp__orakel__lookup_company, mcp__orakel__get_shareholders, mcp__orakel__get_ownership_network, mcp__orakel__get_corporate_group
+---
+
+# Ownership Map
+
+Trace ownership structures, corporate hierarchies, and shareholder networks for Norwegian companies.
+
+## Step 1: Identify the Target Company
+
+The user may provide:
+
+- **Organization number** (9 digits): Use `lookup_company` directly.
+- **Company name**: Use `lookup_company` to search. If ambiguous, list the top matches and ask the user to confirm.
+
+Get the basic company info first so you can reference the name and org number throughout the analysis.
+
+## Step 2: Gather Ownership Data
+
+Make these calls:
+
+1. **`get_shareholders`** with the org number — who owns this company?
+   - Start with `includePersons: false` for privacy (only shows corporate shareholders).
+   - Mention that personal shareholders can be revealed if the user requests it.
+
+2. **`get_ownership_network`** with the org number as `shareholderOrgNumber` — what does this company own?
+   - This is the reverse lookup: shows companies where the target is a shareholder.
+
+3. **`get_corporate_group`** with the org number — formal corporate hierarchy.
+   - Shows the parent company and all subsidiaries registered in Brreg.
+   - This is the legal group structure, which may differ from the shareholder-based ownership.
+
+## Step 3: Build the Ownership Picture
+
+### 3a: Upward Ownership (Who Owns This Company?)
+
+From `get_shareholders`, list all shareholders with their ownership percentage:
+
+**Shareholders of [Company Name] (org: 999888777):**
+
+| Shareholder | Org Number | Ownership % | Type |
+|-------------|-----------|-------------|------|
+| Parent Holdings AS | 888777666 | 67.0% | Majority |
+| Investment Fund AS | 777666555 | 22.5% | Significant |
+| Other shareholders | - | 10.5% | Minor |
+
+Classification thresholds:
+- **Majority:** > 50% ownership (controls the company)
+- **Significant:** > 10% ownership (meaningful influence)
+- **Minor:** < 10% ownership
+
+### 3b: Downward Ownership (What Does This Company Own?)
+
+From `get_ownership_network`, list all companies where the target is a shareholder:
+
+**Companies owned by [Company Name]:**
+
+| Company | Org Number | Ownership % | Employees | Revenue (MNOK) |
+|---------|-----------|-------------|-----------|----------------|
+| Subsidiary One AS | 666555444 | 100% | 25 | 18.5 |
+| Joint Venture AS | 555444333 | 50% | 8 | 5.2 |
+
+### 3c: Formal Corporate Group
+
+From `get_corporate_group`, show the registered group hierarchy:
+
+**Corporate group structure:**
+
+```
+[Ultimate Parent] Holding Group AS (111222333)
+  |
+  +-- [Parent] Parent Holdings AS (888777666)
+  |     |
+  |     +-- [Target] Company Name AS (999888777)  <-- target company
+  |     |
+  |     +-- Sibling Company AS (444333222)
+  |
+  +-- Other Branch AS (333222111)
+```
+
+Note: The formal group structure (from Brreg) may differ from shareholder-based ownership. The group structure shows the registered parent-subsidiary relationships, while shareholders show the actual equity ownership.
+
+## Step 4: Trace One Level Deeper (if warranted)
+
+For majority shareholders and significant holdings, offer to trace one level deeper:
+
+> The majority shareholder is Parent Holdings AS (888777666). Want me to check who owns that company too?
+
+**Important: Limit recursion to 2 levels maximum.** Beyond that, the network becomes unwieldy and may trigger many API calls. If the user wants to go deeper, do it one step at a time.
+
+For each additional level, use `get_shareholders` on the parent company.
+
+## Step 5: Build a Text Tree Visualization
+
+Combine all findings into a single ownership tree. Use indentation and lines to show relationships:
+
+```
+Ownership Network for Company Name AS (999888777)
+==================================================
+
+OWNERS (who owns this company):
+  [67.0%] Parent Holdings AS (888777666)
+    [100%] Ultimate Owner AS (111222333)  <-- level 2
+  [22.5%] Investment Fund AS (777666555)
+  [10.5%] Other/personal shareholders
+
+SUBSIDIARIES (what this company owns):
+  [100%] Subsidiary One AS (666555444) - 25 employees, 18.5 MNOK revenue
+  [ 50%] Joint Venture AS (555444333) - 8 employees, 5.2 MNOK revenue
+
+CORPORATE GROUP (formal Brreg registration):
+  Ultimate Owner AS (111222333)
+    +-- Parent Holdings AS (888777666)
+          +-- ** Company Name AS (999888777) **  <-- target
+          +-- Sibling Company AS (444333222)
+```
+
+## Step 6: Flag Notable Patterns
+
+Highlight any of these patterns if found:
+
+- **Circular ownership:** Company A owns B, which owns A (or through intermediaries). This is unusual and worth flagging.
+- **Shell company indicators:** A shareholder company with zero employees and zero revenue that exists solely as a holding entity. Not necessarily suspicious, but worth noting.
+- **Same person/entity appearing multiple times:** If the same shareholder appears in multiple positions across the network, highlight this — it may indicate concentrated control.
+- **Mismatch between group structure and ownership:** If the Brreg group tree and shareholder data tell different stories, note the discrepancy.
+- **Foreign ownership:** If a shareholder is not found in Norwegian registries, it may be a foreign entity.
+- **Recent changes:** If shareholder data shows different ownership across years, mention the change.
+
+## Step 7: Closing Summary
+
+End with:
+
+- A plain-language summary: "Company Name is majority-owned (67%) by Parent Holdings, which is in turn fully owned by Ultimate Owner. The company itself holds two subsidiaries."
+- The target company's org number for reference.
+- Offer next steps: "Want me to do a deep dive on any of these related companies, or check the financials across the group?"

package/skills/prospect/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: prospect
+description: >
+  Find and qualify Norwegian business prospects by industry, location, and size.
+  Use when looking for potential clients, leads, or market opportunities.
+allowed-tools: mcp__orakel__search_companies, mcp__orakel__find_prospects, mcp__orakel__list_municipalities, mcp__orakel__get_financials, mcp__orakel__push_to_destination, mcp__orakel__list_destinations
+---
+
+# Prospect Finder
+
+Find and qualify Norwegian business prospects using Orakel's company database.
+
+## Step 1: Understand What the User is Looking For
+
+Before searching, clarify these dimensions. If the user is vague, ask structured questions:
+
+- **Industry:** What type of business? (restaurants, IT, construction, retail, etc.)
+- **Region:** Where? (specific city, county, or all of Norway)
+- **Size:** How big? (number of employees, revenue range)
+- **Other filters:** Technology stack, ad spend, part of a corporate group?
+
+Example prompt if the user says "find me some prospects":
+> I can search Norwegian companies by industry, location, and size. Could you tell me:
+> 1. What industry are you targeting?
+> 2. Any geographic preference? (city, county, or nationwide)
+> 3. What company size range? (employees or revenue)
+
+## Step 2: Map Request to Search Filters
+
+Translate the user's plain-language request into API parameters using these reference tables.
+
+### NACE Industry Codes (use as prefix with `nace` parameter)
+
+| Code | Industry |
+|------|----------|
+| 01 | Agriculture, crop production |
+| 02 | Forestry |
+| 03 | Fishing and aquaculture |
+| 10 | Food manufacturing |
+| 11 | Beverage manufacturing |
+| 12 | Tobacco manufacturing |
+| 41 | Building construction |
+| 42 | Civil engineering |
+| 43 | Specialized construction |
+| 46 | Wholesale trade |
+| 47 | Retail trade |
+| 50 | Shipping / water transport |
+| 55 | Hotels and accommodation |
+| 56.1 | Restaurants and cafes |
+| 56.3 | Bars and pubs |
+| 62.01 | Software development |
+| 62.02 | IT consulting |
+| 62.09 | Other IT services |
+| 64 | Financial services |
+| 69.1 | Accounting and auditing |
+| 69.2 | Legal services |
+| 70.22 | Management consulting |
+| 73.1 | Advertising agencies |
+| 85 | Education |
+| 86 | Health services |
+
+Use partial codes for broader searches: `56` matches all food/drink, `62` matches all IT, `41` to `43` matches all construction.
+
+### County Codes (use with `county` parameter)
+
+| Code | County |
+|------|--------|
+| 03 | Oslo |
+| 11 | Rogaland |
+| 15 | More og Romsdal |
+| 18 | Nordland |
+| 30 | Viken |
+| 34 | Innlandet |
+| 38 | Vestfold og Telemark |
+| 42 | Agder |
+| 46 | Vestland |
+| 50 | Trondelag |
+| 54 | Troms og Finnmark |
+
+If the user names a city instead of a county, use `list_municipalities` to find the municipality code and use the `municipality` parameter instead.
+
+### Organization Forms
+
+| Code | Type |
+|------|------|
+| AS | Private limited company (aksjeselskap) — most common |
+| ASA | Public limited company |
+| ENK | Sole proprietorship |
+| NUF | Norwegian branch of foreign company |
+| SA | Cooperative |
+
+## Step 3: Run the Search
+
+Use `find_prospects` for prospect-oriented results (pre-sorted by size, includes financials).
+Use `search_companies` for more flexible filtering (custom sort, more filter options).
+
+Present results as a ranked summary table:
+
+| # | Company | Org Number | Location | Employees | Revenue (MNOK) |
+|---|---------|-----------|----------|-----------|----------------|
+| 1 | Example AS | 999888777 | Oslo | 45 | 32.5 |
+
+Format revenue in millions NOK (MNOK) for readability. Round to one decimal.
+
+If no results are found:
+- Try broadening the NACE code (use parent code like `56` instead of `56.1`)
+- Try removing the county filter
+- Try lowering the minimum employee/revenue threshold
+- Suggest alternative NACE codes that might match what the user meant
+
+## Step 4: Offer Detailed Financials
+
+After presenting the summary, offer:
+
+> Would you like me to pull detailed financials for any of these companies? I can show multi-year revenue, profit, and key ratios.
+
+Use `get_financials` for selected companies. Present year-over-year trends:
+
+- Revenue trend (growing, stable, declining)
+- Profit margin (net result / revenue)
+- Whether they appear financially healthy
+
+### Financial Health Quick Guide
+
+| Metric | Healthy | Caution | Warning |
+|--------|---------|---------|---------|
+| Profit margin | > 10% | 3-10% | < 3% or negative |
+| Revenue growth YoY | > 5% | 0-5% | Declining |
+| Equity ratio | > 30% | 20-30% | < 20% |
+
+## Step 5: Offer CRM Push
+
+If the user seems satisfied with the results, offer:
+
+> Want me to push these companies to your CRM? I can check which destinations are configured.
+
+1. Use `list_destinations` to show available CRM destinations.
+2. Confirm which companies to push (all results, or a selection).
+3. Use `push_to_destination` with the chosen destination name and org numbers.
+4. Report the results: how many were created, updated, or failed.

package/skills/push-to-crm/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: push-to-crm
+description: >
+  Push company data to a configured CRM destination (Attio, HubSpot, webhooks).
+  Use when the user wants to export or sync companies to their CRM.
+allowed-tools: mcp__orakel__list_destinations, mcp__orakel__push_to_destination, mcp__orakel__manage_destination, mcp__orakel__search_companies, mcp__orakel__lookup_company
+---
+
+# Push to CRM
+
+Export company data from Orakel to a configured CRM destination.
+
+## Step 1: Identify Which Companies to Push
+
+The user might provide companies in several ways:
+
+- **Explicit org numbers:** Use those directly.
+- **Coming from a previous search or prospect list:** Offer to push all results or let the user select specific ones.
+- **A company name:** Use `search_companies` or `lookup_company` to resolve the org number first.
+
+If the user says something vague like "push those companies," refer back to the most recent search results in the conversation.
+
+Confirm the list before pushing:
+
+> I'll push these 5 companies to your CRM:
+> 1. Example AS (999888777)
+> 2. Another AS (888777666)
+> 3. ...
+>
+> Which destination should I use?
+
+## Step 2: Check Available Destinations
+
+Use `list_destinations` to show what's configured.
+
+Present them simply:
+
+> You have these CRM destinations set up:
+> - **zero7-attio** (Attio CRM) - Active
+> - **test-webhook** (Webhook) - Active
+
+### If No Destinations Exist
+
+Walk the user through creating one:
+
+> You don't have any CRM destinations configured yet. I can set one up for you.
+> What type of destination do you want?
+> - **Attio** — pushes companies as Attio records
+> - **Webhook** — sends company data to a URL you specify
+
+Then use `manage_destination` with action "create":
+
+- For Attio: Need the Attio API key and workspace slug
+- For Webhook: Need the target URL and optionally an auth header
+
+Example:
+```
+manage_destination(
+  action: "create",
+  name: "my-attio",
+  type: "attio",
+  config: { apiKey: "...", workspaceSlug: "..." }
+)
+```
+
+### If a Destination is Inactive
+
+Mention it and offer to reactivate:
+
+> The destination "old-webhook" exists but is inactive. Want me to reactivate it?
+
+Use `manage_destination` with action "update" and `isActive: true`.
+
+## Step 3: Execute the Push
+
+Use `push_to_destination` with the destination name and array of org numbers.
+
+**Important limits:**
+- Push in batches if there are more than 50 companies (the API may time out on large batches).
+- Each push is idempotent — pushing the same company twice will update rather than duplicate.
+
+## Step 4: Report Results
+
+The push response includes counts of created, updated, and failed records. Report clearly:
+
+> Push complete:
+> - **Created:** 3 new records in Attio
+> - **Updated:** 2 existing records refreshed
+> - **Failed:** 0
+>
+> All 5 companies are now in your CRM.
+
+If any failed, show the org numbers and error messages so the user can investigate.
+
+## Important Notes
+
+- **Attio preserves brand names:** When pushing to Attio, company names from Orakel (legal names from Brreg) will not overwrite brand names that have been manually set in Attio. Only empty name fields get populated.
+- **Data freshness:** Orakel pushes the latest data it has. Financial data may be up to a year old (depends on when the company filed).
+- **Destination management:** Use `manage_destination` to create, update config, activate/deactivate, or delete destinations.