mcpill 1.1.0 → 1.2.1

package/src/__tests__/validate.test.ts

@@ -52,7 +52,7 @@ describe("runValidate", () => {
 
   it("passes on a valid scaffolded pill dir", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
 
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
@@ -74,7 +74,7 @@ describe("runValidate", () => {
 
   it("collects and prints tool error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Break tools.js: handler is not a function
     fs.writeFileSync(
@@ -92,7 +92,7 @@ describe("runValidate", () => {
 
   it("collects and prints prompt error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     fs.writeFileSync(path.join(mcpillDir, "prompts.json"), "not json {{{");
 
@@ -110,7 +110,7 @@ describe("runValidate", () => {
 
   it("collects and prints resource error then exits 1", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Block missing uri
     fs.writeFileSync(
@@ -130,7 +130,7 @@ describe("runValidate", () => {
 
   it("collects errors from multiple loaders before exiting", async () => {
     const base = mkTmp();
-    const mcpillDir = path.join(base, ".mcpill");
+    const mcpillDir = path.join(base, ".mcpill", "server");
     scaffoldValid(mcpillDir);
     // Break both tools and prompts
     fs.writeFileSync(

package/src/commands/compile.ts

@@ -1,5 +1,5 @@
-import { resolve, join, basename } from 'path';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { pathToFileURL } from 'url';
 import { parseServerDir } from '../compiler/parse.js';
 import { serializeServerDir } from '../compiler/serialize.js';
@@ -62,38 +62,28 @@ function serializeResourcesMd(resources: ServerDoc['resources']): string {
   );
 }
 
-function findPillDirs(baseDir: string): string[] {
-  return readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        existsSync(join(baseDir, e.name, 'mcpill.config.json')),
-    )
-    .map((e) => join(baseDir, e.name));
-}
-
 export async function runCompile(opts: {
   dir?: string;
   toMd?: boolean;
   strict?: boolean;
 }): Promise<void> {
   const baseDir = resolve(opts.dir ?? process.cwd());
+  const mcpillDir = join(baseDir, '.mcpill');
+  const serverDir = join(mcpillDir, 'server');
 
   if (opts.toMd) {
-    const pillDirs = findPillDirs(baseDir);
-    if (pillDirs.length === 0) {
-      throw new Error('No pill directories found — run mcpill compile first');
+    const configPath = join(serverDir, 'mcpill.config.json');
+    if (!existsSync(configPath)) {
+      throw new Error('No pill found — run mcpill compile first');
     }
-    const mcpillDir = pillDirs[0]!;
 
-    const config = await loadConfig(mcpillDir);
-    const resources = await loadResources(mcpillDir);
+    const config = await loadConfig(serverDir);
+    const resources = await loadResources(serverDir);
 
-    const promptsPath = join(mcpillDir, 'prompts.json');
+    const promptsPath = join(serverDir, 'prompts.json');
     const prompts = JSON.parse(readFileSync(promptsPath, 'utf-8')) as ServerDoc['prompts'];
 
-    const toolsPath = join(mcpillDir, 'tools.js');
+    const toolsPath = join(serverDir, 'tools.js');
     const handlers = existsSync(toolsPath)
       ? extractHandlers(readFileSync(toolsPath, 'utf-8'))
       : new Map<string, string>();
@@ -130,15 +120,14 @@ export async function runCompile(opts: {
       resources,
     };
 
-    serializeServerDir(doc, baseDir);
+    serializeServerDir(doc, mcpillDir);
     return;
   }
 
-  // Forward direction: server.md + tools/ + prompts/ → .<name>/
-  const doc = parseServerDir(baseDir);
-  const mcpillDir = join(baseDir, '.' + doc.config.name);
+  // Forward direction: .mcpill/server.md + .mcpill/server/tools/ + .mcpill/server/prompts/ → .mcpill/server/
+  const doc = parseServerDir(mcpillDir);
 
-  const toolsJsPath = join(mcpillDir, 'tools.js');
+  const toolsJsPath = join(serverDir, 'tools.js');
   const existing = existsSync(toolsJsPath)
     ? extractHandlers(readFileSync(toolsJsPath, 'utf-8'))
     : new Map<string, string>();
@@ -152,12 +141,11 @@ export async function runCompile(opts: {
     console.warn(`⚠  Stub generated for tool: ${name}`);
   }
 
-  mkdirSync(mcpillDir, { recursive: true });
-  writeFileSync(join(mcpillDir, 'mcpill.config.json'), JSON.stringify(mergedDoc.config, null, 2));
-  writeFileSync(join(mcpillDir, 'prompts.json'), JSON.stringify(mergedDoc.prompts, null, 2));
-  writeFileSync(join(mcpillDir, 'resources.md'), serializeResourcesMd(mergedDoc.resources));
+  mkdirSync(serverDir, { recursive: true });
+  writeFileSync(join(serverDir, 'mcpill.config.json'), JSON.stringify(mergedDoc.config, null, 2));
+  writeFileSync(join(serverDir, 'prompts.json'), JSON.stringify(mergedDoc.prompts, null, 2));
+  writeFileSync(join(serverDir, 'resources.md'), serializeResourcesMd(mergedDoc.resources));
   writeFileSync(toolsJsPath, generateToolsJs(mergedDoc.tools));
 
-  const pillDirName = '.' + doc.config.name;
-  console.log(`✓ ${pillDirName}/ updated from server.md, tools/, prompts/`);
+  console.log(`✓ .mcpill/server/ updated from .mcpill/server.md, .mcpill/server/tools/, .mcpill/server/prompts/`);
 }

package/src/commands/init.ts

@@ -1,46 +1,222 @@
 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}\` };
-    },
-  },
-];
+const 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\`           → 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. **Write** the server files into the pre-created scaffold at \`.mcpill/\`:
+
+   \`.mcpill/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 were specified.
+   Separate multiple resources with a blank line + \`---\` + blank line.
+
+   \`.mcpill/server/tools/{tool-name}.md\` — 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\` — 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: \`{ 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 |
+`;
+
+function makePillMd(projectName: string): string {
+  return `<!-- ═══════════════════════════════════════════════════════════════
+FOR THE AGENT — read this before doing anything else
+═══════════════════════════════════════════════════════════════
+
+You are building an mcpill MCP server from this document.
+Follow the steps in .mcpill/pill-agent-guide.md.
+
+════════════════════════════════════════════════════════════════ -->
+
+# 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.
+
+---
+
+## 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\`
 `;
+}
+
+const HELLO_MCP_MD = `<!-- ═══════════════════════════════════════════════════════════════
+HELLO-MCP — 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
+═══════════════════════════════════════════════════════════════ -->
+
+# Pill: hello-mcp
+
+---
+
+## Server
+
+name: hello-mcp
+description: A hello-world MCP server — 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.
 
-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
-);
-
-const RESOURCES_MD = `uri: config://app
-name: App Config
 ---
-This resource exposes the application configuration.
+
+## Tool: ping
+
+description: Returns pong with the current UTC timestamp.
+inputs:
+output: A pong message with the current timestamp.
+behavior: |
+  Return the string "pong — " 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 — what is hello-mcp and what can it do?"
 `;
 
 // Embedded content of src/templates/server.md — tsup does not copy non-TS assets,
@@ -86,9 +262,77 @@ Generate a greeting
 > user: Say hello to {{name}}
 `;
 
+function makePillUserGuideMd(projectName: string): string {
+  return `# ${projectName} — mcpill user guide
+
+## Quickstart
+
+1. **Describe your server** in \`PILL.md\` — fill in the \`## Server\` block and add \`## Tool\` sections.
+2. **Build it** — 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}/
+├── PILL.md                            ← describe your server here
+└── .mcpill/
+    ├── server.md                      ← server config (name, transport, resources)
+    ├── pill-agent-guide.md            ← instructions Claude follows when building
+    ├── pill-user-guide.md             ← this file
+    └── server/
+        ├── mcpill.config.json         ← compiled config
+        ├── tools/                     ← one .md file per tool
+        │   └── echo.md
+        └── prompts/                   ← one .md file per prompt (optional)
+            └── 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.
+`;
+}
+
 export async function runInit(opts: { dir?: string }): Promise<void> {
   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)) {
@@ -96,50 +340,30 @@ export async function runInit(opts: { dir?: string }): Promise<void> {
     process.exit(1);
   }
 
-  const configJson = JSON.stringify(
-    { name: projectName, transport: "stdio", port: 3333 },
-    null,
-    2,
-  );
+  fs.mkdirSync(path.join(serverDir, "tools"), { recursive: true });
+  fs.mkdirSync(path.join(serverDir, "prompts"), { recursive: true });
 
-  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}`,
+  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("✓ .mcpill/tools.js");
-  console.log("✓ .mcpill/prompts.json");
-  console.log("✓ .mcpill/resources.md");
-  console.log("✓ .mcpill/mcpill.config.json");
-  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");
+  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("✓ PILL.md                        ← describe your server, then tell Claude: \"Build this PILL.md\"");
+  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");
 }

package/src/commands/pack.ts

@@ -6,25 +6,11 @@ import { loadConfig } from "../loaders/config.js";
 export const SERVER_ENTRY_TEMPLATE =
   "import { runPill } from 'mcpill-runtime';\nrunPill();\n";
 
-function resolvePillDir(baseDir: string): string {
-  const entries = fs.readdirSync(baseDir, { withFileTypes: true });
-  const pill = entries.find(
-    (e) =>
-      e.isDirectory() &&
-      /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-      fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-  );
-  if (!pill) {
-    throw new Error("No pill directory found — run mcpill compile first");
-  }
-  return path.join(baseDir, pill.name);
-}
-
 export async function runPack(dir: string): Promise<void> {
   const baseDir = path.resolve(dir);
   await runValidate(baseDir);
 
-  const pillDir = resolvePillDir(baseDir);
+  const pillDir = path.join(baseDir, ".mcpill", "server");
   const config = await loadConfig(pillDir);
   const { name } = config;
 

package/src/commands/run.ts

@@ -1,7 +1,7 @@
 import path from "path";
 import fs from "fs";
 import { z } from "mcpill-runtime";
-import { createServer } from "mcpster";
+import { createServer, applySetup } from "mcpster";
 import { loadConfig } from "../loaders/config.js";
 import { loadTools } from "../loaders/tools.js";
 import { loadPrompts } from "../loaders/prompts.js";
@@ -19,17 +19,11 @@ export async function runServer(opts: {
 
   await runValidate(baseDir);
 
-  const pillDirs = fs
-    .readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-    )
-    .map((e) => path.join(baseDir, e.name));
-
-  const mcpillDir = pillDirs[0]!;
+  const mcpillDir = path.join(baseDir, ".mcpill", "server");
+  if (!fs.existsSync(path.join(mcpillDir, "mcpill.config.json"))) {
+    console.error("No pill found — run mcpill compile first");
+    process.exit(1);
+  };
 
   const [tools, prompts, resources, config] = await Promise.all([
     loadTools(mcpillDir),
@@ -82,6 +76,16 @@ export async function runServer(opts: {
     });
   }
 
+  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) {

package/src/commands/validate.ts

@@ -49,22 +49,11 @@ async function validateOne(mcpillDir: string): Promise<void> {
 }
 
 export async function runValidate(baseDir: string): Promise<void> {
-  const pillDirs = fs
-    .readdirSync(baseDir, { withFileTypes: true })
-    .filter(
-      (e) =>
-        e.isDirectory() &&
-        /^\.[a-z][a-z0-9-]*$/.test(e.name) &&
-        fs.existsSync(path.join(baseDir, e.name, "mcpill.config.json")),
-    )
-    .map((e) => path.join(baseDir, e.name));
-
-  if (pillDirs.length === 0) {
+  const serverDir = path.join(baseDir, ".mcpill", "server");
+  if (!fs.existsSync(path.join(serverDir, "mcpill.config.json"))) {
     console.error("No pill directories found — run mcpill compile first");
     process.exit(1);
   }
 
-  for (const mcpillDir of pillDirs) {
-    await validateOne(mcpillDir);
-  }
+  await validateOne(serverDir);
 }

package/src/compiler/parse.ts

@@ -208,7 +208,7 @@ export function parseServerDir(dir: string): ServerDoc {
   const resourcesBody = sections.get('Resources') ?? '';
   const resources = parseResourcesSection(resourcesBody);
 
-  const toolsDir = join(dir, 'tools');
+  const toolsDir = join(dir, 'server', 'tools');
   const tools: ToolDoc[] = [];
   let toolFiles: string[] = [];
   try {
@@ -220,7 +220,7 @@ export function parseServerDir(dir: string): ServerDoc {
     tools.push(parseToolFile(readFileSync(join(toolsDir, file), 'utf-8')));
   }
 
-  const promptsDir = join(dir, 'prompts');
+  const promptsDir = join(dir, 'server', 'prompts');
   const prompts: PromptDoc[] = [];
   let promptFiles: string[] = [];
   try {