@betterness/cli 1.2.2 → 1.3.1

package/README.md

@@ -172,6 +172,30 @@ betterness workflow daily-brief       # Full health snapshot
 betterness workflow next-actions      # AI-driven recommendations
 ```
 
+### MCP Integration
+
+One-command setup for the [Betterness MCP server](https://www.betterness.ai/mcp) in your AI client:
+
+```bash
+# Install into Claude Desktop, Claude Code, Cursor, or Windsurf
+betterness mcp install claude
+betterness mcp install claude-code
+betterness mcp install claude-code --scope project    # project-level .mcp.json
+betterness mcp install cursor
+betterness mcp install windsurf
+
+# Preview without writing
+betterness mcp install claude --dry-run
+
+# Check status across all clients
+betterness mcp status
+
+# Remove
+betterness mcp uninstall claude
+```
+
+The install command reads your stored credentials, merges the MCP config into the client's config file (preserving existing entries), and creates a `.bak` backup.
+
 ### Schema Discovery
 
 ```bash
@@ -189,6 +213,7 @@ The CLI is designed to be consumed by AI agents. Key features:
 - `betterness schema` for runtime capability discovery
 - `--quiet` mode for exit-code-only checks
 - `--dry-run` on destructive commands for safe planning
+- `betterness mcp install <client>` for one-command MCP setup
 
 ### Skills
 
@@ -211,6 +236,8 @@ Agent skills teach your AI coding agent the Betterness API surface — endpoints
 | [betterness-purchases](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-purchases) | Purchases and Stripe checkout |
 | [betterness-smart-listings](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-smart-listings) | Wellness provider search |
 | [betterness-workflow](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-workflow) | Composite commands (daily brief, next actions) |
+| [betterness-health-profile](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-health-profile) | Health profile questionnaire management |
+| [betterness-mcp](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-mcp) | MCP server integration for AI clients |
 
 **Persona skills:**
 

package/dist/index.js

@@ -408,7 +408,7 @@ var ApiClient = class {
           headers: {
             "Authorization": `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
-            "User-Agent": `betterness-cli/${"1.2.2"}`,
+            "User-Agent": `betterness-cli/${"1.3.1"}`,
             "Accept": "application/json"
           },
           body: body ? JSON.stringify(body) : void 0,
@@ -456,9 +456,9 @@ var ApiClient = class {
     return this.unwrap(raw, schema);
   }
   async upload(path, filePath, fieldName = "file", schema) {
-    const { readFileSync: readFileSync3 } = await import("fs");
+    const { readFileSync: readFileSync4 } = await import("fs");
     const { basename, extname } = await import("path");
-    const buffer = readFileSync3(filePath);
+    const buffer = readFileSync4(filePath);
     const fileName = basename(filePath);
     const ext = extname(filePath).toLowerCase();
     const mimeType = ext === ".pdf" ? "application/pdf" : "application/octet-stream";
@@ -472,7 +472,7 @@ var ApiClient = class {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${this.apiKey}`,
-          "User-Agent": `betterness-cli/${"1.2.2"}`,
+          "User-Agent": `betterness-cli/${"1.3.1"}`,
           "Accept": "application/json"
         },
         body: formData,
@@ -1661,10 +1661,10 @@ function registerLabResultsCommands(program2) {
   });
   labResults.command("upload").description("Upload a lab result PDF for processing").requiredOption("--file <path>", "Path to the PDF file").action(async (opts, cmd) => {
     try {
-      const { existsSync: existsSync4 } = await import("fs");
+      const { existsSync: existsSync5 } = await import("fs");
       const { resolve } = await import("path");
       const filePath = resolve(opts.file);
-      if (!existsSync4(filePath)) {
+      if (!existsSync5(filePath)) {
         console.error(`File not found: ${filePath}`);
         process.exit(1);
       }
@@ -2141,7 +2141,7 @@ function registerDebugCommands(program2) {
     const parentOpts = cmd.optsWithGlobals();
     const authSource = parentOpts.apiKey ? "--api-key flag" : envKey ? "BETTERNESS_API_KEY env" : tokens && !isTokenExpired(tokens) ? "OAuth tokens (~/.betterness/tokens.json)" : stored ? "API key (~/.betterness/credentials.json)" : "none";
     const config = {
-      version: "1.2.2",
+      version: "1.3.1",
       apiUrl: "https://api.betterness.ai",
       auth0Domain: "betterness.us.auth0.com",
       auth0ClientId: "g4lqYHRQb2QMgdRKIlKwoTJl6eu41pWn",
@@ -2193,7 +2193,7 @@ function registerHealthProfileCommands(program2) {
   hp.command("schema").description("List all sections and question IDs available in the health profile").option("--section <acronym>", "Show questions for a specific section only").action(async (opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const schema = await client.get(
         "/api/v1/copilot-config/schema",
         void 0,
@@ -2230,7 +2230,7 @@ function registerHealthProfileCommands(program2) {
   hp.command("get").description("Retrieve the full health profile (all answered questions as a flat map)").action(async (_, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const user = await client.get(
         "/api/betterness-user/detail"
       );
@@ -2247,7 +2247,7 @@ function registerHealthProfileCommands(program2) {
   hp.command("get-section").description("Retrieve health profile answers for a specific section").requiredOption("--section <acronym>", "Section acronym (e.g. HWP, DMH, DA)").action(async (opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const user = await client.get(
         "/api/betterness-user/detail"
       );
@@ -2294,7 +2294,7 @@ function registerHealthProfileCommands(program2) {
         return;
       }
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const user = await client.get(
         "/api/betterness-user/detail"
       );
@@ -2334,7 +2334,7 @@ function registerHealthProfileCommands(program2) {
         return;
       }
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const user = await client.get(
         "/api/betterness-user/detail"
       );
@@ -2349,7 +2349,7 @@ function registerHealthProfileCommands(program2) {
   hp.command("summary").description("Human-readable summary of answered health profile questions").option("--section <acronym>", "Summarize a specific section only").action(async (opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
-      const client = new ApiClient(globalOpts.apiKey);
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
       const [schema, user] = await Promise.all([
         client.get("/api/v1/copilot-config/schema", void 0, healthProfileSchemaSchema),
         client.get("/api/betterness-user/detail")
@@ -2447,10 +2447,230 @@ function formatAnswerValue(value) {
   return value;
 }
 
+// src/commands/mcp.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3, copyFileSync } from "fs";
+import { join as join4, dirname } from "path";
+import { homedir as homedir4, platform } from "os";
+var CLIENTS = {
+  claude: {
+    name: "Claude Desktop",
+    supportsScope: false,
+    configPath: () => {
+      if (platform() === "darwin") {
+        return join4(homedir4(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      }
+      return join4(homedir4(), ".config", "Claude", "claude_desktop_config.json");
+    }
+  },
+  "claude-code": {
+    name: "Claude Code",
+    supportsScope: true,
+    configPath: (scope) => {
+      if (scope === "project") {
+        return join4(process.cwd(), ".mcp.json");
+      }
+      return join4(homedir4(), ".claude", "settings.json");
+    }
+  },
+  cursor: {
+    name: "Cursor",
+    supportsScope: false,
+    configPath: () => join4(process.cwd(), ".cursor", "mcp.json")
+  },
+  windsurf: {
+    name: "Windsurf",
+    supportsScope: false,
+    configPath: () => join4(homedir4(), ".codeium", "windsurf", "mcp_config.json")
+  }
+};
+var VALID_CLIENTS = Object.keys(CLIENTS).join(", ");
+function validateClient(clientArg) {
+  if (!(clientArg in CLIENTS)) {
+    throw new CliError(
+      `Unknown client "${clientArg}". Supported clients: ${VALID_CLIENTS}`,
+      "INVALID_CLIENT"
+    );
+  }
+  return clientArg;
+}
+function getMcpUrl() {
+  const base = "https://api.betterness.ai";
+  if (!base) {
+    throw new CliError(
+      "No API URL configured. This is a build error \u2014 BETTERNESS_API_URL should be baked in at build time.",
+      "CONFIG_MISSING"
+    );
+  }
+  return `${base.replace(/\/$/, "")}/mcp`;
+}
+function buildMcpEntry(apiKey) {
+  return {
+    command: "npx",
+    args: ["-y", "mcp-remote", getMcpUrl(), "--header", `Authorization: Bearer ${apiKey}`]
+  };
+}
+function readConfigFile(filePath) {
+  if (!existsSync4(filePath)) {
+    return {};
+  }
+  try {
+    const content = readFileSync3(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    throw new CliError(
+      `Failed to parse config file: ${filePath}. Ensure it contains valid JSON.`,
+      "INVALID_CONFIG"
+    );
+  }
+}
+function writeConfigFile(filePath, config) {
+  const dir = dirname(filePath);
+  if (!existsSync4(dir)) {
+    mkdirSync3(dir, { recursive: true });
+  }
+  writeFileSync3(filePath, JSON.stringify(config, null, 2) + "\n");
+}
+function truncateKey(apiKey) {
+  if (apiKey.length <= 10) return apiKey;
+  return `${apiKey.slice(0, 6)}\u2026${apiKey.slice(-4)}`;
+}
+function extractKeyFromConfig(config) {
+  const servers = config.mcpServers;
+  if (!servers?.betterness) return null;
+  const entry = servers.betterness;
+  const args = entry.args;
+  if (!args) return null;
+  const headerIdx = args.indexOf("--header");
+  if (headerIdx === -1 || headerIdx + 1 >= args.length) return null;
+  const headerVal = args[headerIdx + 1];
+  const match = headerVal.match(/Bearer\s+(.+)/);
+  return match ? match[1] : null;
+}
+function registerMcpCommands(program2) {
+  const mcp = program2.command("mcp").description("MCP server integration for AI agents (Claude, Cursor, Windsurf)");
+  mcp.command("install").description("Install Betterness MCP integration into an AI client").argument("<client>", `Client to configure (${VALID_CLIENTS})`).option("--scope <scope>", "Config scope: global or project (claude-code only)", "global").option("--dry-run", "Print config without writing").action(async (clientArg, opts, cmd) => {
+    try {
+      const clientId = validateClient(clientArg);
+      const client = CLIENTS[clientId];
+      const scope = opts.scope === "project" ? "project" : "global";
+      if (opts.scope === "project" && !client.supportsScope) {
+        console.error(`Note: --scope is only supported for claude-code. Using default path for ${client.name}.`);
+      }
+      const globalOpts = cmd.optsWithGlobals();
+      const credentials = await resolveCredentials(globalOpts.apiKey);
+      const entry = buildMcpEntry(credentials.apiKey);
+      const configPath = client.configPath(scope);
+      if (opts.dryRun) {
+        const redactedEntry = buildMcpEntry(`${credentials.apiKey.slice(0, 6)}\u2026****`);
+        const preview = { mcpServers: { betterness: redactedEntry } };
+        console.log(`Would write to: ${configPath}
+`);
+        console.log(JSON.stringify(preview, null, 2));
+        return;
+      }
+      const config = readConfigFile(configPath);
+      let backupPath = null;
+      if (existsSync4(configPath)) {
+        backupPath = `${configPath}.bak`;
+        copyFileSync(configPath, backupPath);
+      }
+      if (!config.mcpServers || typeof config.mcpServers !== "object") {
+        config.mcpServers = {};
+      }
+      config.mcpServers.betterness = entry;
+      writeConfigFile(configPath, config);
+      outputRecord(cmd, {
+        client: client.name,
+        configFile: configPath,
+        status: "installed",
+        apiKey: truncateKey(credentials.apiKey),
+        backup: backupPath ?? "none (new file)"
+      });
+      console.log(`
+Restart ${client.name} to activate. Then try asking:
+  "List my connected devices"`);
+    } catch (error) {
+      outputError(error);
+    }
+  });
+  mcp.command("uninstall").description("Remove Betterness MCP integration from an AI client").argument("<client>", `Client to unconfigure (${VALID_CLIENTS})`).option("--scope <scope>", "Config scope: global or project (claude-code only)", "global").action(async (clientArg, opts, cmd) => {
+    try {
+      const clientId = validateClient(clientArg);
+      const client = CLIENTS[clientId];
+      const scope = opts.scope === "project" ? "project" : "global";
+      const configPath = client.configPath(scope);
+      if (!existsSync4(configPath)) {
+        console.log(`No config file found for ${client.name} at ${configPath}`);
+        return;
+      }
+      const config = readConfigFile(configPath);
+      const servers = config.mcpServers;
+      if (!servers?.betterness) {
+        console.log(`Betterness MCP is not configured for ${client.name}.`);
+        return;
+      }
+      delete servers.betterness;
+      if (Object.keys(servers).length === 0) {
+        delete config.mcpServers;
+      }
+      writeConfigFile(configPath, config);
+      outputRecord(cmd, {
+        client: client.name,
+        configFile: configPath,
+        status: "removed"
+      });
+    } catch (error) {
+      outputError(error);
+    }
+  });
+  mcp.command("status").description("Show MCP integration status across all supported clients").action(async (_, cmd) => {
+    try {
+      const mcpUrl = getMcpUrl();
+      const rows = [];
+      for (const [id, client] of Object.entries(CLIENTS)) {
+        const scopes = client.supportsScope ? ["global", "project"] : ["global"];
+        for (const scope of scopes) {
+          const configPath = client.configPath(scope);
+          const exists = existsSync4(configPath);
+          let configured = false;
+          let apiKey = "";
+          if (exists) {
+            try {
+              const config = readConfigFile(configPath);
+              const key = extractKeyFromConfig(config);
+              if (key) {
+                configured = true;
+                apiKey = truncateKey(key);
+              }
+            } catch {
+            }
+          }
+          rows.push({
+            client: client.supportsScope ? `${client.name} (${scope})` : client.name,
+            status: configured ? "\u2713 configured" : "\u2717 not configured",
+            apiKey: apiKey || "\u2014",
+            configFile: configPath
+          });
+        }
+      }
+      console.log(`MCP Endpoint: ${mcpUrl}
+`);
+      outputList(cmd, rows, [
+        { key: "client", label: "Client", width: 26 },
+        { key: "status", label: "Status", width: 18 },
+        { key: "apiKey", label: "API Key", width: 16 },
+        { key: "configFile", label: "Config File", width: 55 }
+      ]);
+    } catch (error) {
+      outputError(error);
+    }
+  });
+}
+
 // src/program.ts
 function createProgram() {
   const program2 = new Command();
-  program2.name("betterness").description("Betterness CLI - Agent-first terminal interface for the Betterness platform").version("1.2.2").option("--api-key <key>", "API key (overrides env and stored credentials)").option("--json", "Output as JSON").option("--markdown", "Output as Markdown").option("--quiet", "Suppress output (exit code only)");
+  program2.name("betterness").description("Betterness CLI - Agent-first terminal interface for the Betterness platform").version("1.3.1").option("--api-key <key>", "API key (overrides env and stored credentials)").option("--json", "Output as JSON").option("--markdown", "Output as Markdown").option("--quiet", "Suppress output (exit code only)");
   registerAuthCommands(program2);
   registerProfileCommands(program2);
   registerBiomarkersCommands(program2);
@@ -2470,6 +2690,7 @@ function createProgram() {
   registerSchemaCommand(program2);
   registerDebugCommands(program2);
   registerHealthProfileCommands(program2);
+  registerMcpCommands(program2);
   return program2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterness/cli",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Betterness CLI - Agent-first terminal interface for the Betterness platform",
   "type": "module",
   "bin": {