@apier-no/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PowerLaunch AS
+
+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,133 @@
+# @apier-no/mcp
+
+Thin npm proxy that connects local MCP clients (Claude Desktop, Cursor, Zed, Codex, etc.) to **[Apier](https://www.apier.no)'s hosted Norwegian compliance MCP server** at `https://www.apier.no/api/mcp`.
+
+Apier exposes Norwegian government compliance data and actions — Brønnøysund company lookups, Altinn delegations, Skatteetaten obligations, deadline math, regulatory rules — as MCP tools that AI agents can call directly. This package is the local bridge: it runs over stdio in your MCP client and forwards every frame to Apier over Streamable HTTP.
+
+## What it is (and what it isn't)
+
+**Is:** a ~150-line transport-level passthrough. Your client speaks MCP over stdio; this proxy forwards every frame to `https://www.apier.no/api/mcp` with your `Authorization: Bearer ${APIER_API_KEY}` header attached.
+
+**Isn't:** a re-implementation of MCP. All tool / resource / prompt semantics live server-side. When Apier ships a new tool, you don't reinstall this package — the new tool surfaces immediately to your local client.
+
+## Install
+
+```sh
+npm install -g @apier-no/mcp
+```
+
+Or use `npx` directly in your MCP client config (recommended — no global install needed):
+
+```sh
+npx -y @apier-no/mcp
+```
+
+## Get an API key
+
+Sign up at [apier.no](https://www.apier.no) and visit your dashboard:
+
+→ **<https://www.apier.no/dashboard/keys>**
+
+The Free tier ships with one key and enough quota for evaluation. Keys are scoped — Apier rotates them and revokes per-key with no global rollover.
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "apier": {
+      "command": "npx",
+      "args": ["-y", "@apier-no/mcp"],
+      "env": {
+        "APIER_API_KEY": "apier_live_<your_key_here>"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Apier tools (company lookup, obligations, deadlines, etc.) will appear in the tool picker.
+
+## Cursor
+
+Edit `~/.cursor/mcp.json` (or use Cursor's MCP settings UI):
+
+```json
+{
+  "mcpServers": {
+    "apier": {
+      "command": "npx",
+      "args": ["-y", "@apier-no/mcp"],
+      "env": {
+        "APIER_API_KEY": "apier_live_<your_key_here>"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor. Apier tools become available to Cursor's agent.
+
+## Other MCP clients
+
+Any MCP client that supports the stdio transport works. The pattern is the same: invoke `npx -y @apier-no/mcp` with `APIER_API_KEY` in the environment.
+
+## Available tools
+
+See **<https://www.apier.no/docs>** for the live tool catalogue and parameter shapes. Tools are versioned server-side; the catalogue is the canonical reference.
+
+A non-exhaustive snapshot:
+
+- `company.lookup` — Brønnøysund company-registry lookups by org number
+- `company.obligations` — current and upcoming regulatory obligations
+- `company.deadlines` — deadline math (MVA filings, A-melding, årsregnskap, …)
+- `delegations.list` — Altinn delegations for an org number
+- `rules.evaluate` — run an evaluation against the live Apier Rulebook
+
+## Configuration
+
+| Variable               | Default                                | Description                                                    |
+|------------------------|----------------------------------------|----------------------------------------------------------------|
+| `APIER_API_KEY`        | **(required, no default)**             | Your Apier API key. Get one at the dashboard link above.       |
+| `APIER_MCP_ENDPOINT`   | `https://www.apier.no/api/mcp`         | Override the server URL. **Must be `https://`**; `http://` is rejected. |
+
+You can also pass `--endpoint <url>` as a CLI flag (env var has priority for the key — see Security below).
+
+## Troubleshooting
+
+**1. "APIER_API_KEY environment variable is required."**
+
+The proxy could not find an `APIER_API_KEY` in its environment. In MCP-client configs, the env var goes inside the `"env"` object of the server entry — *not* as a CLI argument. Re-read the JSON snippets above; the proxy intentionally refuses CLI-flag keys because `ps aux` and Activity Monitor leak CLI arguments to other local users.
+
+**2. "Endpoint must use https://"**
+
+You set `APIER_MCP_ENDPOINT` (or `--endpoint`) to an `http://` URL. The proxy refuses plaintext — your API key would be visible to anything on the network path. Apier's production endpoint is `https://www.apier.no/api/mcp`; only override this for local Apier development behind an HTTPS-terminating proxy.
+
+**3. Tool calls return "401 Unauthorized" or "403 Forbidden"**
+
+Your API key was rejected by Apier. Check at <https://www.apier.no/dashboard/keys> that the key is active and not revoked. If the issue is `403 Forbidden` rather than `401 Unauthorized`, the key is valid but the requested tool requires a higher tier or a scope that the key doesn't carry — the dashboard shows per-key scopes.
+
+## Security
+
+The proxy is built for the worst case: a malicious or buggy MCP client running on the same machine.
+
+- `APIER_API_KEY` is read from the environment **only**. CLI-flag keys are refused — `ps`-listable arguments are a leak channel.
+- `https://` is enforced; `http://` is rejected at startup.
+- The proxy never writes the API key value to stdout, stderr, log files, or error messages. Error formatting uses `err.constructor.name`, never `err.message` (which can carry HTTP header bytes).
+- All diagnostic output goes to stderr; stdout is reserved exclusively for MCP JSON-RPC frames so a stray log line cannot corrupt the protocol stream and crash the client.
+
+## Source + issues
+
+- Source: <https://github.com/PowerLaunch/apier-mcp>
+- Issues: <https://github.com/PowerLaunch/apier-mcp/issues>
+- Apier docs: <https://www.apier.no/docs>
+
+## Versioning
+
+Semver. The proxy aims to be stable — most Apier feature additions land server-side and surface to local clients without a republish. Breaking changes to the proxy itself (CLI flags, env vars, supported Node versions) bump minor or major.
+
+## License
+
+[MIT](LICENSE) © 2026 PowerLaunch AS

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * apier-mcp CLI entry point.
+ *
+ * Reads APIER_API_KEY from the environment ONLY — never accepts the
+ * key as a CLI flag. Process listings (`ps aux`, Activity Monitor)
+ * leak CLI arguments to any local user; environment variables are
+ * scoped to the process and are the documented MCP-client config
+ * pattern (`env: { APIER_API_KEY: "..." }`).
+ *
+ * Recognised flags:
+ *   --endpoint <url>   Override the default https://www.apier.no/api/mcp
+ *                      (or set APIER_MCP_ENDPOINT env var)
+ *   --version, -v      Print version and exit
+ *   --help, -h         Print usage and exit
+ */
+import { startProxy } from "./index.js";
+// Keep in sync with package.json#version. Hardcoded rather than read at
+// runtime so a bundled binary doesn't need fs access. The build script
+// (and prepublishOnly hook) is the discipline that keeps this honest.
+const VERSION = "0.1.0";
+const HELP = `apier-mcp ${VERSION} — Thin proxy to Apier's hosted MCP server.
+
+Usage: apier-mcp [options]
+
+Options:
+  --endpoint <url>     Override default https://www.apier.no/api/mcp
+                       (or set APIER_MCP_ENDPOINT)
+  --version, -v        Print version and exit
+  --help, -h           Print this help and exit
+
+Required environment variable:
+  APIER_API_KEY        Get a key at https://www.apier.no/dashboard/keys
+
+Example MCP client config (Claude Desktop / Cursor):
+  {
+    "mcpServers": {
+      "apier": {
+        "command": "npx",
+        "args": ["-y", "@apier-no/mcp"],
+        "env": { "APIER_API_KEY": "apier_live_<your_key>" }
+      }
+    }
+  }
+
+Docs: https://www.apier.no/docs
+Issues: https://github.com/PowerLaunch/apier-mcp/issues
+`;
+function parseArgs(argv) {
+    let endpoint;
+    let showHelp = false;
+    let showVersion = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            showHelp = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            showVersion = true;
+        }
+        else if (arg === "--endpoint") {
+            const next = argv[i + 1];
+            if (typeof next !== "string" || next.length === 0) {
+                return {
+                    showHelp: false,
+                    showVersion: false,
+                    error: "--endpoint requires a URL argument.",
+                };
+            }
+            endpoint = next;
+            i++;
+        }
+        else {
+            return {
+                showHelp: false,
+                showVersion: false,
+                error: `Unknown argument: ${arg}`,
+            };
+        }
+    }
+    return { endpoint, showHelp, showVersion };
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.error !== undefined) {
+        process.stderr.write(`apier-mcp: ${parsed.error}\n\n${HELP}`);
+        process.exit(1);
+    }
+    if (parsed.showHelp) {
+        // Help goes to stderr (NOT stdout) — stdout is reserved for MCP
+        // JSON-RPC frames. A user running `apier-mcp --help` sees the
+        // text the same way regardless of stream.
+        process.stderr.write(HELP);
+        process.exit(0);
+    }
+    if (parsed.showVersion) {
+        process.stderr.write(`apier-mcp ${VERSION}\n`);
+        process.exit(0);
+    }
+    try {
+        await startProxy({ endpoint: parsed.endpoint });
+    }
+    catch (err) {
+        // Last-resort error handler. Never echo err.message — Supabase /
+        // network error strings can carry token fragments or header
+        // bytes. Only the constructor name is safe.
+        const name = err instanceof Error ? err.constructor.name : typeof err;
+        process.stderr.write(`apier-mcp: fatal error (${name})\n`);
+        process.exit(1);
+    }
+}
+void main();

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export interface StartProxyOptions {
+    /** Override https://www.apier.no/api/mcp. Falls back to
+     *  APIER_MCP_ENDPOINT env var, then to the default. */
+    endpoint?: string;
+}
+export declare function startProxy(options?: StartProxyOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,122 @@
+/**
+ * @apier-no/mcp — Thin transport-level proxy that bridges a local stdio
+ * MCP client (Claude Desktop, Cursor, etc.) to Apier's hosted MCP
+ * server over Streamable HTTP.
+ *
+ * The proxy is intentionally a pure-passthrough pipe at the transport
+ * level — it never inspects, decodes, or rewrites MCP protocol frames.
+ * All tool / resource / prompt semantics live server-side at
+ * https://www.apier.no/api/mcp; a thin proxy makes the local client
+ * transparent to MCP-protocol additions without requiring an npm
+ * republish.
+ *
+ * SECURITY:
+ *   - APIER_API_KEY is read from the environment ONLY (never CLI
+ *     flag — `ps aux` would leak it). Missing or empty key exits 1
+ *     with a helpful stderr message.
+ *   - HTTP endpoint is rejected if not https:// — Apier is HTTPS-only.
+ *   - ALL diagnostic output goes to stderr; stdout is reserved for
+ *     MCP JSON-RPC frames (corrupting stdout with a stray log line
+ *     breaks the MCP client).
+ *   - APIER_API_KEY value is NEVER written to stderr (or anywhere).
+ *     Error messages format only `err.name` / `err.constructor.name`,
+ *     never the message which could carry header / auth bytes.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const DEFAULT_ENDPOINT = "https://www.apier.no/api/mcp";
+export async function startProxy(options = {}) {
+    // ── API key ─────────────────────────────────────────────────
+    const apiKey = process.env.APIER_API_KEY;
+    if (typeof apiKey !== "string" || apiKey.length === 0) {
+        process.stderr.write("apier-mcp: APIER_API_KEY environment variable is required.\n" +
+            "  Get a key at https://www.apier.no/dashboard/keys\n" +
+            "  Then add it to your MCP client config (example for Claude Desktop):\n" +
+            '    "env": { "APIER_API_KEY": "apier_live_<your_key>" }\n');
+        process.exit(1);
+    }
+    // ── Endpoint resolution + HTTPS-only enforcement ────────────
+    const rawEndpoint = options.endpoint ?? process.env.APIER_MCP_ENDPOINT ?? DEFAULT_ENDPOINT;
+    let endpointUrl;
+    try {
+        endpointUrl = new URL(rawEndpoint);
+    }
+    catch {
+        process.stderr.write(`apier-mcp: invalid endpoint URL "${rawEndpoint}". Expected an https:// URL.\n`);
+        process.exit(1);
+    }
+    if (endpointUrl.protocol !== "https:") {
+        process.stderr.write(`apier-mcp: endpoint must use https:// (got "${endpointUrl.protocol}//"). Apier's MCP server is HTTPS-only — http:// would expose API keys in transit.\n`);
+        process.exit(1);
+    }
+    process.stderr.write(`apier-mcp: connecting to ${endpointUrl.href}\n`);
+    // ── Transports ─────────────────────────────────────────────
+    // StreamableHTTPClientTransport: outbound link to Apier.
+    // The Authorization header is set via requestInit so it threads
+    // through every HTTP request the transport makes.
+    const httpTransport = new StreamableHTTPClientTransport(endpointUrl, {
+        requestInit: {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+        },
+    });
+    // StdioServerTransport: local link to Claude Desktop / Cursor /
+    // any stdio-MCP client. Reads framed messages from stdin, writes
+    // to stdout.
+    const stdioTransport = new StdioServerTransport();
+    // ── Bridge ─────────────────────────────────────────────────
+    // Pure transport-level passthrough. We never decode MCP frames,
+    // so a future protocol version with new methods works without a
+    // republish. The MCP session state lives end-to-end between the
+    // local client and the Apier server — we're just plumbing.
+    stdioTransport.onmessage = (message) => {
+        void httpTransport.send(message).catch((err) => {
+            // Log only the error constructor name — error.message can
+            // carry header bytes or fragments of the request body.
+            const name = err instanceof Error ? err.constructor.name : typeof err;
+            process.stderr.write(`apier-mcp: client→server forward failed (${name})\n`);
+        });
+    };
+    httpTransport.onmessage = (message) => {
+        void stdioTransport.send(message).catch((err) => {
+            const name = err instanceof Error ? err.constructor.name : typeof err;
+            process.stderr.write(`apier-mcp: server→client forward failed (${name})\n`);
+        });
+    };
+    // ── Graceful shutdown ──────────────────────────────────────
+    let shuttingDown = false;
+    const handleShutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        process.stderr.write(`apier-mcp: ${signal} received, closing transports.\n`);
+        try {
+            await stdioTransport.close();
+        }
+        catch (err) {
+            const name = err instanceof Error ? err.constructor.name : typeof err;
+            process.stderr.write(`apier-mcp: stdio close error (${name})\n`);
+        }
+        try {
+            await httpTransport.close();
+        }
+        catch (err) {
+            const name = err instanceof Error ? err.constructor.name : typeof err;
+            process.stderr.write(`apier-mcp: http close error (${name})\n`);
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", () => {
+        void handleShutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        void handleShutdown("SIGTERM");
+    });
+    // ── Start ──────────────────────────────────────────────────
+    // Start HTTP first so the local client sees a ready proxy by
+    // the time stdin starts emitting frames.
+    await httpTransport.start();
+    await stdioTransport.start();
+    process.stderr.write("apier-mcp: ready, bridging messages.\n");
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@apier-no/mcp",
+  "version": "0.1.0",
+  "description": "Thin npm proxy: connect local MCP clients (Claude Desktop, Cursor) to Apier's hosted Norwegian compliance MCP server.",
+  "type": "module",
+  "bin": {
+    "apier-mcp": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PowerLaunch/apier-mcp.git"
+  },
+  "homepage": "https://www.apier.no",
+  "bugs": {
+    "url": "https://github.com/PowerLaunch/apier-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "apier",
+    "norway",
+    "norwegian-compliance",
+    "altinn",
+    "skatteetaten",
+    "claude",
+    "cursor"
+  ],
+  "author": "PowerLaunch AS",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}