@martin4455/matomo-mcp-ro 0.4.1

package/CONFIGURATION.md

@@ -0,0 +1,396 @@
+# Matomo MCP configuration guide
+
+For the quick setup, see the [README](README.md). This guide describes version 0.4.0 and newer.
+
+## Source setup
+
+From the source checkout, install its pinned dependencies (retain optional
+dependencies: they include the native module for your OS and CPU):
+
+```sh
+npm ci --ignore-scripts
+```
+
+Then configure from the project where analytics will be used:
+
+```sh
+node "/absolute/path/to/matomo-mcp-ro/cli.mjs" configure
+node "/absolute/path/to/matomo-mcp-ro/cli.mjs" check
+```
+
+When working from source, replace `matomo-mcp` in the remaining examples with
+`node "/absolute/path/to/matomo-mcp-ro/cli.mjs"`. Use that direct command in your
+client settings until this revision is available as an installed package.
+
+Use `npm.cmd`/`npx.cmd` in PowerShell if script execution policy blocks `.ps1`.
+Configuration runs in your own terminal: enter the HTTPS Matomo URL, choose whether
+Basic Auth is required, and enter the API token and optional username/password.
+The wizard has four numbered steps. Type after the colon and press Enter. The
+Basic Auth question accepts `tak`/`nie` or `yes`/`no` and explicitly shows the
+Enter default; an invalid answer repeats the question. Credential input is hidden
+(no characters or asterisks); each field confirms that a new or saved value was
+accepted without displaying it. Ctrl+C cancels. Configuration is saved only after a successful
+read-only site-list request. Old-format records are invalid; enter the complete
+connection again with `configure`. Enter retains valid saved credentials;
+changing the URL requires new credentials.
+
+The file `.matomo-mcp.json` lives in the exact current directory, or at an explicit
+`--config /project/.matomo-mcp.json` path. No home/parent/environment fallback is
+used. It contains only a reference, protected by mode 0600 on Unix or a private
+Windows ACL:
+
+```json
+{
+  "schemaVersion": 2,
+  "credentialId": "c26a0845-51b2-40bf-80d7-e504501fa56b"
+}
+```
+
+The UUID is generated randomly for each new connection. The Matomo HTTPS URL,
+API token, and optional Basic Auth username/password are stored together in the
+keyring, under service `matomo-mcp-ro`. Neither URLs nor usernames are used in
+entry labels. Local metadata cannot override the stored connection's URL.
+The full record is encrypted before it reaches keyring entries, including the
+token and both Basic Auth fields. There is no additional passphrase at session
+startup, signed executable, master-key file or environment key.
+`configure` adds Git/search exclusions. Never paste credentials into AI chats,
+CLI arguments, URLs or MCP client settings. `status`, `check` output
+and summaries omit the connection URL as well as credentials. The URL is visible
+in the interactive editing prompt. Analytics reports can still contain site URLs.
+
+## Operating system requirements
+
+- **Windows:** Windows Credential Manager of the current OS account. Normal use
+  requires no administrator account.
+- **macOS:** User Keychain. The OS may ask to unlock the keychain or authorize
+  access by Node.
+- **Ubuntu/Linux desktop:** Secret Service, such as GNOME Keyring, with the user's
+  D-Bus session and an unlocked persistent collection.
+- **Linux server, SSH, container or WSL:** Prepare a user D-Bus session and
+  persistent Secret Service collection first. Node alone is insufficient. WSL
+  uses Linux storage, not Windows Credential Manager.
+
+On Ubuntu, if these components are missing, the user may need to install
+`gnome-keyring` and the appropriate D-Bus session integration using the system
+package manager. This one-time system setup may require sudo. A graphical session
+typically supplies both. Installing packages alone does not establish an unlocked
+user session. Do not run the MCP server or configurator through sudo.
+
+The pinned `@napi-rs/keyring@2.1.0` dependency has prebuilt modules for Windows
+x64/ARM64, macOS Intel/Apple Silicon, and Linux glibc x64/ARM64. Do not copy
+`node_modules` between platforms. Missing native modules produce an error; normal
+installation does not compile Rust or require Python/Tkinter.
+
+Linux explicitly requires Secret Service and never falls back to the kernel
+keyring. A missing, inaccessible or unsuccessfully unlocked store stops the
+operation. An OS unlock dialog may appear, including during `status` or server
+startup. There is no plaintext, environment-variable or alternate-file fallback.
+
+The local script client forwards only relevant Linux desktop/session variables
+to its MCP child, including `DBUS_SESSION_BUS_ADDRESS`. For hosts that filter this
+variable, the server can discover an existing user-owned socket at
+`/run/user/<uid>/bus` in its protected runtime directory. It does not start a
+daemon or override an explicitly supplied bus address. Custom/headless sessions
+must make their session bus available to the client process.
+
+## Old records and token rotation
+
+Old plaintext configuration files and unencrypted keyring entries are treated as
+invalid credentials. `serve` and `check` stop before any HTTP request; `status`
+reports `credentials: "invalid"`. Run `configure` and enter a fresh URL, token and
+any Basic Auth credentials. Old values are never accepted as defaults. The new
+connection is encrypted and saved only after its read-only connection test
+succeeds. There is no migration command.
+
+Run `configure` again to rotate a token, change Basic Auth or repair a missing or
+corrupt entry. New input is saved only after a successful connection check. Enter
+retains existing values; selecting no Basic Auth removes it. A normalized URL
+change requires fresh credentials. An unavailable store is not treated as a
+missing entry. Restart MCP after changes: an existing process keeps its resolved
+connection in memory.
+
+Copies of the same v2 file on one OS account share a keyring entry and its updates.
+Copying metadata alone to another computer/account does not transfer credentials;
+run `configure` there. Provider/system policies may synchronize credentials; this
+package does not promise otherwise. Keyring storage is not isolation from every
+process running as the same user or from an administrator. Reconfiguration does not
+remove historical plaintext copies from backups or version control.
+
+## Large credentials, consistency and recovery
+
+All supported systems use one manifest entry and one or more fragment entries.
+The complete connection JSON is encrypted with AES-256-GCM using a fresh 32-byte
+salt, a fresh 12-byte IV and a 16-byte authentication tag. A 32-byte key is derived
+with HKDF-SHA-256 from the public credential UUID. The authenticated context is
+`JSON.stringify([SERVICE, 2, 'aes-256-gcm', 'hkdf-sha256', credentialId])`, used
+both as HKDF info and GCM additional authenticated data. The derived key buffer
+is cleared after each operation; JavaScript strings and process memory cannot
+be reliably wiped by this design.
+
+The envelope uses version 2 with algorithm `aes-256-gcm` and KDF `hkdf-sha256`.
+The UUID is public: a program with the UUID and envelope can derive the same key
+and decrypt it.
+This layer masks directly readable credentials and detects corruption/context
+mismatch; the OS credential store remains the access boundary. It does not
+provide per-script isolation from other programs under the same OS account.
+
+The versioned encrypted envelope is encoded as UTF-8/base64 and divided into at most
+1200 ASCII characters per fragment (2400 UTF-16LE bytes). Each fits Windows'
+2560-byte CredentialBlob limit, including the encryption overhead. Base64 is an
+encoding of the encrypted envelope. Manifest, fragments, salt, IV, authentication
+tag and integrity hash all stay in keyring.
+The application file never receives a fragment, URL or encryption key.
+
+The format supports all accepted connection fields: up to 8192 UTF-16 code units
+per credential field, a normalized URL up to 2048 characters, and a defensive
+128 KiB total plaintext payload bound; the stored size bound includes ciphertext
+base64 expansion and envelope metadata. Fragment counts, lengths, canonical
+base64, SHA-256, envelope fields and GCM authentication are checked. Missing or
+modified fragments fail closed. Runtime reads never fall back to plaintext.
+
+Rotation writes a new random generation, verifies every fragment and the full
+payload, then switches the small manifest. Previous fragments stay available until
+the metadata file commit succeeds. On an ordinary failure the adapter restores
+the previous manifest and removes new fragments. Failed recovery is reported
+explicitly. Cleanup failure after success may leave old fragments in keyring and
+is reported separately; it does not undo the valid new connection.
+
+Cooperating processes use locks by canonical configuration path and keyring UUID,
+including readers and references in other directories. An editor also detects a
+changed credential generation even if the metadata file still has the same UUID.
+Lock files under `~/.matomo-mcp-locks/` contain only process ownership metadata.
+They have restricted write access, and no URL or credential is written there.
+On Windows, read/traverse grants added by a host sandbox are accepted for lock
+metadata only; grants allowing other accounts to modify it are rejected. The
+configuration file keeps its stricter private-ACL requirement. Operations wait up
+to five seconds for a lock, then fail with a useful message. After a killed/crashed
+process, stop all related MCP/configuration processes and confirm no operation is
+active before removing abandoned lock directories. Locks are deliberately not
+stolen automatically. Do not clear the system credential store to release a lock.
+
+Keyring and filesystem do not form one crash-atomic transaction. A sudden exit
+can leave orphaned fragments or an abandoned lock; a committed connection is
+always read and validated as a complete generation. External keyring editors do
+not participate in the locking protocol. Do not manually delete shared entries
+based on finding one local reference.
+
+## Connect a client
+
+The [README](README.md#3-connect-your-client) shows the CLI registration commands.
+For a stable installation, `client-config codex`, `client-config claude-code` and
+`client-config claude-desktop` print settings with absolute paths and no secrets.
+These settings launch the installed Node.js executable and package directly.
+Use `--config` to select the project you configured:
+
+```sh
+matomo-mcp client-config codex --config "/absolute/path/to/project/.matomo-mcp.json"
+matomo-mcp client-config claude-code --config "/absolute/path/to/project/.matomo-mcp.json"
+```
+
+Merge the Codex TOML into `~/.codex/config.toml`, or the trusted project's
+`.codex/config.toml` for project scope. Codex CLI and Desktop share these settings.
+The generated server name is `matomo`; README registration examples use
+`matomo-local`. Use the name you registered when addressing the assistant.
+For client behavior, see [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp)
+and [Claude Code MCP](https://code.claude.com/docs/en/mcp).
+
+### Claude Desktop setup
+
+Generate the desktop configuration:
+
+```sh
+matomo-mcp client-config claude-desktop --config "/absolute/path/to/project/.matomo-mcp.json"
+```
+
+Open Claude Desktop's **Settings → Developer → Edit Config** and merge the printed
+`matomo` entry into `mcpServers` in `claude_desktop_config.json`. Preserve existing
+servers, save the file, and fully restart Claude Desktop. The generated command
+uses absolute paths, so keep Node.js and the package at those locations; regenerate
+it after moving an installation. If you want the README's `matomo-local` name,
+rename the generated JSON key from `matomo` to `matomo-local`.
+See the [official local-server setup](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
+for the client configuration workflow.
+
+The configuration is application-wide. Its explicit `--config` selects the
+connection; it does not restrict that connection to a particular desktop chat.
+Keep credentials in the interactive configurator, never in the client JSON.
+
+With no command the CLI starts `serve`. Stdout is reserved for MCP messages.
+The process exits when the client closes stdin. Windows configuration and all
+configuration reads, including server startup, check ACLs using hidden system
+utilities. Keyring access uses native APIs inside Node; it does not launch shells.
+
+## Troubleshooting
+
+- Run `matomo-mcp status --config "/absolute/path/to/project/.matomo-mcp.json"` to
+  check the local file and stored credentials without an HTTP request.
+- Run `matomo-mcp check --config "/absolute/path/to/project/.matomo-mcp.json"` to
+  test access to Matomo. A token needs access to at least one site.
+- If credentials are invalid or missing, run `configure` again with the same
+  `--config`. An unavailable credential store must be unlocked or repaired first.
+- On Linux, make the user's D-Bus session and Secret Service available to the
+  client process. See [operating system requirements](#operating-system-requirements).
+- On Windows, use `npm.cmd` and `npx.cmd` if PowerShell blocks the corresponding
+  `.ps1` scripts. If a client cannot spawn `npx`, use the generated direct-Node
+  settings above.
+- Restart the MCP client after changing credentials. If using `npx @latest`, it
+  can download a newer package on a later launch. For controlled upgrades, use
+  a reviewed installed version and regenerate direct-Node settings after updates.
+
+## Tools
+
+- **`matomo_list_sites`:** Available sites and time zones.
+- **`matomo_site_info`:** Site settings.
+- **`matomo_report_catalog`:** Report metadata. Filter by `query` or `module`,
+  paginate, and use `detailed=false` for a compact index.
+- **`matomo_goals`:** Configured goals.
+- **`matomo_segments`:** Saved segments.
+- **`matomo_segments_metadata`:** Available segment fields.
+- **`matomo_dimensions`:** Configured custom dimensions, active state and
+  visit/action scope.
+- **`matomo_report`:** 53 explicitly allowed reporting methods, including
+  `UserId.getUsers`.
+- **`matomo_visits`:** `Live.getLastVisitsDetails`, with action details, paging
+  and a maximum 31-day date window.
+- **`matomo_report_batch`:** 1–10 reports with ordered per-item results and errors.
+  Concurrency is 1 by default, at most 2.
+
+Example tool arguments (synthetic identifiers):
+
+```json
+{
+  "method": "UserId.getUsers",
+  "idSite": 1,
+  "period": "day",
+  "date": "2026-09-01,2026-09-10",
+  "segment": "dimension2==trial",
+  "filter_limit": 1000,
+  "filter_offset": 0
+}
+```
+
+Confirm the actual dimension ID/value using metadata before querying. A daily
+series has one pagination entry per date. `period=range` instead returns the
+aggregate for the window. All dates are explicit `YYYY-MM-DD` values; metrics are
+requested as numbers (`format_metrics=0`).
+
+```json
+{
+  "idSite": 1,
+  "period": "day",
+  "date": "2026-09-10",
+  "segment": "userId==example-user",
+  "includeActions": true,
+  "filter_limit": 20,
+  "filter_offset": 0
+}
+```
+
+Visits support at most 100 rows per page and `filter_sort_order`, not arbitrary
+sort columns. `includeActions=false` reduces payload. Dedupe visits by site and
+visit ID when collecting pages. A full page means another page may exist; inspect
+`pagination.mayHaveMore`/`nextOffset`. Choose closed dates where possible.
+
+Batch takes `{ "requests": [REPORT_ARGUMENTS, ...], "concurrency": 1 }`. Every
+request is validated before any network access. Results preserve request indexes;
+errors never become zero counts. Batch response budgets are 2 MiB per result and
+8 MiB total; fetch oversized results individually with a smaller page size.
+
+## Read-only boundaries and completeness
+
+Write methods, arbitrary API URLs, `API.getBulkRequest`, credential overrides and
+unlisted parameters are blocked before network requests. Redirects are rejected;
+TLS validation stays enabled. API credentials are sent as a POST body token and
+optional Basic Authorization header. Boolean API flags use PHP-safe 0/1 values.
+Requests have a 60-second timeout and 10 MiB response limit. Report page limit is
+1000. Cancellation stops queued batch work.
+
+API results, MCP responses and error messages replace recognized credentials with
+`[UKRYTO]`. Filtering covers configured credentials and encoded forms, sensitive
+JSON fields such as `token_auth`/`api_key`/`password`, name/value pairs, credentials
+in URLs, authorization strings and common provider token formats. It also covers
+parameters echoed in report and batch results. Token-management APIs are outside
+the allowlist; upstream HTTP bodies and headers are never included in HTTP errors.
+
+This is credential filtering, not anonymization: User IDs, visitor IDs, IP
+addresses and other analytics data can remain in reports. An unknown opaque
+secret inside an ordinary title or custom dimension cannot always be recognized.
+Do not track credentials in the first place. Filtering is local and does not
+remove data already stored in Matomo or in older exported reports.
+
+Metadata does not automatically allow new executable methods. The server does
+not create saved segments, configure archiving, or change retention. Reading a
+report can trigger Matomo's normal archive/cache generation.
+
+Responses preserve `method`, `parameters`, `data` and add `fetchedAt`, `pagination`
+and `completeness`. `Others` summary rows and unfetched subtables produce warnings.
+Finishing pagination does not prove complete telemetry: archive row limits can
+remove identities, raw data can expire, and tracking can be absent. Visitor-log
+access may also be disabled. Action lists are server-returned, not guaranteed
+complete. Visit-scoped dimensions do not establish a state for every individual
+historical action in that visit.
+
+## Use from a local Node script
+
+The generic client export uses the same MCP transport and policy as an AI client.
+It never reads the credential file itself:
+
+```js
+import { connectMatomo } from '@martin4455/matomo-mcp-ro/client';
+const client = await connectMatomo({ configPath: '/project/.matomo-mcp.json' });
+try {
+  const sites = await client.call('matomo_list_sites', {});
+  console.log(sites.data.map(site => site.name));
+} finally {
+  await client.close();
+}
+```
+
+Domain identity conversions, license/business rules, input lists, caching and
+analysis outputs belong in separate private project skills/scripts. They are not
+part of this public package. No persistent job service or output-file tool is
+exposed over MCP.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run test:native
+npm run release:check
+npm pack --ignore-scripts
+```
+
+Unit tests use synthetic credentials, an in-memory keyring and mocked HTTP with
+real MCP transports. They do not access real user entries. The explicit native
+integration test uses a random test service, large synthetic credentials,
+cross-process reads and rotation, then removes its own entries. It also checks
+Windows' actual per-entry boundary and Linux's refusal to fall back without D-Bus.
+It requires a working OS keyring and may display a system dialog.
+
+CI runs both suites on Windows, Ubuntu and macOS; it prepares isolated test
+keychains/Secret Service sessions. The CI setup password is public synthetic test
+data, not an application credential. Session/reboot persistence, denial of unlock
+dialogs and desktop-client authorization should also be checked manually on the
+target OS; a passing mock test or an available binary is not that verification.
+`release:check` verifies an explicit source
+and npm file list. Keep this list current when adding code; the npm package
+contains runtime files, README, this guide and LICENSE, not tests or private data.
+
+Maintainers publish a reviewed release from the source checkout after the checks:
+
+```sh
+npm run release:publish
+```
+
+This publishes the current directory. Do not publish a `.tgz` by its local path:
+npm can copy that path into public registry metadata. `release:check` also rejects
+private npm fields, local paths and credential URLs in the package manifest.
+After publishing, inspect registry metadata and the downloaded package. The npm
+account's publisher email remains public; changing the package does not hide it.
+
+- [Matomo Reporting API](https://developer.matomo.org/guides/reporting-api)
+- [Matomo API tokens](https://matomo.org/faq/general/faq_114/)
+- [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp)
+- [Claude Code MCP](https://code.claude.com/docs/en/mcp)
+- Package license: MIT.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luskan
+
+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,89 @@
+# Matomo MCP Server (Read-Only)
+
+A local MCP server for Claude Code, Claude Desktop and Codex. Use it to read Matomo
+analytics, compare traffic and conversions, and investigate visits and User ID reports.
+
+The server only reads from Matomo: it cannot change sites, goals, segments or users.
+
+## 1. Install
+
+You need Node.js 24+ and a Matomo account with an API token and access to at least one site.
+
+```sh
+node -v
+npm install -g @martin4455/matomo-mcp-ro@latest
+```
+
+The encrypted storage described here requires version **0.4.0+**. For an unreleased
+checkout, use the [source setup](CONFIGURATION.md#source-setup).
+
+## 2. Configure
+
+Run the configurator in your project directory:
+
+```sh
+cd "/absolute/path/to/project"
+matomo-mcp configure
+```
+
+Enter your HTTPS Matomo URL (for example, `https://matomo.example.com`) and API token.
+Create a token under **Administration → Personal → Security → Create new token**;
+see the [Matomo token guide](https://matomo.org/faq/general/faq_114/).
+If your server also requires HTTP Basic Auth, enter its login and password.
+The configurator tests the connection before saving.
+
+The URL, token and optional Basic Auth credentials are encrypted together and stored
+in macOS Keychain, Windows Credential Manager or Linux Secret Service (such as GNOME
+Keyring). The project's `.matomo-mcp.json` stores a UUID reference, not credentials.
+There is no additional passphrase when starting a session.
+Access protection comes from the OS credential store; see the
+[encryption details and limits](CONFIGURATION.md#large-credentials-consistency-and-recovery).
+
+Existing entries in the old format are treated as invalid credentials. Run
+`matomo-mcp configure` again and enter the complete connection.
+
+## 3. Connect your client
+
+From the same project directory, run the command for your client. Replace the quoted
+path with the absolute path to the configuration file created above.
+
+**Claude Code:**
+
+```sh
+claude mcp add matomo-local -- npx -y \
+  @martin4455/matomo-mcp-ro@latest \
+  --config "/absolute/path/to/project/.matomo-mcp.json"
+```
+
+**Codex CLI:**
+
+```sh
+codex mcp add matomo-local -- npx -y \
+  @martin4455/matomo-mcp-ro@latest \
+  --config "/absolute/path/to/project/.matomo-mcp.json"
+```
+
+**Claude Desktop:** follow the [Desktop setup](CONFIGURATION.md#claude-desktop-setup).
+
+Start or restart your client. In Claude Code or Codex CLI, use `/mcp` to check the
+server's status. The first launch may take a moment to download the package.
+
+## 4. Try it
+
+Ask your assistant:
+
+> Use matomo-local to check which Matomo sites I can access.
+
+Then give it an analytics question:
+
+> Compare visits, traffic sources and goal conversions for site 1 in September
+> 2026 with August 2026. Explain the largest changes and flag incomplete data.
+
+You can also ask about a particular User ID, visit details or custom dimensions.
+Use the server name you registered; the generated Desktop settings use `matomo`.
+
+For token changes, platform requirements, storage details, report tools and
+troubleshooting, see the [configuration guide](CONFIGURATION.md).
+
+MIT license. [Source](https://github.com/luskan/matomo-mcp-ro) |
+[Report an issue](https://github.com/luskan/matomo-mcp-ro/issues).

package/api.mjs

@@ -0,0 +1,150 @@
+import { normalizeBaseUrl } from './lib/config.mjs';
+import { VERSION } from './lib/version.mjs';
+import { createRedactor } from './lib/redaction.mjs';
+
+export const REPORT_METHODS = [
+  'VisitsSummary.get', 'VisitFrequency.get', 'VisitTime.getVisitInformationPerServerTime',
+  'VisitTime.getByDayOfWeek', 'Actions.get', 'Actions.getPageUrls', 'Actions.getPageTitles',
+  'Actions.getEntryPageUrls', 'Actions.getExitPageUrls', 'Actions.getDownloads',
+  'Actions.getOutlinks', 'Actions.getSiteSearchKeywords', 'Actions.getSiteSearchNoResultKeywords',
+  'Referrers.get', 'Referrers.getReferrerType', 'Referrers.getAll', 'Referrers.getWebsites',
+  'Referrers.getSearchEngines', 'Referrers.getKeywords', 'Referrers.getSocials',
+  'Referrers.getCampaigns', 'UserCountry.getCountry', 'UserCountry.getContinent',
+  'UserCountry.getRegion', 'UserCountry.getCity', 'UserLanguage.getLanguage',
+  'DevicesDetection.getType', 'DevicesDetection.getBrand', 'DevicesDetection.getModel',
+  'DevicesDetection.getBrowsers', 'DevicesDetection.getBrowserVersions',
+  'DevicesDetection.getOsFamilies', 'DevicesDetection.getOsVersions',
+  'Resolution.getResolution', 'VisitorInterest.getNumberOfVisitsPerPage',
+  'VisitorInterest.getNumberOfVisitsPerVisitDuration', 'VisitorInterest.getNumberOfVisitsByVisitCount',
+  'VisitorInterest.getNumberOfVisitsByDaysSinceLast', 'Events.getCategory',
+  'Events.getAction', 'Events.getName', 'Goals.get', 'Goals.getItemsName',
+  'Goals.getItemsSku', 'Goals.getItemsCategory', 'Contents.getContentNames',
+  'Contents.getContentPieces', 'PagePerformance.get', 'CustomDimensions.getCustomDimension',
+  'CustomReports.getCustomReport', 'MultiSites.getAll', 'MultiSites.getOne', 'UserId.getUsers',
+];
+
+const READ_METHODS = new Set([
+  ...REPORT_METHODS, 'SitesManager.getSitesWithAtLeastViewAccess',
+  'SitesManager.getSiteFromId', 'API.getReportMetadata', 'API.getSegmentsMetadata',
+  'Goals.getGoals', 'SegmentEditor.getAll',
+  'CustomDimensions.getConfiguredCustomDimensions', 'Live.getLastVisitsDetails',
+]);
+const PARAMETERS = new Set([
+  'idSite', 'idSites', 'period', 'date', 'segment', 'idGoal', 'idDimension',
+  'idCustomReport', 'idSubtable', 'expanded', 'flat', 'columns', 'filter_limit',
+  'filter_offset', 'filter_sort_column', 'filter_sort_order', 'filter_pattern',
+  'filter_column', 'format_metrics', 'language', 'showSubtableReports', 'hideMetricsDoc',
+]);
+const LIVE_PARAMETERS = new Set(['idSite', 'period', 'date', 'segment', 'filter_limit',
+  'filter_offset', 'filter_sort_order', 'doNotFetchActions', 'language']);
+
+export class MatomoError extends Error {}
+
+export class MatomoApi {
+  #token;
+  #authorization;
+  #redactor;
+  #fetch;
+  #endpoint;
+
+  constructor({ token, username, password, baseUrl, fetchImpl = globalThis.fetch }) {
+    const hasBasic = username !== undefined || password !== undefined;
+    if (typeof token !== 'string' || !token.length || hasBasic && ![username, password].every(value => typeof value === 'string' && value.length > 0)) {
+      throw new MatomoError('Brak danych logowania. Uruchom matomo-mcp configure w katalogu projektu.');
+    }
+    if (username?.includes(':') || [token, username, password].filter(value => value !== undefined).some(value => /[\x00-\x1f\x7f]/.test(value))) {
+      throw new MatomoError('Login Basic Auth nie może zawierać dwukropka ani końca wiersza.');
+    }
+    this.#endpoint = new URL('index.php', normalizeBaseUrl(baseUrl)).href;
+    this.#token = token;
+    this.#authorization = hasBasic ? `Basic ${Buffer.from(`${username}:${password}`, 'utf8').toString('base64')}` : undefined;
+    this.#redactor = createRedactor([token, username, password, this.#authorization, this.#authorization?.slice(6)]);
+    this.#fetch = fetchImpl;
+  }
+
+  redact(value) {
+    return this.#redactor.text(value);
+  }
+
+  sanitize(value) { return this.#redactor.sanitize(value); }
+
+  async call(method, parameters = {}, signal) {
+    if (!READ_METHODS.has(method)) throw new MatomoError('Ta metoda nie jest dostępna w adapterze raportowym.');
+    const body = new URLSearchParams();
+    const allowed = method === 'Live.getLastVisitsDetails' ? LIVE_PARAMETERS : PARAMETERS;
+    for (const [key, value] of Object.entries(parameters)) {
+      if (!allowed.has(key)) throw new MatomoError('Niedozwolony parametr API.');
+      if (!['string', 'number', 'boolean'].includes(typeof value)) throw new MatomoError('Parametry API muszą być wartościami prostymi.');
+      if (typeof value === 'number' && !Number.isFinite(value)) throw new MatomoError('Parametr liczbowy musi być skończony.');
+      if (key === 'filter_limit' && (!Number.isInteger(Number(value)) || Number(value) < 1 || Number(value) > 1000)) throw new MatomoError('Limit wierszy musi mieścić się w zakresie 1–1000.');
+      if (method === 'Live.getLastVisitsDetails' && key === 'filter_limit' && Number(value) > 100) throw new MatomoError('Limit wizyt wynosi 100.');
+      // PHP APIs must receive 0/1: the non-empty string "false" can be truthy.
+      body.set(key, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
+    }
+    body.set('module', 'API');
+    body.set('method', method);
+    body.set('format', 'JSON');
+    body.set('token_auth', this.#token);
+    const requestSignal = signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(60000)])
+      : AbortSignal.timeout(60000);
+    let response;
+    try {
+      response = await this.#fetch(this.#endpoint, {
+        method: 'POST',
+        headers: {
+          ...(this.#authorization ? { Authorization: this.#authorization } : {}),
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Accept: 'application/json',
+          'User-Agent': `matomo-mcp-ro/${VERSION}`,
+        },
+        body,
+        redirect: 'manual',
+        signal: requestSignal,
+      });
+    } catch {
+      throw new MatomoError(requestSignal.aborted
+        ? 'Zapytanie zostało przerwane lub przekroczyło limit 60 sekund.'
+        : 'Nie udało się połączyć z Matomo. Sprawdź sieć i certyfikat HTTPS.');
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      if (response.status === 401) throw new MatomoError(this.#authorization ? 'HTTP 401: serwer odrzucił uwierzytelnienie; sprawdź token API oraz login i hasło Basic Auth.' : 'HTTP 401: serwer odrzucił dostęp; sprawdź token lub wymaganie HTTP Basic Auth.');
+      if (response.status === 403) throw new MatomoError('HTTP 403: serwer odrzucił dostęp do API.');
+      if (response.status >= 300 && response.status < 400) throw new MatomoError('Serwer zwrócił przekierowanie. Dane logowania nie zostały przekazane pod inny adres.');
+      throw new MatomoError(`Matomo zwróciło HTTP ${response.status}.`);
+    }
+    if (!response.body) throw new MatomoError('Matomo zwróciło pustą odpowiedź.');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.length;
+        if (bytes > 10 * 1024 * 1024) {
+          await reader.cancel();
+          throw new MatomoError('Raport przekracza 10 MB. Zawęź okres lub liczbę wierszy.');
+        }
+        chunks.push(value);
+      }
+    } catch (error) {
+      if (error instanceof MatomoError) throw error;
+      throw new MatomoError('Przerwano pobieranie odpowiedzi Matomo.');
+    } finally {
+      reader.releaseLock();
+    }
+    let data;
+    try {
+      data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch {
+      throw new MatomoError('Odpowiedź nie jest danymi JSON z API Matomo; możliwa strona logowania lub blokada serwera.');
+    }
+    data = this.sanitize(data);
+    if (data?.result === 'error') {
+      throw new MatomoError(`Matomo API: ${this.redact(data.message ?? 'Błąd zapytania')}`);
+    }
+    return data;
+  }
+}