@askthew/mcp-plugin 0.4.7 → 0.4.8

package/README.md

@@ -43,6 +43,8 @@ npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp install
 
 Free install is local-first: it generates `~/.askthew/identity.json`, writes MCP config and agent instructions immediately, and never requires an email code before local capture works. The email is an unverified claim used for upgrade onboarding only; data is keyed by the generated install ID, not email alone.
 
+Installer bookkeeping is separate from local capture data: install receipts live under `~/.local/state/askthew/install-receipts.json` by default, or `$XDG_STATE_HOME/askthew/install-receipts.json` when `XDG_STATE_HOME` is set. This lets `uninstall` remove host config and repo instruction blocks even after `~/.askthew` has been wiped.
+
 Telemetry is aggregate-only and opt-out. Ask The W does not receive code, file contents, file paths, file names, command text, summaries, or decision content in free mode telemetry. Aggregate summaries are signed by the local install identity and stored under the generated install ID. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
 
 ## Refresh vs Uninstall

package/dist/cli.js

@@ -13,16 +13,16 @@ 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, formatInstallCommand, installBehaviorInstructions, installHostConfig, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, } from "./install.js";
+import { createHostConfigSnippet, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, 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>] [--dry-run] [--no-agent-instructions]",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>]",
-        "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--dry-run]",
+        "  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 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 identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
@@ -47,6 +47,7 @@ function parseInstallArgs(argv) {
     let installAgentInstructions = true;
     let free = false;
     let email = process.env.ASKTHEW_EMAIL?.trim() || "";
+    let serverEntrypoint = process.env.ASKTHEW_SERVER_ENTRYPOINT?.trim() || "";
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--dry-run") {
@@ -103,6 +104,11 @@ function parseInstallArgs(argv) {
             index += 1;
             continue;
         }
+        if (argument === "--server-entrypoint") {
+            serverEntrypoint = next;
+            index += 1;
+            continue;
+        }
         throw new Error(`Unknown argument: ${argument}`);
     }
     if (!hostType) {
@@ -128,6 +134,7 @@ function parseInstallArgs(argv) {
         installAgentInstructions,
         free,
         email: email || undefined,
+        serverEntrypoint: serverEntrypoint ? path.resolve(serverEntrypoint) : undefined,
     };
 }
 function normalizeInstallToken(token) {
@@ -204,6 +211,17 @@ async function main() {
                 dryRun: options.dryRun,
             })
             : null;
+        const receipt = result.wroteFile
+            ? writeInstallReceipt({
+                hostType: options.hostType,
+                serverName: options.serverName,
+                settingsPath: result.settingsPath,
+                cwd: process.cwd(),
+                instructionPaths: instructions?.paths ?? [],
+                serverEntrypoint: options.serverEntrypoint,
+                packageVersion: packageVersion(),
+            })
+            : null;
         const heartbeatSent = result.wroteFile && !options.free
             ? await sendInstallHeartbeat(options).catch(() => false)
             : false;
@@ -212,6 +230,9 @@ async function main() {
         if (instructions) {
             console.log(`Agent instructions: ${instructions.paths?.join(", ") ?? instructions.path}`);
         }
+        if (receipt) {
+            console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
+        }
         console.log(`Install command: ${formatInstallCommand(options)}`);
         if (result.wroteFile) {
             if (freeIdentity) {
@@ -344,14 +365,17 @@ async function runUninstallCommand(argv) {
     if (!hostType) {
         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 instructions = keepAgentInstructions
-        ? null
-        : uninstallBehaviorInstructions({ hostType, dryRun });
+    const instructionCwds = Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)]));
+    const instructionPaths = keepAgentInstructions
+        ? []
+        : instructionCwds.flatMap((cwd) => uninstallBehaviorInstructions({ hostType, dryRun, cwd }).paths);
     const dataDir = askTheWDataDir();
     const hadLocalData = fs.existsSync(dataDir);
     const authFile = identityPath();
     const hadAuth = fs.existsSync(authFile);
+    const removedReceipts = dryRun ? receipts.length : removeInstallReceipts({ hostType, serverName });
     if (!keepLocalData && !dryRun) {
         fs.rmSync(dataDir, { recursive: true, force: true });
     }
@@ -366,11 +390,14 @@ async function runUninstallCommand(argv) {
         : config.foundConfigFile
             ? `No MCP server "${config.removedServerName}" found in host config.`
             : "No host config file found.");
-    if (instructions) {
-        console.log(instructions.paths.length > 0
-            ? `Agent instructions ${dryRun ? "would be removed from" : "removed from"}: ${instructions.paths.join(", ")}`
+    if (!keepAgentInstructions) {
+        console.log(instructionPaths.length > 0
+            ? `Agent instructions ${dryRun ? "would be removed from" : "removed from"}: ${Array.from(new Set(instructionPaths)).join(", ")}`
             : "No Ask The W agent instruction blocks found.");
     }
+    console.log(removedReceipts > 0
+        ? `${dryRun ? "Would remove" : "Removed"} ${removedReceipts} install receipt${removedReceipts === 1 ? "" : "s"}.`
+        : "No install receipts found.");
     console.log(keepLocalData
         ? "Local data kept."
         : hadLocalData
@@ -417,6 +444,17 @@ async function runRefreshCommand(argv) {
             dryRun: options.dryRun,
         })
         : null;
+    const receipt = install.wroteFile
+        ? writeInstallReceipt({
+            hostType: options.hostType,
+            serverName: options.serverName,
+            settingsPath: install.settingsPath,
+            cwd: process.cwd(),
+            instructionPaths: installedInstructions?.paths ?? [],
+            serverEntrypoint: options.serverEntrypoint,
+            packageVersion: packageVersion(),
+        })
+        : null;
     if (options.free && freeIdentity && !options.dryRun) {
         await tryRegisterFreeInstall({
             identity: freeIdentity,
@@ -436,6 +474,9 @@ async function runRefreshCommand(argv) {
     if (installedInstructions) {
         console.log(`Installed instructions: ${installedInstructions.paths.join(", ") || installedInstructions.path}`);
     }
+    if (receipt) {
+        console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
+    }
     if (options.free) {
         console.log(freeIdentity
             ? `Local identity preserved: ${freeIdentity.installId}`

package/dist/index.d.ts

@@ -158,4 +158,8 @@ export interface AskTheWMcpServerOptions {
 }
 export declare function normalizeInstallTokenInput(token: string | undefined): string;
 export declare function createAskTheWMcpServer(options?: AskTheWMcpServerOptions): McpServer;
+export declare function runInitializeHandshake(input?: {
+    entrypoint?: string;
+    timeoutMs?: number;
+}): Promise<void>;
 export {};

package/dist/index.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1914,16 +1915,92 @@ const isDirectIndexExecution = Boolean(process.argv[1]) &&
             return invokedPath === modulePath;
         }
     })();
-if (isDirectIndexExecution) {
-    const server = createAskTheWMcpServer();
-    const transport = new StdioServerTransport();
-    server.connect(transport).catch((error) => {
-        if (error instanceof Error) {
-            console.error(error.message);
-        }
-        else {
-            console.error("Ask The W MCP server failed to start.", error);
-        }
-        process.exit(1);
+export async function runInitializeHandshake(input = {}) {
+    const modulePath = input.entrypoint ?? fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [modulePath], {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: ["pipe", "pipe", "pipe"],
     });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    const initialize = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "askthew-initialize-handshake", version: "1.0.0" },
+        },
+    };
+    child.stdin.write(`${JSON.stringify(initialize)}\n`);
+    try {
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error(`Timed out waiting for initialize response. stdout=${stdout} stderr=${stderr}`));
+            }, input.timeoutMs ?? 3000);
+            const failOnExit = (code) => {
+                clearTimeout(timeout);
+                reject(new Error(`MCP stdio server exited before initialize. code=${code} stdout=${stdout} stderr=${stderr}`));
+            };
+            const check = () => {
+                const lineEnd = stdout.indexOf("\n");
+                if (lineEnd === -1)
+                    return;
+                clearTimeout(timeout);
+                child.off("exit", failOnExit);
+                const response = JSON.parse(stdout.slice(0, lineEnd));
+                if (response.id !== 1 || response.jsonrpc !== "2.0" || !response.result) {
+                    reject(new Error(`Unexpected initialize response: ${JSON.stringify(response)}`));
+                    return;
+                }
+                resolve();
+            };
+            child.stdout.on("data", check);
+            child.once("exit", failOnExit);
+            check();
+        });
+    }
+    finally {
+        child.kill();
+    }
+}
+if (isDirectIndexExecution) {
+    if (process.argv[2] === "initialize-handshake") {
+        runInitializeHandshake()
+            .then(() => {
+            console.log("Ask The W MCP initialize handshake succeeded.");
+        })
+            .catch((error) => {
+            if (error instanceof Error) {
+                console.error(error.message);
+            }
+            else {
+                console.error("Ask The W MCP initialize handshake failed.", error);
+            }
+            process.exit(1);
+        });
+    }
+    else {
+        const server = createAskTheWMcpServer();
+        const transport = new StdioServerTransport();
+        server.connect(transport).catch((error) => {
+            if (error instanceof Error) {
+                console.error(error.message);
+            }
+            else {
+                console.error("Ask The W MCP server failed to start.", error);
+            }
+            process.exit(1);
+        });
+    }
 }

package/dist/install.d.ts

@@ -9,6 +9,7 @@ interface HostConfigInput {
     free?: boolean;
     email?: string;
     cwd?: string;
+    serverEntrypoint?: string;
 }
 interface InstallHostConfigInput extends HostConfigInput {
     dryRun?: boolean;
@@ -22,6 +23,17 @@ interface UninstallHostConfigInput {
     homeDirectory?: string;
     cwd?: string;
 }
+export interface InstallReceipt {
+    hostType: SupportedHostType;
+    serverName: string;
+    settingsPath: string;
+    cwd: string;
+    instructionPaths: string[];
+    dataDir: string;
+    serverEntrypoint?: string;
+    installedAt: string;
+    packageVersion?: string;
+}
 export declare function resolveSettingsPath(input: {
     hostType: SupportedHostType;
     homeDirectory?: string;
@@ -107,6 +119,20 @@ export declare function installHostConfig(input: InstallHostConfigInput): {
     wroteFile: boolean;
     nextStep: string;
 };
+export declare function readInstallReceipts(env?: NodeJS.ProcessEnv): InstallReceipt[];
+export declare function writeInstallReceipt(receipt: Omit<InstallReceipt, "dataDir" | "installedAt"> & {
+    dataDir?: string;
+    installedAt?: string;
+}, env?: NodeJS.ProcessEnv): InstallReceipt;
+export declare function findInstallReceipts(input: {
+    hostType: SupportedHostType;
+    serverName?: string;
+}, env?: NodeJS.ProcessEnv): InstallReceipt[];
+export declare function removeInstallReceipts(input: {
+    hostType: SupportedHostType;
+    serverName?: string;
+    cwd?: string;
+}, env?: NodeJS.ProcessEnv): number;
 export declare function uninstallHostConfig(input: UninstallHostConfigInput): {
     settingsPath: string;
     json: string;

package/dist/install.js

@@ -1,9 +1,11 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { askTheWDataDir, installReceiptsPath, readJsonFile, writePrivateJson } from "./lib/paths.js";
 import { resolvePluginScope } from "./scope.js";
 const ASKTHEW_INSTRUCTIONS_START = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_START -->";
 const ASKTHEW_INSTRUCTIONS_END = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_END -->";
+const INSTALL_RECEIPTS_SCHEMA_VERSION = 1;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -19,21 +21,29 @@ export function resolveSettingsPath(input) {
 }
 export function createServerEntry(input) {
     const scope = resolvePluginScope(input.cwd ?? process.cwd());
+    const env = {
+        ASKTHEW_API_URL: input.apiUrl,
+        ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
+        ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
+        ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
+        ASKTHEW_HOST_TYPE: input.hostType,
+        ASKTHEW_SERVER_NAME: input.serverName,
+        ASKTHEW_REPO_NAME: scope.repoName,
+        ...(scope.repoRoot ? { ASKTHEW_REPO_ROOT: scope.repoRoot } : {}),
+        ...(scope.appPath ? { ASKTHEW_APP_PATH: scope.appPath } : {}),
+        ...(scope.serviceName ? { ASKTHEW_SERVICE_NAME: scope.serviceName } : {}),
+    };
+    if (input.serverEntrypoint) {
+        return {
+            command: "node",
+            args: [path.resolve(input.serverEntrypoint)],
+            env,
+        };
+    }
     return {
         command: "npx",
         args: ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"],
-        env: {
-            ASKTHEW_API_URL: input.apiUrl,
-            ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
-            ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
-            ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
-            ASKTHEW_HOST_TYPE: input.hostType,
-            ASKTHEW_SERVER_NAME: input.serverName,
-            ASKTHEW_REPO_NAME: scope.repoName,
-            ...(scope.repoRoot ? { ASKTHEW_REPO_ROOT: scope.repoRoot } : {}),
-            ...(scope.appPath ? { ASKTHEW_APP_PATH: scope.appPath } : {}),
-            ...(scope.serviceName ? { ASKTHEW_SERVICE_NAME: scope.serviceName } : {}),
-        },
+        env,
     };
 }
 export function createHostConfigSnippet(input) {
@@ -150,6 +160,9 @@ export function formatInstallCommand(input) {
             parts.push("--email", JSON.stringify(input.email));
         }
     }
+    if (input.serverEntrypoint) {
+        parts.push("--server-entrypoint", JSON.stringify(input.serverEntrypoint));
+    }
     return parts.join(" ");
 }
 export function verificationNextStep(hostType) {
@@ -188,6 +201,7 @@ export function installHostConfig(input) {
         clientLabel: input.clientLabel,
         free: input.free,
         cwd: input.cwd,
+        serverEntrypoint: input.serverEntrypoint,
     };
     const json = input.hostType === "codex"
         ? mergeCodexSettings({
@@ -211,6 +225,68 @@ export function installHostConfig(input) {
         nextStep: verificationNextStep(input.hostType),
     };
 }
+function normalizeInstructionPaths(paths) {
+    return Array.from(new Set(paths.map((entry) => path.resolve(entry))));
+}
+function normalizeReceipt(receipt) {
+    return {
+        ...receipt,
+        settingsPath: path.resolve(receipt.settingsPath),
+        cwd: path.resolve(receipt.cwd),
+        instructionPaths: normalizeInstructionPaths(receipt.instructionPaths ?? []),
+        dataDir: path.resolve(receipt.dataDir || askTheWDataDir()),
+        serverEntrypoint: receipt.serverEntrypoint ? path.resolve(receipt.serverEntrypoint) : undefined,
+    };
+}
+function receiptKey(receipt) {
+    return `${receipt.hostType}\u0000${receipt.serverName}\u0000${path.resolve(receipt.cwd)}`;
+}
+export function readInstallReceipts(env = process.env) {
+    const parsed = readJsonFile(installReceiptsPath(env));
+    if (!parsed || parsed.schemaVersion !== INSTALL_RECEIPTS_SCHEMA_VERSION || !Array.isArray(parsed.installs)) {
+        return [];
+    }
+    return parsed.installs
+        .filter((receipt) => Boolean(receipt?.hostType && receipt.serverName && receipt.settingsPath && receipt.cwd))
+        .map(normalizeReceipt);
+}
+export function writeInstallReceipt(receipt, env = process.env) {
+    const nextReceipt = normalizeReceipt({
+        ...receipt,
+        dataDir: receipt.dataDir ?? askTheWDataDir(env),
+        installedAt: receipt.installedAt ?? new Date().toISOString(),
+    });
+    const receipts = readInstallReceipts(env).filter((entry) => receiptKey(entry) !== receiptKey(nextReceipt));
+    receipts.push(nextReceipt);
+    receipts.sort((left, right) => left.installedAt.localeCompare(right.installedAt));
+    writePrivateJson(installReceiptsPath(env), {
+        schemaVersion: INSTALL_RECEIPTS_SCHEMA_VERSION,
+        installs: receipts,
+    });
+    return nextReceipt;
+}
+export function findInstallReceipts(input, env = process.env) {
+    return readInstallReceipts(env).filter((receipt) => receipt.hostType === input.hostType &&
+        (!input.serverName || receipt.serverName === input.serverName));
+}
+export function removeInstallReceipts(input, env = process.env) {
+    const cwd = input.cwd ? path.resolve(input.cwd) : undefined;
+    const receipts = readInstallReceipts(env);
+    const next = receipts.filter((receipt) => {
+        if (receipt.hostType !== input.hostType)
+            return true;
+        if (input.serverName && receipt.serverName !== input.serverName)
+            return true;
+        if (cwd && receipt.cwd !== cwd)
+            return true;
+        return false;
+    });
+    writePrivateJson(installReceiptsPath(env), {
+        schemaVersion: INSTALL_RECEIPTS_SCHEMA_VERSION,
+        installs: next,
+    });
+    return receipts.length - next.length;
+}
 export function uninstallHostConfig(input) {
     const settingsPath = resolveSettingsPath({
         hostType: input.hostType,

package/dist/lib/paths.d.ts

@@ -1,8 +1,10 @@
 export declare function askTheWDataDir(env?: NodeJS.ProcessEnv): string;
+export declare function askTheWStateDir(env?: NodeJS.ProcessEnv): string;
 export declare function ensureAskTheWDataDir(env?: NodeJS.ProcessEnv): string;
 export declare function localStorePath(env?: NodeJS.ProcessEnv): string;
 export declare function identityPath(env?: NodeJS.ProcessEnv): string;
 export declare function configPath(env?: NodeJS.ProcessEnv): string;
 export declare function jsonFallbackStorePath(env?: NodeJS.ProcessEnv): string;
+export declare function installReceiptsPath(env?: NodeJS.ProcessEnv): string;
 export declare function writePrivateJson(filePath: string, value: unknown): void;
 export declare function readJsonFile<T>(filePath: string): T | null;

package/dist/lib/paths.js

@@ -12,6 +12,17 @@ export function askTheWDataDir(env = process.env) {
     }
     return path.join(os.homedir(), ".askthew");
 }
+export function askTheWStateDir(env = process.env) {
+    const explicit = env.ASKTHEW_STATE_DIR?.trim();
+    if (explicit) {
+        return path.resolve(explicit);
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome) {
+        return path.join(path.resolve(xdgStateHome), "askthew");
+    }
+    return path.join(os.homedir(), ".local", "state", "askthew");
+}
 export function ensureAskTheWDataDir(env = process.env) {
     const dir = askTheWDataDir(env);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -29,6 +40,9 @@ export function configPath(env = process.env) {
 export function jsonFallbackStorePath(env = process.env) {
     return path.join(askTheWDataDir(env), "store.json");
 }
+export function installReceiptsPath(env = process.env) {
+    return path.join(askTheWStateDir(env), "install-receipts.json");
+}
 export function writePrivateJson(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "private": false,
   "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",