feat: report funnel metrics on channel mcp

## Changed
- Tool calls now emit a call_success or call_error, reported from inside
  CallTool's own try/catch so the original SDK error is still available to
  classify before it is rewritten
- Shutdown flushes the queued events before exiting, capped at 2s
- The cast through the SDK's protected `client` moved to a single guarded
  accessor, reused by the existing X-Lara-Client headers

## New
- src/metrics.ts: batched, fire-and-forget event reporting to the
  integrations monitoring backend. Buys a token from /auth/issue-token,
  posts to /metrics/ingest-events every 2s, retries once on 401, requeues
  on 429/5xx, drops on any other rejection, queue capped at 10 000. A
  backend that is down never delays or fails a translation
- Events: install (first run only), auth_success (deduplicated per account
  per process, since the HTTP transport builds a Translator per request),
  call_success, call_error, and auth_fail beside a call_error Lara answered
  with 401/403. Both transports report
- accountId is the Lara account behind the credentials, read from the id
  claim of the token the SDK holds. No token means no event: a made-up id
  would be a fake account in every dashboard
- Installation id persisted at ${LARA_HOME:-~/.lara}/installation-id, with
  a per-process fallback when the home is not writable
- Opt-out via DO_NOT_TRACK: nothing is measured, queued, written to disk or
  sent. METRICS_URL / METRICS_API_KEY override the compiled-in defaults,
  which are empty until the backend is deployed
- 60 tests covering the client in isolation and the server wiring

Author: Starllordz

.env.example

@@ -4,4 +4,15 @@ PORT=80
 TRANSPORT=http
 
 # Logging
-LOGGING_LEVEL=info
+LOGGING_LEVEL=info
+
+# Usage metrics. Both are compiled in with a default, and these override them.
+# Either one empty = telemetry silently off.
+# METRICS_URL=http://localhost:8080
+# METRICS_API_KEY=dev-mcp-key
+
+# Where the installation id is kept. Default: ~/.lara
+# LARA_HOME=/var/lib/lara
+
+# Opt out of usage metrics entirely (https://consoledonottrack.com).
+# DO_NOT_TRACK=1

CLAUDE.md

@@ -131,6 +131,9 @@ Core configuration (`src/env.ts`):
 - `HOST` / `PORT` - HTTP server binding (default: `0.0.0.0:3000`)
 - `LARA_ACCESS_KEY_ID` / `LARA_ACCESS_KEY_SECRET` - API credentials (required for STDIO mode)
 - `LOGGING_LEVEL` - Log level: `debug`, `info`, `warn`, `error` (default: `info`)
+- `METRICS_URL` / `METRICS_API_KEY` - Override the compiled-in metrics backend
+- `LARA_HOME` - Where the metrics installation id lives (default: `~/.lara`)
+- `DO_NOT_TRACK` - `1`/`true`/`yes` disables usage metrics entirely
 
 ### Error Handling
 
@@ -145,17 +148,61 @@ Error handling in `src/mcp/tools.ts`:
 - Other unexpected errors are logged internally and returned as generic "An error occurred while processing your request" message
 - Privacy-sensitive translations (with `no_trace=true`) are logged for audit purposes
 
+### Usage Metrics (`src/metrics.ts`)
+
+Funnel telemetry for the `mcp` channel of the Lara integrations monitoring
+backend. Both transports report; the module is self-contained and its failures
+never reach a tool call.
+
+- **Configuration**: `DEFAULT_METRICS_URL` / `DEFAULT_METRICS_API_KEY` are
+  compiled in and overridden by `METRICS_URL` / `METRICS_API_KEY`. Either one
+  empty, an unparseable URL, or `DO_NOT_TRACK` set to `1`/`true`/`yes` and
+  `metricsEnabled()` is false — nothing is measured, queued or written to disk.
+- **Delivery**: `POST /auth/issue-token` (API key, `{ installationId }`) buys a
+  token; events go to `POST /metrics/ingest-events` with it. Batched every 2s
+  behind an `unref`'d timer, one retry on 401 only, requeued on 429/5xx, dropped
+  on any other rejection, queue capped at 10 000. `flushNow()` is awaited once,
+  on shutdown, capped at 2s.
+- **Installation id**: a UUID at `${LARA_HOME ?? ~/.lara}/installation-id`,
+  resolved synchronously at module load. `writeFileSync(..., { flag: "wx" })`
+  settles the race between two processes starting together. An unwritable home
+  falls back to a per-process id. A freshly created file is what triggers the
+  one `install` event.
+- **Events**: `install` (no `accountId`), `auth_success` (deduplicated per
+  account per process — the HTTP transport is stateless and builds a Translator
+  per request), `call_success`, `call_error`, and `auth_fail` beside a
+  `call_error` Lara answered with 401/403.
+- **`accountId`**: the `id` claim of the Lara token the SDK holds, read through
+  `getLaraClient()` in `src/lara-client.ts` (the one cast through the SDK's
+  `protected client`). The SDK authenticates lazily, so it is only knowable
+  after a call has succeeded. No token means no account and **no event** — a
+  made-up id would be a fake account in every dashboard.
+- **`metadata`**: `feature` (`text` / `language_detection` /
+  `resource_management` — a shared vocabulary, values are stable forever),
+  `toolName`, `transport`, and `sourceLang`/`targetLang` on `translate`. Never
+  the translated text, never a credential.
+- **Where it is emitted**: inside `CallTool`'s own try/catch, not from a wrapper
+  around it — `CallTool` rewrites `LaraApiError` into `InvalidInputError` before
+  it escapes, so only there is the original error still available to classify.
+
 ### Logging
 
 The server uses Pino structured logging (`src/logger.ts`). Log level is controlled by `LOGGING_LEVEL` environment variable.
 
 ## Testing
 
 Tests are located in `src/__tests__/` and mirror the source structure:
-- `tools/` - Individual tool tests (71 total tests)
-- `server/` - REST server tests
+- `tools/` - Individual tool tests
+- `server/` - REST server tests, plus `mcp.metrics.test.ts` for the metrics wiring
+- `metrics.test.ts` - The metrics client in isolation
 - `utils/mocks.ts` - Shared test utilities with Vitest mocks
 
+The two metrics test files deliberately do **not** import `utils/mocks.ts`: its
+hoisted `vi.mock("@translated/lara")` would replace `LaraApiError`/`TimeoutError`,
+which `errorTypeFor` classifies with `instanceof`. They reset modules and
+re-import instead, because the queue, the token and the installation id are
+module state.
+
 Tests use Vitest with coverage reporting (v8 provider).
 
 ## Security Features

README.md

@@ -234,6 +234,50 @@ Then add to your MCP config:
 
 ---
 
+## Usage Metrics
+
+The server reports anonymous usage events to Lara so we can see how the
+integration is doing: an `install` the first time it runs, `auth_success` /
+`auth_fail` when your credentials are accepted or rejected, and a
+`call_success` / `call_error` per tool call.
+
+**What is sent:** your Lara account id (`acc_...`), the tool name, the source
+and target language tags, how many characters were translated, how long the
+call took, and the server version.
+
+**What is never sent:** the text you translate, your access key, your access
+key secret, and anything else that identifies you or your content.
+
+An installation id (a random UUID, tied to nothing) is generated on first run
+and kept at `~/.lara/installation-id` — set `LARA_HOME` to move it. It exists
+so repeated runs of the same install count as one.
+
+### Opting out
+
+Set `DO_NOT_TRACK` to `1`, `true` or `yes` and nothing is measured, queued,
+written to disk or sent:
+
+```json
+{
+  "mcpServers": {
+    "lara-translate": {
+      "command": "npx",
+      "args": ["-y", "@translated/lara-mcp@latest"],
+      "env": {
+        "LARA_ACCESS_KEY_ID": "<YOUR_ACCESS_KEY_ID>",
+        "LARA_ACCESS_KEY_SECRET": "<YOUR_ACCESS_KEY_SECRET>",
+        "DO_NOT_TRACK": "1"
+      }
+    }
+  }
+}
+```
+
+Metrics never block, slow down or fail a translation: events are batched, sent
+in the background, and a monitoring backend that is down is ignored.
+
+---
+
 ## Support
 
 - For issues with Lara Translate API: visit [Lara Translate Support](https://support.laratranslate.com)