mcpill 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.9.0
+
+- `blocking: true` field on `PILL.md` `## Hook:` blocks; `mcpill compile` generates a `.mjs` `PreToolUse` gate script (exits 1 until a required tool has run) and a `PostToolUse` flag script
+- `required_tool`, `gate_window_seconds` (default 120 s), and multiline `instructions` fields supported on blocking hooks
+- Compile-time validation: `required_tool` must name a known tool; error surfaced during `mcpill compile`
+
+## 1.8.0
+
+- `mcpill run` (stdio) now auto-registers the server in Claude config on start and auto-unregisters on SIGINT, SIGTERM, and process exit — no manual step required
+- `--register` flag and `mcpill unregister` command removed; lifecycle management is now automatic
+
 ## 1.7.0
 
 - `mcpill run` is now side-effect-free by default — stopping the process disconnects the server; no Claude config is written

package/README.md

@@ -20,8 +20,7 @@ Describe your server in plain English, let Claude generate the source files.
 mcpill init                        # scaffolds PILL.md + example source files
 # fill PILL.md                     # describe your server: tools, resources, prompts
 # tell Claude: "Build this PILL.md" # agent generates source files + runs compile
-mcpill run                         # start the server (transient — stops when you do)
-mcpill run --register              # or: register so Claude manages it persistently
+mcpill run                         # start the server — registered while running, removed on exit
 ```
 
 `PILL.md` embeds the agent instructions — Claude knows exactly what to generate and how.
@@ -79,6 +78,25 @@ Compile also writes a `PreToolUse` hook into `.claude/settings.json` that warns
 
 - **`AGENT.md`** — a `## Tools` table with a `Replaces` column (existing format). AGENT.md wins on name conflicts.
 
+#### Blocking hooks
+
+For mandatory workflow steps, add a `## Hook:` section to `PILL.md` with `blocking: true`. Compile generates a hard-enforcement gate instead of a soft reminder:
+
+```markdown
+## Hook: my-hook
+
+trigger: PreToolUse
+blocking: true
+required_tool: analyze-english
+gate_window_seconds: 120
+instructions: |
+  Before calling any other tool, call mcp__my-pill__analyze-english first.
+```
+
+At runtime the gate script exits 1 (blocking the tool call) until `mcp__{pill}__analyze-english` has run within the window. After it runs, the flag script records the timestamp and the gate passes for `gate_window_seconds` seconds (default 120). Pill's own MCP tools are always allowed through. The gate is fail-open — if the pill's state file is missing, the gate passes.
+
+`required_tool` must name a tool defined in the same pill; `mcpill compile` aborts with an error if it doesn't.
+
 ### `mcpill validate`
 
 Validates all pill directories (`.<name>/`) in the project root.
@@ -88,23 +106,11 @@ Validates all pill directories (`.<name>/`) in the project root.
 Starts the MCP server from the pill artifact.
 
 ```bash
-mcpill run                        # stdio (default)
+mcpill run                        # stdio (default) — registered while running, removed on exit
 mcpill run --transport http --port 3333
-mcpill run --register             # also write server entry to Claude config
-```
-
-`--register` is opt-in. Without it, running the server has no side effects on Claude's configuration — stopping the process fully disconnects it.
-
-### `mcpill unregister`
-
-Removes the server entry from all Claude config files — the inverse of `mcpill run --register`.
-
-```bash
-mcpill unregister
-mcpill unregister --dir <path>
 ```
 
-Removes from `.claude/settings.json` (project scope), `~/.claude.json` (user scope), and the Claude Desktop config. Prints what was removed, or reports if the server was not registered.
+For stdio transport, the server entry is automatically written to Claude's config on start and removed on exit (SIGINT, SIGTERM, or normal process exit). HTTP transport is self-hosted — Claude connects to a URL, so no registration occurs.
 
 ### `mcpill pack`
 

package/dist/cli.js

@@ -548,6 +548,7 @@ 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";
 
@@ -755,12 +756,45 @@ function extractFencedBlock(body, lang) {
 }
 function parseKvBlock(body) {
   const result = {};
-  for (const line of body.split("\n")) {
+  const lines = body.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
     const colonIdx = line.indexOf(":");
-    if (colonIdx === -1) continue;
+    if (colonIdx === -1) {
+      i++;
+      continue;
+    }
     const key = line.slice(0, colonIdx).trim();
     const value = line.slice(colonIdx + 1).trim();
-    if (key) result[key] = value;
+    if (!key) {
+      i++;
+      continue;
+    }
+    if (value === "|") {
+      i++;
+      const blockLines = [];
+      let baseIndent = -1;
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        const trimmed = nextLine.trimStart();
+        if (trimmed === "") {
+          blockLines.push("");
+          i++;
+          continue;
+        }
+        const indent = nextLine.length - trimmed.length;
+        if (baseIndent === -1) baseIndent = indent;
+        if (indent < baseIndent) break;
+        blockLines.push(nextLine.slice(baseIndent));
+        i++;
+      }
+      while (blockLines.length > 0 && blockLines[blockLines.length - 1] === "") blockLines.pop();
+      result[key] = blockLines.join("\n");
+    } else {
+      result[key] = value;
+      i++;
+    }
   }
   return result;
 }
@@ -975,13 +1009,31 @@ function parsePillMdHooks(content) {
   for (const piece of pieces) {
     if (!piece.toLowerCase().startsWith("hook:")) continue;
     const nlIdx = piece.indexOf("\n");
+    const sectionTitle = (nlIdx === -1 ? piece : piece.slice(0, nlIdx)).trim();
+    const hookName = sectionTitle.slice("hook:".length).trim();
     const body = nlIdx === -1 ? "" : piece.slice(nlIdx + 1);
     const kv = parseKvBlock(body);
     const trigger = kv["trigger"]?.trim();
     const matcher = kv["matcher"]?.trim();
     const command = kv["command"]?.trim();
-    if (!trigger || !command) continue;
-    hooks.push({ event: trigger, ...matcher ? { matcher } : {}, command });
+    const blocking = kv["blocking"]?.trim().toLowerCase() === "true";
+    if (!trigger || !command && !blocking) continue;
+    const entry = {
+      ...hookName ? { name: hookName } : {},
+      event: trigger,
+      ...matcher ? { matcher } : {},
+      ...command ? { command } : {},
+      ...blocking ? { blocking: true } : {}
+    };
+    if (blocking) {
+      const requiredTool = kv["required_tool"]?.trim();
+      if (requiredTool) entry.required_tool = requiredTool;
+      const windowRaw = kv["gate_window_seconds"]?.trim();
+      if (windowRaw) entry.gate_window_seconds = parseInt(windowRaw, 10);
+      const instructions = kv["instructions"]?.trim();
+      if (instructions) entry.instructions = instructions;
+    }
+    hooks.push(entry);
   }
   return hooks;
 }
@@ -991,8 +1043,23 @@ function parseHookFile(content) {
   const trigger = kv["trigger"]?.trim();
   const matcher = kv["matcher"]?.trim();
   const command = kv["command"]?.trim();
-  if (!trigger || !command) return null;
-  return { event: trigger, ...matcher ? { matcher } : {}, command };
+  const blocking = kv["blocking"]?.trim().toLowerCase() === "true";
+  if (!trigger || !command && !blocking) return null;
+  const entry = {
+    event: trigger,
+    ...matcher ? { matcher } : {},
+    ...command ? { command } : {},
+    ...blocking ? { blocking: true } : {}
+  };
+  if (blocking) {
+    const requiredTool = kv["required_tool"]?.trim();
+    if (requiredTool) entry.required_tool = requiredTool;
+    const windowRaw = kv["gate_window_seconds"]?.trim();
+    if (windowRaw) entry.gate_window_seconds = parseInt(windowRaw, 10);
+    const instructions = kv["instructions"]?.trim();
+    if (instructions) entry.instructions = instructions;
+  }
+  return entry;
 }
 function mergeUserHooksIntoSettings(baseDir, hookBlocks) {
   if (hookBlocks.length === 0) return;
@@ -1039,6 +1106,91 @@ function mergeHookIntoSettings(baseDir, hookEntry) {
   mkdirSync(claudeDir, { recursive: true });
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
+function generateGateScript(pillName, requiredTool, windowSeconds, instructions) {
+  const instrJson = JSON.stringify(instructions);
+  return [
+    `import { readFileSync, existsSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const REQUIRED_TOOL = ${JSON.stringify(requiredTool)};`,
+    `const GATE_WINDOW_SECONDS = ${windowSeconds};`,
+    `const INSTRUCTIONS = ${instrJson};`,
+    ``,
+    `const raw = readFileSync(0, 'utf-8');`,
+    `const input = JSON.parse(raw);`,
+    `const toolName = input.tool_name ?? '';`,
+    ``,
+    `if (toolName.startsWith(\`mcp__\${PILL_NAME}__\`)) process.exit(0);`,
+    ``,
+    `const stateFile = join(homedir(), \`.\${PILL_NAME}\`, 'state.json');`,
+    `if (!existsSync(stateFile)) process.exit(0);`,
+    ``,
+    `const state = JSON.parse(readFileSync(stateFile, 'utf-8'));`,
+    `if (state.enabled === false) process.exit(0);`,
+    ``,
+    `const flagFile = join(homedir(), \`.\${PILL_NAME}\`, \`last_\${REQUIRED_TOOL}_run.json\`);`,
+    `if (existsSync(flagFile)) {`,
+    `  const flag = JSON.parse(readFileSync(flagFile, 'utf-8'));`,
+    `  const elapsedMs = Date.now() - new Date(flag.timestamp).getTime();`,
+    `  if (elapsedMs <= GATE_WINDOW_SECONDS * 1000) process.exit(0);`,
+    `}`,
+    ``,
+    `process.stderr.write(INSTRUCTIONS + '\\n');`,
+    `process.exit(1);`,
+    ``
+  ].join("\n");
+}
+function generateFlagScript(pillName, requiredTool) {
+  return [
+    `import { writeFileSync, mkdirSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const REQUIRED_TOOL = ${JSON.stringify(requiredTool)};`,
+    ``,
+    `const dir = join(homedir(), \`.\${PILL_NAME}\`);`,
+    `const flagFile = join(dir, \`last_\${REQUIRED_TOOL}_run.json\`);`,
+    ``,
+    `try {`,
+    `  mkdirSync(dir, { recursive: true });`,
+    `  writeFileSync(flagFile, JSON.stringify({ timestamp: new Date().toISOString() }));`,
+    `} catch (e) {`,
+    `  process.stderr.write(\`[\${PILL_NAME}] warning: could not write flag file: \${e.message}\\n\`);`,
+    `}`,
+    ``
+  ].join("\n");
+}
+function applyBlockingHookScripts(baseDir, pillName, hook) {
+  const hooksDir = join3(baseDir, ".mcpill", "server", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+  const hookName = hook.name;
+  const requiredTool = hook.required_tool;
+  const windowSeconds = hook.gate_window_seconds ?? 120;
+  const instructions = hook.instructions ?? `[mcpill:${pillName}] Run mcp__${pillName}__${requiredTool} before calling other tools.`;
+  writeFileSync(
+    join3(hooksDir, `${hookName}-gate.mjs`),
+    generateGateScript(pillName, requiredTool, windowSeconds, instructions)
+  );
+  writeFileSync(
+    join3(hooksDir, `${hookName}-flag.mjs`),
+    generateFlagScript(pillName, requiredTool)
+  );
+  return [
+    {
+      event: "PreToolUse",
+      matcher: ".*",
+      command: `node .mcpill/server/hooks/${hookName}-gate.mjs`
+    },
+    {
+      event: "PostToolUse",
+      matcher: `mcp__${pillName}__${requiredTool}`,
+      command: `node .mcpill/server/hooks/${hookName}-flag.mjs`
+    }
+  ];
+}
 
 // src/commands/validate.ts
 async function validateOne(mcpillDir) {
@@ -1106,6 +1258,32 @@ 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);
@@ -1157,7 +1335,7 @@ async function runServer(opts) {
       resolver: async () => content
     });
   }
-  if (opts.register) {
+  if (transport === "stdio") {
     applySetup(name, tools.map((t) => t.name), {
       projectPath: baseDir,
       permissions: "restrictive",
@@ -1167,6 +1345,16 @@ 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();
@@ -1512,9 +1700,26 @@ async function runCompile(opts) {
     }
   }
   const allUserHooks = [...pillHooks, ...fileHooks];
-  if (allUserHooks.length > 0) {
-    mergeUserHooksIntoSettings(baseDir, allUserHooks);
-    console.log(`\u2713 .claude/settings.json updated with ${allUserHooks.length} user-defined hook(s)`);
+  const blockingHooks = allUserHooks.filter((h) => h.blocking);
+  const regularHooks = allUserHooks.filter((h) => !h.blocking);
+  for (const hook of blockingHooks) {
+    if (!hook.name) throw new Error(`blocking hook is missing a name`);
+    if (!hook.required_tool) throw new Error(`blocking hook '${hook.name}' is missing required_tool`);
+    const toolExists = mergedDoc.tools.some((t) => t.name === hook.required_tool);
+    if (!toolExists) {
+      throw new Error(`blocking hook '${hook.name}' references unknown tool '${hook.required_tool}'`);
+    }
+  }
+  if (regularHooks.length > 0) {
+    mergeUserHooksIntoSettings(baseDir, regularHooks);
+    console.log(`\u2713 .claude/settings.json updated with ${regularHooks.length} user-defined hook(s)`);
+  }
+  if (blockingHooks.length > 0) {
+    const generatedEntries = blockingHooks.flatMap(
+      (hook) => applyBlockingHookScripts(baseDir, mergedDoc.config.name, hook)
+    );
+    mergeUserHooksIntoSettings(baseDir, generatedEntries);
+    console.log(`\u2713 .claude/settings.json updated with ${blockingHooks.length} blocking hook(s)`);
   }
 }
 
@@ -1561,72 +1766,6 @@ async function runPublish(dir, access) {
   }
 }
 
-// src/commands/unregister.ts
-import path10 from "path";
-import fs8 from "fs";
-import os from "os";
-function patchJson(filePath, patcher) {
-  if (!fs8.existsSync(filePath)) return false;
-  try {
-    const obj = JSON.parse(fs8.readFileSync(filePath, "utf-8"));
-    patcher(obj);
-    fs8.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n", "utf-8");
-    return true;
-  } catch {
-    return false;
-  }
-}
-function desktopConfigPaths() {
-  const home = os.homedir();
-  if (process.platform === "win32") {
-    const appData = process.env.APPDATA ?? path10.join(home, "AppData", "Roaming");
-    return [path10.join(appData, "Claude", "claude_desktop_config.json")];
-  }
-  return [path10.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")];
-}
-async function runUnregister(opts) {
-  const baseDir = path10.resolve(opts.dir ?? process.cwd());
-  const mcpillDir = path10.join(baseDir, ".mcpill", "server");
-  const config = await loadConfig(mcpillDir);
-  const { name } = config;
-  let removed = 0;
-  const settingsPath = path10.join(baseDir, ".claude", "settings.json");
-  const removedProject = patchJson(settingsPath, (obj) => {
-    const servers = obj.mcpServers;
-    if (servers && name in servers) {
-      delete servers[name];
-      removed++;
-    }
-  });
-  if (removedProject) process.stderr.write(`removed "${name}" from .claude/settings.json
-`);
-  const claudeJsonPath = path10.join(os.homedir(), ".claude.json");
-  const removedUser = patchJson(claudeJsonPath, (obj) => {
-    const servers = obj.mcpServers;
-    if (servers && name in servers) {
-      delete servers[name];
-      removed++;
-    }
-  });
-  if (removedUser) process.stderr.write(`removed "${name}" from ~/.claude.json
-`);
-  for (const configPath of desktopConfigPaths()) {
-    const removedDesktop = patchJson(configPath, (obj) => {
-      const servers = obj.mcpServers;
-      if (servers && name in servers) {
-        delete servers[name];
-        removed++;
-      }
-    });
-    if (removedDesktop) process.stderr.write(`removed "${name}" from Claude Desktop config
-`);
-  }
-  if (removed === 0) {
-    process.stderr.write(`"${name}" was not registered \u2014 nothing to remove
-`);
-  }
-}
-
 // src/cli.ts
 var pkgDir = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
@@ -1637,7 +1776,7 @@ program.name("mcpill").version(pkg.version);
 program.command("init").description("Scaffold a new .mcpill/ directory").option("--dir <path>", "Target directory").action(async (opts) => {
   await runInit(opts);
 });
-program.command("run").description("Start the MCP server").option("--transport <type>", "Transport: stdio (default) or http").option("--port <n>", "Port number (HTTP only)", parseInt).option("--dir <path>", "Project root containing .mcpill/").option("--register", "Write server entry to Claude config so Claude manages the process").action(
+program.command("run").description("Start the MCP server").option("--transport <type>", "Transport: stdio (default) or http").option("--port <n>", "Port number (HTTP only)", parseInt).option("--dir <path>", "Project root containing .mcpill/").action(
   async (opts) => {
     await runServer(opts);
   }
@@ -1649,9 +1788,6 @@ program.command("validate").description("Validate .mcpill/ configuration").optio
 program.command("compile").description("Compile server.md \u2194 .mcpill/ files").option("--dir <path>", "Directory containing server.md and .mcpill/").option("--to-md", "Reverse: generate server.md from .mcpill/ files").option("--strict", "Error on missing tool handlers instead of generating stubs").option("--no-hooks", "Skip writing the PreToolUse hook to .claude/settings.json").action(async (opts) => {
   await runCompile({ ...opts, noHooks: opts.hooks === false });
 });
-program.command("unregister").description("Remove server entry from Claude config (undo mcpill run --register)").option("--dir <path>", "Project root containing .mcpill/").action(async (opts) => {
-  await runUnregister(opts);
-});
 program.command("pack").description("Prepare pill for npm distribution").option("--dir <path>", "pill project root", ".").action(({ dir }) => runPack(dir));
 program.command("publish").description("Pack and publish pill to npm").option("--dir <path>", "pill project root", ".").option("--access <level>", "npm access level", "public").action(({ dir, access }) => runPublish(dir, access));
 program.parseAsync(process.argv).catch((err) => {

package/package.json

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