opedd-mcp 0.4.0 → 0.5.0

package/README.md

@@ -87,9 +87,28 @@ Set environment variables to pre-configure the server:
 | `OPEDD_PUB_BEARER` | Optional | Canonical Publisher API Bearer key (`opedd_pub_<env>_<32-hex>`; issued via `POST /publishers-api-keys action=create_api_key`) — enables `list_publisher_content`. **v0.4.0 canonical.** |
 | `OPEDD_API_KEY` | Deprecated | Legacy Publisher API key (`op_...`) — fallback during the transition window; will stop working when opedd-backend Phase C deploys. Migrate to `OPEDD_PUB_BEARER`. |
 | `OPEDD_API_URL` | Optional | Override the API base URL (default: Opedd production) |
+| `OPEDD_MCP_TELEMETRY` | Optional | Set to `0` to disable anonymous usage telemetry (see below) |
 
 > **Getting a Stripe payment method ID**: Save a card in your Stripe account and retrieve the `pm_...` ID via the [Stripe API](https://stripe.com/docs/api/payment_methods).
 
+## Anonymous usage telemetry
+
+To understand how AI assistants use this server, `opedd-mcp` sends anonymous
+telemetry for each tool call: **only the tool name, its duration, whether it
+succeeded, and the server version** — plus a random per-process id. It never
+sends tool parameters, responses, your email, API keys, tokens, content, or
+your IP. Data goes to Opedd's PostHog (EU region).
+
+**To opt out**, set either environment variable before starting the server:
+
+```
+OPEDD_MCP_TELEMETRY=0
+# or the cross-tool standard:
+DO_NOT_TRACK=1
+```
+
+When opted out, no telemetry client is created and nothing is sent.
+
 ## Claude Desktop setup
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

package/dist/index.js

@@ -3,12 +3,22 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { pathToFileURL } from "node:url";
+import { initTelemetry, captureToolCall, shutdownTelemetry } from "./telemetry.js";
 // ─── Configuration ────────────────────────────────────────────────────────────
 const API_BASE = process.env.OPEDD_API_URL ??
     "https://api.opedd.com";
 const BUYER_EMAIL = process.env.OPEDD_BUYER_EMAIL;
 const PAYMENT_METHOD_ID = process.env.OPEDD_PAYMENT_METHOD_ID;
-const API_KEY = process.env.OPEDD_API_KEY; // publisher API key (op_...)
+// B91 v0.4.0 migration (2026-05-26): canonical Bearer auth.
+// OPEDD_PUB_BEARER is the new canonical opedd_pub_<env>_<32-hex> key
+// (issued via POST /publishers-api-keys action=create_api_key).
+// OPEDD_API_KEY retained as backward-compat alias for legacy op_ keys
+// during the dual-mode transition window on the /api endpoint (Phase A
+// shipped opedd-backend 2026-05-26). Backend Phase C will drop the
+// op_ path entirely; users MUST migrate to OPEDD_PUB_BEARER before
+// then. Prefer Bearer if both set.
+const PUB_BEARER = process.env.OPEDD_PUB_BEARER; // canonical opedd_pub_<env>_<32-hex>
+const API_KEY = process.env.OPEDD_API_KEY; // LEGACY op_<32-hex> — retiring per backend Phase C
 const BUYER_TOKEN = process.env.OPEDD_BUYER_TOKEN; // buyer API token (opedd_buyer_live_... or opedd_buyer_test_...)
 const ACCESS_KEY = process.env.OPEDD_ACCESS_KEY; // enterprise access key (ent_*); for /enterprise-license GET feed
 const BUYER_JWT = process.env.OPEDD_BUYER_JWT; // Supabase JWT; for /buyer-audit + /buyer-compliance-report
@@ -17,7 +27,9 @@ async function opeddFetch(path, options = {}) {
     const url = `${API_BASE}${path}`;
     const headers = {
         "Content-Type": "application/json",
-        ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+        // B91 v0.4.0 (2026-05-26): canonical Bearer preferred; legacy X-API-Key
+        // accepted only as fallback during transition window
+        ...(PUB_BEARER ? { Authorization: `Bearer ${PUB_BEARER}` } : (API_KEY ? { "X-API-Key": API_KEY } : {})),
         ...(options.headers ?? {}),
     };
     const res = await fetch(url, { ...options, headers });
@@ -35,7 +47,8 @@ async function opeddFetchNdjson(path, options = {}) {
     const url = `${API_BASE}${path}`;
     const headers = {
         Accept: "application/x-ndjson",
-        ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+        // B91 v0.4.0 (2026-05-26): canonical Bearer preferred; legacy fallback
+        ...(PUB_BEARER ? { Authorization: `Bearer ${PUB_BEARER}` } : (API_KEY ? { "X-API-Key": API_KEY } : {})),
         ...(options.headers ?? {}),
     };
     const res = await fetch(url, { ...options, headers });
@@ -527,10 +540,10 @@ if (BUYER_JWT) {
     });
 }
 // If a publisher API key is configured, expose publisher-specific tooling
-if (API_KEY) {
+if (PUB_BEARER || API_KEY) {
     TOOLS.push({
         name: "list_publisher_content",
-        description: "List all licensable articles for the authenticated publisher (requires OPEDD_API_KEY). " +
+        description: "List all licensable articles for the authenticated publisher (requires OPEDD_PUB_BEARER, or legacy OPEDD_API_KEY). " +
             "Returns articles with titles, descriptions, pricing, and sales statistics. " +
             "Use article IDs from this list to purchase licenses via purchase_license.",
         inputSchema: {
@@ -556,7 +569,15 @@ if (API_KEY) {
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 const server = new Server({ name: "opedd-mcp", version: "0.3.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-server.setRequestHandler(CallToolRequestSchema, async (request) => dispatchTool(request.params.name, (request.params.arguments ?? {})));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    // Anonymous usage telemetry — captures only the tool name, duration, and
+    // success flag (see telemetry.ts). Wrapping the runtime handler (not
+    // dispatchTool) keeps unit tests, which call dispatchTool directly, silent.
+    const start = Date.now();
+    const result = await dispatchTool(request.params.name, (request.params.arguments ?? {}));
+    captureToolCall(request.params.name, Date.now() - start, result.isError !== true);
+    return result;
+});
 // ─── Tool dispatcher (exported for unit tests) ────────────────────────────────
 //
 // Extracted from the inline handler 2026-05-24 EEST as part of the opedd-mcp
@@ -815,8 +836,8 @@ export async function dispatchTool(name, args) {
             }
             // ── list_publisher_content ─────────────────────────────────────────────
             case "list_publisher_content": {
-                if (!API_KEY) {
-                    return err("OPEDD_API_KEY env var is required for this tool");
+                if (!PUB_BEARER && !API_KEY) {
+                    return err("OPEDD_PUB_BEARER env var is required for this tool (canonical Bearer; legacy OPEDD_API_KEY also accepted during transition)");
                 }
                 const { limit = 20, type, offset = 0 } = args;
                 const params = new URLSearchParams({ action: "articles" });
@@ -844,6 +865,12 @@ export async function dispatchTool(name, args) {
 if (typeof process !== "undefined" &&
     process.argv?.[1] &&
     import.meta.url === pathToFileURL(process.argv[1]).href) {
+    initTelemetry();
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => {
+            void shutdownTelemetry().finally(() => process.exit(0));
+        });
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[opedd-mcp] Server running on stdio");

package/dist/telemetry.js

@@ -0,0 +1,89 @@
+// Anonymous usage telemetry for the Opedd MCP server.
+//
+// Captures ONLY which tool an agent called, how long it took, and whether it
+// succeeded — NEVER parameters, responses, PII, keys, or content. This module
+// is only ever handed the tool name + duration + ok flag, so there is nothing
+// sensitive to leak by construction. It reports to Opedd's PostHog (EU region)
+// so we can understand how AI agents use the MCP distribution channel.
+//
+// Opt out: set OPEDD_MCP_TELEMETRY=0 (or "false"/"off"), or the widely-used
+// DO_NOT_TRACK=1. When opted out no client is created and nothing is sent.
+//
+// stdio-safe: PostHog is reached over HTTPS only; this module NEVER writes to
+// stdout (that would corrupt the MCP JSON-RPC stream). All errors are swallowed
+// so telemetry can never affect a tool call or the server.
+import { PostHog } from "posthog-node";
+import { randomUUID } from "node:crypto";
+// Public, write-only PostHog project key (EU cloud, project 218295). Safe to
+// embed — it can only send events, not read data.
+const POSTHOG_KEY = "phc_zrKQzZLUZikynMWJWMHUiQBgRsJa2fLzDFMdh6HxGU6c";
+const POSTHOG_HOST = "https://eu.i.posthog.com";
+const SERVER_VERSION = "0.5.0";
+/** Whether telemetry is allowed (respects OPEDD_MCP_TELEMETRY + DO_NOT_TRACK). Pure — exported for tests. */
+export function isTelemetryEnabled() {
+    const t = process.env.OPEDD_MCP_TELEMETRY?.toLowerCase();
+    if (t === "0" || t === "false" || t === "off" || t === "no")
+        return false;
+    const dnt = process.env.DO_NOT_TRACK?.toLowerCase();
+    if (dnt === "1" || dnt === "true")
+        return false;
+    return true;
+}
+/**
+ * The ONLY properties ever sent for a tool call — no parameters, responses,
+ * PII, keys, or content by construction. Pure; exported so a test can assert
+ * the privacy invariant directly.
+ */
+export function toolCallProperties(tool, durationMs, ok) {
+    return {
+        tool,
+        duration_ms: Math.round(durationMs),
+        ok,
+        server_version: SERVER_VERSION,
+    };
+}
+let client = null;
+// Anonymous per-process session id — not tied to any user, buyer, key, or IP.
+const sessionId = randomUUID();
+export function initTelemetry() {
+    if (!isTelemetryEnabled())
+        return;
+    try {
+        client = new PostHog(POSTHOG_KEY, {
+            host: POSTHOG_HOST,
+            flushAt: 1, // low-volume telemetry; deliver each event promptly
+            flushInterval: 30000,
+        });
+        // Swallow any transport error so it can never surface or crash the server.
+        client.on?.("error", () => { });
+    }
+    catch {
+        client = null;
+    }
+}
+export function captureToolCall(tool, durationMs, ok) {
+    if (!client)
+        return;
+    try {
+        client.capture({
+            distinctId: sessionId,
+            event: "mcp_tool_call",
+            properties: toolCallProperties(tool, durationMs, ok),
+        });
+    }
+    catch {
+        /* telemetry must never affect a tool call */
+    }
+}
+export async function shutdownTelemetry() {
+    const c = client;
+    client = null;
+    if (!c)
+        return;
+    try {
+        await c.shutdown();
+    }
+    catch {
+        /* ignore */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opedd-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Opedd — discover, purchase, verify, and audit content licenses from AI assistants. Covers Phase 11 buyer-side surfaces + Phase 12 Wave 1 + 3 regulatory surfaces (CDSM Article 4(3) RSL + EU AI Act Article 53 attestation + platform onboarding helper).",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "mcp",
@@ -25,7 +26,8 @@
   "author": "Opedd",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "posthog-node": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
@@ -35,5 +37,8 @@
   },
   "engines": {
     "node": ">=20"
-  }
+  },
+  "files": [
+    "dist"
+  ]
 }

package/.github/workflows/ci.yml

@@ -1,70 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        # Node 18 dropped 2026-05-24 — vitest 4.x (rolldown dep) requires
-        # `node:util.styleText` which is only available on Node 21.7+.
-        # Node 18 reaches active LTS end April 2025; engines.node in
-        # package.json bumped to ">=20" in the same commit. Re-add Node 18
-        # only if vitest downgrade ratified (which is the alternative;
-        # founder picked engines bump).
-        node-version: ["20", "22"]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-
-      - name: Install dependencies
-        # Using `npm install` rather than `npm ci` because the lockfile
-        # generated on macOS doesn't include Linux-conditional optional
-        # native deps (e.g. @emnapi/* used by vitest 4.x via napi-rs).
-        # `npm install` resolves transitively at install time per-platform;
-        # `npm ci` strictly validates lockfile-against-package.json and
-        # rejects when platform-specific transitive deps are missing.
-        # Trade-off: install is slower + slightly looser; acceptable for
-        # this repo's CI scale.
-        run: npm install
-
-      - name: TypeScript compile
-        run: npm run build
-
-      - name: Unit tests (vitest)
-        run: npm test
-
-      - name: Verify dist/index.js produced
-        run: |
-          test -f dist/index.js || (echo "::error::dist/index.js not produced by tsc"; exit 1)
-          echo "dist/index.js bytes: $(wc -c < dist/index.js)"
-
-      - name: Smoke-boot the MCP server
-        run: |
-          # Send initialize + tools/list, confirm v0.2.0 boots and lists tools
-          printf '%s\n%s\n' \
-            '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}' \
-            '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
-            | timeout 10 node dist/index.js > /tmp/mcp-output.txt 2> /tmp/mcp-stderr.txt || true
-          if ! grep -q '"serverInfo":{"name":"opedd-mcp"' /tmp/mcp-output.txt; then
-            echo "::error::MCP server did not respond with expected serverInfo"
-            cat /tmp/mcp-output.txt
-            cat /tmp/mcp-stderr.txt
-            exit 1
-          fi
-          if ! grep -q '"name":"lookup_content"' /tmp/mcp-output.txt; then
-            echo "::error::MCP server did not list lookup_content tool"
-            exit 1
-          fi
-          echo "MCP smoke boot OK"