mcpill 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.2.0
+
+- `mcpill init` now scaffolds `PILL.md` — an intent-level spec the developer fills in plain English
+- `PILL.md` embeds agent instructions; 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,42 @@ 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
+- `PILL.md` — intent-level spec; fill this and hand to Claude to generate source files
+- `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 +97,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}}
+```

package/dist/cli.js

@@ -9,45 +9,141 @@ import { readFileSync as readFileSync3 } from "fs";
 // src/commands/init.ts
 import fs from "fs";
 import path from "path";
-var TOOLS_JS = `import { z } from "mcpill-runtime";
-
-export default [
-  {
-    name: "read_file",
-    description: "Read the contents of a file",
-    schema: {
-      path: z.string().describe("Path to the file to read"),
-    },
-    handler: async ({ path: filePath }) => {
-      return { content: \`Contents of \${filePath}\` };
-    },
-  },
-];
-`;
-var PROMPTS_JSON = JSON.stringify(
-  [
-    {
-      name: "summarize",
-      description: "Summarize the given text",
-      args: {
-        text: { type: "string" }
-      },
-      messages: [
-        {
-          role: "user",
-          content: "Please summarize the following text:\n\n{{text}}"
-        }
-      ]
-    }
-  ],
-  null,
-  2
-);
-var RESOURCES_MD = `uri: config://app
-name: App Config
+function makePillMd(projectName) {
+  return `<!-- \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+FOR THE AGENT \u2014 read this before doing anything else
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+You are building an mcpill MCP server from this document.
+
+STEPS:
+
+1. PARSE the sections below:
+   - ## Server           \u2192 server name, description, transport (+ port if http)
+   - ## Tool: <name>     \u2192 one tool per section (repeatable)
+   - ## Resource: <name> \u2192 static resource (optional, repeatable)
+   - ## Prompt: <name>   \u2192 prompt template (optional, repeatable)
+
+2. CREATE a directory named after the server. Generate inside it:
+
+   server.md
+   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   ## Config
+   name: {name}
+   transport: {transport}
+   port: {port}        \u2190 only if transport is http
+
+   ## Resources
+   uri: {uri}
+   name: {resource-name}
+   ---
+   {content}
+   \u2190 omit ## Resources entirely if none specified
+   \u2190 separate multiple resources with a blank line + --- + blank line
+
+   tools/{tool-name}.md  (one file per ## Tool section)
+   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   # {tool-name}
+
+   {description}
+
+   ## Parameters
+
+   - {param} ({type}): {description}
+
+   ## Handler
+
+   \`\`\`js
+   async ({ {param} }) => {
+     // real implementation \u2014 not a stub
+     return { content: [{ type: "text", text: {result} }] };
+   }
+   \`\`\`
+
+   prompts/{prompt-name}.md  (one file per ## Prompt section)
+   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   # {prompt-name}
+
+   {description}
+
+   ## Args
+
+   - {arg} ({type}): {description}
+
+   ## Message
+
+   > user: {message with {{arg}} placeholders}
+   \u2190 omit ## Args if the prompt takes no arguments
+
+3. TRANSLATE each tool's \`behavior\` field into a working JS async handler.
+   - Implement the described logic fully \u2014 no stubs, no TODOs.
+   - Handler is self-contained: no top-level imports.
+   - For file I/O or network calls: use dynamic import inside the handler.
+   - Return shape must be: { content: [{ type: "text", text: string }] }
+   - Allowed parameter types: string | number | boolean. Default unknown types to string.
+
+4. RUN \`mcpill compile\` (or \`mcpill compile --dir {server-name}\`).
+
+5. REPORT what was generated and show the user the next commands:
+   mcpill validate
+   mcpill run
+   mcpill pack / mcpill publish
+
+EDGE CASES:
+- transport http without port \u2192 default to 3333
+- prompt message without role prefix \u2192 wrap as \`> user: {message}\`
+- server name with spaces \u2192 convert to kebab-case for directory and name field
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550 -->
+
+# Pill: ${projectName}
+
 ---
-This resource exposes the application configuration.
+
+## Server
+
+name: ${projectName}
+description:
+transport: stdio
+
+---
+
+## Tool: echo
+
+description: Echo a message back to the caller.
+inputs:
+  - message (string): The message to echo.
+output: The same message, echoed back as text.
+behavior: |
+  Return the message input unchanged.
+
+---
+
+## Tool: greet
+
+description: Generate a personalised greeting.
+inputs:
+  - name (string): The name of the person to greet.
+output: A greeting string addressed to the given name.
+behavior: |
+  Return "Hello, {name}!" as a text response.
+
+---
+
+## Next Steps
+
+Fill in your server above (replace or extend the example tools), then tell Claude:
+
+> "Build this PILL.md"
+
+After the source files are generated:
+
+- [ ] \`mcpill compile\`
+- [ ] \`mcpill validate\`
+- [ ] \`mcpill run\`
+- [ ] \`mcpill pack\`
+- [ ] \`mcpill publish\`
 `;
+}
 var SERVER_MD_TEMPLATE = `## Config
 name: my-server
 transport: stdio
@@ -100,9 +196,6 @@ async function runInit(opts) {
     2
   );
   fs.mkdirSync(mcpillDir, { recursive: true });
-  fs.writeFileSync(path.join(mcpillDir, "tools.js"), TOOLS_JS);
-  fs.writeFileSync(path.join(mcpillDir, "prompts.json"), PROMPTS_JSON);
-  fs.writeFileSync(path.join(mcpillDir, "resources.md"), RESOURCES_MD);
   fs.writeFileSync(path.join(mcpillDir, "mcpill.config.json"), configJson);
   const toolsDir = path.join(targetDir, "tools");
   const promptsDir = path.join(targetDir, "prompts");
@@ -115,6 +208,7 @@ async function runInit(opts) {
     `name: ${projectName}`
   );
   fs.writeFileSync(path.join(targetDir, "server.md"), serverMd);
+  fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
   const pkgJson = JSON.stringify(
     {
       name: projectName,
@@ -126,15 +220,13 @@ async function runInit(opts) {
     2
   );
   fs.writeFileSync(path.join(targetDir, "package.json"), pkgJson);
-  console.log("\u2713 .mcpill/tools.js");
-  console.log("\u2713 .mcpill/prompts.json");
-  console.log("\u2713 .mcpill/resources.md");
-  console.log("\u2713 .mcpill/mcpill.config.json");
+  console.log('\u2713 PILL.md          \u2190 describe your server, then tell Claude: "Build this PILL.md"');
+  console.log("\u2713 server.md        \u2190 or edit source files directly");
   console.log("\u2713 tools/echo.md");
   console.log("\u2713 prompts/greeting.md");
-  console.log("\u2713 server.md");
   console.log("\u2713 package.json");
-  console.log("Edit your tools, then run: mcpill run");
+  console.log("");
+  console.log("When ready: mcpill compile && mcpill run");
 }
 
 // src/commands/run.ts

package/package.json

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

package/src/commands/init.ts

@@ -1,47 +1,141 @@
 import fs from "fs";
 import path from "path";
 
-const TOOLS_JS = `import { z } from "mcpill-runtime";
-
-export default [
-  {
-    name: "read_file",
-    description: "Read the contents of a file",
-    schema: {
-      path: z.string().describe("Path to the file to read"),
-    },
-    handler: async ({ path: filePath }) => {
-      return { content: \`Contents of \${filePath}\` };
-    },
-  },
-];
-`;
+function makePillMd(projectName: string): string {
+  return `<!-- ═══════════════════════════════════════════════════════════════
+FOR THE AGENT — read this before doing anything else
+═══════════════════════════════════════════════════════════════
 
-const PROMPTS_JSON = JSON.stringify(
-  [
-    {
-      name: "summarize",
-      description: "Summarize the given text",
-      args: {
-        text: { type: "string" },
-      },
-      messages: [
-        {
-          role: "user",
-          content: "Please summarize the following text:\n\n{{text}}",
-        },
-      ],
-    },
-  ],
-  null,
-  2
-);
+You are building an mcpill MCP server from this document.
+
+STEPS:
+
+1. PARSE the sections below:
+   - ## Server           → server name, description, transport (+ port if http)
+   - ## Tool: <name>     → one tool per section (repeatable)
+   - ## Resource: <name> → static resource (optional, repeatable)
+   - ## Prompt: <name>   → prompt template (optional, repeatable)
+
+2. CREATE a directory named after the server. Generate inside it:
+
+   server.md
+   ─────────
+   ## Config
+   name: {name}
+   transport: {transport}
+   port: {port}        ← only if transport is http
+
+   ## Resources
+   uri: {uri}
+   name: {resource-name}
+   ---
+   {content}
+   ← omit ## Resources entirely if none specified
+   ← separate multiple resources with a blank line + --- + blank line
+
+   tools/{tool-name}.md  (one file per ## Tool section)
+   ─────────────────────
+   # {tool-name}
+
+   {description}
+
+   ## Parameters
+
+   - {param} ({type}): {description}
+
+   ## Handler
+
+   \`\`\`js
+   async ({ {param} }) => {
+     // real implementation — not a stub
+     return { content: [{ type: "text", text: {result} }] };
+   }
+   \`\`\`
+
+   prompts/{prompt-name}.md  (one file per ## Prompt section)
+   ─────────────────────────
+   # {prompt-name}
+
+   {description}
+
+   ## Args
+
+   - {arg} ({type}): {description}
+
+   ## Message
+
+   > user: {message with {{arg}} placeholders}
+   ← omit ## Args if the prompt takes no arguments
+
+3. TRANSLATE each tool's \`behavior\` field into a working JS async handler.
+   - Implement the described logic fully — no stubs, no TODOs.
+   - Handler is self-contained: no top-level imports.
+   - For file I/O or network calls: use dynamic import inside the handler.
+   - Return shape must be: { content: [{ type: "text", text: string }] }
+   - Allowed parameter types: string | number | boolean. Default unknown types to string.
+
+4. RUN \`mcpill compile\` (or \`mcpill compile --dir {server-name}\`).
+
+5. REPORT what was generated and show the user the next commands:
+   mcpill validate
+   mcpill run
+   mcpill pack / mcpill publish
+
+EDGE CASES:
+- transport http without port → default to 3333
+- prompt message without role prefix → wrap as \`> user: {message}\`
+- server name with spaces → convert to kebab-case for directory and name field
+════════════════════════════════════════════════════════════════ -->
+
+# Pill: ${projectName}
+
+---
+
+## Server
+
+name: ${projectName}
+description:
+transport: stdio
 
-const RESOURCES_MD = `uri: config://app
-name: App Config
 ---
-This resource exposes the application configuration.
+
+## Tool: echo
+
+description: Echo a message back to the caller.
+inputs:
+  - message (string): The message to echo.
+output: The same message, echoed back as text.
+behavior: |
+  Return the message input unchanged.
+
+---
+
+## Tool: greet
+
+description: Generate a personalised greeting.
+inputs:
+  - name (string): The name of the person to greet.
+output: A greeting string addressed to the given name.
+behavior: |
+  Return "Hello, {name}!" as a text response.
+
+---
+
+## Next Steps
+
+Fill in your server above (replace or extend the example tools), then tell Claude:
+
+> "Build this PILL.md"
+
+After the source files are generated:
+
+- [ ] \`mcpill compile\`
+- [ ] \`mcpill validate\`
+- [ ] \`mcpill run\`
+- [ ] \`mcpill pack\`
+- [ ] \`mcpill publish\`
 `;
+}
 
 // Embedded content of src/templates/server.md — tsup does not copy non-TS assets,
 // so the template is inlined here. Keep in sync with src/templates/server.md.
@@ -103,9 +197,6 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
   );
 
   fs.mkdirSync(mcpillDir, { recursive: true });
-  fs.writeFileSync(path.join(mcpillDir, "tools.js"), TOOLS_JS);
-  fs.writeFileSync(path.join(mcpillDir, "prompts.json"), PROMPTS_JSON);
-  fs.writeFileSync(path.join(mcpillDir, "resources.md"), RESOURCES_MD);
   fs.writeFileSync(path.join(mcpillDir, "mcpill.config.json"), configJson);
 
   const toolsDir = path.join(targetDir, "tools");
@@ -120,6 +211,7 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
     `name: ${projectName}`,
   );
   fs.writeFileSync(path.join(targetDir, "server.md"), serverMd);
+  fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
 
   const pkgJson = JSON.stringify(
     {
@@ -133,13 +225,11 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
   );
   fs.writeFileSync(path.join(targetDir, "package.json"), pkgJson);
 
-  console.log("✓ .mcpill/tools.js");
-  console.log("✓ .mcpill/prompts.json");
-  console.log("✓ .mcpill/resources.md");
-  console.log("✓ .mcpill/mcpill.config.json");
+  console.log("✓ PILL.md          ← describe your server, then tell Claude: \"Build this PILL.md\"");
+  console.log("✓ server.md        ← or edit source files directly");
   console.log("✓ tools/echo.md");
   console.log("✓ prompts/greeting.md");
-  console.log("✓ server.md");
   console.log("✓ package.json");
-  console.log("Edit your tools, then run: mcpill run");
+  console.log("");
+  console.log("When ready: mcpill compile && mcpill run");
 }

package/.claude/commands/add-card.md

@@ -1,9 +0,0 @@
-Create a new flowdeck card. The deck is `.flowdeck/` — columns are folders, cards are `TODO.md` files.
-
-Arguments: $ARGUMENTS
-
-Steps:
-1. Determine the column name from the arguments (e.g. "auth", "payments/checkout", or infer from context).
-2. If `.flowdeck/<column>/` doesn't exist, create it.
-3. Create `.flowdeck/<column>/TODO.md` with a title heading, brief description, and `## BOT` / `## HUMAN` sections. Add any tasks from the arguments to the relevant section.
-4. Commit: `git add -A && git commit -m "deck: add <column> card"`.

package/.claude/commands/append-card.md

@@ -1,10 +0,0 @@
-Append a task, idea, or note to an existing flowdeck card. The deck is `.flowdeck/` — columns are folders, cards are `TODO.md` files.
-
-Arguments: $ARGUMENTS
-
-Steps:
-1. Identify which card to append to from the arguments or from context (e.g. which column is most relevant).
-2. Read the card's current content.
-3. Append to the appropriate section: `## BOT` for tasks Claude should do, `## HUMAN` for tasks the human should do, or `#### COMMENTS` for notes/ideas.
-   - If the task is a question (ends with `?`), use `flowdeck append <column> "<question>"` — the CLI will place it under `## HUMAN` with an answer placeholder.
-4. Commit: `git add -A && git commit -m "deck: append to <column> card"`.

package/.claude/commands/play-card.md

@@ -1,14 +0,0 @@
-Play a single flowdeck card.
-
-The card slug is: $ARGUMENTS
-
-The card is at `.flowdeck/<slug>/TODO.md`.
-
-1. Read the card.
-2. Complete every unchecked `- [ ]` item under `## BOT` — read files, edit code, run commands as needed.
-3. Mark each done `- [x]` with a one-line note indented with `>`.
-4. If something needs the human, add `- [ ]` items under `## HUMAN`.
-5. Commit: `git add -A && git commit -m "deck: <short description>"`.
-6. Check if any project documents (README, AGENT.md, architecture notes, changelogs) need updating based on the changes you made. If so, update them and commit: `git add -A && git commit -m "docs: <short description>"`.
-
-Do not scan or read any other TODO.md files.

package/.claude/commands/turn.md

@@ -1,28 +0,0 @@
-You are playing a full turn in this flowdeck project.
-
-Read `.flowdeck/AGENT.md` for project context (if it exists).
-
-Walk `.flowdeck/` and collect every `TODO.md` that has at least one unchecked `- [ ]` item under `## BOT`. These are your hand. If there are no open cards, say so and stop.
-
-## Assess the hand first
-
-Before executing, read all cards and state your plan (a few lines):
-
-1. **Prioritize** — decide play order. Most blocking or highest-leverage first.
-2. **Discard** — identify cards that are duplicated or obsolete. For each, move unchecked BOT items to a `## DISCARDED` section with a one-line reason. Do not delete the card file.
-3. **Combine** — identify cards with complementary tasks that are more efficient to execute together. Note the combination and work them in a single pass.
-
-## Execute
-
-For each card (or combined set), in your chosen order:
-1. Complete every unchecked `- [ ]` item under `## BOT`
-2. Mark each `- [x]` with a one-line note indented with `>`
-3. If something needs the human, add `- [ ]` items under `## HUMAN`
-4. Commit: `git add -A && git commit -m "deck: <short description>"`
-
-## After the hand
-
-Once all cards are played, do a holistic documentation pass:
-- Check if any project docs (README, architecture notes, changelogs, cross-card insights) need updating based on changes made this turn — update what's out of date, leave the rest untouched
-- Check if `.flowdeck/AGENT.md` needs updating based on what you learned — update it if so
-- Final commit (only if anything changed): `git add -A && git commit -m "docs: post-turn"`

package/.claude/settings.json

@@ -1,10 +0,0 @@
-{
-  "mcpServers": {
-    "htllm": {
-      "command": "node",
-      "args": [
-        "/Users/ruco/projects/sitegrow/module-d-orchestrator/mcp-server/dist/index.js"
-      ]
-    }
-  }
-}

package/.flowdeck/.flowdeckignore

@@ -1,5 +0,0 @@
-node_modules/
-dist/
-.git/
-*.log
-.env