@askthew/mcp-plugin 0.2.8 → 0.4.2

package/README.md

@@ -1,31 +1,55 @@
-# Ask The W MCP Plugin
+# Ask The W 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 --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.
+
+Founder-friendly promise: install from npm, 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.
 
 ## What It Does
 
-- Installs an Ask The W MCP server entry into a supported local client.
+- Installs an Ask The W plugin 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 \
+  --email you@founder.com
+```
+
+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.
+
+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`.
 
-Create a workspace token in Ask The W, then run the installer from your coding agent or terminal.
+## 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.
+
+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,15 +81,17 @@ 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:
+The installer also adds safe, marked project instructions to both markdown convention files plus any host-specific rule file:
 
 - Codex: `AGENTS.md`
 - 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
 {
@@ -129,19 +155,42 @@ The public tool surface is intentionally small.
     "evidence": [{ "role": "user | assistant | system", "excerpt": "string" }],
     "filesTouched": ["string"],
     "commandsRun": ["string"],
-    "metadata": {}
+    "metadata": {},
+    "echo": "summary | full"
   }
 }
 ```
 
-Use compact summaries and short evidence excerpts. Do not send full transcripts.
+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:
+
+| 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. |
+
+Free PLG helpers:
+
+```bash
+npx @askthew/mcp-plugin install-hook --pre-commit
+npx @askthew/mcp-plugin digest --weekly
+```
+
+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.
 
 ## 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/auth-pending.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth-pending.test.js

@@ -0,0 +1,56 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { clearPendingAuth, pendingAuth, pendingAuthForEmail, savePendingAuth } from "./lib/auth-pending.js";
+import { configPath } from "./lib/paths.js";
+function withTempEnv(fn) {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-auth-pending-"));
+    try {
+        return fn({ ASKTHEW_DATA_DIR: dataDir });
+    }
+    finally {
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+}
+test("pending auth stores and resolves the request id for the matching email", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "Founder@Example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+            telemetryOptOut: true,
+        }, env);
+        const pending = pendingAuthForEmail("founder@example.com", env);
+        assert.equal(pending?.requestId, "request_1");
+        assert.equal(pending?.telemetryOptOut, true);
+        assert.equal(pendingAuth(env)?.email, "Founder@Example.com");
+    });
+});
+test("pending auth ignores other emails and clears expired requests", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "founder@example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() - 1_000).toISOString(),
+        }, env);
+        assert.equal(pendingAuthForEmail("other@example.com", env), null);
+        assert.equal(pendingAuthForEmail("founder@example.com", env), null);
+        const config = JSON.parse(fs.readFileSync(configPath(env), "utf8"));
+        assert.equal("pendingAuth" in config, false);
+    });
+});
+test("pending auth clear keeps the config file private and removes only pending auth", () => {
+    withTempEnv((env) => {
+        savePendingAuth({
+            email: "founder@example.com",
+            requestId: "request_1",
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+        }, env);
+        clearPendingAuth(env);
+        const config = JSON.parse(fs.readFileSync(configPath(env), "utf8"));
+        assert.equal("pendingAuth" in config, false);
+        assert.equal((fs.statSync(configPath(env)).mode & 0o777), 0o600);
+    });
+});

package/dist/cli-actions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli-actions.test.js

@@ -0,0 +1,71 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LocalStore } from "./lib/local-store.js";
+import { buildWeeklyDigest, installPreCommitHook, preCommitDecisionGap, writeWeeklyDigest, } from "./lib/cli-actions.js";
+test("pre-commit gap detects staged implementation updates without linked decisions", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-hook-store-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    const signal = store.insertSignal({
+        sessionId: "s1",
+        sequence: 1,
+        kind: "implementation_update",
+        summary: "Changed onboarding page.",
+        filesTouched: ["apps/app/page.tsx"],
+        commandsRun: [],
+    });
+    const gap = preCommitDecisionGap({
+        store,
+        stagedFiles: ["apps/app/page.tsx"],
+        now: new Date(signal.capturedAt),
+    });
+    assert.equal(gap.missing, true);
+    assert.deepEqual(gap.matchedSignals, [signal.id]);
+    store.createDecision({
+        rawContent: "Keep onboarding page copy direct.",
+        sessionId: "s1",
+        sourceSignalIds: [signal.id],
+    });
+    const resolved = preCommitDecisionGap({
+        store,
+        stagedFiles: ["apps/app/page.tsx"],
+        now: new Date(signal.capturedAt),
+    });
+    assert.equal(resolved.missing, false);
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+test("pre-commit hook installer writes the documented inline prompt hook", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-hook-install-"));
+    execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+    const hookPath = installPreCommitHook({ cwd: dir });
+    const hook = fs.readFileSync(hookPath, "utf8");
+    assert.match(hook, /Ask The W pre-commit decision prompt/);
+    assert.match(hook, /@askthew\/mcp-plugin@latest hook-check --pre-commit/);
+    assert.equal((fs.statSync(hookPath).mode & 0o111) > 0, true);
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+test("weekly digest writes markdown with documented footer", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-digest-store-"));
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-digest-out-"));
+    const store = LocalStore.open({ path: path.join(dir, "store.sqlite") });
+    store.createDecision({
+        rawContent: "Ship the free-tier polish.",
+        sessionId: "s1",
+        status: "committed",
+    });
+    const now = new Date("2026-05-06T12:00:00.000Z");
+    const digest = buildWeeklyDigest({ store, now });
+    assert.match(digest, /# Ask The W Weekly Decision Digest 2026-19/);
+    assert.match(digest, /Ship the free-tier polish/);
+    assert.match(digest, /_Captured by Ask The W\._/);
+    const filePath = writeWeeklyDigest({ store, now, outputDir: outDir });
+    assert.equal(path.basename(filePath), "askthew-digest-2026-19.md");
+    assert.match(fs.readFileSync(filePath, "utf8"), /_Captured by Ask The W\._/);
+    store.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.rmSync(outDir, { recursive: true, force: true });
+});

package/dist/cli.d.ts

@@ -1,2 +1,11 @@
 #!/usr/bin/env node
+import { requestMagicLinkCode as requestMagicLinkCodeDefault, verifyMagicLinkCode as verifyMagicLinkCodeDefault } from "./lib/auth-magic-link.js";
+import { tryRegisterFreeInstall } from "./lib/free-install-registration.js";
+type AuthCommandDeps = {
+    log?: (message: string) => void;
+    requestMagicLinkCode?: typeof requestMagicLinkCodeDefault;
+    verifyMagicLinkCode?: typeof verifyMagicLinkCodeDefault;
+    registerFreeInstall?: typeof tryRegisterFreeInstall;
+};
+export declare function runAuthCommand(argv: string[], deps?: AuthCommandDeps): Promise<void>;
 export {};