@askthew/mcp-plugin 0.2.8 → 0.4.0

package/README.md

@@ -1,6 +1,15 @@
 # Ask The W MCP Plugin
 
-Connect a local coding agent to Ask The W.
+Connect a local coding agent to Ask The W. The fastest path is free and local-first:
+
+```bash
+npx -y --prefer-online @askthew/mcp-plugin@latest install --host claude_code --free
+npx @askthew/mcp-plugin auth login --email you@founder.com
+```
+
+This captures decisions and session signals to `~/.askthew/store.sqlite` and lets your agent run `review_decisions`, `review_session`, and `analyze_session` without onboarding into the web app.
+
+Founder-friendly promise: install from npm, magic-link login, then ask your coding agent to review the last session. You should see value in under 60 seconds.
 
 This package runs a small MCP server that lets Codex, Claude Code, Cursor, and other MCP-capable tools send compact work-session signals to an Ask The W workspace.
 
@@ -9,23 +18,38 @@ This package runs a small MCP server that lets Codex, Claude Code, Cursor, and o
 - Installs an Ask The W MCP server entry into a supported local client.
 - Preserves existing MCP servers and settings.
 - Adds marked project instructions so future coding-agent sessions know when to send Ask The W updates.
-- Sends a startup heartbeat so Ask The W can show the plugin as installed.
-- Exposes one primary MCP tool: `capture_session_signal`.
+- 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.
 - 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.
 
 ## What It Does Not Do
 
 - It does not send full transcripts by default.
-- It does not infer decisions locally.
+- 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 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.
 
-## Install
+## Free Local Install
+
+```bash
+npx -y --prefer-online @askthew/mcp-plugin@latest install \
+  --host claude_code \
+  --free
+
+npx @askthew/mcp-plugin auth login --email you@founder.com
+```
+
+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. We do tie aggregate counts, stack, and tool usage to your email for upgrade onboarding. Opt out with `--no-telemetry`, `ASKTHEW_TELEMETRY=off`, or `askthew-mcp telemetry opt-out`.
+
+## Workspace Install
+
+Create a workspace token in Ask The W at `/decisions/settings/connectors`, then run the installer from your coding agent or terminal. Treat the token like a password; anyone with it can write compact source signals into that workspace.
 
-Create a workspace token in Ask The W, then run the installer from your coding agent or terminal.
+Use setup tokens promptly. They expire after 24 hours if the connector never sends activity. Once connected, active tokens renew while in use and expire after 90 days without activity. Rotate the token in Ask The W if it is exposed or if the connector reports an expired or revoked token.
 
 Codex:
 
@@ -57,7 +81,9 @@ npx -y --prefer-online @askthew/mcp-plugin@latest install \
   --server-name "askthew"
 ```
 
-After install, restart or reload your coding agent if needed.
+After install, restart or reload your coding agent if needed. At the start of every new coding-agent session in this repo, before plan mode or exploration, call `capture_session_signal` with `kind: "setup_complete"` and choose "Always allow" if the host prompts for tool permission. If you realize later that the startup call was missed, send it immediately with `metadata.recovered_missed_startup=true`.
+
+Claude Desktop and Cowork custom connectors use Ask The W's hosted Remote MCP URL instead of this local `npx` installer. In Ask The W, create a Claude Remote URL from the plugin source, then paste it into Claude's custom connector form as the Remote MCP server URL. The URL must be public HTTPS; `localhost`, `127.0.0.1`, LAN IPs, VPN-only hosts, and firewall-blocked servers will fail because Claude connects from Anthropic's cloud. Treat the URL like a password and rotate it if it leaks.
 
 The installer also adds safe, marked project instructions:
 
@@ -65,7 +91,7 @@ The installer also adds safe, marked project instructions:
 - Claude Code: `CLAUDE.md`
 - Cursor: `.cursor/rules/askthew.mdc`
 
-These instructions tell the coding agent to send compact Ask The W updates after meaningful direction changes, implementation work, verification, long-session checkpoints, and final summaries. Existing instruction files are preserved.
+These instructions tell the coding agent to send compact Ask The W updates at the start of every new repo session, after meaningful direction changes, implementation work, verification, long-session checkpoints, and final summaries. Existing instruction files are preserved.
 
 To skip this behavior, pass:
 
@@ -116,7 +142,7 @@ Optional environment variables:
 
 ## Tool Contract
 
-The public tool surface is intentionally small.
+The session-signal tool remains the main automatic capture path.
 
 ```json
 {
@@ -136,12 +162,24 @@ The public tool surface is intentionally small.
 
 Use compact summaries and short evidence excerpts. Do not send full transcripts.
 
+The plugin also exposes v1 API tools that map to the app's authenticated routes:
+
+| Tool | Purpose |
+|---|---|
+| `list_decisions`, `get_decision`, `create_decision`, `update_decision`, `delete_decision` | Work with decision feed entries. |
+| `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. |
+
+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.
+
 ## Troubleshooting
 
 - Empty `list_mcp_resources` or `list_mcp_resource_templates` results are normal. This connector is tool-driven.
 - If Ask The W shows "Waiting for install", restart or reload your coding agent.
-- If Ask The W shows "Installed", restart or reload your coding agent if it was already open. On the next Ask The W setup check, choose "Always allow" if your coding agent asks for tool permission.
-- If a token fails, rotate it in Ask The W and rerun the installer.
+- If Ask The W shows "Installed", restart or reload your coding agent if it was already open. At the start of the next repo session, the coding agent should call `capture_session_signal` with `kind: "setup_complete"` before plan mode; choose "Always allow" if it asks for tool permission.
+- For Claude Desktop or Cowork, set `capture_session_signal` to "Always allow" in connector Tool permissions when that panel is available, or choose "Allow always" on the first tool prompt.
+- If a token fails, check whether the error says missing, malformed, expired, or revoked. Copy the full token if it is malformed; rotate it in Ask The W and rerun the installer if it expired or was revoked.
 
 ## Development
 

package/dist/cli.js

@@ -1,14 +1,27 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
 import { createAskTheWMcpServer } from "./index.js";
+import { requestMagicLinkCode, verifyMagicLinkCode } from "./lib/auth-magic-link.js";
+import { credentialsPath, ensureAskTheWDataDir } from "./lib/paths.js";
+import { loadCliCredentials } from "./lib/free-tier-policy.js";
+import { LocalStore } from "./lib/local-store.js";
+import { buildTelemetryPayload } from "./lib/telemetry.js";
+import { syncDryRun, uploadLocalStore } from "./lib/upgrade-sync.js";
 import { createHostConfigSnippet, formatInstallCommand, installBehaviorInstructions, installHostConfig, sendInstallHeartbeat, } from "./install.js";
 function usage() {
     return [
-        "AskTheW Coding Agent Connector",
+        "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 [--api-url <url>] [--server-name <name>]",
+        "  askthew-mcp auth login --email <email> [--code <code>] [--no-telemetry]",
+        "  askthew-mcp auth logout | status",
+        "  askthew-mcp telemetry status | opt-out | opt-in | preview",
+        "  askthew-mcp local stats | reset --hard",
+        "  askthew-mcp sync upload [--dry-run]",
         "  askthew-mcp print-config --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>]",
     ].join("\n");
 }
@@ -21,6 +34,7 @@ function parseInstallArgs(argv) {
     let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
     let dryRun = false;
     let installAgentInstructions = true;
+    let free = false;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--dry-run") {
@@ -31,6 +45,10 @@ function parseInstallArgs(argv) {
             installAgentInstructions = false;
             continue;
         }
+        if (argument === "--free") {
+            free = true;
+            continue;
+        }
         const next = argv[index + 1];
         if (!next) {
             throw new Error(`Missing value for ${argument}.`);
@@ -73,14 +91,14 @@ function parseInstallArgs(argv) {
     if (!hostType) {
         throw new Error("Missing required --host argument.");
     }
-    if (!token) {
+    if (!free && !token) {
         throw new Error("Missing required --token argument.");
     }
     if (!apiUrl) {
-        throw new Error("Missing required --api-url argument.");
+        apiUrl = "https://app.askthew.com";
     }
     if (!serverName) {
-        throw new Error("Missing required --server-name argument.");
+        serverName = "askthew";
     }
     return {
         hostType,
@@ -91,6 +109,7 @@ function parseInstallArgs(argv) {
         serverName,
         dryRun,
         installAgentInstructions,
+        free,
     };
 }
 function normalizeInstallToken(token) {
@@ -117,19 +136,21 @@ async function main() {
                 dryRun: options.dryRun,
             })
             : null;
-        const heartbeatSent = result.wroteFile
+        const heartbeatSent = result.wroteFile && !options.free
             ? await sendInstallHeartbeat(options).catch(() => false)
             : false;
-        console.log(result.wroteFile ? "AskTheW plugin install complete." : "AskTheW plugin dry run complete.");
+        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.path}`);
         }
         console.log(`Install command: ${formatInstallCommand(options)}`);
         if (result.wroteFile) {
-            console.log(heartbeatSent
-                ? "Ask The W setup check sent. Refresh the app to confirm the plugin shows Installed."
-                : "Ask The W setup check could not be sent yet. Restart or reload your coding app, then refresh Ask The W.");
+            console.log(options.free
+                ? "Free local mode installed. Next step: run `askthew-mcp auth login --email you@example.com`."
+                : heartbeatSent
+                    ? "Ask The W install heartbeat sent. Refresh the app to confirm the plugin shows Installed."
+                    : "Ask The W install heartbeat could not be sent yet. Restart or reload your coding app, then refresh Ask The W.");
         }
         console.log(`Next step: ${result.nextStep}`);
         if (!result.wroteFile) {
@@ -138,6 +159,29 @@ async function main() {
         }
         return;
     }
+    if (command === "auth") {
+        await runAuthCommand(argv);
+        return;
+    }
+    if (command === "telemetry") {
+        await runTelemetryCommand(argv);
+        return;
+    }
+    if (command === "local") {
+        await runLocalCommand(argv);
+        return;
+    }
+    if (command === "sync") {
+        await runSyncCommand(argv);
+        return;
+    }
+    if (command === "upgrade") {
+        console.log("Open https://askthew.com/mcp 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.");
+        }
+        return;
+    }
     if (command) {
         throw new Error(`Unknown command "${command}".\n\n${usage()}`);
     }
@@ -145,12 +189,106 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+function argValue(argv, name) {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+async function runAuthCommand(argv) {
+    const [subcommand] = argv;
+    if (subcommand === "status") {
+        const credentials = loadCliCredentials();
+        console.log(credentials
+            ? `Logged in as ${credentials.email ?? credentials.userId}. Telemetry: ${credentials.telemetryOptOut ? "off" : "on"}`
+            : "Not logged in. Run `askthew-mcp auth login --email you@example.com`.");
+        return;
+    }
+    if (subcommand === "logout") {
+        const file = credentialsPath();
+        if (fs.existsSync(file))
+            fs.rmSync(file);
+        console.log("Logged out of Ask The W local free tier.");
+        return;
+    }
+    if (subcommand !== "login") {
+        throw new Error("Usage: askthew-mcp auth login --email <email> [--code <code>] [--no-telemetry]");
+    }
+    ensureAskTheWDataDir();
+    const email = argValue(argv, "--email")?.trim();
+    if (!email)
+        throw new Error("Missing --email.");
+    const noTelemetry = argv.includes("--no-telemetry");
+    const requested = await requestMagicLinkCode({ email, deviceLabel: "askthew-mcp" });
+    console.log(`Code sent to ${email}. It expires at ${requested.expiresAt}.`);
+    if (requested.devCode)
+        console.log(`Dev code: ${requested.devCode}`);
+    const code = argValue(argv, "--code")?.trim() ?? requested.devCode;
+    if (!code) {
+        throw new Error("Re-run with --code <6-digit-code> after checking your email.");
+    }
+    const credentials = await verifyMagicLinkCode({
+        requestId: requested.requestId,
+        code,
+        telemetryOptOut: noTelemetry,
+    });
+    console.log(`Logged in. Account status: ${credentials.accountStatus}. Credentials stored with mode 0600.`);
+}
+async function runTelemetryCommand(argv) {
+    const [subcommand] = argv;
+    const credentials = loadCliCredentials();
+    if (!credentials)
+        throw new Error("Not logged in. Run `askthew-mcp auth login` first.");
+    if (subcommand === "status") {
+        console.log(`Telemetry: ${credentials.telemetryOptOut ? "off" : "on"}`);
+        return;
+    }
+    if (subcommand === "opt-out" || subcommand === "opt-in") {
+        const next = { ...credentials, telemetryOptOut: subcommand === "opt-out" };
+        fs.writeFileSync(credentialsPath(), `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        fs.chmodSync(credentialsPath(), 0o600);
+        console.log(`Telemetry: ${next.telemetryOptOut ? "off" : "on"}`);
+        return;
+    }
+    if (subcommand === "preview") {
+        const store = LocalStore.open();
+        console.log(JSON.stringify(buildTelemetryPayload({ store, credentials }), null, 2));
+        return;
+    }
+    throw new Error("Usage: askthew-mcp telemetry status | opt-out | opt-in | preview");
+}
+async function runLocalCommand(argv) {
+    const [subcommand, flag] = argv;
+    const store = LocalStore.open();
+    if (subcommand === "stats") {
+        console.log(JSON.stringify(store.stats(), null, 2));
+        return;
+    }
+    if (subcommand === "reset" && flag === "--hard") {
+        const dir = ensureAskTheWDataDir();
+        fs.rmSync(dir, { recursive: true, force: true });
+        console.log("Local Ask The W data removed.");
+        return;
+    }
+    throw new Error("Usage: askthew-mcp local stats | reset --hard");
+}
+async function runSyncCommand(argv) {
+    if (argv[0] !== "upload")
+        throw new Error("Usage: askthew-mcp sync upload [--dry-run]");
+    const credentials = loadCliCredentials();
+    if (!credentials)
+        throw new Error("Not logged in. Run `askthew-mcp auth login` first.");
+    const store = LocalStore.open();
+    if (argv.includes("--dry-run")) {
+        console.log(JSON.stringify(syncDryRun(store), null, 2));
+        return;
+    }
+    console.log(JSON.stringify(await uploadLocalStore({ store, credentials }), null, 2));
+}
 main().catch((error) => {
     if (error instanceof Error) {
         console.error(error.message);
     }
     else {
-        console.error("AskTheW plugin failed to start.", error);
+        console.error("Ask The W plugin failed to start.", error);
     }
     process.exit(1);
 });

package/dist/index.d.ts

@@ -82,21 +82,18 @@ export declare const provenanceSignalSchema: z.ZodObject<{
     installToken?: string | undefined;
 }>;
 export type ProvenanceSignal = z.infer<typeof provenanceSignalSchema>;
-export declare function inferFunctionalArea(signal: Pick<ProvenanceSignal, "filesAffected">): string;
 export declare function redactProvenanceSignal(input: ProvenanceSignal): {
+    decision: string;
+    rationale: string;
+    framework: string | undefined;
+    filesAffected: string[];
     originatingPrompt: string | undefined;
-    metadata: {
-        functional_area: string;
-    };
+    installToken: string | undefined;
+    metadata: Record<string, unknown>;
     sessionId: string;
     source: string;
-    decision: string;
-    rationale: string;
     confidence: number;
-    filesAffected: string[];
-    framework?: string | undefined;
     pendingApproval?: boolean | undefined;
-    installToken?: string | undefined;
 };
 export declare function redactCodingSessionSignal(input: CodingSessionSignal): {
     summary: string;
@@ -104,12 +101,27 @@ export declare function redactCodingSessionSignal(input: CodingSessionSignal): {
         excerpt: string;
         role: "user" | "assistant" | "system";
     }[];
+    filesTouched: string[];
     commandsRun: string[];
     metadata: Record<string, unknown>;
     sessionId: string;
     sequence: number;
     kind: "setup_complete" | "session_checkpoint" | "direction_change" | "implementation_update" | "verification_result" | "final_summary";
-    filesTouched: string[];
 };
+export interface AskTheWMcpServerOptions {
+    credentials?: {
+        installToken?: string;
+        userId?: string;
+        apiKey?: string;
+        serverName?: string;
+        clientId?: string;
+        clientLabel?: string;
+        hostType?: "claude_code" | "codex" | "cursor";
+    };
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    runtimeMetadata?: Record<string, unknown> | (() => Record<string, unknown>);
+    sendStartupHeartbeat?: boolean;
+}
 export declare function normalizeInstallTokenInput(token: string | undefined): string;
-export declare function createAskTheWMcpServer(): McpServer;
+export declare function createAskTheWMcpServer(options?: AskTheWMcpServerOptions): McpServer;