create-snipara 1.3.22 → 1.3.23

package/README.md

@@ -197,6 +197,19 @@ Writes `.snipara/companion/doctor.json` and validates:
 - Snipara Sandbox CLI presence
 - environment files
 - hosted MCP reachability when a live API key is available
+- exposed Hosted MCP tool aliases (`snipara_*`, with `rlm_*` reported as legacy)
+- client-specific loading gaps that the terminal cannot prove
+
+For Claude-specific support, run:
+
+```bash
+npx create-snipara doctor --client claude
+```
+
+This separates "Snipara config was written" from "Claude actually loaded the MCP
+server." If Claude uses its cloud/UI MCP configuration instead of local files,
+the doctor output points the user to Claude **Settings -> MCP** instead of
+repeating local file edits.
 
 ### Repair local setup
 

package/dist/index.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "create-snipara",
-  version: "1.3.22",
+  version: "1.3.23",
   description: "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   main: "dist/index.js",
   type: "module",
@@ -174,7 +174,10 @@ function buildProgram() {
     printBanner();
     await runInit(options);
   });
-  program.command("doctor").description("Inspect the current project and write a validation report").option("--json", "Print the report as JSON").action(async (options) => {
+  program.command("doctor").description("Inspect the current project and write a validation report").option(
+    "--client <client>",
+    "Run client-specific diagnostics: claude, claude-code, claude-desktop, cursor, codex, etc."
+  ).option("--skip-npm-check", "Skip npm latest-version freshness check").option("--json", "Print the report as JSON").action(async (options) => {
     printBanner();
     await runDoctor(options);
   });
@@ -291,8 +294,16 @@ async function runInit(options) {
   }
 }
 async function runDoctor(options) {
-  const answers = loadExistingAnswers(options);
-  const report = await runValidation(answers, true);
+  const requestedClient = normalizeClientOption(options.client);
+  const existingAnswers = loadExistingAnswers(options);
+  const answers = {
+    ...existingAnswers,
+    aiClient: requestedClient || existingAnswers.aiClient
+  };
+  const report = await runValidation(answers, true, {
+    client: requestedClient || answers.aiClient,
+    includeNpmFreshness: !options.skipNpmCheck
+  });
   writeDoctorReport(report);
   if (options.json) {
     console.log(JSON.stringify({ detection: detectEnvironment(), validation: report }, null, 2));
@@ -631,6 +642,34 @@ function resolveRequestedProfile(options) {
 function isInstallProfile(value) {
   return ["hosted-only", "hosted-companion", "full-stack", "runtime-only"].includes(value);
 }
+function normalizeClientOption(value) {
+  if (!value) {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  const aliases = {
+    claude: "claude-code",
+    "claude-code": "claude-code",
+    claude_code: "claude-code",
+    claudecli: "claude-code",
+    "claude-cli": "claude-code",
+    "claude-desktop": "claude-desktop",
+    claude_desktop: "claude-desktop",
+    cursor: "cursor",
+    windsurf: "windsurf",
+    codex: "codex",
+    gemini: "gemini",
+    chatgpt: "chatgpt",
+    vscode: "vscode",
+    continue: "continue",
+    other: "other"
+  };
+  const client = aliases[normalized];
+  if (!client) {
+    throw new Error(`Unknown client '${value}'. Use claude, claude-code, cursor, codex, or other.`);
+  }
+  return client;
+}
 function installProfileChoices() {
   return [
     {
@@ -2044,15 +2083,143 @@ function buildGitHubAutomationUrl(answers) {
   }
   return url.toString();
 }
-async function runValidation(answers, includeHostedCheck) {
+function getClaudeClientChecks(answers, detection) {
+  const checks = [];
+  const claudePaths = getClaudeConfigPaths();
+  const projectConfig = readJsonFile(path.join(process.cwd(), ".mcp.json"));
+  const codeSettings = readJsonFile(claudePaths.codeSettingsPath);
+  const desktopConfig = readJsonFile(claudePaths.desktopConfigPath);
+  const projectHasSnipara = containsSniparaMcpReference(projectConfig);
+  const codeSettingsHasSnipara = containsSniparaMcpReference(codeSettings);
+  const desktopHasSnipara = containsSniparaMcpReference(desktopConfig);
+  checks.push({
+    name: "claude_project_config",
+    status: projectHasSnipara ? "pass" : "warn",
+    detail: projectHasSnipara ? "Project .mcp.json contains a Snipara Hosted MCP server" : "Project .mcp.json does not contain a Snipara Hosted MCP server"
+  });
+  if (answers.aiClient === "claude-code") {
+    checks.push({
+      name: "claude_code_settings",
+      status: detection.files.claudeSettings ? codeSettingsHasSnipara ? "pass" : "warn" : "warn",
+      detail: detection.files.claudeSettings ? codeSettingsHasSnipara ? "~/.claude/settings.json references Snipara" : "~/.claude/settings.json exists but no Snipara MCP server was found" : "~/.claude/settings.json not found; Claude may require Settings -> MCP UI setup"
+    });
+  }
+  if (answers.aiClient === "claude-desktop") {
+    checks.push({
+      name: "claude_desktop_config",
+      status: detection.files.claudeDesktopConfig ? desktopHasSnipara ? "pass" : "warn" : "warn",
+      detail: detection.files.claudeDesktopConfig ? desktopHasSnipara ? "Claude Desktop config references Snipara" : "Claude Desktop config exists but no Snipara MCP server was found" : "Claude Desktop config not found"
+    });
+  }
+  checks.push({
+    name: "claude_tools_visible",
+    status: "warn",
+    detail: "This terminal cannot prove Claude loaded the MCP server; confirm Snipara tools in Claude Settings -> MCP or ToolSearch after restart"
+  });
+  return checks;
+}
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function containsSniparaMcpReference(value) {
+  if (value === null || value === void 0) {
+    return false;
+  }
+  if (typeof value === "string") {
+    return value.includes("api.snipara.com/mcp") || value.includes("snipara-mcp");
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => containsSniparaMcpReference(item));
+  }
+  if (typeof value === "object") {
+    const record = value;
+    const mcpServers = record.mcpServers;
+    if (mcpServers && typeof mcpServers === "object" && "snipara" in mcpServers) {
+      return true;
+    }
+    return Object.values(record).some((nested) => containsSniparaMcpReference(nested));
+  }
+  return false;
+}
+function getCreateSniparaPackageFreshnessCheck() {
+  if (!commandExists("npm")) {
+    return {
+      name: "create_snipara_npm_version",
+      status: "warn",
+      detail: "npm not found; could not compare local create-snipara with npm latest"
+    };
+  }
+  try {
+    const raw = execSync("npm view create-snipara version --json", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: "/bin/sh",
+      timeout: 4e3
+    }).trim();
+    const latest = raw.replace(/^"|"$/g, "");
+    const comparison = compareSemver(VERSION, latest);
+    if (comparison === 0) {
+      return {
+        name: "create_snipara_npm_version",
+        status: "pass",
+        detail: `Local package version ${VERSION} matches npm latest`
+      };
+    }
+    if (comparison > 0) {
+      return {
+        name: "create_snipara_npm_version",
+        status: "warn",
+        detail: `Local package version ${VERSION} is newer than npm latest ${latest}; publish may be pending`
+      };
+    }
+    return {
+      name: "create_snipara_npm_version",
+      status: "warn",
+      detail: `npm latest is ${latest}; rerun with npx create-snipara@latest if this local copy is older`
+    };
+  } catch {
+    return {
+      name: "create_snipara_npm_version",
+      status: "warn",
+      detail: "Could not reach npm to compare create-snipara latest version"
+    };
+  }
+}
+function compareSemver(left, right) {
+  const leftParts = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (leftParts[index] || 0) - (rightParts[index] || 0);
+    if (diff !== 0) {
+      return diff > 0 ? 1 : -1;
+    }
+  }
+  return 0;
+}
+async function runValidation(answers, includeHostedCheck, options = {}) {
   console.log(chalk.bold("\n\u{1FA7A} Running Validation\n"));
   const checks = [];
   const detection = detectEnvironment();
+  const targetClient = options.client || answers.aiClient;
+  const effectiveAnswers = { ...answers, aiClient: targetClient };
   checks.push({
     name: "project_slug",
     status: answers.projectSlug ? "pass" : "fail",
     detail: answers.projectSlug || "Project slug missing"
   });
+  checks.push({
+    name: "target_client",
+    status: "pass",
+    detail: getClientDisplayName(targetClient)
+  });
   checks.push({
     name: "mcp_config",
     status: detection.files.mcpConfig ? "pass" : "warn",
@@ -2090,9 +2257,15 @@ async function runValidation(answers, includeHostedCheck) {
   });
   checks.push({
     name: "hooks",
-    status: answers.installHooks && answers.aiClient === "claude-code" ? detection.files.claudeDir ? "pass" : "warn" : "pass",
-    detail: answers.installHooks && answers.aiClient === "claude-code" ? detection.files.claudeDir ? "~/.claude detected" : "~/.claude missing" : "Hooks not requested"
+    status: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeDir ? "pass" : "warn" : "pass",
+    detail: answers.installHooks && targetClient === "claude-code" ? detection.files.claudeDir ? "~/.claude detected" : "~/.claude missing" : "Hooks not requested"
   });
+  if (targetClient === "claude-code" || targetClient === "claude-desktop") {
+    checks.push(...getClaudeClientChecks(effectiveAnswers, detection));
+  }
+  if (options.includeNpmFreshness) {
+    checks.push(getCreateSniparaPackageFreshnessCheck());
+  }
   const githubRepo = answers.githubRepo || detectGitRepository();
   checks.push({
     name: "github_answer_packs",
@@ -2125,11 +2298,12 @@ function writeDoctorReport(report) {
   console.log(chalk.green("   \u2713 Wrote .snipara/companion/doctor.json"));
 }
 function printDoctorReport(detection, report) {
+  const targetClient = report.checks.find((check) => check.name === "target_client")?.detail || detection.aiClient;
   console.log(chalk.bold("\n\u{1FA7A} Snipara Doctor\n"));
   console.log(
     `   Project slug: ${detection.existingConfig.slug || detection.projectSlug || "unknown"}`
   );
-  console.log(`   AI client: ${detection.aiClient}`);
+  console.log(`   AI client: ${targetClient}`);
   console.log(`   In git repo: ${detection.inGitRepo ? "yes" : "no"}`);
   console.log(`   Profile: ${report.profile}`);
   console.log("");
@@ -2164,22 +2338,31 @@ async function testHostedConnection(answers) {
       ];
     }
     spinner.succeed("Connected to Snipara Hosted MCP.");
+    const toolNames = extractMcpToolNames(toolsResponse.data);
+    const hasSniparaTools = toolNames.some((name) => name.startsWith("snipara_"));
+    const hasLegacyTools = toolNames.some((name) => name.startsWith("rlm_"));
     const checks = [
       {
         name: "hosted_connection",
         status: "pass",
         detail: "tools/list succeeded"
+      },
+      {
+        name: "hosted_tool_aliases",
+        status: hasSniparaTools ? "pass" : hasLegacyTools ? "warn" : "warn",
+        detail: hasSniparaTools ? "snipara_* tools are exposed by Hosted MCP" : hasLegacyTools ? "Only legacy rlm_* tool aliases were detected; Hosted MCP is usable but naming is stale" : "tools/list succeeded, but expected snipara_* tools were not detected"
       }
     ];
+    const settingsTool = hasSniparaTools ? "snipara_settings" : hasLegacyTools ? "rlm_settings" : "snipara_settings";
     const settingsResponse = await callHostedMcp(answers, "tools/call", {
-      name: "snipara_settings",
+      name: settingsTool,
       arguments: {}
     });
     if (settingsResponse.ok && !settingsResponse.data.error) {
       checks.push({
         name: "hosted_settings",
         status: "pass",
-        detail: "snipara_settings tool call succeeded"
+        detail: `${settingsTool} tool call succeeded`
       });
     } else {
       checks.push({
@@ -2200,6 +2383,15 @@ async function testHostedConnection(answers) {
     ];
   }
 }
+function extractMcpToolNames(data) {
+  const tools = data.result?.tools;
+  if (!Array.isArray(tools)) {
+    return [];
+  }
+  return tools.map(
+    (tool) => tool && typeof tool === "object" && "name" in tool ? String(tool.name || "") : ""
+  ).filter(Boolean);
+}
 async function callHostedMcp(answers, method, params) {
   const response = await fetch(`${API_URL}/mcp/${answers.projectSlug}`, {
     method: "POST",
@@ -2251,6 +2443,39 @@ function describeJsonRpcError(data) {
   const code = data.error.code !== void 0 ? ` ${data.error.code}` : "";
   return `JSON-RPC error${code}: ${data.error.message || "unknown error"}`;
 }
+function getCheck(report, name) {
+  return report.checks.find((check) => check.name === name);
+}
+function formatCheckStatus(check) {
+  if (!check) {
+    return "not checked";
+  }
+  if (check.status === "pass") {
+    return `OK - ${check.detail}`;
+  }
+  if (check.status === "fail") {
+    return `FAILED - ${check.detail}`;
+  }
+  return `NEEDS ATTENTION - ${check.detail}`;
+}
+function printSetupVerdict(answers, report) {
+  const hostedConnection = getCheck(report, "hosted_connection");
+  const toolAliases = getCheck(report, "hosted_tool_aliases");
+  const claudeTools = getCheck(report, "claude_tools_visible");
+  console.log(chalk.bold("\nSetup verdict:\n"));
+  console.log(`   Config written: ${answers.profile !== "runtime-only" ? "OK" : "not requested"}`);
+  console.log(`   Hosted MCP: ${formatCheckStatus(hostedConnection)}`);
+  if (toolAliases) {
+    console.log(`   Tool aliases: ${formatCheckStatus(toolAliases)}`);
+  }
+  if (answers.aiClient === "claude-code" || answers.aiClient === "claude-desktop") {
+    console.log(
+      `   Claude loaded MCP: ${claudeTools ? formatCheckStatus(claudeTools) : "not verified"}`
+    );
+  } else {
+    console.log("   AI client loaded MCP: not verifiable from this terminal");
+  }
+}
 function printSuccess(answers, report) {
   console.log(
     chalk.green(`
@@ -2263,6 +2488,7 @@ function printSuccess(answers, report) {
   );
   console.log(chalk.bold("Installed profile:\n"));
   console.log(`   ${chalk.green("\u2713")} ${answers.profile}`);
+  printSetupVerdict(answers, report);
   console.log(chalk.bold("\nWhat was installed:\n"));
   if (answers.installMcp) {
     console.log(
@@ -2300,6 +2526,20 @@ function printSuccess(answers, report) {
     nextStep += 1;
   };
   printNextStep("Restart your AI client if you created or changed hosted MCP config.");
+  if (answers.aiClient === "claude-code") {
+    printNextStep(
+      "For Claude Code, confirm Snipara appears in Settings -> MCP or ToolSearch; local files alone do not prove Claude loaded the server."
+    );
+    printNextStep("If Snipara tools are missing, run: npx create-snipara doctor --client claude");
+  }
+  if (answers.aiClient === "claude-desktop") {
+    printNextStep(
+      "For Claude Desktop, confirm the Snipara server appears in the desktop MCP settings after restart."
+    );
+    printNextStep(
+      "If Snipara tools are missing, run: npx create-snipara doctor --client claude-desktop"
+    );
+  }
   if (answers.aiClient === "codex") {
     printNextStep(
       "For Codex, merge .snipara/templates/codex-config.toml into ~/.codex/config.toml if the app does not read project .codex/config.toml."
@@ -2365,8 +2605,16 @@ function commandExists(command) {
     return false;
   }
 }
+function getClaudeConfigPaths() {
+  const desktopDir = process.platform === "darwin" ? path.join(homedir(), "Library", "Application Support", "Claude") : process.platform === "win32" ? path.join(homedir(), "AppData", "Roaming", "Claude") : path.join(homedir(), ".config", "claude");
+  return {
+    codeSettingsPath: path.join(homedir(), ".claude", "settings.json"),
+    desktopConfigPath: path.join(desktopDir, "claude_desktop_config.json")
+  };
+}
 function detectEnvironment() {
   const existingConfig = getExistingConfig();
+  const claudePaths = getClaudeConfigPaths();
   return {
     cwd: process.cwd(),
     projectSlug: detectProjectSlug(),
@@ -2382,6 +2630,8 @@ function detectEnvironment() {
       codexConfig: fs.existsSync(path.join(process.cwd(), ".codex", "config.toml")),
       cursorRule: fs.existsSync(path.join(process.cwd(), ".cursor", "rules", "snipara.mdc")),
       claudeDir: fs.existsSync(path.join(homedir(), ".claude")),
+      claudeSettings: fs.existsSync(claudePaths.codeSettingsPath),
+      claudeDesktopConfig: fs.existsSync(claudePaths.desktopConfigPath),
       cursorDir: fs.existsSync(path.join(homedir(), ".cursor")),
       sniparaCompanionPack: fs.existsSync(path.join(process.cwd(), ".snipara", "companion")),
       sniparaTemplates: fs.existsSync(path.join(process.cwd(), ".snipara", "templates"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snipara",
-  "version": "1.3.22",
+  "version": "1.3.23",
   "description": "Onboard Snipara Hosted MCP Context + Memory with auth, companion workflows, and optional Snipara Sandbox",
   "main": "dist/index.js",
   "type": "module",