@askthew/mcp-plugin 0.2.1 → 0.2.3

package/README.md

@@ -8,6 +8,7 @@ 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 that the plugin was seen.
 - Exposes one primary MCP tool: `capture_session_signal`.
 - Redacts obvious secrets from summaries, evidence excerpts, commands, and metadata before sending.
@@ -58,6 +59,20 @@ npx -y @askthew/mcp-plugin@latest install \
 
 After install, restart or reload your coding agent if needed.
 
+The installer also adds safe, marked project instructions:
+
+- 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.
+
+To skip this behavior, pass:
+
+```bash
+--no-agent-instructions
+```
+
 ## Configuration
 
 The installer writes an MCP server entry like this:

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createAskTheWMcpServer } from "./index.js";
-import { createHostConfigSnippet, formatInstallCommand, installHostConfig, } from "./install.js";
+import { createHostConfigSnippet, formatInstallCommand, installBehaviorInstructions, installHostConfig, sendInstallHeartbeat, } from "./install.js";
 function usage() {
     return [
         "AskTheW 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]",
+        "  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 print-config --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>]",
     ].join("\n");
 }
@@ -20,12 +20,17 @@ function parseInstallArgs(argv) {
     let apiUrl = process.env.ASKTHEW_API_URL?.trim() || "";
     let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
     let dryRun = false;
+    let installAgentInstructions = true;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--dry-run") {
             dryRun = true;
             continue;
         }
+        if (argument === "--no-agent-instructions") {
+            installAgentInstructions = false;
+            continue;
+        }
         const next = argv[index + 1];
         if (!next) {
             throw new Error(`Missing value for ${argument}.`);
@@ -85,6 +90,7 @@ function parseInstallArgs(argv) {
         apiUrl,
         serverName,
         dryRun,
+        installAgentInstructions,
     };
 }
 function normalizeInstallToken(token) {
@@ -105,9 +111,26 @@ async function main() {
     if (command === "install") {
         const options = parseInstallArgs(argv);
         const result = installHostConfig(options);
+        const instructions = options.installAgentInstructions
+            ? installBehaviorInstructions({
+                hostType: options.hostType,
+                dryRun: options.dryRun,
+            })
+            : null;
+        const heartbeatSent = result.wroteFile
+            ? await sendInstallHeartbeat(options).catch(() => false)
+            : false;
         console.log(result.wroteFile ? "AskTheW plugin install complete." : "AskTheW 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 was seen."
+                : "Ask The W setup check 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) {
             console.log("");

package/dist/install.d.ts

@@ -62,4 +62,17 @@ export declare function installHostConfig(input: InstallHostConfigInput): {
     wroteFile: boolean;
     nextStep: string;
 };
+export declare function sendInstallHeartbeat(input: HostConfigInput & {
+    cwd?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<boolean>;
+export declare function installBehaviorInstructions(input: {
+    hostType: SupportedHostType;
+    cwd?: string;
+    dryRun?: boolean;
+}): {
+    path: string;
+    wroteFile: boolean;
+    content: string;
+};
 export {};

package/dist/install.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { resolvePluginScope } from "./scope.js";
+const ASKTHEW_INSTRUCTIONS_START = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_START -->";
+const ASKTHEW_INSTRUCTIONS_END = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_END -->";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -68,7 +71,7 @@ export function formatInstallCommand(input) {
 }
 export function verificationNextStep(hostType) {
     const hostLabel = hostType === "claude_code" ? "Claude Code" : "Codex";
-    return `Restart ${hostLabel} if it is already open, then send a setup_complete signal with capture_session_signal. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
+    return `Refresh Ask The W to confirm the plugin was seen. Restart ${hostLabel} if it is already open. The installed project instructions tell the coding agent when to send Ask The W updates automatically. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
 }
 export function installHostConfig(input) {
     const settingsPath = resolveSettingsPath({
@@ -109,3 +112,89 @@ export function installHostConfig(input) {
         nextStep: verificationNextStep(input.hostType),
     };
 }
+export async function sendInstallHeartbeat(input) {
+    const fetcher = input.fetchImpl ?? fetch;
+    const scope = resolvePluginScope(input.cwd ?? process.cwd());
+    const apiUrl = input.apiUrl.replace(/\/$/, "");
+    const response = await fetcher(`${apiUrl}/api/connectors/mcp/heartbeat`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            installToken: input.token,
+            clientId: input.clientId || input.hostType,
+            clientLabel: input.clientLabel,
+            hostType: input.hostType,
+            serverName: input.serverName,
+            repoName: scope.repoName,
+            ...(scope.repoRoot ? { repoRoot: scope.repoRoot } : {}),
+            ...(scope.appPath ? { appPath: scope.appPath } : {}),
+            ...(scope.serviceName ? { serviceName: scope.serviceName } : {}),
+        }),
+    });
+    return response.ok;
+}
+function behaviorInstructions(hostType) {
+    const hostLabel = hostType === "claude_code" ? "Claude Code" : hostType === "cursor" ? "Cursor" : "Codex";
+    return [
+        ASKTHEW_INSTRUCTIONS_START,
+        "",
+        "## Ask The W Plugin",
+        "",
+        `This workspace uses the Ask The W Plugin. When working in this repo with ${hostLabel}, send compact Ask The W updates automatically with the MCP tool \`capture_session_signal\`.`,
+        "",
+        "Send an update:",
+        "- after the user accepts or rejects product, architecture, or implementation direction",
+        "- after meaningful implementation changes",
+        "- after tests, builds, lint, or other verification",
+        "- every 8-12 turns in long sessions",
+        "- at the final summary",
+        "",
+        "Keep updates compact: short summary, minimal evidence excerpts, files touched, commands run, and useful metadata. Do not send full transcripts. Redact obvious secrets before sending.",
+        "",
+        "If this is the first session after install or reload, send a `setup_complete` update first.",
+        "",
+        ASKTHEW_INSTRUCTIONS_END,
+        "",
+    ].join("\n");
+}
+function cursorBehaviorInstructions() {
+    return [
+        "---",
+        "description: Ask The W Plugin capture rules",
+        "alwaysApply: true",
+        "---",
+        "",
+        behaviorInstructions("cursor"),
+    ].join("\n");
+}
+function upsertMarkedBlock(existing, block) {
+    const startIndex = existing.indexOf(ASKTHEW_INSTRUCTIONS_START);
+    const endIndex = existing.indexOf(ASKTHEW_INSTRUCTIONS_END);
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+        const afterEnd = endIndex + ASKTHEW_INSTRUCTIONS_END.length;
+        return `${existing.slice(0, startIndex).trimEnd()}\n\n${block.trimEnd()}\n${existing.slice(afterEnd).trimStart()}`.trimEnd() + "\n";
+    }
+    return `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block.trimEnd()}\n`;
+}
+export function installBehaviorInstructions(input) {
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const instructionsPath = input.hostType === "claude_code"
+        ? path.join(cwd, "CLAUDE.md")
+        : input.hostType === "cursor"
+            ? path.join(cwd, ".cursor", "rules", "askthew.mdc")
+            : path.join(cwd, "AGENTS.md");
+    const block = input.hostType === "cursor" ? cursorBehaviorInstructions() : behaviorInstructions(input.hostType);
+    const existing = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, "utf8") : "";
+    const next = input.hostType === "cursor" ? block : upsertMarkedBlock(existing, block);
+    if (!input.dryRun) {
+        fs.mkdirSync(path.dirname(instructionsPath), { recursive: true });
+        fs.writeFileSync(instructionsPath, next, "utf8");
+    }
+    return {
+        path: instructionsPath,
+        wroteFile: !input.dryRun,
+        content: next,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "description": "Ask The W MCP connector for capturing compact coding-agent session signals.",
   "type": "module",