mcpill 1.1.0 → 1.2.1

package/dist/cli.js

@@ -9,44 +9,220 @@ 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 PILL_AGENT_GUIDE_MD = `# pill-agent-guide
+
+Instructions for building an mcpill MCP server from a filled \`PILL.md\`.
+
+---
+
+## Steps
+
+1. **Parse** the sections in \`PILL.md\`:
+   - \`## 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. **Write** the server files into the pre-created scaffold at \`.mcpill/\`:
+
+   \`.mcpill/server.md\`
+   \`\`\`
+   ## Config
+   name: {name}
+   transport: {transport}
+   port: {port}        \u2190 only if transport is http
+
+   ## Resources
+   uri: {uri}
+   name: {resource-name}
+   ---
+   {content}
+   \`\`\`
+   Omit \`## Resources\` entirely if none were specified.
+   Separate multiple resources with a blank line + \`---\` + blank line.
+
+   \`.mcpill/server/tools/{tool-name}.md\` \u2014 one file per \`## Tool\` section:
+   \`\`\`
+   # {tool-name}
+
+   {description}
+
+   ## Parameters
+
+   - {param} ({type}): {description}
+
+   ## Handler
+
+   \`\`\`js
+   async ({ {param} }) => {
+     return { content: [{ type: "text", text: {result} }] };
+   }
+   \`\`\`
+   \`\`\`
+
+   \`.mcpill/server/prompts/{prompt-name}.md\` \u2014 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 \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: \`{ content: [{ type: "text", text: string }] }\`
+   - Allowed parameter types: \`string | number | boolean\`. Default unknown types to \`string\`.
+
+4. **Run** \`mcpill compile\`.
+
+5. **Report** what was generated and show the user the next commands:
+   \`\`\`
+   mcpill validate
+   mcpill run
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+---
+
+## Edge cases
+
+| Situation | Handling |
+|---|---|
+| \`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 \`name\` field |
+| Input type not \`string\\|number\\|boolean\` | Default to \`string\`, note the assumption |
+| Vague \`behavior\` field | Implement the most literal reasonable interpretation |
 `;
-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.
+Follow the steps in .mcpill/pill-agent-guide.md.
+
+\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}
+
+---
+
+## 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.
+
 ---
-This resource exposes the application configuration.
+
+## 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 HELLO_MCP_MD = `<!-- \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
+HELLO-MCP \u2014 a ready-to-run example
+
+Want to see mcpill in action before building your own server?
+
+1. Copy the content below into your PILL.md (replace everything).
+2. Tell Claude: "Build this PILL.md"
+3. Run: mcpill compile && mcpill validate && mcpill run
+\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: hello-mcp
+
+---
+
+## Server
+
+name: hello-mcp
+description: A hello-world MCP server \u2014 see mcpill in action.
+transport: stdio
+
+---
+
+## Resource: server-info
+
+uri: info://server
+name: Server Info
+content: |
+  hello-mcp is a demo MCP server built with mcpill.
+  Tools: ping, echo. Prompt: introduce.
+
+---
+
+## Tool: ping
+
+description: Returns pong with the current UTC timestamp.
+inputs:
+output: A pong message with the current timestamp.
+behavior: |
+  Return the string "pong \u2014 " followed by new Date().toISOString().
+
+---
+
+## Tool: echo
+
+description: Echoes 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.
+
+---
+
+## Prompt: introduce
+
+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?"
 `;
 var SERVER_MD_TEMPLATE = `## Config
 name: my-server
@@ -86,62 +262,111 @@ Generate a greeting
 
 > user: Say hello to {{name}}
 `;
+function makePillUserGuideMd(projectName) {
+  return `# ${projectName} \u2014 mcpill user guide
+
+## Quickstart
+
+1. **Describe your server** in \`PILL.md\` \u2014 fill in the \`## Server\` block and add \`## Tool\` sections.
+2. **Build it** \u2014 open Claude Code and say:
+   > "Build this PILL.md"
+   Claude reads \`.mcpill/pill-agent-guide.md\` and generates the source files.
+3. **Compile**
+   \`\`\`sh
+   mcpill compile
+   \`\`\`
+4. **Test locally**
+   \`\`\`sh
+   mcpill validate   # schema check
+   mcpill run        # start the server
+   \`\`\`
+5. **Pack & publish**
+   \`\`\`sh
+   mcpill pack
+   mcpill publish
+   \`\`\`
+
+## Project layout
+
+\`\`\`
+${projectName}/
+\u251C\u2500\u2500 PILL.md                            \u2190 describe your server here
+\u2514\u2500\u2500 .mcpill/
+    \u251C\u2500\u2500 server.md                      \u2190 server config (name, transport, resources)
+    \u251C\u2500\u2500 pill-agent-guide.md            \u2190 instructions Claude follows when building
+    \u251C\u2500\u2500 pill-user-guide.md             \u2190 this file
+    \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
+        \u2514\u2500\u2500 prompts/                   \u2190 one .md file per prompt (optional)
+            \u2514\u2500\u2500 greeting.md
+\`\`\`
+
+## Editing tools manually
+
+Each file in \`.mcpill/server/tools/\` follows this shape:
+
+\`\`\`markdown
+# tool-name
+
+One-line description.
+
+## Parameters
+
+- param (string): what it is
+
+## Handler
+
+\`\`\`js
+async ({ param }) => {
+  return { content: [{ type: "text", text: param }] };
+}
+\`\`\`
+\`\`\`
+
+Run \`mcpill compile\` after any edit to regenerate the server bundle.
+`;
+}
 async function runInit(opts) {
   const targetDir = path.resolve(opts.dir ?? process.cwd());
   const mcpillDir = path.join(targetDir, ".mcpill");
+  const serverDir = path.join(mcpillDir, "server");
   const projectName = path.basename(targetDir);
   if (fs.existsSync(mcpillDir)) {
     console.error(".mcpill/ already exists. Remove it manually to re-init.");
     process.exit(1);
   }
-  const configJson = JSON.stringify(
-    { name: projectName, transport: "stdio", port: 3333 },
-    null,
-    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");
-  fs.mkdirSync(toolsDir, { recursive: true });
-  fs.mkdirSync(promptsDir, { recursive: true });
-  fs.writeFileSync(path.join(toolsDir, "echo.md"), ECHO_TOOL_MD);
-  fs.writeFileSync(path.join(promptsDir, "greeting.md"), GREETING_PROMPT_MD);
-  const serverMd = SERVER_MD_TEMPLATE.replace(
-    "name: my-server",
-    `name: ${projectName}`
+  fs.mkdirSync(path.join(serverDir, "tools"), { recursive: true });
+  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"),
+    JSON.stringify({ name: projectName, transport: "stdio", port: 3333 }, null, 2)
   );
-  fs.writeFileSync(path.join(targetDir, "server.md"), serverMd);
-  const pkgJson = JSON.stringify(
-    {
-      name: projectName,
-      version: "0.1.0",
-      private: true,
-      scripts: { pack: "mcpill pack", publish: "mcpill publish" }
-    },
-    null,
-    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 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");
+  fs.writeFileSync(path.join(mcpillDir, "pill-agent-guide.md"), PILL_AGENT_GUIDE_MD);
+  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));
+  console.log('\u2713 PILL.md                        \u2190 describe your server, then tell Claude: "Build this PILL.md"');
+  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");
 }
 
 // src/commands/run.ts
 import path7 from "path";
 import fs6 from "fs";
 import { z as z2 } from "mcpill-runtime";
-import { createServer } from "mcpster";
+import { createServer, applySetup } from "mcpster";
 
 // src/loaders/config.ts
 import fs2 from "fs";
@@ -333,26 +558,24 @@ async function validateOne(mcpillDir) {
   console.log(`\u2713 Valid: ${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources`);
 }
 async function runValidate(baseDir) {
-  const pillDirs = fs5.readdirSync(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs5.existsSync(path6.join(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => path6.join(baseDir, e.name));
-  if (pillDirs.length === 0) {
+  const serverDir = path6.join(baseDir, ".mcpill", "server");
+  if (!fs5.existsSync(path6.join(serverDir, "mcpill.config.json"))) {
     console.error("No pill directories found \u2014 run mcpill compile first");
     process.exit(1);
   }
-  for (const mcpillDir of pillDirs) {
-    await validateOne(mcpillDir);
-  }
+  await validateOne(serverDir);
 }
 
 // src/commands/run.ts
 async function runServer(opts) {
   const baseDir = path7.resolve(opts.dir ?? process.cwd());
   await runValidate(baseDir);
-  const pillDirs = fs6.readdirSync(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs6.existsSync(path7.join(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => path7.join(baseDir, e.name));
-  const mcpillDir = pillDirs[0];
+  const mcpillDir = path7.join(baseDir, ".mcpill", "server");
+  if (!fs6.existsSync(path7.join(mcpillDir, "mcpill.config.json"))) {
+    console.error("No pill found \u2014 run mcpill compile first");
+    process.exit(1);
+  }
+  ;
   const [tools, prompts, resources, config] = await Promise.all([
     loadTools(mcpillDir),
     loadPrompts(mcpillDir),
@@ -395,6 +618,15 @@ 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]
+    }
+  });
   try {
     await server.start();
   } catch (err) {
@@ -415,7 +647,7 @@ async function runServer(opts) {
 
 // src/commands/compile.ts
 import { resolve, join as join3 } from "path";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync, readdirSync as readdirSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync } from "fs";
 import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/compiler/parse.ts
@@ -562,7 +794,7 @@ function parseServerDir(dir) {
   };
   const resourcesBody = sections.get("Resources") ?? "";
   const resources = parseResourcesSection(resourcesBody);
-  const toolsDir = join(dir, "tools");
+  const toolsDir = join(dir, "server", "tools");
   const tools = [];
   let toolFiles = [];
   try {
@@ -572,7 +804,7 @@ function parseServerDir(dir) {
   for (const file of toolFiles) {
     tools.push(parseToolFile(readFileSync(join(toolsDir, file), "utf-8")));
   }
-  const promptsDir = join(dir, "prompts");
+  const promptsDir = join(dir, "server", "prompts");
   const prompts = [];
   let promptFiles = [];
   try {
@@ -601,8 +833,8 @@ ${r.content}`;
   }).join("\n---\n");
 }
 function serializeServerDir(doc, dir) {
-  mkdirSync(join2(dir, "tools"), { recursive: true });
-  mkdirSync(join2(dir, "prompts"), { recursive: true });
+  mkdirSync(join2(dir, "server", "tools"), { recursive: true });
+  mkdirSync(join2(dir, "server", "prompts"), { recursive: true });
   let serverMd = "## Config\n";
   serverMd += `name: ${doc.config.name}
 `;
@@ -642,7 +874,7 @@ ${cleanHandler}
 \`\`\`
 `;
     }
-    writeFileSync(join2(dir, "tools", `${tool.name}.md`), md);
+    writeFileSync(join2(dir, "server", "tools", `${tool.name}.md`), md);
   }
   for (const prompt of doc.prompts) {
     let md = `# ${prompt.name}
@@ -666,7 +898,7 @@ ${cleanHandler}
 `;
       }
     }
-    writeFileSync(join2(dir, "prompts", `${prompt.name}.md`), md);
+    writeFileSync(join2(dir, "server", "prompts", `${prompt.name}.md`), md);
   }
   console.log(`\u2713 tools/ updated (${doc.tools.length} files)`);
   console.log(`\u2713 prompts/ updated (${doc.prompts.length} files)`);
@@ -801,24 +1033,20 @@ mimeType: ${r.mimeType}`;
 ${r.content}`;
   }).join("\n---\n") + "\n";
 }
-function findPillDirs(baseDir) {
-  return readdirSync2(baseDir, { withFileTypes: true }).filter(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && existsSync(join3(baseDir, e.name, "mcpill.config.json"))
-  ).map((e) => join3(baseDir, e.name));
-}
 async function runCompile(opts) {
   const baseDir = resolve(opts.dir ?? process.cwd());
+  const mcpillDir = join3(baseDir, ".mcpill");
+  const serverDir = join3(mcpillDir, "server");
   if (opts.toMd) {
-    const pillDirs = findPillDirs(baseDir);
-    if (pillDirs.length === 0) {
-      throw new Error("No pill directories found \u2014 run mcpill compile first");
+    const configPath = join3(serverDir, "mcpill.config.json");
+    if (!existsSync(configPath)) {
+      throw new Error("No pill found \u2014 run mcpill compile first");
     }
-    const mcpillDir2 = pillDirs[0];
-    const config = await loadConfig(mcpillDir2);
-    const resources = await loadResources(mcpillDir2);
-    const promptsPath = join3(mcpillDir2, "prompts.json");
+    const config = await loadConfig(serverDir);
+    const resources = await loadResources(serverDir);
+    const promptsPath = join3(serverDir, "prompts.json");
     const prompts = JSON.parse(readFileSync2(promptsPath, "utf-8"));
-    const toolsPath = join3(mcpillDir2, "tools.js");
+    const toolsPath = join3(serverDir, "tools.js");
     const handlers = existsSync(toolsPath) ? extractHandlers(readFileSync2(toolsPath, "utf-8")) : /* @__PURE__ */ new Map();
     let tools = [];
     if (existsSync(toolsPath)) {
@@ -848,12 +1076,11 @@ async function runCompile(opts) {
       prompts,
       resources
     };
-    serializeServerDir(doc2, baseDir);
+    serializeServerDir(doc2, mcpillDir);
     return;
   }
-  const doc = parseServerDir(baseDir);
-  const mcpillDir = join3(baseDir, "." + doc.config.name);
-  const toolsJsPath = join3(mcpillDir, "tools.js");
+  const doc = parseServerDir(mcpillDir);
+  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);
   if (opts.strict && stubbed.length > 0) {
@@ -862,33 +1089,22 @@ async function runCompile(opts) {
   for (const name of stubbed) {
     console.warn(`\u26A0  Stub generated for tool: ${name}`);
   }
-  mkdirSync2(mcpillDir, { recursive: true });
-  writeFileSync2(join3(mcpillDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
-  writeFileSync2(join3(mcpillDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
-  writeFileSync2(join3(mcpillDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
+  mkdirSync2(serverDir, { recursive: true });
+  writeFileSync2(join3(serverDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
+  writeFileSync2(join3(serverDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
+  writeFileSync2(join3(serverDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
   writeFileSync2(toolsJsPath, generateToolsJs(mergedDoc.tools));
-  const pillDirName = "." + doc.config.name;
-  console.log(`\u2713 ${pillDirName}/ updated from server.md, tools/, prompts/`);
+  console.log(`\u2713 .mcpill/server/ updated from .mcpill/server.md, .mcpill/server/tools/, .mcpill/server/prompts/`);
 }
 
 // src/commands/pack.ts
 import fs7 from "fs";
 import path8 from "path";
 var SERVER_ENTRY_TEMPLATE = "import { runPill } from 'mcpill-runtime';\nrunPill();\n";
-function resolvePillDir(baseDir) {
-  const entries = fs7.readdirSync(baseDir, { withFileTypes: true });
-  const pill = entries.find(
-    (e) => e.isDirectory() && /^\.[a-z][a-z0-9-]*$/.test(e.name) && fs7.existsSync(path8.join(baseDir, e.name, "mcpill.config.json"))
-  );
-  if (!pill) {
-    throw new Error("No pill directory found \u2014 run mcpill compile first");
-  }
-  return path8.join(baseDir, pill.name);
-}
 async function runPack(dir) {
   const baseDir = path8.resolve(dir);
   await runValidate(baseDir);
-  const pillDir = resolvePillDir(baseDir);
+  const pillDir = path8.join(baseDir, ".mcpill", "server");
   const config = await loadConfig(pillDir);
   const { name } = config;
   fs7.mkdirSync(path8.join(baseDir, "bin"), { recursive: true });

package/package.json

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

package/src/__tests__/init.test.ts

@@ -20,35 +20,36 @@ describe("runInit", () => {
     }
   });
 
-  it("writes all four files with expected content in an empty dir", async () => {
+  it("scaffolds the expected files and directories", async () => {
     const base = mkTmp();
     vi.spyOn(console, "log").mockImplementation(() => {});
 
     await runInit({ dir: base });
 
     const mcpillDir = path.join(base, ".mcpill");
+    const serverDir = path.join(mcpillDir, "server");
+
     expect(fs.existsSync(mcpillDir)).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "tools.js"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "prompts.json"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "resources.md"))).toBe(true);
-    expect(fs.existsSync(path.join(mcpillDir, "mcpill.config.json"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "server.md"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "pill-agent-guide.md"))).toBe(true);
+    expect(fs.existsSync(path.join(mcpillDir, "pill-user-guide.md"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "mcpill.config.json"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "tools", "echo.md"))).toBe(true);
+    expect(fs.existsSync(path.join(serverDir, "prompts", "greeting.md"))).toBe(true);
+    expect(fs.existsSync(path.join(base, "PILL.md"))).toBe(true);
+    expect(fs.existsSync(path.join(base, "README.md"))).toBe(false);
+    expect(fs.existsSync(path.join(base, "package.json"))).toBe(false);
 
     const config = JSON.parse(
-      fs.readFileSync(path.join(mcpillDir, "mcpill.config.json"), "utf-8")
+      fs.readFileSync(path.join(serverDir, "mcpill.config.json"), "utf-8")
     );
     expect(config).toMatchObject({ name: path.basename(base), transport: "stdio", port: 3333 });
 
-    const prompts = JSON.parse(
-      fs.readFileSync(path.join(mcpillDir, "prompts.json"), "utf-8")
-    );
-    expect(Array.isArray(prompts)).toBe(true);
-    expect(prompts[0].name).toBe("summarize");
-
-    const resources = fs.readFileSync(path.join(mcpillDir, "resources.md"), "utf-8");
-    expect(resources).toContain("uri: config://app");
+    const serverMd = fs.readFileSync(path.join(mcpillDir, "server.md"), "utf-8");
+    expect(serverMd).toContain(`name: ${path.basename(base)}`);
 
-    const tools = fs.readFileSync(path.join(mcpillDir, "tools.js"), "utf-8");
-    expect(tools).toContain("read_file");
+    const pillMd = fs.readFileSync(path.join(base, "PILL.md"), "utf-8");
+    expect(pillMd).toContain(".mcpill/pill-agent-guide.md");
   });
 
   it("exits with code 1 and correct message when .mcpill/ already exists", async () => {

package/src/__tests__/pack.test.ts

@@ -5,7 +5,7 @@ import os from "os";
 import { runPack, SERVER_ENTRY_TEMPLATE } from "../commands/pack.js";
 
 function scaffoldPill(baseDir: string, name = "test-pill") {
-  const mcpillDir = path.join(baseDir, ".test-pill");
+  const mcpillDir = path.join(baseDir, ".mcpill", "server");
   fs.mkdirSync(mcpillDir, { recursive: true });
   fs.writeFileSync(
     path.join(mcpillDir, "tools.js"),