mcpill 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.2.3
+
+- `mcpill init` now scaffolds a `package.json` with `type: module` and `mcpill-runtime` as the only dependency; prints `Run: npm install` rather than auto-installing
+- `mcpill run` and `mcpill validate` now catch missing `mcpill-runtime` import errors and surface an actionable message
+- Removed stale `echo`/`greet` tool examples from the default scaffold; replaced with a single `my-tool` placeholder — examples moved to `pill-user-guide.md`
+- `mcpill compile` parses `PILL.md` `## Server` block and lets it win over `server.md` for `name`/`transport`; both files coexist with different roles — `server.md` is editable directly, `PILL.md` is the intent-level spec for the agent
+
 ## 1.2.2
 
 - Fix: bump mcpster dependency to `^0.3.0` — `0.2.x` did not export `applySetup`, causing a crash on `mcpill --version` after global install

package/README.md

@@ -42,13 +42,12 @@ mcpill run           # start the server
 
 Scaffolds a new project in the current directory:
 
-- `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
-- `package.json` — with `pack` and `publish` scripts ready
+- `.mcpill/pill-agent-guide.md` — agent instructions read by Claude when building from `PILL.md`
+- `.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)
+- `package.json` — `{ type: "module", dependencies: { mcpill-runtime } }` — run `npm install`
 
 ### `mcpill compile`
 

package/dist/cli.js

@@ -127,25 +127,14 @@ transport: stdio
 
 ---
 
-## Tool: echo
+## Tool: my-tool
 
-description: Echo a message back to the caller.
+description: Describe what this tool does.
 inputs:
-  - message (string): The message to echo.
-output: The same message, echoed back as text.
+  - param (string): A parameter.
+output: What the tool returns.
 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.
+  Describe the logic here. Claude will implement it.
 
 ---
 
@@ -234,22 +223,6 @@ name: Status
 ---
 The server is running.
 `;
-var ECHO_TOOL_MD = `# echo
-
-Echo a message back
-
-## Parameters
-
-- message (string): The message to echo
-
-## Handler
-
-\`\`\`js
-async ({ message }) => {
-  return { content: [{ type: "text", text: message }] };
-}
-\`\`\`
-`;
 var GREETING_PROMPT_MD = `# greeting
 
 Generate a greeting
@@ -298,7 +271,7 @@ ${projectName}/
     \u2514\u2500\u2500 server/
         \u251C\u2500\u2500 mcpill.config.json         \u2190 compiled config
         \u251C\u2500\u2500 tools/                     \u2190 one .md file per tool
-        \u2502   \u2514\u2500\u2500 echo.md
+        \u2502   \u2514\u2500\u2500 my-tool.md
         \u2514\u2500\u2500 prompts/                   \u2190 one .md file per prompt (optional)
             \u2514\u2500\u2500 greeting.md
 \`\`\`
@@ -341,7 +314,6 @@ async function runInit(opts) {
   fs.mkdirSync(path.join(serverDir, "prompts"), { recursive: true });
   const serverMd = SERVER_MD_TEMPLATE.replace("name: my-server", `name: ${projectName}`);
   fs.writeFileSync(path.join(mcpillDir, "server.md"), serverMd);
-  fs.writeFileSync(path.join(serverDir, "tools", "echo.md"), ECHO_TOOL_MD);
   fs.writeFileSync(path.join(serverDir, "prompts", "greeting.md"), GREETING_PROMPT_MD);
   fs.writeFileSync(
     path.join(serverDir, "mcpill.config.json"),
@@ -351,15 +323,27 @@ async function runInit(opts) {
   fs.writeFileSync(path.join(mcpillDir, "pill-user-guide.md"), makePillUserGuideMd(projectName));
   fs.writeFileSync(path.join(mcpillDir, "HELLO-MCP.md"), HELLO_MCP_MD);
   fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
+  const pkgJsonPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) {
+    const pkg2 = {
+      name: projectName,
+      version: "0.1.0",
+      type: "module",
+      dependencies: {
+        "mcpill-runtime": "latest"
+      }
+    };
+    fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg2, null, 2) + "\n");
+  }
   console.log('\u2713 PILL.md                        \u2190 describe your server, then tell Claude: "Build this PILL.md"');
+  console.log("\u2713 package.json                   \u2190 Run: npm install");
   console.log("\u2713 .mcpill/HELLO-MCP.md           \u2190 copy into PILL.md to see a working example instantly");
   console.log("\u2713 .mcpill/server.md              \u2190 or edit source files directly");
-  console.log("\u2713 .mcpill/server/tools/echo.md");
   console.log("\u2713 .mcpill/server/prompts/greeting.md");
   console.log("\u2713 .mcpill/pill-agent-guide.md    \u2190 agent instructions (read by Claude)");
   console.log("\u2713 .mcpill/pill-user-guide.md     \u2190 start here");
   console.log("");
-  console.log("When ready: mcpill compile && mcpill run");
+  console.log("Next: npm install && mcpill compile && mcpill run");
 }
 
 // src/commands/run.ts
@@ -397,6 +381,11 @@ async function loadTools(mcpillDir) {
     mod = await import(pathToFileURL(toolsPath).href);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("mcpill-runtime")) {
+      throw new Error(
+        "tools.js failed to load: mcpill-runtime not found.\nRun: npm install mcpill-runtime"
+      );
+    }
     throw new Error(`tools.js failed to load: ${msg}`);
   }
   const tools = mod.default;
@@ -1083,6 +1072,18 @@ async function runCompile(opts) {
   const toolsJsPath = join3(serverDir, "tools.js");
   const existing = existsSync(toolsJsPath) ? extractHandlers(readFileSync2(toolsJsPath, "utf-8")) : /* @__PURE__ */ new Map();
   const { doc: mergedDoc, stubbed } = mergeHandlers(doc, existing);
+  const pillMdPath = join3(baseDir, "PILL.md");
+  if (existsSync(pillMdPath)) {
+    const pillContent = readFileSync2(pillMdPath, "utf-8");
+    const serverSection = ("\n" + pillContent).split("\n## ").find((s) => s.startsWith("Server\n"));
+    if (serverSection) {
+      const kv = parseKvBlock(serverSection.slice("Server\n".length));
+      if (kv["name"]) mergedDoc.config.name = kv["name"];
+      if (kv["transport"] === "stdio" || kv["transport"] === "http") {
+        mergedDoc.config.transport = kv["transport"];
+      }
+    }
+  }
   if (opts.strict && stubbed.length > 0) {
     throw new Error("Missing handlers for: " + stubbed.join(", "));
   }

package/package.json

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

package/src/commands/compile.ts

@@ -1,7 +1,7 @@
 import { resolve, join } from 'path';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { pathToFileURL } from 'url';
-import { parseServerDir } from '../compiler/parse.js';
+import { parseServerDir, parseKvBlock } from '../compiler/parse.js';
 import { serializeServerDir } from '../compiler/serialize.js';
 import { extractHandlers, mergeHandlers } from '../compiler/merge-tools.js';
 import { loadConfig } from '../loaders/config.js';
@@ -134,6 +134,21 @@ export async function runCompile(opts: {
 
   const { doc: mergedDoc, stubbed } = mergeHandlers(doc, existing);
 
+  // If PILL.md declares a name/transport in its ## Server section, let it win
+  // over whatever server.md still has (catches cases where the agent forgets to update server.md).
+  const pillMdPath = join(baseDir, 'PILL.md');
+  if (existsSync(pillMdPath)) {
+    const pillContent = readFileSync(pillMdPath, 'utf-8');
+    const serverSection = ('\n' + pillContent).split('\n## ').find((s) => s.startsWith('Server\n'));
+    if (serverSection) {
+      const kv = parseKvBlock(serverSection.slice('Server\n'.length));
+      if (kv['name']) mergedDoc.config.name = kv['name'];
+      if (kv['transport'] === 'stdio' || kv['transport'] === 'http') {
+        mergedDoc.config.transport = kv['transport'];
+      }
+    }
+  }
+
   if (opts.strict && stubbed.length > 0) {
     throw new Error('Missing handlers for: ' + stubbed.join(', '));
   }

package/src/commands/init.ts

@@ -120,25 +120,14 @@ 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: my-tool
 
-## Tool: greet
-
-description: Generate a personalised greeting.
+description: Describe what this tool does.
 inputs:
-  - name (string): The name of the person to greet.
-output: A greeting string addressed to the given name.
+  - param (string): A parameter.
+output: What the tool returns.
 behavior: |
-  Return "Hello, {name}!" as a text response.
+  Describe the logic here. Claude will implement it.
 
 ---
 
@@ -232,23 +221,6 @@ name: Status
 The server is running.
 `;
 
-const ECHO_TOOL_MD = `# echo
-
-Echo a message back
-
-## Parameters
-
-- message (string): The message to echo
-
-## Handler
-
-\`\`\`js
-async ({ message }) => {
-  return { content: [{ type: "text", text: message }] };
-}
-\`\`\`
-`;
-
 const GREETING_PROMPT_MD = `# greeting
 
 Generate a greeting
@@ -298,7 +270,7 @@ ${projectName}/
     └── server/
         ├── mcpill.config.json         ← compiled config
         ├── tools/                     ← one .md file per tool
-        │   └── echo.md
+        │   └── my-tool.md
         └── prompts/                   ← one .md file per prompt (optional)
             └── greeting.md
 \`\`\`
@@ -345,7 +317,6 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
 
   const serverMd = SERVER_MD_TEMPLATE.replace("name: my-server", `name: ${projectName}`);
   fs.writeFileSync(path.join(mcpillDir, "server.md"), serverMd);
-  fs.writeFileSync(path.join(serverDir, "tools", "echo.md"), ECHO_TOOL_MD);
   fs.writeFileSync(path.join(serverDir, "prompts", "greeting.md"), GREETING_PROMPT_MD);
   fs.writeFileSync(
     path.join(serverDir, "mcpill.config.json"),
@@ -357,13 +328,26 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
 
   fs.writeFileSync(path.join(targetDir, "PILL.md"), makePillMd(projectName));
 
+  const pkgJsonPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) {
+    const pkg = {
+      name: projectName,
+      version: "0.1.0",
+      type: "module",
+      dependencies: {
+        "mcpill-runtime": "latest",
+      },
+    };
+    fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+  }
+
   console.log("✓ PILL.md                        ← describe your server, then tell Claude: \"Build this PILL.md\"");
+  console.log("✓ package.json                   ← Run: npm install");
   console.log("✓ .mcpill/HELLO-MCP.md           ← copy into PILL.md to see a working example instantly");
   console.log("✓ .mcpill/server.md              ← or edit source files directly");
-  console.log("✓ .mcpill/server/tools/echo.md");
   console.log("✓ .mcpill/server/prompts/greeting.md");
   console.log("✓ .mcpill/pill-agent-guide.md    ← agent instructions (read by Claude)");
   console.log("✓ .mcpill/pill-user-guide.md     ← start here");
   console.log("");
-  console.log("When ready: mcpill compile && mcpill run");
+  console.log("Next: npm install && mcpill compile && mcpill run");
 }

package/src/loaders/tools.ts

@@ -16,6 +16,11 @@ export async function loadTools(mcpillDir: string): Promise<RawToolDef[]> {
     mod = await import(pathToFileURL(toolsPath).href);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("mcpill-runtime")) {
+      throw new Error(
+        "tools.js failed to load: mcpill-runtime not found.\nRun: npm install mcpill-runtime"
+      );
+    }
     throw new Error(`tools.js failed to load: ${msg}`);
   }