From f95b13be107153ca663980ae4ac85dc0099a3a24 Mon Sep 17 00:00:00 2001
From: Klappy <klappy@klappy.dev>
Date: Wed, 15 Apr 2026 01:45:08 +0000
Subject: [PATCH 1/2] feat: add ?consumer= query param as highest-priority
 consumer identification

---
 workers/src/telemetry.ts | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/workers/src/telemetry.ts b/workers/src/telemetry.ts
index 9c4534e..f3b6192 100644
--- a/workers/src/telemetry.ts
+++ b/workers/src/telemetry.ts
@@ -77,27 +77,36 @@ function parseClientInfoName(payload: unknown): string | null {
 
 /**
  * Consumer label resolution chain:
- * 1. x-oddkit-client header (explicit, highest priority)
- * 2. MCP initialize → clientInfo.name (protocol-native)
- * 3. User-Agent header (fallback)
- * 4. "unknown" (default)
+ * 1. ?consumer= query parameter (URL-level, highest priority)
+ * 2. x-oddkit-client header (explicit)
+ * 3. MCP initialize → clientInfo.name (protocol-native)
+ * 4. User-Agent header (fallback)
+ * 5. "unknown" (default)
  */
 export function parseConsumerLabel(
   request: Request,
   payload: unknown,
 ): { label: string; source: string } {
-  // 1. Explicit header
+  // 1. URL query parameter — lets platforms that block custom headers self-identify
+  const url = new URL(request.url);
+  const consumer = url.searchParams.get("consumer");
+  if (consumer) {
+    const label = sanitize(consumer);
+    if (label) return { label, source: "query-param" };
+  }
+
+  // 2. Explicit header
   const explicit = request.headers.get("x-oddkit-client");
   if (explicit) {
     const label = sanitize(explicit);
     if (label) return { label, source: "x-oddkit-client" };
   }
 
-  // 2. MCP initialize clientInfo.name
+  // 3. MCP initialize clientInfo.name
   const fromInit = parseClientInfoName(payload);
   if (fromInit) return { label: fromInit, source: "initialize.clientInfo.name" };
 
-  // 3. User-Agent
+  // 4. User-Agent
   const ua = request.headers.get("user-agent");
   if (ua) {
     const first = ua.split(/\s+/)[0] ?? "";

From 347dd8969ac58d33fbc5804a7f6d57c3cfd2e7c8 Mon Sep 17 00:00:00 2001
From: Klappy <klappy@klappy.dev>
Date: Wed, 15 Apr 2026 01:53:14 +0000
Subject: [PATCH 2/2] docs: add ?consumer= query param to all connection URLs

---
 README.md           | 12 +++++++-----
 docs/CLAUDE-CODE.md |  2 +-
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 1240c36..7129f1a 100644
--- a/README.md
+++ b/README.md
@@ -14,17 +14,19 @@ oddkit reads markdown files from a GitHub repository — decisions, constraints,
 
 oddkit is a remote MCP server. You don't install anything — you point your AI tool at a URL.
 
+You can optionally add `?consumer=yourname` to the URL to identify yourself on the public transparency leaderboard. oddkit tracks which tools are used and how often, but never what you search for or what documents contain. Replace `yourname` with your name, a handle, or a project name — or leave it off to stay anonymous.
+
 ### Claude.ai
 
 Settings → Connectors → Add Custom Integration:
 - **Name:** `oddkit`
-- **URL:** `https://oddkit.klappy.dev/mcp`
+- **URL:** `https://oddkit.klappy.dev/mcp?consumer=yourname`
 
 ### ChatGPT
 
 Settings → Developer Mode → Create App → add MCP server URL:
 
-`https://oddkit.klappy.dev/mcp`
+`https://oddkit.klappy.dev/mcp?consumer=yourname`
 
 ### Claude Code / Cursor / Any MCP Client
 
@@ -35,19 +37,19 @@ Add to your `.mcp.json`:
   "mcpServers": {
     "oddkit": {
       "type": "http",
-      "url": "https://oddkit.klappy.dev/mcp"
+      "url": "https://oddkit.klappy.dev/mcp?consumer=yourname"
     }
   }
 }
 ```
 
-Or in Claude Code: `claude mcp add --transport http oddkit https://oddkit.klappy.dev/mcp`
+Or in Claude Code: `claude mcp add --transport http oddkit https://oddkit.klappy.dev/mcp?consumer=yourname`
 
 ### Lovable / Replit / Gemini / ElevenLabs / Others
 
 Any tool that supports MCP can connect. Look for "MCP server" or "custom integration" in your tool's settings and provide the URL:
 
-`https://oddkit.klappy.dev/mcp`
+`https://oddkit.klappy.dev/mcp?consumer=yourname`
 
 ---
 
diff --git a/docs/CLAUDE-CODE.md b/docs/CLAUDE-CODE.md
index 96a7767..75a19cf 100644
--- a/docs/CLAUDE-CODE.md
+++ b/docs/CLAUDE-CODE.md
@@ -40,7 +40,7 @@ npm run deploy
 
 Then add the remote MCP server in Claude.ai:
 1. Go to Settings → Integrations → MCP
-2. Add server URL: `https://oddkit.klappy.dev/mcp`
+2. Add server URL: `https://oddkit.klappy.dev/mcp?consumer=yourname`
 
 See [workers/README.md](../workers/README.md) for full deployment instructions.