mcpill 1.2.4 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.3.0
+
+- `PILL.md` tool sections now accept a `replaces` field (comma-separated native tool names, e.g. `replaces: Read, Bash`); `mcpill compile` reads these and generates the `PreToolUse` hook without requiring a separate `AGENT.md`
+- `AGENT.md` `## Tools` table still supported; AGENT.md wins on name conflict when both sources declare the same tool
+- `mcpill init` template updated to include `replaces` in the example tool section
+
 ## 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

package/MANUAL-TEST-GUIDE-SPEC.md

@@ -0,0 +1,270 @@
+---
+title: "Feature Specification"
+type: planning
+tags: [planning, specification, scoping]
+---
+
+# Specification: mcpill compile-hooks — Manual Test Guide
+
+**Date:** 2026-05-26
+**Author:** ruco
+**Status:** Draft
+
+---
+
+## Overview
+
+> `mcpill compile` auto-generates a `PreToolUse` hook in `.claude/settings.json` that warns Claude to use the pill's MCP tools instead of native file tools (`Read`, `Bash`, `Edit`, `Write`). The hook derives its matcher and message from the `## Tools` table in `AGENT.md`, making each pill self-enforcing without manual setup. Key behaviours: merge without overwrite, `--no-hooks` opt-out, and `mcpill validate` warning when the hook is absent.
+
+---
+
+## Background & Motivation
+
+Without this feature, a pill author must manually wire a `PreToolUse` hook into `.claude/settings.json` every time they publish or update a pill. Agents forget to use the registered MCP tools and fall back to native tools, bypassing the pill entirely. The compile step already has all the information needed (pill name, tool names, which native tools each replaces) — generating the hook at compile time ties it to the source of truth.
+
+## Goals
+
+- `mcpill compile` writes or updates a `PreToolUse` hook in `<project>/.claude/settings.json` derived from the pill's `AGENT.md ## Tools` table.
+- Existing entries in `settings.json` (e.g. `mcpServers`) are preserved; only the matching `PreToolUse` entry is replaced.
+- `--no-hooks` opts out and writes `.mcpill/.no-hooks` as a sentinel so `validate` skips the check.
+- `mcpill validate` emits a non-fatal warning when `AGENT.md` declares replacements but no hook is present.
+
+## Non-Goals
+
+- Auto-generating `AGENT.md` — the pill author writes it manually.
+- Writing to the global `~/.claude/settings.json` — scope is always the project root.
+- Enforcing hook presence (fatal error) — the warning is advisory only.
+
+## Detailed Design
+
+### Data Model
+
+```
+AGENT.md ## Tools table — expected columns (order-independent, case-insensitive header):
+  | Tool         | Description       | Replaces      |
+  |--------------|-------------------|---------------|
+  | read-chunks  | Read file chunks  | Read          |
+  | run-query    | Execute SQL       | Bash,Read     |
+
+"Replaces" cell: comma-separated native tool names (Read, Bash, Edit, Write).
+Omitting the column or leaving a cell blank → no hook generated for that row.
+
+.claude/settings.json — hooks section written by compile:
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Bash",
+        "hooks": [{ "type": "command", "command": "echo \"[mcpill:<name>] Use pill tools instead: <tool>→<native>; ... See .mcpill/AGENT.md.\"" }]
+      }
+    ]
+  }
+}
+
+Merge key: matcher string (exact match). Replace entry if matcher already exists; append otherwise.
+
+.mcpill/.no-hooks — presence signals that hook generation was opted out; written by --no-hooks flag.
+```
+
+### API / Interface
+
+```
+# CLI
+mcpill compile [--dir <path>] [--no-hooks]
+
+# Programmatic
+runCompile(opts: { dir?: string; toMd?: boolean; strict?: boolean; noHooks?: boolean }): Promise<void>
+
+# AGENT.md lookup order
+1. <baseDir>/AGENT.md
+2. <baseDir>/.mcpill/AGENT.md
+(first found wins; if neither exists, hook generation is skipped silently)
+
+# Hook message format
+[mcpill:<pillName>] Use pill tools instead: <tool1>→<native1>,<native2>; <tool2>→<native3>. See .mcpill/AGENT.md.
+```
+
+### Behavior
+
+1. `mcpill compile` runs the standard compile pipeline (server.md → .mcpill/server/).
+2. If `--no-hooks` was passed: write `.mcpill/.no-hooks`, return early — no hook written.
+3. Locate `AGENT.md` at `baseDir/AGENT.md` or `.mcpill/AGENT.md`; if absent, skip hook generation.
+4. Parse `## Tools` table — find the `replaces` column (case-insensitive). Extract comma-separated native tool names per row. Skip rows with empty/missing replaces cell.
+5. If no rows have replacements, skip hook generation.
+6. Build `HookEntry`: matcher = all unique native tool names joined by `|`; command = static `echo` with pill name and full tool→native summary baked in.
+7. Read `.claude/settings.json` (or start from `{}`). Find existing `hooks.PreToolUse` array entry with same matcher; replace it, or append if not found. Write back.
+8. `mcpill validate` — after structural validation passes, check: if `.mcpill/.no-hooks` absent AND `AGENT.md` declares replacements AND `.claude/settings.json` has no `PreToolUse` entries → emit `⚠  No PreToolUse hook in .claude/settings.json — run mcpill compile to add it`.
+
+## Error Handling
+
+| Error Case | Behavior | User-Facing Message |
+|---|---|---|
+| `.claude/settings.json` exists but is invalid JSON | `JSON.parse` throws → compile crashes with a JS stack trace | *(raw error)* — fix or delete the malformed settings.json |
+| `AGENT.md` exists but has no `## Tools` section | `parseAgentMdTools` returns `[]` → hook generation silently skipped | *(none)* |
+| `AGENT.md` has `## Tools` but no `replaces` column | `parseAgentMdTools` returns `[]` → silently skipped | *(none)* |
+| Compile run with `--no-hooks`; later `validate` called | `.no-hooks` sentinel present → validate skips hook check entirely | *(none)* |
+| `baseDir/.claude/` does not exist | `mkdirSync(claudeDir, { recursive: true })` creates it | *(none — transparent)* |
+
+## Security Considerations
+
+- Hook command is a static `echo` — no shell variable expansion, no user-controlled input interpolated into the command string at runtime. `JSON.stringify(message)` in `buildHookEntry` ensures the baked-in string is safely quoted.
+- `settings.json` is scoped to `baseDir/.claude/` — no writes to global config.
+- `AGENT.md` content is read and parsed; no `eval`/`exec` of its contents.
+
+## Testing Plan
+
+Run all automated tests first: `npm test` — all 6 hook tests in `src/__tests__/compile.test.ts` must pass.
+
+Then follow these manual steps against a real pill directory.
+
+### Setup
+
+Create a scratch pill for testing:
+
+```sh
+mkdir /tmp/test-pill && cd /tmp/test-pill
+mcpill init
+```
+
+Add a minimal `AGENT.md` at the project root:
+
+```markdown
+# AGENT
+
+## Tools
+
+| Tool | Description | Replaces |
+|------|-------------|----------|
+| read-chunks | Read a file in chunks | Read |
+| run-query | Execute a SQL query | Bash,Read |
+```
+
+---
+
+### Test 1 — Happy path: hook is written
+
+- [ ] Run `mcpill compile` in `/tmp/test-pill`.
+- [ ] Verify `.claude/settings.json` was created.
+- [ ] Open it and confirm:
+  - `hooks.PreToolUse` is an array with one entry.
+  - `matcher` is `"Read|Bash"` (or `"Bash|Read"` — order may vary).
+  - `hooks[0].command` contains `echo`.
+  - The echo string contains `[mcpill:` followed by the pill name (from `.mcpill/server.md` or `PILL.md`).
+  - The echo string contains `read-chunks→Read` and `run-query→Bash,Read`.
+  - The echo string ends with `See .mcpill/AGENT.md.`
+
+---
+
+### Test 2 — Merge: existing settings.json is preserved
+
+- [ ] Add a fake `mcpServers` entry to `.claude/settings.json`:
+  ```json
+  { "mcpServers": { "some-server": { "command": "node", "args": [] } } }
+  ```
+- [ ] Run `mcpill compile` again.
+- [ ] Verify `.claude/settings.json` still contains `mcpServers.some-server`.
+- [ ] Verify `hooks.PreToolUse` is also present (not the only key).
+
+---
+
+### Test 3 — Re-compile replaces the hook, not appends
+
+- [ ] Change the `Replaces` cell of `run-query` to just `Bash` (remove `Read`).
+- [ ] Run `mcpill compile`.
+- [ ] Verify `hooks.PreToolUse` still has exactly **one** entry (not two).
+- [ ] Verify the matcher reflects the updated set.
+
+---
+
+### Test 4 — `--no-hooks` flag
+
+- [ ] Delete `.claude/settings.json` and `.mcpill/.no-hooks` if they exist.
+- [ ] Run `mcpill compile --no-hooks`.
+- [ ] Verify `.claude/settings.json` was **not** created.
+- [ ] Verify `.mcpill/.no-hooks` **was** created (empty file).
+
+---
+
+### Test 5 — `mcpill validate` warns when hook is absent
+
+- [ ] Delete `.claude/settings.json` and `.mcpill/.no-hooks`.
+- [ ] Run `mcpill compile --no-hooks` (ensures `.no-hooks` is present, then delete it manually).
+- [ ] Delete `.mcpill/.no-hooks`.
+- [ ] Ensure `AGENT.md` still has a `Replaces` column with values.
+- [ ] Run `mcpill validate`.
+- [ ] Verify output contains `⚠  No PreToolUse hook in .claude/settings.json`.
+- [ ] Verify the exit code is **0** (non-fatal — validate still passes).
+
+---
+
+### Test 6 — `mcpill validate` skips hook check when `.no-hooks` present
+
+- [ ] Run `mcpill compile --no-hooks`.
+- [ ] Run `mcpill validate`.
+- [ ] Verify **no** `⚠  No PreToolUse hook` warning appears in output.
+
+---
+
+### Test 7 — No AGENT.md: hook silently skipped
+
+- [ ] Move `AGENT.md` out of the project root (e.g. `/tmp/AGENT.md.bak`).
+- [ ] Delete `.claude/settings.json` if present.
+- [ ] Run `mcpill compile`.
+- [ ] Verify `.claude/settings.json` was **not** created.
+- [ ] Restore `AGENT.md`.
+
+---
+
+### Test 8 — AGENT.md in `.mcpill/` subdirectory
+
+- [ ] Move `AGENT.md` to `.mcpill/AGENT.md`.
+- [ ] Delete `.claude/settings.json` if present.
+- [ ] Run `mcpill compile`.
+- [ ] Verify `.claude/settings.json` **was** created with the hook.
+- [ ] Move `AGENT.md` back to project root.
+
+---
+
+### Test 9 — AGENT.md with no `replaces` column: no hook
+
+- [ ] Replace `AGENT.md` content with a table that has no `Replaces` column:
+  ```markdown
+  ## Tools
+  | Tool | Description |
+  |------|-------------|
+  | read-chunks | Read a file |
+  ```
+- [ ] Delete `.claude/settings.json`.
+- [ ] Run `mcpill compile`.
+- [ ] Verify `.claude/settings.json` was **not** created.
+- [ ] Restore the original `AGENT.md`.
+
+---
+
+### Test 10 — Real pill smoke test (xtage or mcpster)
+
+- [ ] Run `mcpill compile` in a pill repo that already has a real `AGENT.md` with tool replacements.
+- [ ] Open `.claude/settings.json` and read the generated hook command.
+- [ ] Start a Claude Code session in that repo and deliberately use `Read` on a file.
+- [ ] Verify the hook fires and the reminder message is shown in the terminal output.
+- [ ] Confirm the message names specific MCP tools and the pill name — not a generic warning.
+
+---
+
+## Open Questions
+
+- [ ] Should the hook message include a direct invocation hint (`call read-chunks with path=...`) or keep it as a passive reminder? Currently a passive reminder. Defer until Test 10 reveals whether agents change behavior.
+- [ ] Should `mcpill validate` check that the *specific matcher* in `settings.json` covers *all* declared replacements, or just that any `PreToolUse` entry exists? Currently the latter (any entry = ok). Tighten in a follow-up if agents still miss tools.
+
+## Alternatives Considered
+
+| Alternative | Pros | Cons | Decision |
+|---|---|---|---|
+| Read AGENT.md at hook-trigger time (not baked in) | Always up-to-date without recompile | I/O on every `Read`/`Bash` call; hook latency spikes | Rejected — bake at compile time |
+| Write to `~/.claude/settings.json` (global) | Works without project setup | Bleeds hook into every project on the machine | Rejected — project-scoped only |
+| Fatal error in `validate` if hook missing | Strong enforcement | Breaks projects that manage hooks separately | Rejected — non-fatal warning only |
+| Generate `AGENT.md` at compile time | Less manual work for pill authors | Inverts ownership — `replaces` is semantic knowledge only the author can declare | Rejected — user writes it manually |
+
+---
+
+*Made with [mdblu](https://github.com/ruco-ai/mdblu) · source: `templates/SPEC.md.template`*

package/README.md

@@ -47,6 +47,7 @@ Scaffolds a new project in the current directory:
 - `.mcpill/server.md` — server config + resources
 - `.mcpill/server/prompts/greeting.md` — example prompt
 - `.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
 - `package.json` — `{ type: "module", dependencies: { mcpill-runtime } }` — run `npm install`
 
 ### `mcpill compile`
@@ -57,8 +58,24 @@ 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
 ```
 
+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:
+
+- **`PILL.md`** (recommended) — add a `replaces` field to any `## Tool:` section:
+
+  ```markdown
+  ## Tool: read-chunks
+
+  description: Read a file by token-sized chunks.
+  replaces: Read
+  behavior: |
+    ...
+  ```
+
+- **`AGENT.md`** — a `## Tools` table with a `Replaces` column (existing format). AGENT.md wins on name conflicts.
+
 ### `mcpill validate`
 
 Validates all pill directories (`.<name>/`) in the project root.