@askthew/mcp-plugin 0.2.2 → 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, sendInstallHeartbeat, } 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,11 +111,20 @@ 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

package/dist/install.d.ts

@@ -66,4 +66,13 @@ 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

@@ -2,6 +2,8 @@ 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);
 }
@@ -69,7 +71,7 @@ export function formatInstallCommand(input) {
 }
 export function verificationNextStep(hostType) {
     const hostLabel = hostType === "claude_code" ? "Claude Code" : "Codex";
-    return `Refresh Ask The W to confirm the plugin was seen. Restart ${hostLabel} if it is already open, then send a first setup check. 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({
@@ -133,3 +135,66 @@ export async function sendInstallHeartbeat(input) {
     });
     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.2",
+  "version": "0.2.3",
   "private": false,
   "description": "Ask The W MCP connector for capturing compact coding-agent session signals.",
   "type": "module",