@askthew/mcp-plugin 0.4.8 → 0.4.10

package/README.md

@@ -6,7 +6,7 @@ Connect a local coding agent to Ask The W. The fastest path is free and local-fi
 npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install --host claude_code --free --email you@founder.com
 ```
 
-This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent run `review_decisions`, `review_session`, `recap`, `coach`, and `promote_signal_to_decision` without onboarding into the web app.
+This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent list the trail, keep decisions, and get limited local recap and coaching without onboarding into the web app.
 
 Founder-friendly promise: install from npm, then ask your coding agent to review the last session. You should see value in under 60 seconds.
 
@@ -19,7 +19,7 @@ This package runs a small MCP server that lets Codex, Claude Code, Cursor, and o
 - Adds marked project instructions so future coding-agent sessions know when to send Ask The W updates.
 - Free mode stores full-fidelity signals and decisions locally in SQLite.
 - Paid workspace mode sends a startup heartbeat so Ask The W can show the plugin as installed.
-- Exposes `capture_session_signal` plus v1 API tools for decisions, outcomes, signals, outcome detail graphs, and north star reads or updates.
+- Exposes a small MCP surface for capture, signals, decisions, recap, and coaching.
 - Redacts obvious secrets from summaries, evidence excerpts, commands, and metadata before sending.
 - Adds lightweight workspace metadata such as host type, repo name, app path, and server name.
 
@@ -27,10 +27,10 @@ This package runs a small MCP server that lets Codex, Claude Code, Cursor, and o
 
 - It does not send full transcripts by default.
 - It does not send local free-tier content to Ask The W unless you upgrade and run sync upload.
-- It does not link outcomes, score confidence, dedupe signals, or update the graph locally.
+- It does not expose internal workspace APIs through the plugin.
 - It does not include the Ask The W app, private server code, Supabase code, or internal analytics code.
 
-Ask The W performs inference, linking, approval state, dedupe, and outcome updates in the app.
+Ask The W keeps the local plugin focused on the trail your agent can use while it works.
 
 ## Free Local Install
 
@@ -183,15 +183,13 @@ The session-signal tool remains the main automatic capture path.
 
 Use compact summaries and short evidence excerpts. Do not send full transcripts. By default, write tools return compact responses; use `echo: "full"` only when you need the larger payload for debugging.
 
-The plugin also exposes v1 API tools that map to the app's authenticated routes:
+The plugin exposes a small public tool surface:
 
 | Tool | Purpose |
 |---|---|
-| `list_decisions`, `get_decision`, `create_decision`, `update_decision`, `delete_decision` | Work with decision feed entries. |
-| `review_session`, `recap`, `coach`, `promote_signal_to_decision`, `find_signal_by_summary` | Review local sessions, get session coaching, find recent evidence, and turn signals into decisions in free mode. |
-| `list_outcomes`, `get_outcome`, `list_outcome_signals`, `create_outcome`, `update_outcome`, `delete_outcome` | Work with outcomes and their linked signals. |
-| `get_north_star`, `update_north_star` | Read or update the workspace north star. API updates are allowed only for private workspaces. |
-| `list_signals`, `get_signal` | Read workspace signals. |
+| `capture_session_signal`, `list_signals` | Capture and list the local signal trail. |
+| `list_decisions`, `get_decision`, `create_decision`, `promote_signal_to_decision` | Keep the decisions worth remembering. |
+| `recap`, `coach` | Get up to three local recaps and three coaching nudges. After that, the plugin returns `Limit reached. Upgrade to the paid plan.` |
 
 Free PLG helpers:
 
@@ -202,7 +200,7 @@ npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp digest -
 
 The hook prompts when staged files recently had implementation signals but no linked decision. The weekly digest writes `~/Documents/askthew-digest-YYYY-WW.md`.
 
-API mutations are text-only and are recorded back into the workspace signal feed. Decision and outcome deletes require a `confirmText` value that exactly matches the stored decision headline or outcome name after whitespace normalization. North star delete is not available through the API.
+Decision writes are text-only and are recorded with the local trail.
 
 ## Troubleshooting
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createAskTheWMcpServer } from "./index.js";
+import { createAskTheWMcpServer, runInitializeHandshake } from "./index.js";
 import { askTheWDataDir, ensureAskTheWDataDir, identityPath } from "./lib/paths.js";
 import { loadCliCredentials } from "./lib/free-tier-policy.js";
 import { describeFreeIdentity, tryRegisterFreeInstall } from "./lib/free-install-registration.js";
@@ -13,17 +13,21 @@ import { LocalStore } from "./lib/local-store.js";
 import { buildTelemetryPayload } from "./lib/telemetry.js";
 import { syncDryRun, uploadLocalStore } from "./lib/upgrade-sync.js";
 import { installPreCommitHook, localScopeKey, preCommitDecisionGap, stagedFiles, writeWeeklyDigest, } from "./lib/cli-actions.js";
-import { createHostConfigSnippet, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, writeInstallReceipt, } from "./install.js";
+import { createHostConfigSnippet, defaultServerNameForTier, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, packageVersion, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, upgradePinnedHostConfig, writeInstallReceipt, } from "./install.js";
 function usage() {
     return [
         "Ask The W Coding Agent Connector",
         "",
         "Usage:",
-        "  askthew-mcp",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>] [--server-entrypoint <path>] [--dry-run] [--no-agent-instructions]",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>]",
+        "  askthew-mcp [stdio MCP server when stdin is piped]",
+        "  askthew-mcp --version",
+        "  askthew-mcp doctor [--server-entrypoint <path>]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> [--server-name <name>] [--client-id <id>] [--client-label <label>] [--server-entrypoint <path>] [--dry-run] [--no-agent-instructions]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
         "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
         "  askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>] [--dry-run] [--keep-local-data] [--keep-auth] [--keep-agent-instructions]",
+        "  askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]",
+        "  askthew-mcp upgrade --browser",
         "  askthew-mcp identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
         "  askthew-mcp auth login --email <email> [--no-telemetry]",
@@ -43,6 +47,7 @@ function parseInstallArgs(argv) {
     let token = normalizeInstallToken(process.env.ASKTHEW_INSTALL_TOKEN) || "";
     let apiUrl = process.env.ASKTHEW_API_URL?.trim() || "";
     let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let installAgentInstructions = true;
     let free = false;
@@ -96,6 +101,7 @@ function parseInstallArgs(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -121,7 +127,7 @@ function parseInstallArgs(argv) {
         apiUrl = "https://app.askthew.com";
     }
     if (!serverName) {
-        serverName = "askthew";
+        serverName = defaultServerNameForTier(free);
     }
     return {
         hostType,
@@ -130,6 +136,7 @@ function parseInstallArgs(argv) {
         token,
         apiUrl,
         serverName,
+        serverNameExplicit,
         dryRun,
         installAgentInstructions,
         free,
@@ -140,16 +147,6 @@ function parseInstallArgs(argv) {
 function normalizeInstallToken(token) {
     return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
 }
-function packageVersion() {
-    try {
-        const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
-        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-        return typeof parsed.version === "string" ? parsed.version : "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
 function detectLoginEmail() {
     for (const value of [
         process.env.ASKTHEW_EMAIL,
@@ -189,6 +186,14 @@ async function main() {
         console.log(usage());
         return;
     }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(packageVersion());
+        return;
+    }
+    if (command === "doctor") {
+        await runDoctorCommand(argv);
+        return;
+    }
     if (command === "print-config") {
         const options = parseInstallArgs(argv);
         const snippet = createHostConfigSnippet(options);
@@ -196,6 +201,7 @@ async function main() {
         return;
     }
     if (command === "install") {
+        console.error(`Downloading @askthew/mcp-plugin@${packageVersion()}...`);
         const options = parseInstallArgs(argv);
         let freeIdentity = null;
         if (options.free && !options.dryRun) {
@@ -228,11 +234,14 @@ async function main() {
         console.log(result.wroteFile ? "Ask The W plugin install complete." : "Ask The W plugin dry run complete.");
         console.log(`Settings path: ${result.settingsPath}`);
         if (instructions) {
-            console.log(`Agent instructions: ${instructions.paths?.join(", ") ?? instructions.path}`);
+            console.log(`${options.dryRun ? "Would update agent instructions" : "Agent instructions"}: ${instructions.paths?.join(", ") ?? instructions.path}`);
         }
         if (receipt) {
             console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
         }
+        else if (options.dryRun) {
+            console.log(`Would write install receipt: ${options.hostType}/${options.serverName} at ${process.cwd()}`);
+        }
         console.log(`Install command: ${formatInstallCommand(options)}`);
         if (result.wroteFile) {
             if (freeIdentity) {
@@ -257,6 +266,7 @@ async function main() {
         console.log(`Next step: ${result.nextStep}`);
         if (!result.wroteFile) {
             console.log("");
+            console.log("Planned host config:");
             console.log(result.json);
         }
         return;
@@ -306,22 +316,24 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Open https://askthew.com/plugin to upgrade, then run `askthew-mcp upgrade --finalize`.");
-        if (argv.includes("--finalize")) {
-            console.log("Finalize will rewrite host config after a paid workspace token is available in the web app.");
-        }
+        await runUpgradeCommand(argv);
         return;
     }
     if (command) {
         throw new Error(`Unknown command "${command}".\n\n${usage()}`);
     }
+    if (process.stdin.isTTY) {
+        console.log(usage());
+        return;
+    }
     const server = createAskTheWMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 async function runUninstallCommand(argv) {
     let hostType;
-    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "askthew";
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let keepLocalData = false;
     let keepAuth = false;
@@ -357,6 +369,7 @@ async function runUninstallCommand(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -366,7 +379,12 @@ async function runUninstallCommand(argv) {
         throw new Error("Usage: askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>]");
     }
     const receipts = findInstallReceipts({ hostType, serverName });
-    const config = uninstallHostConfig({ hostType, serverName, dryRun });
+    const config = uninstallHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
     const instructionCwds = Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)]));
     const instructionPaths = keepAgentInstructions
         ? []
@@ -419,6 +437,9 @@ async function runRefreshCommand(argv) {
     const options = {
         ...parsed,
         free: !isPaidRefresh,
+        serverName: parsed.serverNameExplicit
+            ? parsed.serverName
+            : defaultServerNameForTier(!isPaidRefresh),
     };
     const existingIdentity = loadLocalIdentity();
     let freeIdentity = existingIdentity;
@@ -497,6 +518,98 @@ async function runRefreshCommand(argv) {
         console.log(install.json);
     }
 }
+async function runDoctorCommand(argv) {
+    const serverEntrypoint = argValue(argv, "--server-entrypoint")?.trim();
+    const result = await runInitializeHandshake({
+        entrypoint: serverEntrypoint ? path.resolve(serverEntrypoint) : undefined,
+    });
+    const expectedVersion = packageVersion();
+    if (result.serverInfoVersion !== expectedVersion) {
+        throw new Error(`MCP initialize version mismatch: package.json=${expectedVersion} serverInfo.version=${result.serverInfoVersion ?? "missing"}`);
+    }
+    console.log("Ask The W MCP doctor passed.");
+    console.log(`Package version: ${expectedVersion}`);
+    console.log(`serverInfo.version: ${result.serverInfoVersion}`);
+}
+async function runUpgradeCommand(argv) {
+    if (argv.includes("--browser")) {
+        console.log("Open https://askthew.com/plugin to manage workspace upgrades.");
+        return;
+    }
+    let hostType = process.env.ASKTHEW_HOST_TYPE?.trim();
+    if (hostType !== "claude_code" && hostType !== "codex" && hostType !== "cursor") {
+        hostType = undefined;
+    }
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
+    let version = process.env.ASKTHEW_PIN?.trim() || packageVersion();
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next)
+            throw new Error(`Missing value for ${argument}.`);
+        if (argument === "--host") {
+            if (next !== "claude_code" && next !== "codex" && next !== "cursor") {
+                throw new Error(`Unsupported host "${next}". Expected claude_code, codex, or cursor.`);
+            }
+            hostType = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--server-name") {
+            serverName = next;
+            serverNameExplicit = true;
+            index += 1;
+            continue;
+        }
+        if (argument === "--version" || argument === "--pin") {
+            version = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!hostType) {
+        throw new Error("Usage: askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]");
+    }
+    const packageSpec = version.startsWith("@askthew/mcp-plugin@")
+        ? version
+        : `@askthew/mcp-plugin@${version}`;
+    if (!dryRun) {
+        const handshake = await runInitializeHandshake();
+        if (handshake.serverInfoVersion !== packageVersion()) {
+            throw new Error(`Refusing to upgrade pinned host config: MCP initialize returned ${handshake.serverInfoVersion ?? "missing"} but package.json is ${packageVersion()}.`);
+        }
+    }
+    const receipts = findInstallReceipts({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+    });
+    const result = upgradePinnedHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        packageSpec,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
+    console.log(dryRun ? "Ask The W plugin upgrade dry run complete." : "Ask The W plugin upgrade complete.");
+    console.log(`Settings path: ${result.settingsPath}`);
+    console.log(`Pinned package: ${result.packageSpec}`);
+    console.log(result.upgradedServer
+        ? `${dryRun ? "Would update" : "Updated"} MCP server pin${result.upgradedServerNames.length ? `: ${result.upgradedServerNames.join(", ")}` : "."}`
+        : result.foundConfigFile
+            ? "No Ask The W MCP server pins needed an update."
+            : "No host config file found.");
+    if (dryRun && result.json) {
+        console.log("");
+        console.log(result.json);
+    }
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;

package/dist/index.d.ts

@@ -160,6 +160,9 @@ export declare function normalizeInstallTokenInput(token: string | undefined): s
 export declare function createAskTheWMcpServer(options?: AskTheWMcpServerOptions): McpServer;
 export declare function runInitializeHandshake(input?: {
     entrypoint?: string;
+    env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
-}): Promise<void>;
+}): Promise<{
+    serverInfoVersion?: string;
+}>;
 export {};