@asif2bd/umami-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M Asif Rahman
+
+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,400 @@
+# Umami MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [Umami Analytics](https://umami.is).
+Ask Claude, Cursor or any MCP client about your traffic — and let it create and manage websites — while your
+credentials stay on your own machine.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
+![Umami](https://img.shields.io/badge/Umami-v3-blue)
+
+```
+"Which pages drove the most visitors last month, and where did that traffic come from?"
+"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
+"Add analytics for my new site blog.example.com and give me the tracking snippet."
+```
+
+## Why this exists
+
+Umami has no official MCP server. Several community ones exist, and if you just want broad API
+coverage you should look at [`0xtlt/umami-mcp`](https://github.com/0xtlt/umami-mcp) first — it
+wraps more of the API than this does. Some of the older servers
+([`jakeyShakey`](https://github.com/jakeyShakey/umami_mcp_server),
+[`mikusnuz`](https://github.com/mikusnuz/umami-mcp),
+[`mittwald`](https://github.com/mittwald/umami-mcp),
+[`Macawls`](https://github.com/Macawls/umami-mcp-server)) were written against the **v2** API and
+break on a modern instance, because v3 renamed things without aliases:
+
+| | Umami v2 | Umami v3 |
+|---|---|---|
+| Top pages | `/metrics?type=url` | `/metrics?type=path` |
+| Hostnames | `/metrics?type=host` | `/metrics?type=hostname` |
+| UTM data | `/metrics?type=utm_source` | `POST /api/reports/utm` |
+| Funnels, retention, journeys, attribution, revenue | — | `POST /api/reports/*` |
+
+This server exists for two things the others do not do:
+
+**1. Complete, verified v3 report coverage.** All seven v3 report types — funnel, retention,
+journey, goal, revenue, attribution and UTM — were exercised against a live **Umami 3.3.1**
+instance. The report envelope is easy to get wrong: dates go in `parameters` as ISO-8601 strings,
+not in `filters`, and not as the epoch milliseconds the rest of the API uses. Attribution takes
+`first-click` / `last-click`, not the camelCase spellings you would guess.
+
+**2. A capability model rather than a boolean.** See below.
+
+## Security model
+
+An analytics MCP server holds a credential that can read every visitor session you have ever
+recorded — and, if you let it, delete the lot. The design follows from that.
+
+**Your credentials never leave your environment.** Configuration is read only from the process
+environment. There is no telemetry, no phone-home, and no hosted relay. The only host this
+server ever contacts is the `UMAMI_URL` you set. If you self-host it, nothing about your
+analytics ever reaches a third party — including the author of this software.
+
+> Be wary of any Umami MCP that offers a hosted endpoint you point at your instance.
+> Self-hosted Umami has no API keys, so "convenient" hosting means mailing your **admin
+> password** to someone else's server.
+
+**Least privilege by default.** The server starts in `read` mode. Widening is a deliberate act:
+
+| Mode | Adds |
+|---|---|
+| `read` *(default)* | Analytics, reports, listing websites |
+| `write` | Create and update websites and teams |
+| `admin` | User management |
+| `+ UMAMI_MCP_ALLOW_DESTRUCTIVE=true` | Delete website, reset data, delete user |
+
+Withheld tools are **not registered at all**, so they never appear in the model's tool list.
+This is the part that differs from a `READONLY=true` flag: a tool that was never advertised
+cannot be invoked by a prompt-injected instruction hidden in, say, a referrer string or a page
+title inside your own analytics data. There is no runtime check to forget or bypass, because
+there is no tool.
+
+**Destructive actions need a typed confirmation checked against reality.** `umami_delete_website`
+takes a `confirmDomain` argument, fetches the live record, and refuses unless they match. A model
+that reaches for the wrong website UUID gets an error, not a wiped dataset.
+
+**Credentials stay out of client config.** Rather than requiring your password inside
+`~/.claude.json` or `mcp.json`, the server reads it from a file you control at
+`~/.config/umami-mcp/env`, and warns if that file is readable by other users. See
+[Credentials](#credentials).
+
+**Secrets are scrubbed from output.** MCP output flows into a model and often into a chat
+transcript, which cannot be un-said. Passwords, bearer tokens and JWTs are redacted from every
+error and response before they leave the process.
+
+**Refuses to leak credentials over the wire.** Plaintext HTTP to a remote host is rejected at
+startup; it is permitted only for `localhost`, for local development.
+
+## Install
+
+Three ways to run it. **Self-hosting is the default and the recommended one** — the hosted
+instance exists so you can try it in two minutes without cloning anything.
+
+| | Runs where | Credentials live | Best for |
+|---|---|---|---|
+| **Hosted** | asif.dev | Sealed in your token, never stored | Trying it out; Claude web and Cowork |
+| **Source** | Your machine | A file only you can read | Daily use in Claude Code |
+| **Docker** | Your server | Your `.env` | Teams, always-on |
+
+If you self-host and want it in Claude web, run it with `UMAMI_MCP_OAUTH=true` behind your own
+domain — then nothing of yours touches anyone else's infrastructure.
+
+### 1. Use the hosted instance (nothing to install)
+
+Add a custom connector in Claude pointing at:
+
+```
+https://umami-mcp.asif.dev/mcp
+```
+
+You will be asked for your own Umami URL and login on a consent screen. See
+[Claude web, Cowork, and Claude Code on web](#claude-web-cowork-and-claude-code-on-web)
+for how the credentials are handled.
+
+### 2. From source
+
+```bash
+git clone https://github.com/Asif2BD/umami-mcp.git
+cd umami-mcp
+npm install && npm run build
+```
+
+Then set up [credentials](#credentials) and register it with your client:
+
+```bash
+claude mcp add umami --scope user -- node "$PWD/dist/index.js"
+```
+
+Requires Node 20 or newer.
+
+### 3. Docker
+
+```bash
+git clone https://github.com/Asif2BD/umami-mcp.git
+cd umami-mcp
+cp .env.example .env    # then edit .env
+docker compose up -d
+```
+
+> **npm:** not published yet. Once it is, `npx -y @asif2bd/umami-mcp` will replace the
+> clone-and-build step above. Until then use source or Docker.
+
+## Credentials
+
+Self-hosted Umami has no API keys, so the credential this server holds is a **real account
+password**. MCP clients normally want that embedded in their config JSON — `~/.claude.json`,
+`mcp.json` and friends — which are widely readable, get pasted into issues and screen-shares, and
+are synced between machines by some clients.
+
+So this server reads credentials from a file you control instead. Create it once:
+
+```bash
+mkdir -p ~/.config/umami-mcp
+cat > ~/.config/umami-mcp/env <<'EOF'
+UMAMI_URL=https://analytics.example.com
+UMAMI_USERNAME=mcp-bot
+UMAMI_PASSWORD=your-password
+UMAMI_MCP_MODE=read
+EOF
+chmod 600 ~/.config/umami-mcp/env
+```
+
+The server loads it automatically. It warns on startup if the file is readable by other users.
+
+Lookup order — the first file found wins, and **real environment variables always override the
+file**, so you can still pass settings from the client config when you want to:
+
+1. `$UMAMI_MCP_ENV_FILE`, if set
+2. `~/.config/umami-mcp/env` (or `$XDG_CONFIG_HOME/umami-mcp/env`)
+3. `./.env` in the working directory
+
+## Connect your client
+
+### Claude Code
+
+With the credentials file above, the registration carries no secrets at all:
+
+```bash
+claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js
+```
+
+Use the absolute path to your checkout. If your Node lives under nvm, give the full
+interpreter path too, since MCP clients do not load your shell profile:
+
+```bash
+claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js
+```
+
+### Claude Desktop / Cursor / VS Code
+
+```json
+{
+  "mcpServers": {
+    "umami": {
+      "command": "node",
+      "args": ["/absolute/path/to/umami-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+If you would rather keep everything in one place, environment variables still work and take
+precedence over the file:
+
+```json
+{
+  "mcpServers": {
+    "umami": {
+      "command": "node",
+      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
+      "env": {
+        "UMAMI_URL": "https://analytics.example.com",
+        "UMAMI_USERNAME": "mcp-bot",
+        "UMAMI_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Check it works
+
+Ask your client to run `umami_whoami`. It reports the instance, the account, and the permission
+mode — the fastest way to confirm the connection and see how much the server is allowed to do:
+
+```json
+{
+  "instance": "https://analytics.example.com",
+  "authenticatedAs": "mcp-bot",
+  "role": "admin",
+  "serverMode": "read",
+  "destructiveOperations": "disabled"
+}
+```
+
+Then try: *"List my Umami websites"*, or *"What were my top pages last week?"*
+
+## Claude web, Cowork, and Claude Code on web
+
+Those clients cannot launch a local process, so they need a public HTTPS MCP server — and their
+connector UI accepts **OAuth only**, with no field for a static bearer token or custom header.
+
+Hosting the obvious way, with one set of Umami credentials baked in and no authentication, turns
+the URL into an open proxy to that Umami. So this server does OAuth instead, and does it without
+becoming a credential store.
+
+### Use the hosted instance
+
+Add a custom connector in Claude with this URL:
+
+```
+https://umami-mcp.asif.dev/mcp
+```
+
+Claude registers itself, sends you to a consent screen, and asks for **your own** Umami URL,
+username and password. Nothing is shared with other users of the host.
+
+### Host your own
+
+```bash
+UMAMI_MCP_OAUTH=true
+UMAMI_MCP_TRANSPORT=http
+UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
+UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
+UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days
+```
+
+Generate the key once and keep it:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+```
+
+Set `UMAMI_URL` as well to pin every user to one instance instead of letting them choose.
+
+### How the credentials are handled
+
+The consent screen verifies the credentials against the Umami instance the user named, then seals
+them into the access token with AES-256-GCM. The server keeps **no session table and stores no
+credentials**: each request decrypts the token, builds an MCP server scoped to that one user,
+serves the call, and discards it.
+
+The honest trade-off: whoever holds `UMAMI_MCP_TOKEN_KEY` can decrypt any token they capture.
+Treat it as the most sensitive value in the deployment. Rotating it invalidates every issued
+token, which is the intended blast-radius control.
+
+Destructive tools are **never** exposed over OAuth, whatever permission the user picks. Their
+typed-confirmation guard assumes a local operator who can see what they are about to delete, and
+a remote caller cannot be shown that.
+
+## Running it as a plain HTTP service
+
+Set `UMAMI_MCP_TRANSPORT=http` without `UMAMI_MCP_OAUTH` for a single-tenant endpoint at `/mcp`,
+plus `/health`.
+
+**In this mode the server has no authentication of its own.** Anyone who can reach the port can
+use your Umami credentials. Keep it on loopback and tunnel to it:
+
+```bash
+ssh -N -L 3334:127.0.0.1:3334 you@your-server
+claude mcp add --transport http umami http://127.0.0.1:3334/mcp
+```
+
+The server warns at startup when it is bound to anything other than loopback.
+
+## Tools
+
+| Tool | Requires | Description |
+|---|---|---|
+| `umami_list_websites` | read | List the websites tracked by this Umami instance, with their UUIDs |
+| `umami_get_website` | read | Fetch a single website by UUID, including its domain, owner and creation date. |
+| `umami_create_website` | write | Register a new website for tracking and return its UUID, which is the value to put in the data-website-id attribute of the Umami tracking script. |
+| `umami_update_website` | write | Change a website's name, domain or share slug |
+| `umami_reset_website` | destructive | PERMANENTLY DELETE all collected analytics data for a website, keeping the website itself |
+| `umami_delete_website` | destructive | PERMANENTLY DELETE a website and every event ever recorded for it |
+| `umami_get_tracking_snippet` | read | Return the ready-to-paste HTML script tag that sends data to this Umami instance for a given website. |
+| `umami_get_stats` | read | Headline totals for a website over a period: pageviews, visitors, visits, bounces and total time on site |
+| `umami_get_pageviews` | read | Pageviews and sessions bucketed over time, for charting traffic |
+| `umami_get_metrics` | read | Top values for one dimension, ranked by visitor count -- top pages, referrers, countries, browsers and so on |
+| `umami_get_active_visitors` | read | Number of visitors active on the site in the last few minutes |
+| `umami_get_realtime` | read | Live snapshot of current activity: recent events with country, URL, browser and device, plus rollups by country, URL and referrer |
+| `umami_get_event_stats` | read | Totals for custom tracked events over a period: event count, unique event names, visitors and visits, with a comparison against the preceding period. |
+| `umami_list_sessions` | read | Individual visitor sessions with browser, OS, device, country and region |
+| `umami_get_session_activity` | read | The ordered sequence of pageviews and events for one visitor session -- their path through the site. |
+| `umami_report_utm` | read | Breakdown of traffic by UTM parameters: source, medium, campaign, term and content |
+| `umami_report_funnel` | read | Step-by-step conversion funnel |
+| `umami_report_retention` | read | Cohort retention: of the visitors first seen on a given day, how many returned on each subsequent day. |
+| `umami_report_journey` | read | Most common ordered paths visitors take through the site, as sequences of pages with a count for each. |
+| `umami_report_goal` | read | Progress toward a single goal: how many visitors hit a given path or custom event. |
+| `umami_report_revenue` | read | Revenue over time from events carrying a revenue property, broken down by country, region, referrer and channel |
+| `umami_report_attribution` | read | Credits conversions to acquisition channels -- referrer, paid ads and UTM parameters -- under either a first-click or last-click model. |
+| `umami_list_users` | admin | List Umami user accounts with their roles |
+| `umami_create_user` | admin | Create a Umami user account |
+| `umami_delete_user` | destructive | PERMANENTLY DELETE a user account and the websites they own |
+| `umami_list_teams` | read | List teams and their members. |
+| `umami_create_team` | write | Create a team so websites can be shared between users. |
+| `umami_whoami` | read | Verify that this MCP server can reach the configured Umami instance and report which account it is authenticated as, plus the permission mode the server is running in |
+
+### Time ranges
+
+Every analytics tool accepts a `period` shorthand — `24h`, `7d`, `30d`, `12m`, `today`,
+`yesterday` — instead of epoch milliseconds. Models are reliably good at "last 30 days" and
+unreliably good at timestamp arithmetic, and a miscalculated epoch returns data for the wrong
+window *without erroring*. Explicit `startAt`/`endAt` in epoch milliseconds still work and take
+precedence.
+
+## Configuration
+
+See [.env.example](.env.example) for every option. The essentials:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `UMAMI_URL` | *required* | Your Umami instance |
+| `UMAMI_USERNAME` / `UMAMI_PASSWORD` | | Self-hosted login |
+| `UMAMI_API_KEY` | | Umami Cloud alternative |
+| `UMAMI_MCP_MODE` | `read` | `read` / `write` / `admin` |
+| `UMAMI_MCP_ALLOW_DESTRUCTIVE` | `false` | Unlock delete and reset |
+| `UMAMI_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `UMAMI_MCP_HOST` | `127.0.0.1` | HTTP bind address |
+| `UMAMI_MCP_PORT` | `3334` | HTTP port |
+| `UMAMI_MCP_ENV_FILE` | | Explicit path to a credentials file |
+
+## Recommended setup
+
+Create a dedicated Umami account for the MCP server rather than reusing your admin login, and
+give it only the websites it needs. Then, if the credential is ever exposed, the blast radius is
+one bot account you can delete — not your administrator.
+
+## Compatibility
+
+Verified against **Umami 3.3.1** (self-hosted, PostgreSQL). Umami Cloud works via `UMAMI_API_KEY`.
+Umami v2 is not supported: the renamed metric types above mean v2 and v3 need different clients,
+and this one targets v3.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test          # unit tests, no network required
+```
+
+`test/e2e.mjs` and `test/write-e2e.mjs` drive the built server through a real MCP client against
+a live instance. The write test creates a throwaway website on a `.invalid` domain and deletes it
+again; point it at a non-production instance.
+
+## Contributing
+
+Issues and pull requests welcome. Umami v3 exposes around 127 API routes and this server covers
+the most useful ones — session replay, heatmaps, pixels, link tracking, boards and segments are
+all still unmapped. If you add tools, keep the tier and `destructive` flags honest, because the
+whole safety model rests on them.
+
+If the Umami team would like to adopt, fork or upstream this, please open an issue — that is the
+outcome this was built for.
+
+## License
+
+MIT © M Asif Rahman

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import type { Config } from './config.js';
+/**
+ * A thin, dependency-free client for the Umami HTTP API.
+ *
+ * Self-hosted Umami has no API keys: you POST credentials to /api/auth/login
+ * and receive a bearer token. That token is held in memory only, never
+ * written to disk, and refreshed automatically when the server rejects it.
+ * Umami Cloud does issue API keys, which are sent as x-umami-api-key instead.
+ */
+export declare class UmamiError extends Error {
+    readonly status?: number | undefined;
+    readonly path?: string | undefined;
+    constructor(message: string, status?: number | undefined, path?: string | undefined);
+}
+type Query = Record<string, string | number | boolean | undefined | null>;
+export declare class UmamiClient {
+    private readonly config;
+    private token?;
+    private loginInFlight?;
+    constructor(config: Config);
+    private get usesApiKey();
+    /** Authenticate and cache the bearer token. Concurrent callers share one login. */
+    private login;
+    private authHeaders;
+    private raw;
+    private errorBody;
+    /** Perform an authenticated API call, retrying once if the token expired. */
+    request<T = unknown>(method: string, path: string, opts?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
+    get<T = unknown>(path: string, query?: Query): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, query?: Query): Promise<T>;
+    del<T = unknown>(path: string, query?: Query): Promise<T>;
+    /** Verify credentials and reachability. Returns the authenticated user. */
+    verify(): Promise<{
+        username?: string;
+        role?: string;
+        isAdmin?: boolean;
+    }>;
+}
+export declare function buildQuery(query?: Query): string;
+export {};

package/dist/client.js

@@ -0,0 +1,163 @@
+import { redact, redactUnknown } from './redact.js';
+/**
+ * A thin, dependency-free client for the Umami HTTP API.
+ *
+ * Self-hosted Umami has no API keys: you POST credentials to /api/auth/login
+ * and receive a bearer token. That token is held in memory only, never
+ * written to disk, and refreshed automatically when the server rejects it.
+ * Umami Cloud does issue API keys, which are sent as x-umami-api-key instead.
+ */
+export class UmamiError extends Error {
+    status;
+    path;
+    constructor(message, status, path) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = 'UmamiError';
+    }
+}
+export class UmamiClient {
+    config;
+    token;
+    loginInFlight;
+    constructor(config) {
+        this.config = config;
+    }
+    get usesApiKey() {
+        return Boolean(this.config.apiKey);
+    }
+    /** Authenticate and cache the bearer token. Concurrent callers share one login. */
+    async login() {
+        if (this.loginInFlight)
+            return this.loginInFlight;
+        this.loginInFlight = (async () => {
+            const res = await this.raw('/api/auth/login', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    username: this.config.username,
+                    password: this.config.password,
+                }),
+            });
+            if (!res.ok) {
+                const detail = res.status === 401 ? 'check UMAMI_USERNAME and UMAMI_PASSWORD' : await this.errorBody(res);
+                throw new UmamiError(`Login failed (HTTP ${res.status}): ${detail}`, res.status, '/api/auth/login');
+            }
+            const body = (await res.json());
+            if (!body.token) {
+                throw new UmamiError('Login succeeded but returned no token', res.status, '/api/auth/login');
+            }
+            this.token = body.token;
+            return body.token;
+        })();
+        try {
+            return await this.loginInFlight;
+        }
+        finally {
+            this.loginInFlight = undefined;
+        }
+    }
+    async authHeaders() {
+        if (this.usesApiKey)
+            return { 'x-umami-api-key': this.config.apiKey };
+        const token = this.token ?? (await this.login());
+        return { authorization: `Bearer ${token}` };
+    }
+    async raw(path, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            return await fetch(this.config.url + path, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new UmamiError(`Request to ${path} timed out after ${this.config.timeoutMs}ms`, undefined, path);
+            }
+            throw new UmamiError(`Request to ${path} failed: ${redactUnknown(err)}`, undefined, path);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async errorBody(res) {
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch {
+            return res.statusText || 'no response body';
+        }
+        try {
+            const parsed = JSON.parse(text);
+            const msg = typeof parsed.error === 'string' ? parsed.error : parsed.error?.message;
+            if (msg)
+                return redact(msg);
+        }
+        catch {
+            /* not JSON; fall through */
+        }
+        return redact(text.slice(0, 400)) || res.statusText;
+    }
+    /** Perform an authenticated API call, retrying once if the token expired. */
+    async request(method, path, opts = {}) {
+        const qs = buildQuery(opts.query);
+        const fullPath = path + qs;
+        const attempt = async () => {
+            const headers = { ...(await this.authHeaders()), accept: 'application/json' };
+            const init = { method, headers };
+            if (opts.body !== undefined) {
+                headers['content-type'] = 'application/json';
+                init.body = JSON.stringify(opts.body);
+            }
+            return this.raw(fullPath, init);
+        };
+        let res = await attempt();
+        // A cached token can expire mid-session; re-login once and retry.
+        if (res.status === 401 && !this.usesApiKey) {
+            this.token = undefined;
+            res = await attempt();
+        }
+        if (!res.ok) {
+            throw new UmamiError(`Umami API ${method} ${path} failed (HTTP ${res.status}): ${await this.errorBody(res)}`, res.status, path);
+        }
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new UmamiError(`Umami API ${method} ${path} returned malformed JSON`, res.status, path);
+        }
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, query) {
+        return this.request('POST', path, { body, query });
+    }
+    del(path, query) {
+        return this.request('DELETE', path, { query });
+    }
+    /** Verify credentials and reachability. Returns the authenticated user. */
+    async verify() {
+        const me = await this.get('/api/me');
+        return me.user ?? {};
+    }
+}
+export function buildQuery(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        params.set(k, String(v));
+    }
+    const s = params.toString();
+    return s ? `?${s}` : '';
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration is read exclusively from the process environment.
+ *
+ * Nothing here is ever transmitted anywhere except to the single Umami
+ * instance named by UMAMI_URL. There is no telemetry, no phone-home, and no
+ * remote credential broker. If you self-host this server, your credentials
+ * stay on your machine.
+ */
+export type Mode = 'read' | 'write' | 'admin';
+export type Transport = 'stdio' | 'http';
+export interface OAuthConfig {
+    enabled: boolean;
+    issuer: string;
+    tokenKey: string;
+    ttlSeconds: number;
+    /** When set, every user is pinned to this Umami rather than choosing one. */
+    fixedUrl?: string;
+}
+export interface Config {
+    url: string;
+    username?: string;
+    password?: string;
+    apiKey?: string;
+    teamId?: string;
+    mode: Mode;
+    allowDestructive: boolean;
+    transport: Transport;
+    host: string;
+    port: number;
+    timeoutMs: number;
+    oauth?: OAuthConfig;
+}
+export declare class ConfigError extends Error {
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+/** Human-readable summary for startup logs. Never includes secrets. */
+export declare function describeConfig(c: Config): string;