mcpill 1.2.4 → 1.5.0

package/src/commands/init.ts

@@ -1,353 +0,0 @@
-import fs from "fs";
-import path from "path";
-
-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: my-tool
-
-description: Describe what this tool does.
-inputs:
-  - param (string): A parameter.
-output: What the tool returns.
-behavior: |
-  Describe the logic here. Claude will implement it.
-
----
-
-## 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.
-
----
-
-## 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,
-// so the template is inlined here. Keep in sync with src/templates/server.md.
-const SERVER_MD_TEMPLATE = `## Config
-name: my-server
-transport: stdio
-
-## Resources
-uri: info://status
-name: Status
----
-The server is running.
-`;
-
-const GREETING_PROMPT_MD = `# greeting
-
-Generate a greeting
-
-## Args
-
-- name (string): The name to greet
-
-## Message
-
-> 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
-        │   └── my-tool.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)) {
-    console.error(".mcpill/ already exists. Remove it manually to re-init.");
-    process.exit(1);
-  }
-
-  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, "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(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));
-
-  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/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("Next: npm install && mcpill compile && mcpill run");
-}

package/src/commands/pack.ts

@@ -1,38 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { runValidate } from "./validate.js";
-import { loadConfig } from "../loaders/config.js";
-
-export const SERVER_ENTRY_TEMPLATE =
-  "import { runPill } from 'mcpill-runtime';\nrunPill();\n";
-
-export async function runPack(dir: string): Promise<void> {
-  const baseDir = path.resolve(dir);
-  await runValidate(baseDir);
-
-  const pillDir = path.join(baseDir, ".mcpill", "server");
-  const config = await loadConfig(pillDir);
-  const { name } = config;
-
-  fs.mkdirSync(path.join(baseDir, "bin"), { recursive: true });
-  fs.writeFileSync(path.join(baseDir, "bin", "server.js"), SERVER_ENTRY_TEMPLATE);
-
-  const pkgPath = path.join(baseDir, "package.json");
-  let pkg: Record<string, unknown> = {};
-  if (fs.existsSync(pkgPath)) {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as Record<string, unknown>;
-  }
-
-  pkg.type = "module";
-  pkg.bin = { [name]: "bin/server.js" };
-
-  const deps = (pkg.dependencies as Record<string, string> | undefined) ?? {};
-  if (!deps["mcpill-runtime"]) {
-    deps["mcpill-runtime"] = "^0.1.0";
-  }
-  pkg.dependencies = deps;
-
-  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-
-  console.log(`✓ ${name} packed — bin/server.js + package.json ready`);
-}

package/src/commands/publish.ts

@@ -1,17 +0,0 @@
-import { spawnSync } from "child_process";
-import path from "path";
-import { runPack } from "./pack.js";
-
-export async function runPublish(dir: string, access: string): Promise<void> {
-  const baseDir = path.resolve(dir);
-  await runPack(baseDir);
-
-  const result = spawnSync("npm", ["publish", "--access", access], {
-    cwd: baseDir,
-    stdio: "inherit",
-  });
-
-  if (result.status !== 0) {
-    throw new Error("npm publish failed");
-  }
-}

package/src/commands/run.ts

@@ -1,105 +0,0 @@
-import path from "path";
-import fs from "fs";
-import { z } from "mcpill-runtime";
-import { createServer, applySetup } from "mcpster";
-import { loadConfig } from "../loaders/config.js";
-import { loadTools } from "../loaders/tools.js";
-import { loadPrompts } from "../loaders/prompts.js";
-import { loadResources } from "../loaders/resources.js";
-import { runValidate } from "./validate.js";
-
-type ZodRawShape = Record<string, z.ZodTypeAny>;
-
-export async function runServer(opts: {
-  dir?: string;
-  transport?: "stdio" | "http";
-  port?: number;
-}): Promise<void> {
-  const baseDir = path.resolve(opts.dir ?? process.cwd());
-
-  await runValidate(baseDir);
-
-  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),
-    loadPrompts(mcpillDir),
-    loadResources(mcpillDir),
-    loadConfig(mcpillDir),
-  ]);
-
-  const transport = opts.transport ?? config.transport;
-  const port = opts.port ?? config.port;
-  const { name } = config;
-
-  const server = createServer({
-    name,
-    version: "0.1.0",
-    transport,
-    http: { port },
-  });
-
-  for (const { name: toolName, description, schema, handler } of tools) {
-    server.defineTool({
-      name: toolName,
-      description,
-      schema: z.object(schema as ZodRawShape),
-      handler: handler as (input: Record<string, unknown>) => Promise<unknown>,
-    });
-  }
-
-  for (const { name: promptName, description, messages } of prompts) {
-    server.definePrompt({
-      name: promptName,
-      description,
-      handler: async (args: Record<string, string>) =>
-        messages
-          .map((m) =>
-            m.content.replace(
-              /\{\{(\w+)\}\}/g,
-              (_, k: string) => String(args[k] ?? "")
-            )
-          )
-          .join("\n"),
-    });
-  }
-
-  for (const { uri, name: resourceName, content } of resources) {
-    server.defineResource({
-      uri,
-      description: resourceName ?? uri,
-      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) {
-    const nodeErr = err as NodeJS.ErrnoException;
-    if (nodeErr.code === "EADDRINUSE") {
-      console.error(
-        `Port ${port} is already in use. Use --port to specify another.`
-      );
-      process.exit(1);
-    }
-    throw err;
-  }
-
-  process.stderr.write(
-    `✓ MCPill running — ${tools.length} tools, ${prompts.length} prompts, ${resources.length} resources [${transport}]\n`
-  );
-}

package/src/commands/validate.ts

@@ -1,59 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { loadConfig } from "../loaders/config.js";
-import { loadTools } from "../loaders/tools.js";
-import { loadPrompts } from "../loaders/prompts.js";
-import { loadResources } from "../loaders/resources.js";
-
-async function validateOne(mcpillDir: string): Promise<void> {
-  const errors: string[] = [];
-  let toolCount = 0;
-  let promptCount = 0;
-  let resourceCount = 0;
-
-  try {
-    const tools = await loadTools(mcpillDir);
-    toolCount = tools.length;
-  } catch (err) {
-    errors.push(err instanceof Error ? err.message : String(err));
-  }
-
-  try {
-    const prompts = await loadPrompts(mcpillDir);
-    promptCount = prompts.length;
-  } catch (err) {
-    errors.push(err instanceof Error ? err.message : String(err));
-  }
-
-  try {
-    const resources = await loadResources(mcpillDir);
-    resourceCount = resources.length;
-  } catch (err) {
-    errors.push(err instanceof Error ? err.message : String(err));
-  }
-
-  try {
-    await loadConfig(mcpillDir);
-  } catch (err) {
-    errors.push(err instanceof Error ? err.message : String(err));
-  }
-
-  if (errors.length > 0) {
-    for (const error of errors) {
-      console.error(error);
-    }
-    process.exit(1);
-  }
-
-  console.log(`✓ Valid: ${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources`);
-}
-
-export async function runValidate(baseDir: string): Promise<void> {
-  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);
-  }
-
-  await validateOne(serverDir);
-}

package/src/compiler/merge-tools.ts

@@ -1,99 +0,0 @@
-import type { ServerDoc } from './types.js';
-
-function dedent(s: string): string {
-  const lines = s.split('\n');
-  const nonEmpty = lines.filter((l) => l.trim());
-  if (nonEmpty.length === 0) return s;
-  const minIndent = nonEmpty.reduce((min, l) => {
-    const m = l.match(/^([ \t]*)/);
-    return Math.min(min, m?.[1]?.length ?? 0);
-  }, Infinity);
-  return lines.map((l) => l.slice(minIndent === Infinity ? 0 : minIndent)).join('\n');
-}
-
-export function extractHandlers(toolsJsContent: string): Map<string, string> {
-  const result = new Map<string, string>();
-
-  // Marker-based extraction: // @handler:name ... // @end-handler:name
-  // Allow leading whitespace before the // so indented markers in tools.js are matched.
-  const markerRegex = /[ \t]*\/\/ @handler:([^\n]+)\n([\s\S]*?)\n[ \t]*\/\/ @end-handler:[^\n]+/g;
-  let match: RegExpExecArray | null;
-  while ((match = markerRegex.exec(toolsJsContent)) !== null) {
-    result.set(match[1]!.trim(), dedent(match[2]!).trim());
-  }
-
-  if (result.size > 0) return result;
-
-  // Fallback: find name: "toolname" then locate handler: expression via brace counting
-  const nameRegex = /name:\s*["']([^"']+)["']/g;
-  while ((match = nameRegex.exec(toolsJsContent)) !== null) {
-    const toolName = match[1]!;
-    const handlerKeyIdx = toolsJsContent.indexOf('handler:', match.index);
-    if (handlerKeyIdx === -1) continue;
-    const expr = extractExpression(toolsJsContent, handlerKeyIdx + 'handler:'.length);
-    if (expr) result.set(toolName, expr);
-  }
-
-  return result;
-}
-
-function extractExpression(src: string, start: number): string | null {
-  let i = start;
-  while (i < src.length && /[ \t]/.test(src[i]!)) i++;
-  const exprStart = i;
-  let depth = 0;
-  let inStr: string | null = null;
-
-  while (i < src.length) {
-    const ch = src[i]!;
-    if (inStr) {
-      if (ch === '\\') { i += 2; continue; }
-      if (ch === inStr) inStr = null;
-    } else if (ch === '"' || ch === "'" || ch === '`') {
-      inStr = ch;
-    } else if (ch === '{' || ch === '(' || ch === '[') {
-      depth++;
-    } else if (ch === '}' || ch === ')' || ch === ']') {
-      depth--;
-      if (depth === 0) {
-        // Peek ahead: if followed by => this is an arrow function params group,
-        // so continue scanning to capture the body too.
-        const rest = src.slice(i + 1);
-        const arrowMatch = rest.match(/^[ \t]*=>/);
-        if (arrowMatch) {
-          i += 1 + arrowMatch[0].length;
-          while (i < src.length && /[ \t]/.test(src[i]!)) i++;
-          // Reset depth — next balanced group is the body
-          continue;
-        }
-        return src.slice(exprStart, i + 1).trim();
-      }
-    } else if (depth === 0 && (ch === ',' || ch === ';' || ch === '\n')) {
-      break;
-    }
-    i++;
-  }
-
-  if (i > exprStart) return src.slice(exprStart, i).trim();
-  return null;
-}
-
-export function mergeHandlers(
-  doc: ServerDoc,
-  existing: Map<string, string>,
-): { doc: ServerDoc; stubbed: string[] } {
-  const stubbed: string[] = [];
-
-  const tools = doc.tools.map((tool) => {
-    if (tool.handler !== undefined) return tool;
-    const found = existing.get(tool.name);
-    if (found !== undefined) return { ...tool, handler: found };
-    stubbed.push(tool.name);
-    return {
-      ...tool,
-      handler: `async () => ({ content: [{ type: 'text', text: 'TODO: implement ${tool.name}' }] })`,
-    };
-  });
-
-  return { doc: { ...doc, tools }, stubbed };
-}