@askthew/mcp-plugin 0.4.12 → 0.4.14

package/README.md

@@ -61,18 +61,24 @@ The v1 MCP tools are:
 
 ## CLI
 
+If the binary is not on your PATH, prefix commands with `npx -y --package @askthew/mcp-plugin`.
+
 ```bash
 askthew-mcp                 # stdio MCP server
 askthew-mcp install --host claude_code
 askthew-mcp install --host claude_code --bind <paid_bind_token>
+askthew-mcp doctor
+askthew-mcp identity status
 askthew-mcp bind
 askthew-mcp token rotate
 askthew-mcp token revoke
 askthew-mcp export
 askthew-mcp delete-me --confirm
+askthew-mcp uninstall --host claude_code
 ```
 
 `token revoke` revokes only the current token. Install-level revocation is handled by the workspace web endpoint or `delete-me`.
+`uninstall` removes the MCP config and marked agent-instructions block, but leaves the local identity and outbox on disk so you can reinstall or delete cloud data intentionally.
 
 ## Development
 

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import { spawn } from "node:child_process";
 import prompts from "prompts";
 import { AskTheWCloudClient, completeSignup, loadCloudToken, saveCloudToken, startSignup } from "./cloud-client.js";
+import { cloudTokenPath, installMetadataPath, localStorePath } from "./lib/paths.js";
 import { Outbox } from "./outbox.js";
-import { DEFAULT_SERVER_NAME, dataDirSummary, installHostConfig, packageVersion, writeBehaviorInstructions, writeInstallMetadata, } from "./install.js";
+import { DEFAULT_SERVER_NAME, dataDirSummary, installHostConfig, packageVersion, removeBehaviorInstructions, resolveSettingsPath, uninstallHostConfig, writeBehaviorInstructions, writeInstallMetadata, } from "./install.js";
 import { runStdioServer } from "./index.js";
 function usage() {
     return [
@@ -12,7 +14,10 @@ function usage() {
         "Usage:",
         "  askthew-mcp",
         "  askthew-mcp install --host <claude_code|codex|cursor> [--bind <paid-bind-token>] [--skip-auth]",
+        "  askthew-mcp uninstall --host <claude_code|codex|cursor> [--dry-run]",
         "  askthew-mcp bind [--allow-pending]",
+        "  askthew-mcp identity status [--json]",
+        "  askthew-mcp doctor [--host <claude_code|codex|cursor>] [--json]",
         "  askthew-mcp token rotate|revoke",
         "  askthew-mcp export",
         "  askthew-mcp delete-me --confirm",
@@ -170,6 +175,22 @@ async function installCommand(argv) {
         process.exitCode = 1;
     }
 }
+async function uninstallCommand(argv) {
+    const args = parseArgs(argv);
+    const hostType = requireHost(stringArg(args, "--host"));
+    const dryRun = boolArg(args, "--dry-run");
+    const config = uninstallHostConfig({
+        hostType,
+        serverName: DEFAULT_SERVER_NAME,
+        dryRun,
+    });
+    const instructions = removeBehaviorInstructions({ hostType, dryRun });
+    console.log(`${dryRun ? "Would uninstall" : "Uninstalled"} Ask The W for ${hostType}.`);
+    console.log(`${config.removed ? "Removed" : "No matching"} MCP config: ${config.settingsPath}`);
+    console.log(`${instructions.removed ? "Removed" : "No matching"} agent instructions: ${instructions.filePath}`);
+    console.log(`Local identity and outbox were left in ${dataDirSummary()}.`);
+    console.log("Run `askthew-mcp delete-me --confirm` before uninstall if you also want to delete install-scoped cloud data.");
+}
 function openBrowser(url) {
     const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
@@ -223,9 +244,121 @@ async function bindCommand(argv) {
     }
     throw new Error("Timed out waiting for workspace binding.");
 }
+function pendingOutboxCount() {
+    if (!fs.existsSync(localStorePath()))
+        return 0;
+    try {
+        return new Outbox().pendingCount();
+    }
+    catch {
+        return null;
+    }
+}
+function printObject(value, asJson) {
+    if (asJson) {
+        console.log(JSON.stringify(value, null, 2));
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        if (typeof entry === "object" && entry !== null) {
+            console.log(`${key}: ${JSON.stringify(entry)}`);
+        }
+        else {
+            console.log(`${key}: ${entry}`);
+        }
+    }
+}
+async function identityStatusCommand(argv) {
+    const args = parseArgs(argv);
+    const tokenFile = loadCloudToken();
+    const client = new AskTheWCloudClient({ apiUrl: apiUrl(args) });
+    const status = {
+        ok: true,
+        configured: Boolean(tokenFile?.token),
+        data_dir: dataDirSummary(),
+        token_path: cloudTokenPath(),
+        install_metadata_path: installMetadataPath(),
+        outbox_pending: pendingOutboxCount(),
+        api_url: stringArg(args, "--api-url") || tokenFile?.api_url || "https://app.askthew.com",
+    };
+    if (!tokenFile?.token) {
+        status.message = "No local Ask The W identity is configured. Run `askthew-mcp install --host <host>`.";
+        printObject(status, boolArg(args, "--json"));
+        return;
+    }
+    status.install_id = tokenFile.install_id;
+    status.tier = tokenFile.tier ?? "free";
+    status.token_purpose = tokenFile.token_purpose ?? "device";
+    const cloud = await client.request("/me", { method: "GET" });
+    status.cloud_ok = cloud.ok;
+    status.cloud_status = cloud.status;
+    status.cloud = cloud.body;
+    printObject(status, boolArg(args, "--json"));
+}
+async function probeHealth(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/v1/agent/health`, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+        });
+        const body = await response.json().catch(() => ({
+            ok: false,
+            code: "invalid_health_response",
+            message: "Health endpoint did not return JSON.",
+        }));
+        return { ok: response.ok && body?.ok !== false, status: response.status, body };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 0,
+            body: {
+                ok: false,
+                code: "network_error",
+                message: error instanceof Error ? error.message : "Could not reach Ask The W.",
+            },
+        };
+    }
+}
+async function doctorCommand(argv) {
+    const args = parseArgs(argv);
+    const host = stringArg(args, "--host");
+    const hostType = host ? requireHost(host) : null;
+    const baseUrl = apiUrl(args);
+    const tokenFile = loadCloudToken();
+    const health = await probeHealth(baseUrl);
+    const pendingCount = pendingOutboxCount();
+    const checks = {
+        cli_version: packageVersion(),
+        api_url: baseUrl,
+        api_health: health,
+        data_dir: dataDirSummary(),
+        token_file_exists: fs.existsSync(cloudTokenPath()),
+        install_metadata_exists: fs.existsSync(installMetadataPath()),
+        outbox_exists: fs.existsSync(localStorePath()),
+        outbox_pending: pendingCount,
+        identity_configured: Boolean(tokenFile?.token),
+    };
+    if (hostType) {
+        checks.host = hostType;
+        checks.settings_path = resolveSettingsPath({ hostType });
+    }
+    if (tokenFile?.token) {
+        const cloud = await new AskTheWCloudClient({ apiUrl: baseUrl }).request("/me", { method: "GET" });
+        checks.identity_cloud = cloud;
+    }
+    const ok = Boolean(health.ok);
+    printObject({ ok, checks }, boolArg(args, "--json"));
+    if (!ok && boolArg(args, "--strict")) {
+        process.exitCode = 1;
+    }
+}
 async function tokenCommand(argv) {
     const [action] = argv;
-    const client = new AskTheWCloudClient();
+    const args = parseArgs(argv.slice(1));
+    const client = new AskTheWCloudClient({ apiUrl: apiUrl(args) });
     if (action === "rotate") {
         const result = await client.request("/token/rotate", { method: "POST", body: "{}" });
         const body = result.body;
@@ -248,8 +381,9 @@ async function tokenCommand(argv) {
     }
     throw new Error("Usage: askthew-mcp token rotate|revoke");
 }
-async function exportCommand() {
-    const client = new AskTheWCloudClient();
+async function exportCommand(argv = []) {
+    const args = parseArgs(argv);
+    const client = new AskTheWCloudClient({ apiUrl: apiUrl(args) });
     const result = await client.request("/export", { method: "GET" });
     if (!result.ok) {
         const body = result.body;
@@ -266,7 +400,7 @@ async function deleteMeCommand(argv) {
     if (tokenFile?.tier === "paid") {
         console.error("This install is workspace-bound. Install-scoped data will be deleted; workspace data is retained.");
     }
-    const client = new AskTheWCloudClient();
+    const client = new AskTheWCloudClient({ apiUrl: apiUrl(args) });
     const result = await client.request("/me", { method: "DELETE" });
     const body = result.body;
     if (!result.ok || body.ok === false)
@@ -291,16 +425,31 @@ async function main() {
         await installCommand(argv);
         return;
     }
+    if (command === "uninstall") {
+        await uninstallCommand(argv);
+        return;
+    }
     if (command === "bind") {
         await bindCommand(argv);
         return;
     }
+    if (command === "identity") {
+        const [action, ...rest] = argv;
+        if (action !== "status")
+            throw new Error("Usage: askthew-mcp identity status [--json]");
+        await identityStatusCommand(rest);
+        return;
+    }
+    if (command === "doctor") {
+        await doctorCommand(argv);
+        return;
+    }
     if (command === "token") {
         await tokenCommand(argv);
         return;
     }
     if (command === "export") {
-        await exportCommand();
+        await exportCommand(argv);
         return;
     }
     if (command === "delete-me") {

package/dist/cloud-client.d.ts

@@ -13,6 +13,7 @@ export type CloudClientOptions = {
     fetcher?: Fetcher;
     env?: NodeJS.ProcessEnv;
 };
+export declare function trimBaseUrl(value?: string): string;
 export declare function loadCloudToken(env?: NodeJS.ProcessEnv): CloudTokenFile | null;
 export declare function saveCloudToken(tokenFile: CloudTokenFile, env?: NodeJS.ProcessEnv): void;
 export declare class AskTheWCloudClient {
@@ -24,12 +25,12 @@ export declare class AskTheWCloudClient {
     request(path: string, init?: RequestInit): Promise<{
         ok: boolean;
         status: number;
-        body: any;
+        body: Record<string, unknown>;
     }>;
     captureSignal(payload: Record<string, unknown>): Promise<{
         ok: boolean;
         status: number;
-        body: any;
+        body: Record<string, unknown>;
     }>;
     listSignals(input?: {
         sessionId?: string;
@@ -43,7 +44,7 @@ export declare class AskTheWCloudClient {
     createDecision(payload: Record<string, unknown>): Promise<{
         ok: boolean;
         status: number;
-        body: any;
+        body: Record<string, unknown>;
     }>;
     listDecisions(input?: {
         limit?: number;
@@ -55,12 +56,12 @@ export declare class AskTheWCloudClient {
     recap(input: Record<string, unknown>): Promise<{
         ok: boolean;
         status: number;
-        body: any;
+        body: Record<string, unknown>;
     }>;
     coach(input: Record<string, unknown>): Promise<{
         ok: boolean;
         status: number;
-        body: any;
+        body: Record<string, unknown>;
     }>;
 }
 export declare function startSignup(input: {
@@ -68,7 +69,11 @@ export declare function startSignup(input: {
     apiUrl?: string;
     clientHint?: string;
     fetcher?: Fetcher;
-}): Promise<any>;
+}): Promise<Record<string, unknown> | {
+    ok: boolean;
+    code: string;
+    message: string;
+}>;
 export declare function completeSignup(input: {
     email: string;
     code: string;
@@ -77,4 +82,8 @@ export declare function completeSignup(input: {
     tokenPurpose?: "conversation" | "device";
     fetcher?: Fetcher;
     env?: NodeJS.ProcessEnv;
-}): Promise<any>;
+}): Promise<Record<string, unknown> | {
+    ok: boolean;
+    code: string;
+    message: string;
+}>;

package/dist/cloud-client.js

@@ -1,7 +1,41 @@
 import { cloudTokenPath, readJsonFile, writePrivateJson } from "./lib/paths.js";
-function trimBaseUrl(value) {
+export function trimBaseUrl(value) {
     return (value?.trim() || "https://app.askthew.com").replace(/\/+$/, "");
 }
+function errorMessage(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}
+async function readResponseBody(response) {
+    const text = await response.text().catch(() => "");
+    if (!text.trim()) {
+        return {
+            ok: false,
+            code: response.ok ? "empty_response" : `http_${response.status}`,
+            message: `Ask The W returned HTTP ${response.status} with no JSON response body.`,
+        };
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+        return { ok: response.ok, value: parsed };
+    }
+    catch {
+        return {
+            ok: false,
+            code: "invalid_json_response",
+            message: `Ask The W returned HTTP ${response.status} with a non-JSON response body.`,
+        };
+    }
+}
+function networkFailure(error) {
+    return {
+        ok: false,
+        code: "network_error",
+        message: `Could not reach Ask The W: ${errorMessage(error, "network request failed")}`,
+    };
+}
 export function loadCloudToken(env = process.env) {
     return readJsonFile(cloudTokenPath(env));
 }
@@ -58,16 +92,21 @@ export class AskTheWCloudClient {
                 },
             };
         }
-        const response = await this.fetcher(`${this.apiUrl}/api/v1/agent${path}`, {
-            ...init,
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${this.token}`,
-                ...(init.headers ?? {}),
-            },
-        });
-        const body = await response.json().catch(() => ({}));
-        return { ok: response.ok, status: response.status, body };
+        try {
+            const response = await this.fetcher(`${this.apiUrl}/api/v1/agent${path}`, {
+                ...init,
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.token}`,
+                    ...(init.headers ?? {}),
+                },
+            });
+            const body = await readResponseBody(response);
+            return { ok: response.ok, status: response.status, body };
+        }
+        catch (error) {
+            return { ok: false, status: 0, body: networkFailure(error) };
+        }
     }
     async captureSignal(payload) {
         return this.request("/signals", {
@@ -117,27 +156,47 @@ export class AskTheWCloudClient {
 }
 export async function startSignup(input) {
     const base = trimBaseUrl(input.apiUrl);
-    const response = await (input.fetcher ?? fetch)(`${base}/api/v1/agent/signup`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ email: input.email, client_hint: input.clientHint }),
-    });
-    return response.json();
+    try {
+        const response = await (input.fetcher ?? fetch)(`${base}/api/v1/agent/signup`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ email: input.email, client_hint: input.clientHint }),
+        });
+        return readResponseBody(response);
+    }
+    catch (error) {
+        return networkFailure(error);
+    }
 }
 export async function completeSignup(input) {
     const base = trimBaseUrl(input.apiUrl);
-    const response = await (input.fetcher ?? fetch)(`${base}/api/v1/agent/verify`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            email: input.email,
-            code: input.code,
-            client_hint: input.clientHint,
-            token_purpose: input.tokenPurpose ?? "device",
-        }),
-    });
-    const body = await response.json();
-    if (response.ok && body?.ok && body.token && body.install_id) {
+    let response;
+    let body;
+    try {
+        response = await (input.fetcher ?? fetch)(`${base}/api/v1/agent/verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                email: input.email,
+                code: input.code,
+                client_hint: input.clientHint,
+                token_purpose: input.tokenPurpose ?? "device",
+            }),
+        });
+        body = await readResponseBody(response);
+    }
+    catch (error) {
+        return networkFailure(error);
+    }
+    if (response.ok &&
+        typeof body === "object" &&
+        body !== null &&
+        "ok" in body &&
+        body.ok &&
+        "token" in body &&
+        typeof body.token === "string" &&
+        "install_id" in body &&
+        typeof body.install_id === "string") {
         saveCloudToken({
             token: body.token,
             install_id: body.install_id,

package/dist/install.d.ts

@@ -82,6 +82,11 @@ export declare function writeBehaviorInstructions(input: InstructionInstallInput
     text: string;
     wroteFile: boolean;
 };
+export declare function removeBehaviorInstructions(input: InstructionInstallInput): {
+    filePath: string;
+    removed: boolean;
+    wroteFile: boolean;
+};
 export declare function writeInstallMetadata(input: {
     hostType: SupportedHostType;
     apiUrl?: string;

package/dist/install.js

@@ -201,8 +201,9 @@ export function uninstallHostConfig(input) {
     let next = raw;
     let removed = false;
     if (input.hostType === "codex") {
-        next = `${removeCodexTomlServer(raw, serverName)}\n`;
-        removed = next !== raw;
+        const stripped = removeCodexTomlServer(raw, serverName);
+        next = `${stripped}${stripped ? "\n" : ""}`;
+        removed = stripped.trimEnd() !== raw.trimEnd();
     }
     else {
         const parsed = raw.trim() ? JSON.parse(raw) : {};
@@ -224,9 +225,9 @@ export function uninstallHostConfig(input) {
             next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
         }
     }
-    if (!input.dryRun)
+    if (removed && !input.dryRun)
         fs.writeFileSync(settingsPath, next, "utf8");
-    return { settingsPath, removed, wroteFile: !input.dryRun };
+    return { settingsPath, removed, wroteFile: removed && !input.dryRun };
 }
 export function instructionFileForHost(hostType, cwd = process.cwd()) {
     return path.join(path.resolve(cwd), hostType === "claude_code" ? "CLAUDE.md" : "AGENTS.md");
@@ -269,6 +270,38 @@ export function writeBehaviorInstructions(input) {
         wroteFile: !input.dryRun,
     };
 }
+function removeMarkedBlock(existing) {
+    const start = existing.indexOf(INSTRUCTIONS_START);
+    const end = existing.indexOf(INSTRUCTIONS_END);
+    if (start < 0 || end < start) {
+        return { text: existing, removed: false };
+    }
+    const after = end + INSTRUCTIONS_END.length;
+    const text = `${existing.slice(0, start).trimEnd()}${existing.slice(after).trimStart() ? "\n\n" : ""}${existing
+        .slice(after)
+        .trimStart()}`.trimEnd();
+    return { text: text ? `${text}\n` : "", removed: true };
+}
+export function removeBehaviorInstructions(input) {
+    const filePath = instructionFileForHost(input.hostType, input.cwd);
+    if (!fs.existsSync(filePath)) {
+        return {
+            filePath,
+            removed: false,
+            wroteFile: false,
+        };
+    }
+    const existing = fs.readFileSync(filePath, "utf8");
+    const next = removeMarkedBlock(existing);
+    if (next.removed && !input.dryRun) {
+        fs.writeFileSync(filePath, next.text, "utf8");
+    }
+    return {
+        filePath,
+        removed: next.removed,
+        wroteFile: next.removed && !input.dryRun,
+    };
+}
 export function writeInstallMetadata(input) {
     const metadata = {
         host: input.hostType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "private": false,
   "description": "Ask The W cloud-shim MCP plugin for coding-agent decisions and signals.",
   "type": "module",