mcpill 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.2.1
+
+- All init assets scoped under `.mcpill/` — only `PILL.md` is written to the project root
+- `mcpill init` scaffolds `pill-user-guide.md` inside `.mcpill/` — covers quickstart, project layout, and manual tool editing; replaces any need for a root-level README
+- `HELLO-MCP.md` added to `.mcpill/` — a ready-to-run example developers can copy into `PILL.md`
+
+## 1.2.0
+
+- `mcpill init` now scaffolds `PILL.md` — an intent-level spec the developer fills in plain English
+- `mcpill init` generates `pill-agent-guide.md` with the full agent instructions for building from `PILL.md`
+- `PILL.md` references `pill-agent-guide.md`; tell Claude "Build this PILL.md" to generate source files and compile
+- Example source files (`tools/echo.md`, `prompts/greeting.md`, `server.md`) still scaffolded for direct editing
+- Removed `tools.js`, `prompts.json`, `resources.md` from `.mcpill/` initial scaffold (generated by `mcpill compile`)
+- Updated `mcpill init` console output to guide both entry points
+
 ## 1.1.0
 
 - Renamed to `mcpill`; `@ruco-ai/mcpill` deprecated — install `mcpill` instead

package/README.md

@@ -10,28 +10,44 @@ CLI for building, validating, and publishing MCP servers using the pill format.
 npm install -g mcpill
 ```
 
-## Author workflow
+## Workflows
+
+### PILL-first (recommended for new servers)
+
+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
+```
+
+`PILL.md` embeds the agent instructions — Claude knows exactly what to generate and how.
+
+### Direct edit (for devs who know the pill format)
 
 ```
-mcpill init       # scaffold server.md + tools/ + prompts/
-# write your tools, prompts, resources
-mcpill compile    # compile server.md → .<name>/ pill artifact
-mcpill validate   # validate the pill artifact
-mcpill run        # start the MCP server locally (dev)
-mcpill pack       # prepare bin/server.js + package.json for npm
-mcpill publish    # pack + npm publish
+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
 ```
 
+---
+
 ## Commands
 
 ### `mcpill init`
 
 Scaffolds a new project in the current directory:
 
-- `server.md` — Config + Resources in human-readable Markdown
+- `README.md` — quickstart guide for the scaffolded project
+- `PILL.md` — intent-level spec; fill this and hand to Claude to generate source files
+- `pill-agent-guide.md` — agent instructions read by Claude when building from `PILL.md`
+- `server.md` — server config + resources
 - `tools/echo.md` — example tool
 - `prompts/greeting.md` — example prompt
-- `.mcpill/` — pre-compiled pill artifact
 - `package.json` — with `pack` and `publish` scripts ready
 
 ### `mcpill compile`
@@ -83,3 +99,55 @@ mcpill publish --access restricted
 ## Options
 
 All commands accept `--dir <path>` to target a directory other than the current working directory.
+
+## Pill source format
+
+### `server.md`
+
+```markdown
+## Config
+name: my-server
+transport: stdio
+
+## Resources
+uri: info://status
+name: Status
+---
+The server is running.
+```
+
+### `tools/{name}.md`
+
+```markdown
+# tool-name
+
+Description of what the tool does
+
+## Parameters
+
+- param (string): Description of the parameter
+
+## Handler
+
+\`\`\`js
+async ({ param }) => {
+  return { content: [{ type: "text", text: param }] };
+}
+\`\`\`
+```
+
+### `prompts/{name}.md`
+
+```markdown
+# prompt-name
+
+Description of the prompt
+
+## Args
+
+- name (string): The name to greet
+
+## Message
+
+> user: Say hello to {{name}}
+```