kontex-mcp 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# kontex-mcp
+
+One command to connect [Kontex](https://www.kontex.so) to Claude Desktop,
+Claude Code, and Cursor.
+
+```bash
+npx kontex-mcp connect kx_your_key
+```
+
+Get a key from the MCP keys page in your Kontex dashboard. Each key belongs
+to one person and can be revoked there at any time.
+
+What it does, per tool it finds on your machine:
+
+- **Claude Desktop**: adds a `kontex` server to `claude_desktop_config.json`
+  that runs `npx mcp-remote` against `https://www.kontex.so/api/mcp` with your
+  key in an environment variable. Restart Claude Desktop afterwards.
+- **Claude Code**: runs `claude mcp add --transport http --scope user kontex …`.
+- **Cursor**: adds a `kontex` server with `url` and `headers` to
+  `~/.cursor/mcp.json`.
+
+Other servers in those files are left untouched; the previous file is kept
+as `.bak`. Tools that are not installed are skipped.
+
+```bash
+npx kontex-mcp connect kx_… --dry-run          # show the changes only
+npx kontex-mcp connect kx_… --only cursor      # one tool
+npx kontex-mcp disconnect                      # remove Kontex from all three
+```
+
+Requires Node 18 or newer. claude.ai and ChatGPT web connectors are not
+covered: they need OAuth, which Kontex will add separately.

package/bin/kontex-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from "../lib/cli.js";
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  },
+);

package/lib/claude-code.js

@@ -0,0 +1,39 @@
+// @ts-check
+import { spawnSync } from "node:child_process";
+import { SERVER_NAME } from "./clients.js";
+
+/** Claude Code keeps its own config; we go through its CLI. */
+
+const BIN = process.platform === "win32" ? "claude.cmd" : "claude";
+
+export function claudeCodeInstalled() {
+  const r = spawnSync(BIN, ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+  return !r.error && r.status === 0;
+}
+
+/** @param {{ url: string; key: string }} t */
+export function claudeCodeAddArgs({ url, key }) {
+  return ["mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, url, "--header", `Authorization: Bearer ${key}`];
+}
+
+export function claudeCodeRemoveArgs() {
+  return ["mcp", "remove", "--scope", "user", SERVER_NAME];
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ ok: boolean; output: string }}
+ */
+export function runClaude(args) {
+  const r = spawnSync(BIN, args, { encoding: "utf8", shell: process.platform === "win32" });
+  const output = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+  return { ok: !r.error && r.status === 0, output };
+}
+
+/**
+ * Human-readable form for --dry-run; the key is masked.
+ * @param {string[]} args
+ */
+export function formatCommand(args) {
+  return ["claude", ...args.map((a) => (a.startsWith("Authorization: Bearer ") ? `"Authorization: Bearer kx_…"` : a))].join(" ");
+}

package/lib/cli.js

@@ -0,0 +1,203 @@
+// @ts-check
+import {
+  DEFAULT_URL,
+  claudeDesktopConfigPath,
+  claudeDesktopEntry,
+  cursorConfigPath,
+  cursorEntry,
+  dirExists,
+  looksLikeKey,
+  readJson,
+  withServer,
+  withoutServer,
+  writeJson,
+} from "./clients.js";
+import { claudeCodeAddArgs, claudeCodeInstalled, claudeCodeRemoveArgs, formatCommand, runClaude } from "./claude-code.js";
+import path from "node:path";
+
+const CLIENT_IDS = /** @type {const} */ (["claude-desktop", "claude-code", "cursor"]);
+/** @typedef {(typeof CLIENT_IDS)[number]} ClientId */
+
+const LABELS = { "claude-desktop": "Claude Desktop", "claude-code": "Claude Code", cursor: "Cursor" };
+
+const HELP = `kontex-mcp — connect Kontex to your AI tools
+
+Usage:
+  npx kontex-mcp connect <key>      Add Kontex to Claude Desktop, Claude Code, and Cursor
+  npx kontex-mcp disconnect         Remove Kontex from all three
+  npx kontex-mcp --help
+
+Options:
+  --only <list>    Comma-separated subset: claude-desktop, claude-code, cursor
+  --url <url>      MCP endpoint (default: ${DEFAULT_URL})
+  --dry-run        Show what would change without writing anything
+
+Get a key from https://www.kontex.so/dashboard/mcp. Each key belongs to one
+person; do not share it. Tools that are not installed are skipped.`;
+
+/**
+ * @param {string[]} argv
+ * @returns {{ command: string | undefined; positional: string[]; only: ClientId[] | null; url: string; dryRun: boolean; help: boolean }}
+ */
+export function parseArgs(argv) {
+  /** @type {string[]} */
+  const positional = [];
+  /** @type {ClientId[] | null} */
+  let only = null;
+  let url = DEFAULT_URL;
+  let dryRun = false;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") help = true;
+    else if (a === "--dry-run") dryRun = true;
+    else if (a === "--url") url = argv[++i] ?? url;
+    else if (a.startsWith("--url=")) url = a.slice(6);
+    else if (a === "--only" || a.startsWith("--only=")) {
+      const raw = a === "--only" ? (argv[++i] ?? "") : a.slice(7);
+      const ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
+      const bad = ids.filter((id) => !CLIENT_IDS.includes(/** @type {ClientId} */ (id)));
+      if (bad.length) throw new Error(`Unknown client(s): ${bad.join(", ")}. Use: ${CLIENT_IDS.join(", ")}`);
+      only = /** @type {ClientId[]} */ (ids);
+    } else if (a.startsWith("-")) throw new Error(`Unknown option: ${a}`);
+    else positional.push(a);
+  }
+  const [command, ...rest] = positional;
+  return { command, positional: rest, only, url, dryRun, help };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ log?: (s: string) => void; home?: string }} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, io = {}) {
+  const log = io.log ?? ((s) => console.log(s));
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    log(e instanceof Error ? e.message : String(e));
+    return 2;
+  }
+  if (opts.help || !opts.command) {
+    log(HELP);
+    return opts.help ? 0 : 2;
+  }
+  const wanted = opts.only ?? [...CLIENT_IDS];
+  const paths = { desktop: claudeDesktopConfigPath({ home: io.home }), cursor: cursorConfigPath({ home: io.home }) };
+
+  if (opts.command === "connect") {
+    const key = opts.positional[0];
+    if (!key) {
+      log("Missing key. Usage: npx kontex-mcp connect <key>");
+      return 2;
+    }
+    if (!looksLikeKey(key)) {
+      log("That does not look like a Kontex key (they start with kx_). Copy it from the MCP keys page.");
+      return 2;
+    }
+    let url;
+    try {
+      url = new URL(opts.url).toString();
+    } catch {
+      log(`Invalid --url: ${opts.url}`);
+      return 2;
+    }
+    const target = { url, key };
+    log(opts.dryRun ? "Dry run: nothing will be written." : "Connecting Kontex to your AI tools…");
+    let configured = 0;
+    /** @type {string[]} */
+    const notes = [];
+
+    if (wanted.includes("claude-desktop")) {
+      if (dirExists(path.dirname(paths.desktop))) {
+        const next = withServer(readJson(paths.desktop), claudeDesktopEntry(target));
+        if (opts.dryRun) log(`  would write ${paths.desktop}:\n${indent(JSON.stringify(next.mcpServers.kontex, null, 2))}`);
+        else writeJson(paths.desktop, next);
+        log(`✓ ${LABELS["claude-desktop"]}`);
+        configured++;
+        notes.push("Restart Claude Desktop to see Kontex.");
+      } else log(`– ${LABELS["claude-desktop"]} (not installed, skipped)`);
+    }
+
+    if (wanted.includes("claude-code")) {
+      if (claudeCodeInstalled()) {
+        const add = claudeCodeAddArgs(target);
+        if (opts.dryRun) log(`  would run: ${formatCommand(claudeCodeRemoveArgs())} (if present)\n  would run: ${formatCommand(add)}`);
+        else {
+          runClaude(claudeCodeRemoveArgs()); // replace a previous key; failure just means it was not there
+          const r = runClaude(add);
+          if (!r.ok) {
+            log(`✗ ${LABELS["claude-code"]}: ${r.output || "claude mcp add failed"}`);
+            return finish(log, configured, notes, 1);
+          }
+        }
+        log(`✓ ${LABELS["claude-code"]}`);
+        configured++;
+      } else log(`– ${LABELS["claude-code"]} (not installed, skipped)`);
+    }
+
+    if (wanted.includes("cursor")) {
+      if (dirExists(path.dirname(paths.cursor))) {
+        const next = withServer(readJson(paths.cursor), cursorEntry(target));
+        if (opts.dryRun) log(`  would write ${paths.cursor}:\n${indent(JSON.stringify(next.mcpServers.kontex, null, 2))}`);
+        else writeJson(paths.cursor, next);
+        log(`✓ ${LABELS.cursor}`);
+        configured++;
+      } else log(`– ${LABELS.cursor} (not installed, skipped)`);
+    }
+
+    return finish(log, configured, notes, 0);
+  }
+
+  if (opts.command === "disconnect") {
+    log(opts.dryRun ? "Dry run: nothing will be written." : "Removing Kontex from your AI tools…");
+    let removed = 0;
+    for (const [id, file] of /** @type {const} */ ([["claude-desktop", paths.desktop], ["cursor", paths.cursor]])) {
+      if (!wanted.includes(id)) continue;
+      const { config, removed: had } = withoutServer(readJson(file));
+      if (had) {
+        if (!opts.dryRun) writeJson(file, config);
+        log(`✓ ${LABELS[id]}`);
+        removed++;
+      } else log(`– ${LABELS[id]} (nothing to remove)`);
+    }
+    if (wanted.includes("claude-code")) {
+      if (claudeCodeInstalled()) {
+        const r = opts.dryRun ? { ok: true } : runClaude(claudeCodeRemoveArgs());
+        log(r.ok ? `✓ ${LABELS["claude-code"]}` : `– ${LABELS["claude-code"]} (nothing to remove)`);
+        if (r.ok) removed++;
+      } else log(`– ${LABELS["claude-code"]} (not installed, skipped)`);
+    }
+    log(removed ? "Done. Your key still works until you revoke it on the MCP keys page." : "Kontex was not configured anywhere.");
+    return 0;
+  }
+
+  log(`Unknown command: ${opts.command}\n\n${HELP}`);
+  return 2;
+}
+
+/**
+ * @param {(s: string) => void} log
+ * @param {number} configured
+ * @param {string[]} notes
+ * @param {number} code
+ */
+function finish(log, configured, notes, code) {
+  if (configured === 0) {
+    log("Nothing configured: none of Claude Desktop, Claude Code, or Cursor was found on this machine.");
+    log("Install one of them, or paste the manual snippet from the MCP keys page into another MCP client.");
+    return code || 1;
+  }
+  log(`Done.${notes.length ? " " + notes.join(" ") : ""}`);
+  return code;
+}
+
+/** @param {string} s */
+function indent(s) {
+  return s
+    .split("\n")
+    .map((l) => "    " + l)
+    .join("\n");
+}

package/lib/clients.js

@@ -0,0 +1,117 @@
+// @ts-check
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Pure config logic for each MCP client. Nothing here touches the network;
+ * file access is limited to the helpers at the bottom so `--dry-run` can
+ * reuse the same merge functions.
+ */
+
+export const SERVER_NAME = "kontex";
+export const DEFAULT_URL = "https://www.kontex.so/api/mcp";
+const ENV_NAME = "KONTEX_AUTH";
+
+/** @typedef {{ url: string; key: string }} Target */
+/** @typedef {Record<string, any>} JsonObject */
+
+/**
+ * Kontex keys are `kx_` + 32 random bytes in base64url.
+ * @param {unknown} value
+ */
+export function looksLikeKey(value) {
+  return typeof value === "string" && /^kx_[A-Za-z0-9_-]{30,}$/.test(value);
+}
+
+/**
+ * Claude Desktop reads a JSON file per OS. Its Windows build splits args on
+ * spaces, so the header value goes through an env var (mcp-remote README).
+ * @param {{ platform?: NodeJS.Platform; home?: string; appData?: string }} [opts]
+ */
+export function claudeDesktopConfigPath(opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const home = opts.home ?? os.homedir();
+  if (platform === "darwin") return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (platform === "win32") return path.join(opts.appData ?? process.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+
+/** @param {{ home?: string }} [opts] */
+export function cursorConfigPath(opts = {}) {
+  return path.join(opts.home ?? os.homedir(), ".cursor", "mcp.json");
+}
+
+/** @param {Target} t */
+export function claudeDesktopEntry({ url, key }) {
+  return {
+    command: "npx",
+    args: ["-y", "mcp-remote", url, "--header", `Authorization:\${${ENV_NAME}}`],
+    env: { [ENV_NAME]: `Bearer ${key}` },
+  };
+}
+
+/** @param {Target} t */
+export function cursorEntry({ url, key }) {
+  return { url, headers: { Authorization: `Bearer ${key}` } };
+}
+
+/**
+ * Returns a copy of `config` with our server set, every other server kept.
+ * @param {JsonObject | null | undefined} config
+ * @param {JsonObject} entry
+ */
+export function withServer(config, entry) {
+  const base = config && typeof config === "object" && !Array.isArray(config) ? config : {};
+  const servers = base.mcpServers && typeof base.mcpServers === "object" ? base.mcpServers : {};
+  return { ...base, mcpServers: { ...servers, [SERVER_NAME]: entry } };
+}
+
+/**
+ * @param {JsonObject | null | undefined} config
+ * @returns {{ config: JsonObject; removed: boolean }}
+ */
+export function withoutServer(config) {
+  const base = config && typeof config === "object" && !Array.isArray(config) ? config : {};
+  const servers = base.mcpServers && typeof base.mcpServers === "object" ? { ...base.mcpServers } : {};
+  const removed = SERVER_NAME in servers;
+  delete servers[SERVER_NAME];
+  return { config: { ...base, mcpServers: servers }, removed };
+}
+
+/**
+ * Reads a JSON config, tolerating a missing file. A file that exists but
+ * does not parse is an error: overwriting it could destroy other servers.
+ * @param {string} file
+ * @returns {JsonObject | null}
+ */
+export function readJson(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8");
+  if (text.trim() === "") return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${file} is not valid JSON. Fix or remove it, then run this again.`);
+  }
+}
+
+/**
+ * Writes JSON with a `.bak` of the previous contents next to it.
+ * @param {string} file
+ * @param {JsonObject} data
+ */
+export function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+
+/** @param {string} file */
+export function dirExists(file) {
+  try {
+    return fs.statSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "kontex-mcp",
+  "version": "0.1.0",
+  "description": "Connect Kontex to Claude Desktop, Claude Code, and Cursor with one command.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kontex-mcp": "bin/kontex-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gzariaga/kontex.git",
+    "directory": "packages/kontex-mcp"
+  },
+  "homepage": "https://www.kontex.so",
+  "keywords": [
+    "kontex",
+    "mcp",
+    "claude",
+    "cursor",
+    "customer-intelligence"
+  ],
+  "scripts": {
+    "check": "tsc -p tsconfig.json"
+  }
+}