@joy-loyalty/mcp 0.4.0 → 0.5.0

package/README.md

@@ -21,7 +21,7 @@ For **Claude Desktop**, edit your config file:
   "mcpServers": {
     "joy-loyalty": {
       "command": "npx",
-      "args": ["-y", "@joy-loyalty/mcp"],
+      "args": ["-y", "@joy-loyalty/mcp@latest"],
       "env": {
         "JOY_APP_KEY": "<your-shop-id>",
         "JOY_SECRET_KEY": "<your-key-from-step-1>"
@@ -76,6 +76,34 @@ Your Joy plan must be **Advanced or higher** to use the API.
 
 Every point-changing action requires a stated reason and is recorded in your Joy activity log for audit purposes.
 
+## Usage telemetry
+
+Starting with 0.5.0, choose telemetry behavior with `JOY_MCP_TELEMETRY` in your MCP client's `env` block:
+
+| Setting | What is sent |
+|---|---|
+| Unset (default) | Metadata headers on normal Joy API requests: call ID, tool name, transport (`stdio`), server version, client application name (when valid), and a random process session ID. No telemetry event relay requests. |
+| `"on"` | The same headers plus batched session and tool-call metadata sent to Joy's telemetry endpoint. |
+| `"off"`, `"false"`, or `"0"` | No telemetry headers or event relay. `DO_NOT_TRACK="1"` or `DO_NOT_TRACK="true"` also disables telemetry and takes precedence over `"on"`. |
+
+Both settings ignore case and surrounding whitespace (for example, `"OFF"` and `" off "` disable telemetry).
+
+Telemetry goes to `https://api.joy.so` by default; full mode uses `/rest_api/v2/internal/mcp-telemetry`. If Joy support configures `JOY_API_BASE_URL`, telemetry uses that same API destination. Normal API authentication still uses your configured credential; credentials are never included in telemetry events.
+
+In full mode, events contain only these metadata fields when applicable:
+
+- Shared: `event`, `schema_version`, `event_id`, `server_version`, `session_id`, `mcp_client_name`, `mcp_client_version`.
+- Session: `protocol_version`, `client_capabilities` (capability names only), `tools_exposed`.
+- Tool call: `call_id`, `tool`, `tool_kind`, `outcome`, `error_kind`, `error_code` (a machine code), `http_status`, `duration_ms`, `api_calls`, `api_ms`, `result_bytes` (UTF-8 byte count only).
+
+Joy's backend adds verified shop ID/domain, Joy and Shopify plans, authentication mode, access scope, and transport. With either header mode or full mode, the backend can also record API status, duration, route pattern, and BigQuery usage. Header mode cannot report calls served entirely from cache, failures before an API request, or result byte counts.
+
+**Telemetry does not send tool arguments, tool result content, prompts, SQL, or free-form error messages.** Normal tool requests and responses still carry the data needed to perform the tool's work. Telemetry never writes to the stdio protocol output.
+
+To enable event relay, add `"JOY_MCP_TELEMETRY": "on"` to your client's `env` block. To disable all telemetry, add `"JOY_MCP_TELEMETRY": "off"` or `"DO_NOT_TRACK": "1"`. Restart your AI client after changing these settings.
+
+Run the latest version with `npx -y @joy-loyalty/mcp@latest`.
+
 ## Security
 
 - The server only talks to Joy's official API — it never sends your data anywhere else.

package/build/config.js

@@ -67,3 +67,14 @@ export function loadConfig(env = process.env) {
         deductDryRunThreshold
     };
 }
+export const DEFAULT_TELEMETRY_MODE = 'headers';
+/** Choose header-only telemetry by default, full relay by opt-in, or complete opt-out. */
+export function telemetryMode(env = process.env) {
+    const mode = (env.JOY_MCP_TELEMETRY ?? '').trim().toLowerCase();
+    const doNotTrack = (env.DO_NOT_TRACK ?? '').trim().toLowerCase();
+    if (['1', 'true'].includes(doNotTrack) || ['off', 'false', '0'].includes(mode))
+        return 'off';
+    if (mode === 'on')
+        return 'full';
+    return DEFAULT_TELEMETRY_MODE;
+}