komplian 0.4.5 → 0.4.7

package/komplian-localhost.mjs

@@ -1,22 +1,13 @@
 #!/usr/bin/env node
 /**
- * Komplian localhost — genera `.env.local` con secretos aleatorios (crypto) y arranca
- * api, app, web, admin, docs en paralelo (concurrently).
+ * Komplian localhost — genera `.env.local` completos a partir de cada proyecto `/.env.example`
+ * (misma estructura y comentarios) + secretos aleatorios (crypto). Arranca api, app, web, admin, docs.
  *
- * Seguridad: nada se commitea; secretos solo en disco local (.env*.local / .komplian/).
- * No imprime valores de claves.
+ * Seguridad: los `.env*` no van en el paquete npm `komplian` (solo *.mjs + JSON + README).
+ * No imprime secretos. Tras generar, muestra tabla de URLs locales (puertos fijos).
  *
- * Uso:
- *   npx komplian localhost --yes
- *   npx komplian localhost --yes --minimal          # solo app + web + docs (sin DB real)
- *   npx komplian localhost --env-only --force       # solo escribir env
- *
- * URLs de Neon (opcional, una o tres):
- *   KOMPLIAN_LOCALHOST_DATABASE_URL                 # misma para app/admin/web/api
- *   KOMPLIAN_LOCALHOST_APP_DATABASE_URL
- *   KOMPLIAN_LOCALHOST_ADMIN_DATABASE_URL
- *   KOMPLIAN_LOCALHOST_WEB_DATABASE_URL
- * O archivo (gitignored): komplian-localhost.secrets.env o .komplian/localhost-secrets.env
+ * Neon: KOMPLIAN_LOCALHOST_APP_DATABASE_URL, …_ADMIN_…, …_WEB_… o KOMPLIAN_LOCALHOST_SECRETS.env
+ * (plantilla en la raíz del monorepo: KOMPLIAN_LOCALHOST_SECRETS.env.example).
  */
 
 import { randomBytes } from "node:crypto";
@@ -72,6 +63,8 @@ function parseEnvFile(content) {
 
 function loadSecretsFromDisk(workspaceRoot) {
   const paths = [
+    join(workspaceRoot, "KOMPLIAN_LOCALHOST_SECRETS.env"),
+    join(workspaceRoot, ".komplian", "KOMPLIAN_LOCALHOST_SECRETS.env"),
     join(workspaceRoot, "komplian-localhost.secrets.env"),
     join(workspaceRoot, ".komplian", "localhost-secrets.env"),
   ];
@@ -153,120 +146,240 @@ function buildShared() {
 }
 
 function header(project) {
-  return `# Generated by komplian localhost — do not commit (${project})
-# Regenerate: npx komplian localhost --yes --force
+  return `# KOMPLIAN — generado por komplian localhost (no commitear) — ${project}
+# Regenerar: npx komplian localhost --yes --force
+# Los .env / .env.local no se publican en el paquete npm \`komplian\` (solo scripts/*.mjs).
 
 `;
 }
 
+/** Serializa valor para KEY= en .env (comillas si hace falta). */
+function formatEnvValue(val) {
+  if (val === undefined || val === null) return '""';
+  const s = String(val);
+  if (s === "") return '""';
+  if (/[\s#"']/.test(s) || s.includes("\n")) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+function collectKeysFromEnvContent(content) {
+  const keys = new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    keys.add(line.slice(0, eq).trim());
+  }
+  return keys;
+}
+
+/**
+ * Sustituye claves presentes en el contenido y añade al final las que faltan.
+ * Mantiene comentarios al final de línea (# ...).
+ */
+function applyOverridesToEnvContent(content, overrides) {
+  const present = collectKeysFromEnvContent(content);
+  const lines = content.split(/\r?\n/);
+  const out = lines.map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) return line;
+    const eq = line.indexOf("=");
+    if (eq === -1) return line;
+    const key = line.slice(0, eq).trim();
+    if (!Object.prototype.hasOwnProperty.call(overrides, key)) return line;
+    const rest = line.slice(eq + 1);
+    const hashIdx = rest.search(/\s+#/);
+    const suffix = hashIdx >= 0 ? rest.slice(hashIdx) : "";
+    return `${key}=${formatEnvValue(overrides[key])}${suffix}`;
+  });
+  const append = [];
+  for (const [key, val] of Object.entries(overrides)) {
+    if (!present.has(key)) append.push(`${key}=${formatEnvValue(val)}`);
+  }
+  const tail =
+    append.length > 0
+      ? `\n\n# --- KOMPLIAN localhost (claves que no estaban en .env.example) ---\n${append.join("\n")}`
+      : "";
+  return out.join("\n") + tail;
+}
+
+function buildAppOverrides(s, db, opts) {
+  const appUrl = db.app || PLACEHOLDER_DB;
+  const useNoDb = opts.minimal || String(appUrl).includes("placeholder");
+  /** @type {Record<string, string>} */
+  const o = {
+    DATABASE_URL: appUrl,
+    NEXTAUTH_SECRET: s.nextAuthSecret,
+    NEXTAUTH_URL: "http://localhost:3001",
+    CSRF_SECRET: s.csrfSecret,
+    NEXT_PUBLIC_APP_URL: "http://localhost:3001",
+    KOMPLIAN_API_URL: "http://localhost:4000",
+    KOMPLIAN_API_KEY: s.apiKey,
+    KOMPLIAN_INTERNAL_WEBHOOK_SECRET: s.internalWebhook,
+    ENCRYPTION_KEY: s.encryptionKey,
+    OPENAI_API_KEY: "",
+    MAILBOX_OAUTH_SECRET: s.nextAuthSecret,
+    NEXT_PUBLIC_API_URL: "http://localhost:4000",
+    AUTH_SECRET: s.nextAuthSecret,
+    TWO_FACTOR_ENCRYPTION_KEY: s.twoFactorEnc,
+    HASH_SECRET: s.hashSecret,
+  };
+  if (useNoDb) o.DEV_MODE_NO_DB = "true";
+  return o;
+}
+
+function buildApiOverrides(s, db) {
+  return {
+    APP_DATABASE_URL: db.apiApp || PLACEHOLDER_DB,
+    ADMIN_DATABASE_URL: db.apiAdmin || PLACEHOLDER_DB,
+    WEB_DATABASE_URL: db.apiWeb || PLACEHOLDER_DB,
+    API_KEY: s.apiKey,
+    ADMIN_API_KEY: s.adminApiKey,
+    KOMPLIAN_INTERNAL_WEBHOOK_SECRET: s.internalWebhook,
+    JWT_SECRET: s.jwtSecret,
+    ENCRYPTION_KEY: s.encryptionKey,
+    OPENAI_API_KEY: "",
+    RESEND_API_KEY: "",
+    CRON_SECRET: s.cronSecret,
+    APP_URL: "http://localhost:3001",
+    WEB_URL: "http://localhost:3003",
+    ADMIN_URL: "http://localhost:3002",
+    API_BASE_URL: "http://localhost:4000",
+    PORT: "4000",
+    NODE_ENV: "development",
+    LOG_LEVEL: "debug",
+  };
+}
+
+function buildWebOverrides(s, db) {
+  return {
+    DATABASE_URL: db.web || PLACEHOLDER_DB,
+    KOMPLIAN_API_URL: "http://localhost:4000",
+    KOMPLIAN_API_KEY: s.apiKey,
+  };
+}
+
+function buildAdminOverrides(s, db) {
+  return {
+    DATABASE_URL: db.admin || PLACEHOLDER_DB,
+    NEXTAUTH_URL: "http://localhost:3002",
+    NEXTAUTH_SECRET: s.nextAuthAdmin,
+    AUTH_SECRET: s.nextAuthAdmin,
+    API_URL: "http://localhost:4000",
+    ADMIN_API_KEY: s.adminApiKey,
+  };
+}
+
+function buildDocsOverrides() {
+  return {
+    NODE_ENV: "development",
+  };
+}
+
+function envFromOverridesOnly(overrides) {
+  return Object.entries(overrides)
+    .map(([k, v]) => `${k}=${formatEnvValue(v)}`)
+    .join("\n");
+}
+
 function writeAppEnv(root, s, db, opts) {
   const p = join(root, "app", ".env.local");
   if (existsSync(p) && !opts.force) return { path: p, skipped: true };
-  const useNoDb = opts.minimal || !db.app || db.app.includes("placeholder");
-  const lines = [
-    header("app"),
-    useNoDb ? "DEV_MODE_NO_DB=true" : "DEV_MODE_NO_DB=",
-    "",
-    `DATABASE_URL=${db.app || PLACEHOLDER_DB}`,
-    `NEXTAUTH_URL=http://localhost:3001`,
-    `NEXTAUTH_SECRET=${s.nextAuthSecret}`,
-    `AUTH_SECRET=${s.nextAuthSecret}`,
-    `CSRF_SECRET=${s.csrfSecret}`,
-    "",
-    `NEXT_PUBLIC_APP_URL=http://localhost:3001`,
-    `NEXT_PUBLIC_API_URL=http://localhost:4000`,
-    "",
-    `KOMPLIAN_API_URL=http://localhost:4000`,
-    `KOMPLIAN_API_KEY=${s.apiKey}`,
-    `KOMPLIAN_INTERNAL_WEBHOOK_SECRET=${s.internalWebhook}`,
-    "",
-    `ENCRYPTION_KEY=${s.encryptionKey}`,
-    `TWO_FACTOR_ENCRYPTION_KEY=${s.twoFactorEnc}`,
-    `HASH_SECRET=${s.hashSecret}`,
-    "",
-    "# Optional: OPENAI_API_KEY=  Stripe, Shopify, Google OAuth — ver app/.env.example",
-  ];
-  writeAtomic(p, lines.join("\n"));
+  const examplePath = join(root, "app", ".env.example");
+  const overrides = buildAppOverrides(s, db, opts);
+  let body;
+  if (existsSync(examplePath)) {
+    body = applyOverridesToEnvContent(readFileSync(examplePath, "utf8"), overrides);
+  } else {
+    body = envFromOverridesOnly(overrides);
+  }
+  writeAtomic(p, header("app") + body);
   return { path: p, skipped: false };
 }
 
 function writeApiEnv(root, s, db, opts) {
   const p = join(root, "api", ".env.local");
   if (existsSync(p) && !opts.force) return { path: p, skipped: true };
-  const appU = db.apiApp || PLACEHOLDER_DB;
-  const adminU = db.apiAdmin || PLACEHOLDER_DB;
-  const webU = db.apiWeb || PLACEHOLDER_DB;
-  const lines = [
-    header("api"),
-    `APP_DATABASE_URL=${appU}`,
-    `ADMIN_DATABASE_URL=${adminU}`,
-    `WEB_DATABASE_URL=${webU}`,
-    "",
-    `API_KEY=${s.apiKey}`,
-    `ADMIN_API_KEY=${s.adminApiKey}`,
-    `KOMPLIAN_INTERNAL_WEBHOOK_SECRET=${s.internalWebhook}`,
-    `JWT_SECRET=${s.jwtSecret}`,
-    `ENCRYPTION_KEY=${s.encryptionKey}`,
-    "",
-    "# OPENAI_API_KEY=  RESEND_API_KEY=  — ver api/.env.example",
-    "",
-    `CRON_SECRET=${s.cronSecret}`,
-    "",
-    `APP_URL=http://localhost:3001`,
-    `WEB_URL=http://localhost:3003`,
-    `ADMIN_URL=http://localhost:3002`,
-    `API_BASE_URL=http://localhost:4000`,
-    "",
-    `PORT=4000`,
-    `NODE_ENV=development`,
-    `LOG_LEVEL=debug`,
-  ];
-  writeAtomic(p, lines.join("\n"));
+  const examplePath = join(root, "api", ".env.example");
+  const overrides = buildApiOverrides(s, db);
+  let body;
+  if (existsSync(examplePath)) {
+    body = applyOverridesToEnvContent(readFileSync(examplePath, "utf8"), overrides);
+  } else {
+    body = envFromOverridesOnly(overrides);
+  }
+  writeAtomic(p, header("api") + body);
   return { path: p, skipped: false };
 }
 
 function writeWebEnv(root, s, db, opts) {
   const p = join(root, "web", ".env.local");
   if (existsSync(p) && !opts.force) return { path: p, skipped: true };
-  const lines = [
-    header("web"),
-    `DATABASE_URL=${db.web || PLACEHOLDER_DB}`,
-    `KOMPLIAN_API_URL=http://localhost:4000`,
-    `KOMPLIAN_API_KEY=${s.apiKey}`,
-    "",
-    "# GMAIL_USER= GMAIL_PASS= — opcional",
-  ];
-  writeAtomic(p, lines.join("\n"));
+  const examplePath = join(root, "web", ".env.example");
+  const overrides = buildWebOverrides(s, db);
+  let body;
+  if (existsSync(examplePath)) {
+    body = applyOverridesToEnvContent(readFileSync(examplePath, "utf8"), overrides);
+  } else {
+    body = envFromOverridesOnly(overrides);
+  }
+  writeAtomic(p, header("web") + body);
   return { path: p, skipped: false };
 }
 
 function writeAdminEnv(root, s, db, opts) {
   const p = join(root, "admin", ".env.local");
   if (existsSync(p) && !opts.force) return { path: p, skipped: true };
-  const lines = [
-    header("admin"),
-    `DATABASE_URL=${db.admin || PLACEHOLDER_DB}`,
-    `NEXTAUTH_URL=http://localhost:3002`,
-    `NEXTAUTH_SECRET=${s.nextAuthAdmin}`,
-    `AUTH_SECRET=${s.nextAuthAdmin}`,
-    `API_URL=http://localhost:4000`,
-    `ADMIN_API_KEY=${s.adminApiKey}`,
-  ];
-  writeAtomic(p, lines.join("\n"));
+  const examplePath = join(root, "admin", ".env.example");
+  const overrides = buildAdminOverrides(s, db);
+  let body;
+  if (existsSync(examplePath)) {
+    body = applyOverridesToEnvContent(readFileSync(examplePath, "utf8"), overrides);
+  } else {
+    body = envFromOverridesOnly(overrides);
+  }
+  writeAtomic(p, header("admin") + body);
   return { path: p, skipped: false };
 }
 
 function writeDocsEnv(root, opts) {
   const p = join(root, "docs", ".env.local");
   if (existsSync(p) && !opts.force) return { path: p, skipped: true };
-  const lines = [
-    header("docs"),
-    "# Vacío: docs no requiere secretos para next dev local",
-  ];
-  writeAtomic(p, lines.join("\n"));
+  const examplePath = join(root, "docs", ".env.example");
+  if (!existsSync(examplePath)) {
+    writeAtomic(
+      p,
+      `${header("docs")}# Sin variables obligatorias para next dev.\n`
+    );
+    return { path: p, skipped: false };
+  }
+  const overrides = buildDocsOverrides();
+  let content = readFileSync(examplePath, "utf8");
+  content = applyOverridesToEnvContent(content, overrides);
+  writeAtomic(p, header("docs") + content);
   return { path: p, skipped: false };
 }
 
+function printLocalUrls(minimal) {
+  log("");
+  log(`${c.bold}Local — abre en el navegador${c.reset}`);
+  if (!minimal) {
+    log(`  ${c.cyan}API${c.reset}   http://localhost:4000   ${c.dim}(/health)${c.reset}`);
+  }
+  log(`  ${c.cyan}App${c.reset}   http://localhost:3001`);
+  if (!minimal) {
+    log(`  ${c.cyan}Admin${c.reset} http://localhost:3002`);
+    log(`  ${c.cyan}Web${c.reset}   http://localhost:3003`);
+  } else {
+    log(`  ${c.cyan}Web${c.reset}   http://localhost:3003`);
+  }
+  log(`  ${c.cyan}Docs${c.reset}  http://localhost:3004`);
+  log("");
+}
+
 async function confirmOverwrite(yes) {
   if (yes) return true;
   const rl = createInterface({ input, output });
@@ -307,14 +420,14 @@ function parseLocalhostArgs(argv) {
 function usageLocalhost() {
   log(`Uso: npx komplian localhost [opciones] [carpeta-monorepo]`);
   log(``);
-  log(`  Genera .env.local por proyecto (secretos aleatorios) y ejecuta npm run dev en paralelo.`);
-  log(`  ${c.dim}Neon: export KOMPLIAN_LOCALHOST_DATABASE_URL=… o komplian-localhost.secrets.env${c.reset}`);
+  log(`  Genera .env.local completos (desde cada .env.example + secretos KOMPLIAN) y arranca todos los dev servers.`);
+  log(`  ${c.dim}Neon: KOMPLIAN_LOCALHOST_APP_DATABASE_URL, …_ADMIN_…, …_WEB_… o archivo KOMPLIAN_LOCALHOST_SECRETS.env${c.reset}`);
   log(``);
-  log(`  -y, --yes       Sin confirmación interactiva`);
-  log(`  --force         Sobrescribir .env.local aunque existan`);
-  log(`  --minimal       Solo app + web + docs (omitir api y admin)`);
-  log(`  --env-only      Solo escribir env, no arrancar servidores`);
-  log(`  -w, --workspace Ruta al monorepo (por defecto: cwd)`);
+  log(`  -y, --yes       Sin confirmación`);
+  log(`  --force         Regenerar .env.local`);
+  log(`  --minimal       Solo app + web + docs`);
+  log(`  --env-only      Solo escribir .env.local`);
+  log(`  -w, --workspace Ruta al monorepo`);
   log(`  -h, --help`);
 }
 
@@ -383,22 +496,24 @@ export async function runLocalhost(argv) {
   written.push(writeDocsEnv(workspaceRoot, opts));
 
   log("");
-  log(`${c.cyan}━━ .env.local ━━${c.reset} ${c.dim}(permisos 600)${c.reset}`);
+  log(`${c.cyan}━━ .env.local ━━${c.reset} ${c.dim}(600, no se publican en npm)${c.reset}`);
   for (const w of written) {
     const st = w.skipped ? `${c.dim}sin cambios${c.reset}` : `${c.green}ok${c.reset}`;
     log(`  ${st} ${w.path}`);
   }
 
+  printLocalUrls(opts.minimal);
+
   if (!db.hasReal && !opts.minimal) {
+    log(
+      `${c.yellow}⚠${c.reset} Sin Neon: exporta ${c.bold}KOMPLIAN_LOCALHOST_APP_DATABASE_URL${c.reset} / ${c.bold}ADMIN${c.reset} / ${c.bold}WEB${c.reset} o usa ${c.bold}KOMPLIAN_LOCALHOST_SECRETS.env${c.reset} (plantilla: KOMPLIAN_LOCALHOST_SECRETS.env.example).`
+    );
+    log(`${c.dim}   O ${c.bold}--minimal${c.reset} (solo app + web + docs).${c.reset}`);
     log("");
-    log(`${c.yellow}⚠${c.reset} Sin URLs Neon reales: api/admin/web usarán un placeholder local.`);
-    log(`  ${c.dim}Define KOMPLIAN_LOCALHOST_DATABASE_URL o komplian-localhost.secrets.env${c.reset}`);
-    log(`  ${c.dim}O usa ${c.bold}--minimal${c.reset} para solo app + web + docs.${c.reset}`);
   }
 
   if (opts.envOnly) {
-    log("");
-    log(`${c.green}✓${c.reset} Solo entorno. Arranca con: ${c.bold}npx komplian localhost --yes${c.reset}`);
+    log(`${c.green}✓${c.reset} Entorno listo. Arranca: ${c.bold}npx komplian localhost --yes${c.reset}`);
     return;
   }
 
@@ -423,9 +538,7 @@ export async function runLocalhost(argv) {
     return `npm run dev --prefix ${dir}`;
   });
 
-  log("");
-  log(`${c.cyan}━━ Servicios (${services.length}) ━━${c.reset} ${workspaceRoot}`);
-  log(`${c.dim}Ctrl+C detiene todos.${c.reset}`);
+  log(`${c.cyan}━━ Arranque (${services.length}) ━━${c.reset} ${c.dim}Ctrl+C detiene todo${c.reset}`);
   log("");
 
   // shell: false — con shell:true Node concatena args para /bin/sh -c y concurrently

package/komplian-mcp-tools.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * Komplian MCP — escribe `.cursor/mcp.json` con servidores MCP por stdio (prefijo KOMPLIAN-*)
+ * y genera `.cursor/KOMPLIAN_MCP_SETUP.md` (plugins de Cursor que no van en JSON).
+ *
+ * No incluye secretos: tokens vacíos; rellena en Cursor o vía KOMPLIAN_MCP_SECRETS.env (local, gitignored).
+ *
+ * Uso: npx komplian mcp-tools --yes
+ */
+
+import { mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const c = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+};
+
+function log(s = "") {
+  console.log(s);
+}
+
+/** Preset Komplian: solo claves KOMPLIAN-* para no pisar servidores del dev. */
+const KOMPLIAN_MCP_PRESET = {
+  mcpServers: {
+    "KOMPLIAN-github": {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-github"],
+      env: {
+        GITHUB_PERSONAL_ACCESS_TOKEN: "",
+      },
+    },
+    "KOMPLIAN-sentry": {
+      command: "npx",
+      args: ["-y", "@sentry/mcp-server@latest"],
+      env: {},
+    },
+    "KOMPLIAN-stripe": {
+      command: "npx",
+      args: ["-y", "@stripe/mcp"],
+      env: {
+        STRIPE_SECRET_KEY: "",
+      },
+    },
+  },
+};
+
+const SETUP_MD = `# KOMPLIAN — MCP en Cursor
+
+Este archivo lo genera \`npx komplian mcp-tools\`. **No commitees** tokens; \`.cursor/mcp.json\` puede llevar env vacíos que rellenas solo en local.
+
+## 1. Servidores en \`.cursor/mcp.json\` (stdio / npx)
+
+| ID | Qué es | Rellena |
+|----|--------|---------|
+| **KOMPLIAN-github** | GitHub API (issues, PRs) | \`GITHUB_PERSONAL_ACCESS_TOKEN\` en el bloque \`env\` del servidor (PAT con scopes repo/workflow según necesidad). El paquete npm está deprecado a favor del servidor oficial; si falla, sustituye por la config que indique [github/github-mcp-server](https://github.com/github/github-mcp-server). |
+| **KOMPLIAN-sentry** | Sentry (issues, trazas) | Primera vez: login por navegador (device code). **Komplian:** \`organizationSlug\` = \`komplian\`, \`regionUrl\` = \`https://de.sentry.io\`. Proyectos: \`komplian-api\`, \`komplian-app\`. |
+| **KOMPLIAN-stripe** | Stripe API | \`STRIPE_SECRET_KEY\` en \`env\` (mejor **Restricted key** / test en dev). Modo test vs live según [docs Stripe MCP](https://docs.stripe.com/mcp). |
+
+## 2. Solo en Cursor (plugins / integraciones)
+
+Estos **no** se instalan con npx en este JSON; actívalos en **Cursor → Settings → MCP** (o integraciones) e inicia sesión:
+
+| Integración | Uso en Komplian |
+|-------------|-----------------|
+| **Atlassian** (Jira + Confluence) | Site \`komplian.atlassian.net\`, proyecto Jira **KAPP**. Plugin \`plugin-atlassian-atlassian\` / \`user-mcp-atlassian\`. |
+| **Chrome DevTools** | Depuración del navegador (\`user-chrome-devtools\`). |
+
+## 3. Reinicio
+
+Tras editar \`mcp.json\`, **reinicia Cursor** (o recarga ventana) para cargar MCP.
+
+## 4. Referencia interna
+
+Ver \`.cursor/rules/mcp-integrations.mdc\` en el monorepo (org Sentry, Stripe, reglas KAPP).
+`;
+
+function findWorkspaceRoot(start) {
+  let dir = resolve(start);
+  for (let i = 0; i < 8; i++) {
+    if (
+      existsSync(join(dir, "api", "package.json")) &&
+      existsSync(join(dir, "app", "package.json"))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(start);
+}
+
+function mergeKomplianPreset(existing, preset, force) {
+  const base =
+    existing && typeof existing === "object" ? structuredClone(existing) : {};
+  if (!base.mcpServers || typeof base.mcpServers !== "object") {
+    base.mcpServers = {};
+  }
+  for (const [name, cfg] of Object.entries(preset.mcpServers)) {
+    if (!name.startsWith("KOMPLIAN-")) continue;
+    if (!force && base.mcpServers[name]) continue;
+    base.mcpServers[name] = structuredClone(cfg);
+  }
+  return base;
+}
+
+function parseMcpArgs(argv) {
+  const opts = {
+    yes: false,
+    force: false,
+    dryRun: false,
+    global: false,
+    help: false,
+    workspace: "",
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--force") opts.force = true;
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--global") opts.global = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--workspace" || a === "-w") opts.workspace = argv[++i] || "";
+    else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Opción desconocida: ${a}`);
+      process.exit(1);
+    } else rest.push(a);
+  }
+  if (rest[0]) opts.workspace = rest[0];
+  return opts;
+}
+
+function usageMcpTools() {
+  log(`Uso: npx komplian mcp-tools [opciones] [carpeta-monorepo]`);
+  log(``);
+  log(`  Añade servidores MCP KOMPLIAN-* en .cursor/mcp.json (GitHub, Sentry, Stripe)`);
+  log(`  y genera .cursor/KOMPLIAN_MCP_SETUP.md (Atlassian + Chrome DevTools = solo Cursor).`);
+  log(``);
+  log(`  ${c.dim}Secretos: vacíos en JSON; no se publican en el paquete npm komplian.${c.reset}`);
+  log(``);
+  log(`  -y, --yes       Sin confirmación`);
+  log(`  --force         Sobreescribe entradas KOMPLIAN-* existentes`);
+  log(`  --dry-run       Imprime JSON sin escribir`);
+  log(`  --global        Fusiona en ~/.cursor/mcp.json (toda la máquina)`);
+  log(`  -w, --workspace Raíz del monorepo (por defecto: cwd)`);
+  log(`  -h, --help`);
+}
+
+async function confirmForceOverwrite(yes) {
+  if (yes) return true;
+  const rl = createInterface({ input, output });
+  const ans = await rl.question(
+    `\n${c.bold}¿Sobrescribir entradas KOMPLIAN-* existentes? [y/N]${c.reset} `
+  );
+  rl.close();
+  return /^y(es)?$/i.test((ans || "").trim());
+}
+
+export async function runMcpTools(argv) {
+  const opts = parseMcpArgs(argv);
+  if (opts.help) {
+    usageMcpTools();
+    return;
+  }
+
+  const workspaceRoot = opts.workspace.trim()
+    ? resolve(opts.workspace.replace(/^~(?=$|[/\\])/, homedir()))
+    : findWorkspaceRoot(process.cwd());
+
+  const cursorDir = opts.global
+    ? join(homedir(), ".cursor")
+    : join(workspaceRoot, ".cursor");
+  const mcpPath = join(cursorDir, "mcp.json");
+  const setupPath = join(cursorDir, "KOMPLIAN_MCP_SETUP.md");
+
+  let existing = {};
+  if (existsSync(mcpPath)) {
+    try {
+      existing = JSON.parse(readFileSync(mcpPath, "utf8"));
+    } catch {
+      log(`${c.red}✗${c.reset} JSON inválido: ${mcpPath}`);
+      process.exit(1);
+    }
+  }
+
+  const hadKomplian = Object.keys(existing.mcpServers || {}).some((k) =>
+    k.startsWith("KOMPLIAN-")
+  );
+  if (opts.force && hadKomplian && !opts.yes) {
+    const ok = await confirmForceOverwrite(opts.yes);
+    if (!ok) {
+      log(`${c.yellow}○${c.reset} Cancelado.`);
+      return;
+    }
+  }
+
+  const merged = mergeKomplianPreset(existing, KOMPLIAN_MCP_PRESET, opts.force);
+  const json = JSON.stringify(merged, null, 2);
+
+  if (opts.dryRun) {
+    log(`${c.cyan}━━ dry-run ━━${c.reset} ${mcpPath}`);
+    log(json);
+    log("");
+    log(SETUP_MD);
+    return;
+  }
+
+  mkdirSync(cursorDir, { recursive: true });
+  const prevStr = existsSync(mcpPath) ? readFileSync(mcpPath, "utf8") : "";
+  const changed = prevStr.trim() !== json.trim();
+  if (changed) {
+    writeFileSync(mcpPath, json + "\n", "utf8");
+  }
+  writeFileSync(setupPath, SETUP_MD, "utf8");
+
+  log("");
+  const mcpMark = changed ? `${c.green}✓${c.reset}` : `${c.dim}○${c.reset}`;
+  const mcpNote = changed ? "" : ` ${c.dim}(sin cambios)${c.reset}`;
+  log(`${mcpMark} ${c.bold}mcp.json${c.reset}  ${c.dim}${mcpPath}${c.reset}${mcpNote}`);
+  log(`${c.green}✓${c.reset} ${c.bold}KOMPLIAN_MCP_SETUP.md${c.reset}  ${c.dim}${setupPath}${c.reset}`);
+  log("");
+  log(`${c.bold}Siguiente${c.reset}`);
+  log(`  1. Rellena tokens vacíos en Cursor (Settings → MCP) o edita ${c.bold}mcp.json${c.reset} en local.`);
+  log(`  2. Activa en Cursor: ${c.dim}Atlassian + Chrome DevTools${c.reset} (ver guía arriba).`);
+  log(`  3. Reinicia Cursor.`);
+  log("");
+  log(`${c.dim}Paquete npm komplian solo incluye *.mjs — nunca sube tu mcp.json.${c.reset}`);
+}

package/komplian-onboard.mjs

@@ -394,11 +394,12 @@ function npmInstallEach(workspace) {
 }
 
 function usage() {
-  log(`Uso: komplian onboard [opciones] [carpeta]  |  komplian postman [opciones]  |  komplian localhost [opciones]`);
+  log(`Uso: komplian onboard | postman | localhost | mcp-tools [opciones]`);
   log(`  npx komplian onboard --yes`);
   log(`  npx komplian postman login   ${c.dim}(una vez · guarda API key)${c.reset}`);
   log(`  npx komplian postman --yes    ${c.dim}(email @komplian.com)${c.reset}`);
   log(`  npx komplian localhost --yes  ${c.dim}(env local + api app web admin docs)${c.reset}`);
+  log(`  npx komplian mcp-tools --yes  ${c.dim}(.cursor/mcp.json + guía MCP Komplian)${c.reset}`);
   log(``);
   log(`  Antes (una vez): gh auth login -h github.com -s repo -s read:org -w`);
   log(`  Requisitos: Node 18+, git, GitHub CLI (gh)`);
@@ -492,6 +493,11 @@ async function main() {
     await runLocalhost(rawArgv.slice(1));
     return;
   }
+  if (rawArgv[0] === "mcp-tools") {
+    const { runMcpTools } = await import("./komplian-mcp-tools.mjs");
+    await runMcpTools(rawArgv.slice(1));
+    return;
+  }
 
   const configPath = join(__dirname, "komplian-team-repos.json");
   const { argv, fromOnboardSubcommand } = normalizeArgv(rawArgv);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "komplian",
-  "version": "0.4.5",
-  "description": "Komplian developer workspace: GitHub clone (onboard) + Postman collection/environments (postman). Node 18+.",
+  "version": "0.4.7",
+  "description": "Komplian CLI: onboard, Postman, localhost, mcp-tools (Cursor MCP). Node 18+. Published tarball has no .env / secrets.",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -13,6 +13,7 @@
     "komplian-onboard.mjs",
     "komplian-postman.mjs",
     "komplian-localhost.mjs",
+    "komplian-mcp-tools.mjs",
     "komplian-team-repos.json",
     "README.md"
   ],
@@ -20,7 +21,7 @@
     "access": "public"
   },
   "scripts": {
-    "prepublishOnly": "node --check komplian-onboard.mjs && node --check komplian-postman.mjs && node --check komplian-localhost.mjs"
+    "prepublishOnly": "node --check komplian-onboard.mjs && node --check komplian-postman.mjs && node --check komplian-localhost.mjs && node --check komplian-mcp-tools.mjs"
   },
   "keywords": [
     "komplian",