mcpill 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.7.0
+
+- `mcpill run` is now side-effect-free by default — stopping the process disconnects the server; no Claude config is written
+- `mcpill run --register` retains the old persistent behavior: registers the server entry in Claude config so Claude manages the process
+- `mcpill unregister` removes the server entry from `.claude/settings.json`, `~/.claude.json`, and Claude Desktop config
+
+## 1.6.0
+
+- `HELLO-MCP.md` template (scaffolded by `mcpill init`) now includes a commented-out `## Hook:` section stub with inline field explanations for all four Claude Code event types
+
 ## 1.5.0
 
 - `mcpill init` scaffolds `.mcpill/server/hooks/` with a commented `example-hook.md` stub covering all four Claude Code event types (`PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`)

package/README.md

@@ -20,7 +20,8 @@ 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
+mcpill run                         # start the server (transient — stops when you do)
+mcpill run --register              # or: register so Claude manages it persistently
 ```
 
 `PILL.md` embeds the agent instructions — Claude knows exactly what to generate and how.
@@ -31,7 +32,7 @@ mcpill run                         # start the server
 mcpill init          # scaffolds server.md + tools/ + prompts/
 # edit source files  # tools/*.md, prompts/*.md, server.md
 mcpill compile       # compile source → .{name}/ pill artifact
-mcpill run           # start the server
+mcpill run           # start the server (transient — stops when you do)
 ```
 
 ---
@@ -49,6 +50,7 @@ Scaffolds a new project in the current directory:
 - `.mcpill/server/hooks/example-hook.md` — stub hook file (see file for format; all fields commented out by default)
 - `.mcpill/HELLO-MCP.md` — ready-to-run example (copy into `PILL.md` to try it)
 - `.claude/commands/create-pill.md` — `/create-pill` slash command; say `/create-pill` in Claude Code to start the guided pill-creation workflow
+- `README.md` — quickstart guide covering project layout and tool-editing workflow
 - `package.json` — `{ type: "module", dependencies: { mcpill-runtime } }` — deps are installed automatically by `mcpill compile` and `mcpill validate`
 
 ### `mcpill compile`
@@ -88,8 +90,22 @@ Starts the MCP server from the pill artifact.
 ```bash
 mcpill run                        # stdio (default)
 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.
+
 ### `mcpill pack`
 
 Prepares the pill for npm distribution:

package/dist/cli.js

@@ -273,6 +273,24 @@ description: Ask the server to introduce itself.
 behavior: |
   A prompt (no args) with a single user message:
   "Introduce yourself \u2014 what is hello-mcp and what can it do?"
+
+---
+
+<!-- Add a ## Hook: section to run a shell command when Claude Code fires an event.
+     Run: mcpill compile after editing to apply changes to .claude/settings.json.
+     Remove comment markers to activate.
+
+     trigger  \u2014 event that fires the hook: PreToolUse | PostToolUse | PreCompact | Stop
+     matcher  \u2014 regex matched against tool name (PreToolUse/PostToolUse only); blank = all tools
+     command  \u2014 shell command; stdout shown to Claude; exit!=0 blocks (PreToolUse)
+
+## Hook: example-hook
+
+trigger: PreToolUse
+matcher: .*
+command: echo "example hook \u2014 replace this command"
+
+-->
 `;
 var SERVER_MD_TEMPLATE = `## Config
 name: my-server
@@ -1139,15 +1157,17 @@ async function runServer(opts) {
       resolver: async () => content
     });
   }
-  applySetup(name, tools.map((t) => t.name), {
-    projectPath: baseDir,
-    permissions: "restrictive",
-    register: true,
-    cmdOverride: {
-      command: "mcpill",
-      args: ["run", "--dir", baseDir]
-    }
-  });
+  if (opts.register) {
+    applySetup(name, tools.map((t) => t.name), {
+      projectPath: baseDir,
+      permissions: "restrictive",
+      register: true,
+      cmdOverride: {
+        command: "mcpill",
+        args: ["run", "--dir", baseDir]
+      }
+    });
+  }
   try {
     await server.start();
   } catch (err) {
@@ -1541,6 +1561,72 @@ 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(
@@ -1551,7 +1637,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 <transport>", "Transport type: stdio or http").option("--port <n>", "Port number (HTTP only)", parseInt).option("--dir <path>", "Directory containing .mcpill/").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/").option("--register", "Write server entry to Claude config so Claude manages the process").action(
   async (opts) => {
     await runServer(opts);
   }
@@ -1563,6 +1649,9 @@ 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.5.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "CLI for building, validating, and publishing MCP servers using the pill format.",
   "homepage": "https://mcpill.ruco.dev",