mcpill 1.1.0

package/src/__tests__/validate.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { runValidate } from "../commands/validate.js";
+
+// Sets up a minimal valid .<name>/ pill dir using CJS tools.js so dynamic
+// import works without a mcpill-runtime resolution in the temp tree.
+function scaffoldValid(mcpillDir: string) {
+  fs.mkdirSync(mcpillDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(mcpillDir, "tools.js"),
+    `module.exports = [{ name: "t", description: "d", schema: {}, handler: async () => ({}) }]`
+  );
+  fs.writeFileSync(
+    path.join(mcpillDir, "prompts.json"),
+    JSON.stringify([{ name: "p", args: {}, messages: [] }])
+  );
+  fs.writeFileSync(
+    path.join(mcpillDir, "resources.md"),
+    "uri: config://app\n---\nContent."
+  );
+  fs.writeFileSync(
+    path.join(mcpillDir, "mcpill.config.json"),
+    JSON.stringify({ name: "srv", transport: "stdio", port: 3333 })
+  );
+}
+
+describe("runValidate", () => {
+  const dirs: string[] = [];
+
+  function mkTmp(): string {
+    const d = fs.mkdtempSync(path.join(os.tmpdir(), "mcpill-validate-"));
+    dirs.push(d);
+    return d;
+  }
+
+  function mockExit() {
+    return vi
+      .spyOn(process, "exit")
+      .mockImplementation((_code?: number | string | null) => {
+        throw new Error("process.exit called");
+      });
+  }
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    for (const d of dirs.splice(0)) {
+      fs.rmSync(d, { recursive: true, force: true });
+    }
+  });
+
+  it("passes on a valid scaffolded pill dir", async () => {
+    const base = mkTmp();
+    const mcpillDir = path.join(base, ".mcpill");
+    scaffoldValid(mcpillDir);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await runValidate(base);
+    expect(logSpy).toHaveBeenCalledWith("✓ Valid: 1 tools, 1 prompts, 1 resources");
+  });
+
+  it("exits with code 1 when no pill directories found", async () => {
+    const base = mkTmp();
+    const exitSpy = mockExit();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(runValidate(base)).rejects.toThrow("process.exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errSpy).toHaveBeenCalledWith(
+      "No pill directories found — run mcpill compile first"
+    );
+  });
+
+  it("collects and prints tool error then exits 1", async () => {
+    const base = mkTmp();
+    const mcpillDir = path.join(base, ".mcpill");
+    scaffoldValid(mcpillDir);
+    // Break tools.js: handler is not a function
+    fs.writeFileSync(
+      path.join(mcpillDir, "tools.js"),
+      `module.exports = [{ name: "t", description: "d", schema: {}, handler: "bad" }]`
+    );
+
+    const exitSpy = mockExit();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(runValidate(base)).rejects.toThrow("process.exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errSpy).toHaveBeenCalledWith("Tool 't': handler must be a function");
+  });
+
+  it("collects and prints prompt error then exits 1", async () => {
+    const base = mkTmp();
+    const mcpillDir = path.join(base, ".mcpill");
+    scaffoldValid(mcpillDir);
+    fs.writeFileSync(path.join(mcpillDir, "prompts.json"), "not json {{{");
+
+    const exitSpy = mockExit();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(runValidate(base)).rejects.toThrow("process.exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(
+      errSpy.mock.calls.some((c) =>
+        String(c[0]).startsWith("prompts.json is not valid JSON:")
+      )
+    ).toBe(true);
+  });
+
+  it("collects and prints resource error then exits 1", async () => {
+    const base = mkTmp();
+    const mcpillDir = path.join(base, ".mcpill");
+    scaffoldValid(mcpillDir);
+    // Block missing uri
+    fs.writeFileSync(
+      path.join(mcpillDir, "resources.md"),
+      "name: No Uri\n---\nContent."
+    );
+
+    const exitSpy = mockExit();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(runValidate(base)).rejects.toThrow("process.exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errSpy).toHaveBeenCalledWith(
+      "resources.md block 1 is missing required frontmatter field: uri"
+    );
+  });
+
+  it("collects errors from multiple loaders before exiting", async () => {
+    const base = mkTmp();
+    const mcpillDir = path.join(base, ".mcpill");
+    scaffoldValid(mcpillDir);
+    // Break both tools and prompts
+    fs.writeFileSync(
+      path.join(mcpillDir, "tools.js"),
+      `module.exports = [{ description: "d", schema: {}, handler: async () => ({}) }]`
+    );
+    fs.writeFileSync(path.join(mcpillDir, "prompts.json"), "bad json");
+
+    const exitSpy = mockExit();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(runValidate(base)).rejects.toThrow("process.exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    // Both errors must have been printed
+    const messages = errSpy.mock.calls.map((c) => String(c[0]));
+    expect(messages.some((m) => m.includes("Tool at index 0 is missing"))).toBe(true);
+    expect(messages.some((m) => m.startsWith("prompts.json is not valid JSON:"))).toBe(true);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,76 @@
+import { Command } from "commander";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { readFileSync } from "fs";
+import { runInit } from "./commands/init.js";
+import { runServer } from "./commands/run.js";
+import { runValidate } from "./commands/validate.js";
+import { runCompile } from "./commands/compile.js";
+import { runPack } from "./commands/pack.js";
+import { runPublish } from "./commands/publish.js";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(pkgDir, "../package.json"), "utf-8")
+) as { version: string };
+
+const program = new Command();
+
+program.name("mcpill").version(pkg.version);
+
+program
+  .command("init")
+  .description("Scaffold a new .mcpill/ directory")
+  .option("--dir <path>", "Target directory")
+  .action(async (opts: { dir?: string }) => {
+    await runInit(opts);
+  });
+
+program
+  .command("run")
+  .description("Start the MCP server")
+  .option("--transport <transport>", "Transport type: stdio or http")
+  .option("--port <n>", "Port number (HTTP only)", parseInt)
+  .option("--dir <path>", "Directory containing .mcpill/")
+  .action(
+    async (opts: { transport?: "stdio" | "http"; port?: number; dir?: string }) => {
+      await runServer(opts);
+    }
+  );
+
+program
+  .command("validate")
+  .description("Validate .mcpill/ configuration")
+  .option("--dir <path>", "Directory containing .mcpill/")
+  .action(async (opts: { dir?: string }) => {
+    const { resolve } = await import("path");
+    await runValidate(resolve(opts.dir ?? process.cwd()));
+  });
+
+program
+  .command("compile")
+  .description("Compile server.md ↔ .mcpill/ files")
+  .option("--dir <path>", "Directory containing server.md and .mcpill/")
+  .option("--to-md", "Reverse: generate server.md from .mcpill/ files")
+  .option("--strict", "Error on missing tool handlers instead of generating stubs")
+  .action(async (opts: { dir?: string; toMd?: boolean; strict?: boolean }) => {
+    await runCompile(opts);
+  });
+
+program
+  .command("pack")
+  .description("Prepare pill for npm distribution")
+  .option("--dir <path>", "pill project root", ".")
+  .action(({ dir }: { dir: string }) => runPack(dir));
+
+program
+  .command("publish")
+  .description("Pack and publish pill to npm")
+  .option("--dir <path>", "pill project root", ".")
+  .option("--access <level>", "npm access level", "public")
+  .action(({ dir, access }: { dir: string; access: string }) => runPublish(dir, access));
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/commands/compile.ts

@@ -0,0 +1,163 @@
+import { resolve, join, basename } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { parseServerDir } from '../compiler/parse.js';
+import { serializeServerDir } from '../compiler/serialize.js';
+import { extractHandlers, mergeHandlers } from '../compiler/merge-tools.js';
+import { loadConfig } from '../loaders/config.js';
+import { loadResources } from '../loaders/resources.js';
+import type { ServerDoc, ToolDoc } from '../compiler/types.js';
+
+const zodTypeNameMap: Record<string, 'string' | 'number' | 'boolean'> = {
+  ZodString: 'string',
+  ZodNumber: 'number',
+  ZodBoolean: 'boolean',
+};
+
+function generateToolsJs(tools: ToolDoc[]): string {
+  const lines: string[] = [`import { z } from 'mcpill-runtime';\n\nexport default [`];
+
+  for (const tool of tools) {
+    const schemaLines = Object.entries(tool.schema).map(([key, def]) => {
+      const zodCall = def.description
+        ? `z.${def.type}().describe(${JSON.stringify(def.description)})`
+        : `z.${def.type}()`;
+      return `      ${key}: ${zodCall},`;
+    });
+
+    // Indent handler lines 6 spaces; dedent+trim is applied on extract so this round-trips cleanly.
+    const handlerBody = (tool.handler ?? '').split('\n').map((l) => `      ${l}`).join('\n');
+
+    lines.push(
+      `  {`,
+      `    name: ${JSON.stringify(tool.name)},`,
+      `    description: ${JSON.stringify(tool.description)},`,
+      `    schema: {`,
+      ...schemaLines,
+      `    },`,
+      `    handler:`,
+      `      // @handler:${tool.name}`,
+      handlerBody,
+      `      // @end-handler:${tool.name}`,
+      `    ,`,
+      `  },`,
+    );
+  }
+
+  lines.push(`];`);
+  return lines.join('\n') + '\n';
+}
+
+function serializeResourcesMd(resources: ServerDoc['resources']): string {
+  if (resources.length === 0) return '';
+  return (
+    resources
+      .map((r) => {
+        let fm = `uri: ${r.uri}`;
+        if (r.name) fm += `\nname: ${r.name}`;
+        if (r.mimeType) fm += `\nmimeType: ${r.mimeType}`;
+        return `${fm}\n---\n${r.content}`;
+      })
+      .join('\n---\n') + '\n'
+  );
+}
+
+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());
+
+  if (opts.toMd) {
+    const pillDirs = findPillDirs(baseDir);
+    if (pillDirs.length === 0) {
+      throw new Error('No pill directories found — run mcpill compile first');
+    }
+    const mcpillDir = pillDirs[0]!;
+
+    const config = await loadConfig(mcpillDir);
+    const resources = await loadResources(mcpillDir);
+
+    const promptsPath = join(mcpillDir, 'prompts.json');
+    const prompts = JSON.parse(readFileSync(promptsPath, 'utf-8')) as ServerDoc['prompts'];
+
+    const toolsPath = join(mcpillDir, 'tools.js');
+    const handlers = existsSync(toolsPath)
+      ? extractHandlers(readFileSync(toolsPath, 'utf-8'))
+      : new Map<string, string>();
+
+    let tools: ToolDoc[] = [];
+    if (existsSync(toolsPath)) {
+      const mod = (await import(pathToFileURL(toolsPath).href)) as {
+        default: Array<{ name: string; description: string; schema: Record<string, unknown> }>;
+      };
+      tools = mod.default.map((t) => {
+        const schema: ToolDoc['schema'] = {};
+        for (const [key, val] of Object.entries(t.schema)) {
+          const def = (val as { _def: { typeName: string; description?: string } })._def;
+          const type = zodTypeNameMap[def.typeName] ?? 'string';
+          schema[key] = def.description ? { type, description: def.description } : { type };
+        }
+        return {
+          name: t.name,
+          description: t.description,
+          schema,
+          handler: handlers.get(t.name),
+        };
+      });
+    }
+
+    const doc: ServerDoc = {
+      config: {
+        name: config.name,
+        transport: config.transport,
+        ...(config.port !== 3333 ? { port: config.port } : {}),
+      },
+      tools,
+      prompts,
+      resources,
+    };
+
+    serializeServerDir(doc, baseDir);
+    return;
+  }
+
+  // Forward direction: server.md + tools/ + prompts/ → .<name>/
+  const doc = parseServerDir(baseDir);
+  const mcpillDir = join(baseDir, '.' + doc.config.name);
+
+  const toolsJsPath = join(mcpillDir, 'tools.js');
+  const existing = existsSync(toolsJsPath)
+    ? extractHandlers(readFileSync(toolsJsPath, 'utf-8'))
+    : new Map<string, string>();
+
+  const { doc: mergedDoc, stubbed } = mergeHandlers(doc, existing);
+
+  if (opts.strict && stubbed.length > 0) {
+    throw new Error('Missing handlers for: ' + stubbed.join(', '));
+  }
+  for (const name of stubbed) {
+    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));
+  writeFileSync(toolsJsPath, generateToolsJs(mergedDoc.tools));
+
+  const pillDirName = '.' + doc.config.name;
+  console.log(`✓ ${pillDirName}/ updated from server.md, tools/, prompts/`);
+}

package/src/commands/init.ts

@@ -0,0 +1,145 @@
+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 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.
+`;
+
+// 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 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
+
+## Args
+
+- name (string): The name to greet
+
+## Message
+
+> user: Say hello to {{name}}
+`;
+
+export async function runInit(opts: { dir?: string }): Promise<void> {
+  const targetDir = path.resolve(opts.dir ?? process.cwd());
+  const mcpillDir = path.join(targetDir, ".mcpill");
+  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.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");
+}

package/src/commands/pack.ts

@@ -0,0 +1,52 @@
+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";
+
+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 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

@@ -0,0 +1,17 @@
+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");
+  }
+}