@chadanalytics/mcp-setup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chad Analytics
+
+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,141 @@
+# @chadanalytics/mcp-setup
+
+Connect [Chad Analytics](https://chadanalytics.com)' hosted MCP server to Codex,
+Claude Code, Cursor, or Claude Desktop without hand-editing client config.
+
+The package is dependency-free and ready to run with `npx` on Node 18+.
+
+## 1. Create a credential
+
+In the Slack workspace connected to Chad, run:
+
+```text
+/chad mcp
+```
+
+Only the person who connected Chad can issue or rotate the credential. Chad
+shows it once. The current hosted credential is read-only, limited to the
+connected site, replaces the previous credential, and expires after 90 days.
+
+## 2. Run setup
+
+Pass the token through the environment so it does not enter shell history or
+the process argument list:
+
+```sh
+CHAD_MCP_TOKEN='chad_mcp_…' npx @chadanalytics/mcp-setup codex
+```
+
+Configure more than one client:
+
+```sh
+CHAD_MCP_TOKEN='chad_mcp_…' npx @chadanalytics/mcp-setup cursor claude-code
+```
+
+Configure every supported client:
+
+```sh
+CHAD_MCP_TOKEN='chad_mcp_…' npx @chadanalytics/mcp-setup all
+```
+
+If the environment variable is omitted in an interactive terminal, setup asks
+for the credential with a hidden prompt. It deliberately has no `--token`
+option.
+
+## Preview without changing files
+
+Validate the planned client paths:
+
+```sh
+npx @chadanalytics/mcp-setup all --dry-run
+```
+
+Print isolated Chad config snippets with the credential redacted:
+
+```sh
+npx @chadanalytics/mcp-setup codex cursor --print
+```
+
+Both modes work without a real token and never write files. Print mode does not
+read or echo existing client configuration, so it cannot expose credentials for
+other MCP servers.
+
+## Where setup writes
+
+| Client | User-level configuration |
+| --- | --- |
+| Codex | `~/.codex/config.toml` |
+| Claude Code | `~/.claude.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Claude Desktop, macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop, Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |
+| Claude Desktop, Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Existing settings and other MCP servers are retained. The `chad` entry is
+created or replaced. Files are written atomically and restricted to the current
+user with mode `0600` on platforms that support POSIX permissions.
+
+Because these clients need the bearer token on every hosted MCP request, the
+token is stored in their private user configuration. Treat those files as
+credentials. Never commit them, paste them into chat, or use project-shared MCP
+configuration for this token. Rotate it with `/chad mcp` if it is exposed.
+
+## Custom token variable or endpoint
+
+```sh
+MY_CHAD_TOKEN='chad_mcp_…' npx @chadanalytics/mcp-setup codex \
+  --token-env MY_CHAD_TOKEN
+```
+
+The production endpoint defaults to `https://chadanalytics.com/api/mcp`. A
+different HTTPS endpoint can be selected for an authorized staging deployment:
+
+```sh
+CHAD_MCP_TOKEN='chad_mcp_…' npx @chadanalytics/mcp-setup codex \
+  --url https://staging.example.com/api/mcp
+```
+
+## Verify
+
+Restart the configured client and ask:
+
+```text
+What traffic did I get today?
+Which AI assistants sent visitors this week?
+What pages did AI crawlers request?
+What was my bounce rate in the last 24 hours?
+Break down this week's visitors by country and device.
+How many signups and how much attributed revenue did I get this month?
+Show the drop-off in my signup funnel.
+```
+
+The hosted MCP server currently exposes these read-only tools:
+
+| Tool | Returns |
+| --- | --- |
+| `chad_websites_list` | Sites available to this credential |
+| `chad_analytics_overview` | Visitors, sessions, bounce rate, duration, AI traffic, goals, and revenue |
+| `chad_analytics_ai_traffic` | Human referrals from ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok, and other detected AI tools |
+| `chad_analytics_crawlers` | Server-side AI answer, indexing, training, and crawler requests |
+| `chad_analytics_top_pages` | Most-viewed pages |
+| `chad_analytics_dimensions` | Country, device, browser, or operating-system breakdown |
+| `chad_visitor_journeys` | Chronological anonymous page and session journeys |
+| `chad_goals_list` | Custom-goal completions, visitors, and values |
+| `chad_revenue_overview` | Attributed revenue, payments, buyers, conversion rate, and revenue per visitor |
+| `chad_funnels_list` | Saved funnel definitions |
+| `chad_funnel_results` | Sequential reach, conversion, drop-off, and attributed revenue |
+| `chad_segments_list` | Saved segments and active exclusions |
+| `chad_integrations_status` | Connected provider status without credentials |
+
+All tools are read-only. The credential is checked on every request and the
+server limits results to its authorized Chad tenant and site IDs. A metric may
+be empty until its tracker, goal, funnel, or provider connection is configured.
+See `docs/mcp.md` in the Chad repository for the transport and security model.
+
+## Development
+
+```sh
+npm test
+npm run check
+npm pack --dry-run
+```

package/bin/chad-mcp-setup.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+
+const { stdin, stdout, stderr, env } = process;
+const pkg = require("../package.json");
+const {
+  CLIENTS,
+  DEFAULT_URL,
+  REDACTED_TOKEN,
+  install,
+  normalizeClients,
+  redact,
+  renderClientConfig,
+  resolveClientPath,
+  validateToken,
+  validateUrl,
+} = require("../src/config");
+
+const HELP = `Chad Analytics MCP setup
+
+Safely connect Chad's hosted MCP server to your AI clients.
+
+Usage:
+  CHAD_MCP_TOKEN=chad_mcp_... npx @chadanalytics/mcp-setup codex
+  CHAD_MCP_TOKEN=chad_mcp_... npx @chadanalytics/mcp-setup cursor claude-code
+  CHAD_MCP_TOKEN=chad_mcp_... npx @chadanalytics/mcp-setup all
+
+Clients:
+  codex           OpenAI Codex CLI, desktop app, and IDE extension
+  claude-code     Claude Code, user scope
+  cursor          Cursor, user scope
+  claude-desktop  Claude Desktop
+
+Options:
+  -c, --client <name>  Add a client (repeatable; comma-separated also works)
+      --all            Configure every supported client
+      --dry-run        Validate and show target paths without writing
+      --print          Print only Chad's redacted config snippets; do not write
+      --token-env <n>  Read the credential from env var n (default CHAD_MCP_TOKEN)
+      --url <url>      Override the hosted URL (default ${DEFAULT_URL})
+  -h, --help           Show help
+  -v, --version        Show version
+
+Security:
+  The CLI does not accept a --token argument, so credentials do not enter shell
+  history or process arguments. Set the token environment variable or paste it
+  into the hidden prompt. Config files are written atomically with mode 0600.
+  --dry-run and --print always redact the token.
+`;
+
+function parseArgs(argv) {
+  const options = { clients: [], tokenEnv: "CHAD_MCP_TOKEN" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help") options.help = true;
+    else if (arg === "-v" || arg === "--version") options.version = true;
+    else if (arg === "--all") options.clients.push("all");
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--print") options.print = true;
+    else if (arg === "-c" || arg === "--client") {
+      if (!argv[index + 1]) throw new Error(`${arg} requires a client name.`);
+      options.clients.push(argv[++index]);
+    } else if (arg === "--token-env") {
+      if (!argv[index + 1]) throw new Error("--token-env requires an environment variable name.");
+      options.tokenEnv = argv[++index];
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(options.tokenEnv)) {
+        throw new Error("--token-env must be a valid environment variable name.");
+      }
+    } else if (arg === "--url") {
+      if (!argv[index + 1]) throw new Error("--url requires an HTTPS URL.");
+      options.url = argv[++index];
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option "${arg}".`);
+    } else {
+      options.clients.push(arg);
+    }
+  }
+  return options;
+}
+
+function promptSecret(prompt = "Paste the private token from /chad mcp in Slack: ") {
+  return new Promise((resolve, reject) => {
+    if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") {
+      reject(new Error("Set CHAD_MCP_TOKEN because a hidden interactive prompt is not available."));
+      return;
+    }
+    let value = "";
+    stdout.write(prompt);
+    stdin.setEncoding("utf8");
+    stdin.setRawMode(true);
+    stdin.resume();
+    const finish = (error) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener("data", onData);
+      stdout.write("\n");
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\u0003") return finish(new Error("Cancelled."));
+        if (char === "\r" || char === "\n") return finish();
+        if (char === "\u007f" || char === "\b") value = value.slice(0, -1);
+        else value += char;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (args.version) {
+    stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+  const clients = normalizeClients(args.clients);
+  if (!clients.length) throw new Error(`Choose a client (${CLIENTS.join(", ")}) or use all.`);
+
+  let token = env[args.tokenEnv];
+  if (!token && (args.dryRun || args.print)) token = `chad_mcp_${"0".repeat(64)}`;
+  if (!token) token = await promptSecret();
+
+  if (args.print) {
+    validateToken(token);
+    const url = validateUrl(args.url || DEFAULT_URL);
+    for (const client of clients) {
+      stdout.write(`\n# ${client}: ${resolveClientPath(client)}\n`);
+      // Render an isolated Chad entry so --print can never echo unrelated
+      // credentials already stored in the user's client configuration.
+      stdout.write(redact(renderClientConfig(client, "", token, url), token));
+    }
+    return 0;
+  }
+
+  const plan = install({
+    clients,
+    token,
+    url: args.url,
+    dryRun: args.dryRun,
+  });
+
+  for (const item of plan) {
+    stdout.write(`${args.dryRun ? "Would configure" : "Configured"} ${item.client}: ${item.path}\n`);
+  }
+  if (!args.dryRun) {
+    stdout.write("Restart the configured app, then ask: ‘What traffic did I get today?’\n");
+  } else {
+    stdout.write(`Token: ${REDACTED_TOKEN}\nNo files were changed.\n`);
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    stderr.write(`Error: ${String(error && error.message || error)}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { HELP, main, parseArgs, promptSecret };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@chadanalytics/mcp-setup",
+  "version": "0.1.0",
+  "mcpName": "com.chadanalytics/chad",
+  "description": "Safely connect Chad Analytics hosted MCP to Codex, Claude Code, Cursor, or Claude Desktop",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "chad-mcp-setup": "bin/chad-mcp-setup.js"
+  },
+  "main": "src/config.js",
+  "exports": {
+    ".": "./src/config.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check bin/chad-mcp-setup.js && node --check src/config.js && npm test"
+  },
+  "keywords": [
+    "chad analytics",
+    "mcp",
+    "model context protocol",
+    "codex",
+    "claude code",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/config.js

@@ -0,0 +1,222 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const DEFAULT_URL = "https://chadanalytics.com/api/mcp";
+const SERVER_NAME = "chad";
+const CLIENTS = ["codex", "claude-code", "cursor", "claude-desktop"];
+const TOKEN_PATTERN = /^chad_mcp_[a-f0-9]{64}$/;
+const REDACTED_TOKEN = "chad_mcp_<redacted>";
+
+const CLIENT_ALIASES = Object.freeze({
+  codex: "codex",
+  claude: "claude-code",
+  "claude-code": "claude-code",
+  cursor: "cursor",
+  desktop: "claude-desktop",
+  "claude-desktop": "claude-desktop",
+});
+
+function validateToken(token) {
+  if (!TOKEN_PATTERN.test(String(token || ""))) {
+    throw new Error("CHAD_MCP_TOKEN must be the private chad_mcp_ credential issued by /chad mcp in Slack.");
+  }
+  return String(token);
+}
+
+function validateUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value || ""));
+  } catch {
+    throw new Error("The MCP URL must be a valid HTTPS URL.");
+  }
+  if (parsed.protocol !== "https:") throw new Error("The MCP URL must use HTTPS.");
+  if (parsed.username || parsed.password) throw new Error("The MCP URL must not contain credentials.");
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function normalizeClients(values) {
+  const requested = Array.isArray(values) ? values : [values];
+  const expanded = requested
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+  if (expanded.includes("all")) return [...CLIENTS];
+  const normalized = expanded.map((value) => {
+    const client = CLIENT_ALIASES[value];
+    if (!client) throw new Error(`Unknown client "${value}". Choose: ${CLIENTS.join(", ")}, or all.`);
+    return client;
+  });
+  return [...new Set(normalized)];
+}
+
+function resolveClientPath(client, options = {}) {
+  const home = options.home || os.homedir();
+  const platform = options.platform || process.platform;
+  const env = options.env || process.env;
+  switch (client) {
+    case "codex":
+      return path.join(home, ".codex", "config.toml");
+    case "claude-code":
+      return path.join(home, ".claude.json");
+    case "cursor":
+      return path.join(home, ".cursor", "mcp.json");
+    case "claude-desktop":
+      if (platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      }
+      if (platform === "win32") {
+        return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+      }
+      return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    default:
+      throw new Error(`Unsupported client "${client}".`);
+  }
+}
+
+function jsonServer(token, url, includeType) {
+  return {
+    ...(includeType ? { type: "http" } : {}),
+    url,
+    headers: { Authorization: `Bearer ${token}` },
+  };
+}
+
+function mergeJsonConfig(existing, token, url, includeType) {
+  let parsed = {};
+  if (String(existing || "").trim()) {
+    try {
+      parsed = JSON.parse(existing);
+    } catch {
+      throw new Error("Existing client configuration is not valid JSON; it was left unchanged.");
+    }
+  }
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error("Existing client configuration must contain a JSON object; it was left unchanged.");
+  }
+  const currentServers = parsed.mcpServers;
+  if (currentServers !== undefined && (!currentServers || Array.isArray(currentServers) || typeof currentServers !== "object")) {
+    throw new Error("Existing mcpServers value must be a JSON object; it was left unchanged.");
+  }
+  return `${JSON.stringify({
+    ...parsed,
+    mcpServers: {
+      ...(currentServers || {}),
+      [SERVER_NAME]: jsonServer(token, url, includeType),
+    },
+  }, null, 2)}\n`;
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function stripTomlServer(existing) {
+  const lines = String(existing || "").split(/\r?\n/);
+  const exact = /^\s*\[mcp_servers\.chad\]\s*(?:#.*)?$/;
+  const table = /^\s*\[([^\]]+)\]/;
+  const start = lines.findIndex((line) => exact.test(line));
+  if (start === -1) return String(existing || "").trimEnd();
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const match = lines[index].match(table);
+    if (match && match[1] !== "mcp_servers.chad" && !match[1].startsWith("mcp_servers.chad.")) {
+      end = index;
+      break;
+    }
+  }
+  lines.splice(start, end - start);
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function mergeCodexConfig(existing, token, url) {
+  const before = stripTomlServer(existing);
+  const block = [
+    "[mcp_servers.chad]",
+    `url = ${tomlString(url)}`,
+    `http_headers = { Authorization = ${tomlString(`Bearer ${token}`)} }`,
+  ].join("\n");
+  return `${before ? `${before}\n\n` : ""}${block}\n`;
+}
+
+function readExisting(filePath, fsApi = fs) {
+  try {
+    return fsApi.readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function renderClientConfig(client, existing, token, url) {
+  if (client === "codex") return mergeCodexConfig(existing, token, url);
+  // Claude Code requires an explicit HTTP type. Cursor and Claude Desktop use
+  // the standard remote-server shape documented for config-based MCP clients.
+  return mergeJsonConfig(existing, token, url, client === "claude-code");
+}
+
+function buildPlan(options) {
+  const clients = normalizeClients(options.clients);
+  if (!clients.length) throw new Error("Choose at least one client, or use all.");
+  const token = validateToken(options.token);
+  const url = validateUrl(options.url || DEFAULT_URL);
+  const fsApi = options.fs || fs;
+  return clients.map((client) => {
+    const filePath = resolveClientPath(client, options);
+    const existing = readExisting(filePath, fsApi);
+    return {
+      client,
+      path: filePath,
+      existed: Boolean(existing),
+      content: renderClientConfig(client, existing, token, url),
+    };
+  });
+}
+
+function atomicWrite(filePath, content, fsApi = fs) {
+  const directory = path.dirname(filePath);
+  fsApi.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.chad-${process.pid}-${Date.now()}.tmp`);
+  try {
+    fsApi.writeFileSync(tempPath, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    fsApi.renameSync(tempPath, filePath);
+    fsApi.chmodSync(filePath, 0o600);
+  } catch (error) {
+    try { fsApi.unlinkSync(tempPath); } catch {}
+    throw error;
+  }
+}
+
+function install(options) {
+  const fsApi = options.fs || fs;
+  const plan = buildPlan(options);
+  if (!options.dryRun) {
+    for (const item of plan) atomicWrite(item.path, item.content, fsApi);
+  }
+  return plan;
+}
+
+function redact(value, token) {
+  return String(value).split(String(token)).join(REDACTED_TOKEN);
+}
+
+module.exports = {
+  CLIENTS,
+  DEFAULT_URL,
+  REDACTED_TOKEN,
+  TOKEN_PATTERN,
+  atomicWrite,
+  buildPlan,
+  install,
+  mergeCodexConfig,
+  mergeJsonConfig,
+  normalizeClients,
+  redact,
+  renderClientConfig,
+  resolveClientPath,
+  validateToken,
+  validateUrl,
+};