mcpill 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.13.0
+
+- Non-blocking user-defined hooks (`## Hook:` entries with `command:` but no `blocking: true`) are now distributed into the standalone `install.js` and wired into the target agent's config during `<pill> install --agent claude-code` (claude-code only in v1)
+- `HAS_USER_HOOKS` flag in `install.js` is independent of `HAS_BLOCKING_HOOKS` — pills with only informational hooks produce a correct success message
+- `<pill> install --agent codex` prints a warning when the pill defines hooks that Codex cannot run
+- `mcpill compile` auto-generates a `UserPromptSubmit` hook for the pill's first declared tool and merges it into `.claude/settings.json`; hook is a no-op until `~/.<pill-name>/state.json` sets `enabled: true` (written by `<pill-name> install`); idempotent; skipped by `--no-hooks`
+
 ## 1.12.0
 
 - Fix: `runValidate` used `console.log` for the `✓ Valid:` summary line, writing plain text to stdout and breaking stdio MCP transport (clients tried to parse it as JSON-RPC and crashed). Output is now sent to `process.stderr.write` instead.
@@ -62,7 +69,7 @@
 
 ## 1.2.4
 
-- Fix: bump `mcpill-runtime` to `^0.1.2` — `0.1.0` dist imported `@ruco-ai/mcpster` (old scoped name), causing `ERR_MODULE_NOT_FOUND` on global install
+- Fix: bump `mcpill-runtime` to `^0.1.2` — `0.1.0` dist imported `,ruco-ai/mcpster` (old scoped name), causing `ERR_MODULE_NOT_FOUND` on global install
 
 ## 1.2.3
 
@@ -92,7 +99,7 @@
 
 ## 1.1.0
 
-- Renamed to `mcpill`; `@ruco-ai/mcpill` deprecated — install `mcpill` instead
-- `mcpill-runtime` renamed from `@ruco-ai/mcpill-runtime`
+- Renamed to `mcpill`; `,ruco-ai/mcpill` deprecated — install `mcpill` instead
+- `mcpill-runtime` renamed from `,ruco-ai/mcpill-runtime`
 - Canonical home: https://mcpill.ruco.dev
 - Added `repository`, `homepage`, and `bugs` metadata to package.json

package/README.md

@@ -2,7 +2,7 @@
 
 CLI for building, validating, and publishing MCP servers using the pill format.
 
-> **Renamed from `@ruco-ai/mcpill`** — if you have the scoped package, run `npm uninstall -g @ruco-ai/mcpill && npm install -g mcpill`.
+> **Renamed from `,ruco-ai/mcpill`** — if you have the scoped package, run `npm uninstall -g ,ruco-ai/mcpill && npm install -g mcpill`.
 
 ## Install
 
@@ -60,10 +60,13 @@ Compiles `server.md` + `tools/*.md` + `prompts/*.md` into a `.<name>/` pill arti
 mcpill compile              # forward: source → pill
 mcpill compile --to-md      # reverse: pill → source
 mcpill compile --strict     # error on missing tool handlers (default: stub)
-mcpill compile --no-hooks   # skip writing PreToolUse hook to .claude/settings.json
+mcpill compile --no-hooks   # skip writing all hooks to .claude/settings.json
 ```
 
-Compile also writes a `PreToolUse` hook into `.claude/settings.json` that warns Claude to use the pill's MCP tools instead of native file tools (`Read`, `Bash`, etc.). Hook mappings are read from two sources, merged at compile time — rerun `mcpill compile` after any change:
+Compile also writes two auto-generated hooks into `.claude/settings.json`:
+
+- **`PreToolUse`** — warns Claude to use the pill's MCP tools instead of native file tools (`Read`, `Bash`, etc.) when the pill declares a `replaces` field.
+- **`UserPromptSubmit`** — on every user message, injects context instructing Claude to call the pill's first declared tool before responding. Present whenever the pill has at least one tool; no-op until `~/.<pill-name>/state.json` sets `enabled: true` (written by `<pill-name> install`). Hook mappings are read from two sources, merged at compile time — rerun `mcpill compile` after any change:
 
 - **`PILL.md`** (recommended) — add a `replaces` field to any `## Tool:` section:
 
@@ -97,6 +100,10 @@ At runtime the gate script exits 1 (blocking the tool call) until `mcp__{pill}__
 
 `required_tool` must name a tool defined in the same pill; `mcpill compile` aborts with an error if it doesn't.
 
+#### Non-blocking hooks and distribution
+
+`## Hook:` entries without `blocking: true` but with a `command` field emit soft hooks (context injectors) to `.claude/settings.json`. They are also bundled into the standalone distribution: when an end user runs `<pill> install --agent claude-code`, these hooks are wired into their config automatically. Codex installs print a warning when the pill defines hooks that Codex cannot run.
+
 ### `mcpill validate`
 
 Validates all pill directories (`.<name>/`) in the project root.

package/dist/cli.js

@@ -97,6 +97,7 @@ Instructions for building an mcpill MCP server from a filled \`PILL.md\`.
 4. **Run** \`mcpill compile\`.
    - If the pill's \`AGENT.md\` has a \`## Tools\` table with a \`replaces\` column, compile writes a \`PreToolUse\` hook into \`.claude/settings.json\` that warns Claude to use the pill's MCP tools instead of native file tools.
    - If PILL.md has \`## Hook:\` sections (or \`.mcpill/server/hooks/*.md\` files exist), compile writes those hooks into \`.claude/settings.json\` under the corresponding event key. These coexist with the auto-generated \`replaces:\` hooks \u2014 both are merged.
+   - Compile also auto-generates a \`UserPromptSubmit\` hook for the pill's first declared tool. When the pill is active (\`~/.\${pillName}/state.json\` has \`enabled: true\`), this hook injects context on every user message instructing Claude to call the main tool first. The hook is always present but is a no-op until state.json is written (typically by \`\${pillName} install\`).
    - To skip all hook generation: \`mcpill compile --no-hooks\`.
 
 5. **Report** what was generated and show the user the next commands:
@@ -422,6 +423,10 @@ After writing \`PILL.md\`, tell the user:
 > "PILL.md is ready. Review the tool descriptions, then say: **Build this PILL.md**"
 
 Do not run \`mcpill compile\` or generate source files yourself \u2014 that is the build phase, handled separately by \`pill-agent-guide.md\`.
+
+### Auto-generated UserPromptSubmit hook
+
+When the user runs \`mcpill compile\`, a \`UserPromptSubmit\` hook is automatically written to \`.claude/settings.json\`. It injects context on every user message instructing Claude to call the pill's first tool before responding. The hook is always present but is a no-op until \`~/.\${pillName}/state.json\` sets \`enabled: true\` \u2014 this file is written by \`\${pillName} install\` during the distribution flow. To opt out of all hook generation the user can pass \`--no-hooks\` to compile.
 `;
 function makePillUserGuideMd(projectName) {
   return `# ${projectName} \u2014 mcpill user guide
@@ -548,7 +553,6 @@ async function runInit(opts) {
 // src/commands/run.ts
 import path7 from "path";
 import fs6 from "fs";
-import os from "os";
 import { z as z2 } from "mcpill-runtime";
 import { createServer, applySetup } from "mcpster";
 
@@ -1264,32 +1268,6 @@ async function runValidate(baseDir) {
 }
 
 // src/commands/run.ts
-function patchJson(filePath, patcher) {
-  if (!fs6.existsSync(filePath)) return;
-  try {
-    const obj = JSON.parse(fs6.readFileSync(filePath, "utf-8"));
-    patcher(obj);
-    fs6.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n", "utf-8");
-  } catch {
-  }
-}
-function desktopConfigPaths() {
-  const home = os.homedir();
-  if (process.platform === "win32") {
-    const appData = process.env.APPDATA ?? path7.join(home, "AppData", "Roaming");
-    return [path7.join(appData, "Claude", "claude_desktop_config.json")];
-  }
-  return [path7.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")];
-}
-function unregisterSync(name, baseDir) {
-  const remove = (obj) => {
-    const servers = obj.mcpServers;
-    if (servers) delete servers[name];
-  };
-  patchJson(path7.join(baseDir, ".claude", "settings.json"), remove);
-  patchJson(path7.join(os.homedir(), ".claude.json"), remove);
-  for (const p of desktopConfigPaths()) patchJson(p, remove);
-}
 async function runServer(opts) {
   const baseDir = path7.resolve(opts.dir ?? process.cwd());
   await runValidate(baseDir);
@@ -1351,16 +1329,6 @@ async function runServer(opts) {
         args: ["run", "--dir", baseDir]
       }
     });
-    const cleanup = () => unregisterSync(name, baseDir);
-    process.on("exit", cleanup);
-    process.on("SIGINT", () => {
-      cleanup();
-      process.exit(0);
-    });
-    process.on("SIGTERM", () => {
-      cleanup();
-      process.exit(0);
-    });
   }
   try {
     await server.start();
@@ -1433,7 +1401,7 @@ ${tool.description}
 `;
     }
     if (tool.handler !== void 0) {
-      const cleanHandler = tool.handler.split("\n").filter((l) => !l.trim().startsWith("// @handler:") && !l.trim().startsWith("// @end-handler:")).join("\n").trim();
+      const cleanHandler = tool.handler.split("\n").filter((l) => !l.trim().startsWith("// ,handler:") && !l.trim().startsWith("// ,end-handler:")).join("\n").trim();
       md += `
 ## Handler
 
@@ -1485,7 +1453,7 @@ function dedent(s) {
 }
 function extractHandlers(toolsJsContent) {
   const result = /* @__PURE__ */ new Map();
-  const markerRegex = /[ \t]*\/\/ @handler:([^\n]+)\n([\s\S]*?)\n[ \t]*\/\/ @end-handler:[^\n]+/g;
+  const markerRegex = /[ \t]*\/\/ ,handler:([^\n]+)\n([\s\S]*?)\n[ \t]*\/\/ ,end-handler:[^\n]+/g;
   let match;
   while ((match = markerRegex.exec(toolsJsContent)) !== null) {
     result.set(match[1].trim(), dedent(match[2]).trim());
@@ -1781,9 +1749,21 @@ function installClaudeCode() {
       });
     }
   }
+  if (HAS_USER_HOOKS) {
+    if (!s.hooks) s.hooks = {};
+    for (const uh of USER_HOOKS) {
+      if (!s.hooks[uh.event]) s.hooks[uh.event] = [];
+      s.hooks[uh.event] = s.hooks[uh.event].filter(e => e.hooks?.[0]?.command !== uh.command);
+      const entry = uh.event === 'UserPromptSubmit'
+        ? { hooks: [{ type: 'command', command: uh.command }] }
+        : { matcher: uh.matcher ?? '.*', hooks: [{ type: 'command', command: uh.command }] };
+      s.hooks[uh.event].push(entry);
+    }
+  }
   writeJson(settingsPath, s);
   activatePill();
-  if (!silent) process.stdout.write('[mcpill] info: ' + (wasInstalled ? 'reinstalled' : 'installed') + ' ' + PILL_NAME + (HAS_BLOCKING_HOOKS ? '' : ' (no blocking hooks \u2014 MCP server only)') + ' for claude-code\\n');
+  const _hookSuffix = (HAS_BLOCKING_HOOKS || HAS_USER_HOOKS) ? '' : ' (no hooks \u2014 MCP server only)';
+  if (!silent) process.stdout.write('[mcpill] info: ' + (wasInstalled ? 'reinstalled' : 'installed') + ' ' + PILL_NAME + _hookSuffix + ' for claude-code\\n');
 }
 
 function uninstallClaudeCode() {
@@ -1795,6 +1775,13 @@ function uninstallClaudeCode() {
     const gateMarker = '/' + PILL_NAME + '/hooks/';
     if (s.hooks.PreToolUse) s.hooks.PreToolUse = s.hooks.PreToolUse.filter(e => !e.hooks?.[0]?.command?.includes(gateMarker));
     if (s.hooks.PostToolUse) s.hooks.PostToolUse = s.hooks.PostToolUse.filter(e => !e.matcher?.startsWith('mcp__' + PILL_NAME + '__'));
+    if (HAS_USER_HOOKS) {
+      for (const uh of USER_HOOKS) {
+        if (s.hooks[uh.event]) {
+          s.hooks[uh.event] = s.hooks[uh.event].filter(e => e.hooks?.[0]?.command !== uh.command);
+        }
+      }
+    }
   }
   writeJson(settingsPath, s);
   deactivatePill();
@@ -1949,7 +1936,12 @@ function installCodex() {
   existing += '\\n\\n[mcp_servers.' + PILL_NAME + ']\\ncommand = "node"\\nargs = [' + JSON.stringify(INDEX_PATH) + ']\\n';
   writeFileSync(configPath, existing.trim() + '\\n');
   activatePill();
-  if (!silent) process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for codex (MCP server only \u2014 hooks not yet supported for codex)\\n');
+  if (!silent) {
+    if (HAS_USER_HOOKS || HAS_BLOCKING_HOOKS) {
+      process.stderr.write('[mcpill] warning: ' + PILL_NAME + ' defines hooks that Codex does not support \u2014 hook-dependent features will not work\\n');
+    }
+    process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for codex (MCP server only \u2014 hooks not yet supported for codex)\\n');
+  }
 }
 
 function uninstallCodex() {
@@ -1981,10 +1973,15 @@ if (command === 'install') {
   }
 }
 `;
-function generateStandaloneInstallJs(pillName, version, blockingHooks) {
+function generateStandaloneInstallJs(pillName, version, blockingHooks, userHooks) {
   const hooksData = blockingHooks.map((h) => ({
     required_tool: h.required_tool
   }));
+  const userHooksData = userHooks.map((h) => ({
+    event: h.event,
+    command: h.command,
+    ...h.matcher !== void 0 ? { matcher: h.matcher } : {}
+  }));
   const constants = [
     `#!/usr/bin/env node`,
     `import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs';`,
@@ -1999,6 +1996,8 @@ function generateStandaloneInstallJs(pillName, version, blockingHooks) {
     `const PILL_VERSION = ${JSON.stringify(version)};`,
     `const HAS_BLOCKING_HOOKS = ${blockingHooks.length > 0};`,
     `const HOOKS = ${JSON.stringify(hooksData, null, 2)};`,
+    `const HAS_USER_HOOKS = ${userHooks.length > 0};`,
+    `const USER_HOOKS = ${JSON.stringify(userHooksData, null, 2)};`,
     `const VALID_AGENTS = ['claude-code', 'cursor', 'windsurf', 'github-copilot', 'codex'];`,
     ``,
     `const argv = process.argv.slice(2);`,
@@ -2044,7 +2043,7 @@ function generateDistPackageJson(pillName, version, opts) {
   }
   return JSON.stringify(pkg2, null, 2) + "\n";
 }
-function emitStandalonePackage(baseDir, pillName, version, toolsJsContent, doc, blockingHooks, opts = {}) {
+function emitStandalonePackage(baseDir, pillName, version, toolsJsContent, doc, blockingHooks, opts = {}, userHooks = []) {
   const distDir = join5(baseDir, ".mcpill", "dist", pillName);
   const hooksDir = join5(distDir, "hooks");
   mkdirSync3(hooksDir, { recursive: true });
@@ -2055,7 +2054,7 @@ function emitStandalonePackage(baseDir, pillName, version, toolsJsContent, doc,
     join5(distDir, "index.js"),
     generateStandaloneIndexJs(pillName, version, doc.prompts, doc.resources, blockingHookTools)
   );
-  writeFileSync3(join5(distDir, "install.js"), generateStandaloneInstallJs(pillName, version, blockingHooks));
+  writeFileSync3(join5(distDir, "install.js"), generateStandaloneInstallJs(pillName, version, blockingHooks, userHooks));
   if (blockingHooks.length > 0) {
     writeFileSync3(join5(hooksDir, "pre-tool-gate.js"), generateStandaloneGateScript(pillName, blockingHooks));
     writeFileSync3(join5(hooksDir, "post-analysis-flag.js"), generateStandaloneFlagScript(pillName));
@@ -2086,9 +2085,9 @@ export default [`];
       ...schemaLines,
       `    },`,
       `    handler:`,
-      `      // @handler:${tool.name}`,
+      `      // ,handler:${tool.name}`,
       handlerBody,
-      `      // @end-handler:${tool.name}`,
+      `      // ,end-handler:${tool.name}`,
       `    ,`,
       `  },`
     );
@@ -2258,7 +2257,18 @@ async function runCompile(opts) {
     mergeUserHooksIntoSettings(baseDir, generatedEntries);
     console.log(`\u2713 .claude/settings.json updated with ${blockingHooks.length} blocking hook(s)`);
   }
-  emitStandalonePackage(baseDir, mergedDoc.config.name, pillVersion, toolsJsContent, mergedDoc, blockingHooks, { postinstall: pillPostinstall });
+  if (mergedDoc.tools.length > 0) {
+    const mainToolName = mergedDoc.tools[0].name;
+    const pillName = mergedDoc.config.name;
+    const pillNameUpper = pillName.toUpperCase();
+    const additionalContext = `${pillNameUpper} ACTIVE: You MUST call mcp__${pillName}__${mainToolName} with the user text before responding. If results are relevant, mention them in your reply.`;
+    const hookJson = JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext } });
+    const autoHookCommand = `enabled=$(jq -r '.enabled // false' ~/.${pillName}/state.json 2>/dev/null || echo false); [ "$enabled" = "true" ] && printf '${hookJson}' || true`;
+    mergeUserHooksIntoSettings(baseDir, [{ event: "UserPromptSubmit", command: autoHookCommand }]);
+    console.log(`\u2713 .claude/settings.json updated with UserPromptSubmit auto-hook (main tool: ${mainToolName})`);
+  }
+  const distributedUserHooks = regularHooks.filter((h) => !!h.command);
+  emitStandalonePackage(baseDir, mergedDoc.config.name, pillVersion, toolsJsContent, mergedDoc, blockingHooks, { postinstall: pillPostinstall }, distributedUserHooks);
   console.log(`\u2713 .mcpill/dist/${mergedDoc.config.name}/ updated`);
 }
 
@@ -2296,6 +2306,14 @@ import path9 from "path";
 async function runPublish(dir, access) {
   const baseDir = path9.resolve(dir);
   await runPack(baseDir);
+  const whoami = spawnSync("npm", ["whoami"], { stdio: "pipe", encoding: "utf-8" });
+  if (whoami.status !== 0) {
+    console.log("Not logged in to npm \u2014 running npm login...");
+    const login = spawnSync("npm", ["login"], { stdio: "inherit" });
+    if (login.status !== 0) {
+      throw new Error("npm login failed");
+    }
+  }
   const result = spawnSync("npm", ["publish", "--access", access], {
     cwd: baseDir,
     stdio: "inherit"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpill",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "type": "module",
   "description": "CLI for building, validating, and publishing MCP servers using the pill format.",
   "homepage": "https://mcpill.ruco.dev",