@askthew/mcp-plugin 0.2.2 → 0.2.4

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,9 +59,38 @@ 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:
+The installer writes the MCP server into the host's native MCP configuration so it appears in that host's MCP server list:
+
+- Codex: `~/.codex/config.toml`
+- Claude Code: `~/.claude.json`, scoped to the current project
+- Cursor: `~/.cursor/mcp.json`
+
+Codex example:
+
+```toml
+[mcp_servers.askthew]
+command = "npx"
+args = ["-y", "@askthew/mcp-plugin@latest"]
+env = { ASKTHEW_INSTALL_TOKEN = "<ASKTHEW_INSTALL_TOKEN>", ASKTHEW_HOST_TYPE = "codex", ASKTHEW_API_URL = "https://app.askthew.com/", ASKTHEW_SERVER_NAME = "askthew" }
+```
+
+Claude Code and Cursor use an MCP JSON entry like this:
 
 ```json
 {

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

@@ -10,6 +10,7 @@ interface HostConfigInput {
 interface InstallHostConfigInput extends HostConfigInput {
     dryRun?: boolean;
     homeDirectory?: string;
+    cwd?: string;
 }
 export declare function resolveSettingsPath(input: {
     hostType: SupportedHostType;
@@ -28,6 +29,10 @@ export declare function createServerEntry(input: HostConfigInput): {
     };
 };
 export declare function createHostConfigSnippet(input: HostConfigInput): {
+    settingsPath: string;
+    snippet: string;
+    json: string;
+} | {
     settingsPath: string;
     snippet: {
         mcpServers: {
@@ -66,4 +71,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,13 +2,20 @@ 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);
 }
 export function resolveSettingsPath(input) {
     const homeDirectory = input.homeDirectory ?? os.homedir();
-    const configDirectory = input.hostType === "claude_code" ? ".claude" : ".codex";
-    return path.join(homeDirectory, configDirectory, "settings.json");
+    if (input.hostType === "codex") {
+        return path.join(homeDirectory, ".codex", "config.toml");
+    }
+    if (input.hostType === "cursor") {
+        return path.join(homeDirectory, ".cursor", "mcp.json");
+    }
+    return path.join(homeDirectory, ".claude.json");
 }
 export function createServerEntry(input) {
     return {
@@ -25,6 +32,14 @@ export function createServerEntry(input) {
     };
 }
 export function createHostConfigSnippet(input) {
+    if (input.hostType === "codex") {
+        const toml = createCodexTomlSection(input);
+        return {
+            settingsPath: resolveSettingsPath({ hostType: input.hostType }),
+            snippet: toml,
+            json: toml,
+        };
+    }
     const snippet = {
         mcpServers: {
             [input.serverName]: createServerEntry(input),
@@ -36,6 +51,63 @@ export function createHostConfigSnippet(input) {
         json: JSON.stringify(snippet, null, 2),
     };
 }
+function escapeTomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlKey(value) {
+    return /^[A-Za-z0-9_-]+$/.test(value) ? value : escapeTomlString(value);
+}
+function createCodexTomlSection(input) {
+    const entry = createServerEntry(input);
+    const args = entry.args.map(escapeTomlString).join(", ");
+    const env = Object.entries(entry.env)
+        .map(([key, value]) => `${key} = ${escapeTomlString(String(value))}`)
+        .join(", ");
+    return [
+        `[mcp_servers.${tomlKey(input.serverName)}]`,
+        `command = ${escapeTomlString(entry.command)}`,
+        `args = [${args}]`,
+        `env = { ${env} }`,
+    ].join("\n");
+}
+function removeCodexTomlServer(content, serverName) {
+    const escapedServerName = serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const quotedServerName = escapeTomlString(serverName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const sectionPattern = new RegExp(`\\n?\\[mcp_servers\\.(?:${escapedServerName}|${quotedServerName})\\]\\n[\\s\\S]*?(?=\\n\\[[^\\]]+\\]|$)`, "g");
+    return content.replace(sectionPattern, "").trimEnd();
+}
+function mergeCodexSettings(input) {
+    let next = input.existingSettings.trimEnd();
+    if (input.serverName !== "askthew") {
+        next = removeCodexTomlServer(next, "askthew");
+    }
+    next = removeCodexTomlServer(next, input.serverName);
+    return `${next}${next ? "\n\n" : ""}${createCodexTomlSection(input)}\n`;
+}
+function mergeClaudeCodeSettings(input) {
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const existingSettings = isRecord(input.existingSettings) ? input.existingSettings : {};
+    const existingProjects = isRecord(existingSettings.projects) ? existingSettings.projects : {};
+    const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
+    const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
+    const nextMcpServers = { ...existingMcpServers };
+    if (input.serverName !== "askthew" && "askthew" in nextMcpServers) {
+        delete nextMcpServers.askthew;
+    }
+    return {
+        ...existingSettings,
+        projects: {
+            ...existingProjects,
+            [cwd]: {
+                ...existingProject,
+                mcpServers: {
+                    ...nextMcpServers,
+                    [input.serverName]: createServerEntry(input),
+                },
+            },
+        },
+    };
+}
 export function mergeHostSettings(input) {
     const existingSettings = isRecord(input.existingSettings) ? input.existingSettings : {};
     const existingMcpServers = isRecord(existingSettings.mcpServers) ? existingSettings.mcpServers : {};
@@ -68,8 +140,8 @@ export function formatInstallCommand(input) {
     ].join(" ");
 }
 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.`;
+    const hostLabel = hostType === "claude_code" ? "Claude Code" : hostType === "cursor" ? "Cursor" : "Codex";
+    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({
@@ -77,11 +149,15 @@ export function installHostConfig(input) {
         homeDirectory: input.homeDirectory,
     });
     let existingSettings = {};
+    let existingText = "";
     if (fs.existsSync(settingsPath)) {
         const raw = fs.readFileSync(settingsPath, "utf8");
+        existingText = raw;
         if (raw.trim().length > 0) {
             try {
-                existingSettings = JSON.parse(raw);
+                if (input.hostType !== "codex") {
+                    existingSettings = JSON.parse(raw);
+                }
             }
             catch (error) {
                 const detail = error instanceof Error ? error.message : "Unknown parse failure.";
@@ -89,7 +165,7 @@ export function installHostConfig(input) {
             }
         }
     }
-    const merged = mergeHostSettings({
+    const hostInput = {
         existingSettings,
         hostType: input.hostType,
         token: input.token,
@@ -97,11 +173,21 @@ export function installHostConfig(input) {
         serverName: input.serverName,
         clientId: input.clientId,
         clientLabel: input.clientLabel,
-    });
-    const json = JSON.stringify(merged, null, 2);
+    };
+    const json = input.hostType === "codex"
+        ? mergeCodexSettings({
+            ...hostInput,
+            existingSettings: existingText,
+        })
+        : JSON.stringify(input.hostType === "claude_code"
+            ? mergeClaudeCodeSettings({
+                ...hostInput,
+                cwd: input.cwd,
+            })
+            : mergeHostSettings(hostInput), null, 2);
     if (!input.dryRun) {
         fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-        fs.writeFileSync(settingsPath, `${json}\n`, "utf8");
+        fs.writeFileSync(settingsPath, json.endsWith("\n") ? json : `${json}\n`, "utf8");
     }
     return {
         settingsPath,
@@ -133,3 +219,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.4",
   "private": false,
   "description": "Ask The W MCP connector for capturing compact coding-agent session signals.",
   "type": "module",