mcpill 1.1.0

package/src/commands/run.ts

@@ -0,0 +1,101 @@
+import path from "path";
+import fs from "fs";
+import { z } from "mcpill-runtime";
+import { createServer } 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 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 [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,
+    });
+  }
+
+  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

@@ -0,0 +1,70 @@
+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 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) {
+    console.error("No pill directories found — run mcpill compile first");
+    process.exit(1);
+  }
+
+  for (const mcpillDir of pillDirs) {
+    await validateOne(mcpillDir);
+  }
+}

package/src/compiler/merge-tools.ts

@@ -0,0 +1,99 @@
+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 };
+}

package/src/compiler/parse.ts

@@ -0,0 +1,236 @@
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import type { ServerDoc, ToolDoc, PromptDoc, ResourceDoc } from './types.js';
+
+function extractSections(content: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  const pieces = ('\n' + content).split('\n## ');
+  for (const piece of pieces) {
+    if (!piece.trim()) continue;
+    const nlIdx = piece.indexOf('\n');
+    if (nlIdx === -1) continue;
+    const name = piece.slice(0, nlIdx).trim();
+    const body = piece.slice(nlIdx + 1);
+    sections.set(name, body);
+  }
+  return sections;
+}
+
+function extractFencedBlock(body: string, lang: string): string | null {
+  // Match ``` + lang followed immediately by a newline to avoid matching
+  // a longer lang identifier (e.g. ```json when looking for ```js).
+  const startMarker = '```' + lang + '\n';
+  const start = body.indexOf(startMarker);
+  if (start === -1) return null;
+  const contentStart = start + startMarker.length;
+  const end = body.indexOf('\n```', contentStart);
+  if (end === -1) return body.slice(contentStart).trim();
+  return body.slice(contentStart, end).trim();
+}
+
+export function parseKvBlock(body: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const line of body.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function parseFrontmatter(block: string): Record<string, string> {
+  return parseKvBlock(block);
+}
+
+function stripHandlerMarkers(jsContent: string): string {
+  return jsContent
+    .split('\n')
+    .filter((l) => !l.trim().startsWith('// @handler:') && !l.trim().startsWith('// @end-handler:'))
+    .join('\n')
+    .trim();
+}
+
+function parseToolsSection(body: string): ToolDoc[] {
+  const tools: ToolDoc[] = [];
+  const pieces = ('\n' + body).split('\n### ');
+  for (const piece of pieces.slice(1)) {
+    const nlIdx = piece.indexOf('\n');
+    const name = (nlIdx === -1 ? piece : piece.slice(0, nlIdx)).trim();
+    const rest = nlIdx === -1 ? '' : piece.slice(nlIdx + 1);
+
+    const descMatch = rest.match(/\*\*Description:\*\*\s*(.+)/);
+    const description = descMatch?.[1]?.trim() ?? '';
+
+    const schemaStr = extractFencedBlock(rest, 'json');
+    const schema = schemaStr
+      ? (JSON.parse(schemaStr) as ToolDoc['schema'])
+      : {};
+
+    const jsBlock = extractFencedBlock(rest, 'js');
+    // Strip @handler/@end-handler markers so ToolDoc.handler holds only the function source.
+    const handler = jsBlock !== null ? stripHandlerMarkers(jsBlock) : undefined;
+
+    tools.push({ name, description, schema, handler });
+  }
+  return tools;
+}
+
+function parseResourcesSection(body: string): ResourceDoc[] {
+  const resources: ResourceDoc[] = [];
+  const blocks = body.split('\n---\n');
+  for (let i = 0; i < blocks.length; i += 2) {
+    const frontmatterBlock = (blocks[i] ?? '').trim();
+    if (!frontmatterBlock) continue;
+    const bodyBlock = blocks[i + 1] ?? '';
+    const frontmatter = parseFrontmatter(frontmatterBlock);
+    if (!frontmatter['uri']) continue;
+    resources.push({
+      uri: frontmatter['uri'],
+      name: frontmatter['name'],
+      mimeType: frontmatter['mimeType'],
+      content: bodyBlock.trim(),
+    });
+  }
+  return resources;
+}
+
+function parseToolFile(content: string): ToolDoc {
+  const lines = content.split('\n');
+
+  const h1Line = lines.find((l) => l.startsWith('# '));
+  const name = h1Line ? h1Line.slice(2).trim() : '';
+
+  let h1Seen = false;
+  let description = '';
+  for (const line of lines) {
+    if (line.startsWith('# ')) { h1Seen = true; continue; }
+    if (!h1Seen) continue;
+    if (line.startsWith('#')) break;
+    const trimmed = line.trim();
+    if (trimmed) { description = trimmed; break; }
+  }
+
+  const sections = extractSections(content);
+
+  const parametersBody = sections.get('Parameters') ?? '';
+  const schema: ToolDoc['schema'] = {};
+  for (const line of parametersBody.split('\n')) {
+    if (!line.startsWith('- ')) continue;
+    const m = line.match(/^- (\w+) \(([^)]+)\): (.+)/);
+    if (!m) continue;
+    const pName = m[1]!;
+    const typeStr = m[2]!.split(',')[0]!.trim() as 'string' | 'number' | 'boolean';
+    const desc = m[3]!.trim();
+    schema[pName] = { type: typeStr, description: desc };
+  }
+
+  const handlerBody = sections.get('Handler') ?? '';
+  const handler = extractFencedBlock(handlerBody, 'js') ?? undefined;
+
+  return { name, description, schema, handler };
+}
+
+function parsePromptFile(content: string): PromptDoc {
+  const lines = content.split('\n');
+
+  const h1Line = lines.find((l) => l.startsWith('# '));
+  const name = h1Line ? h1Line.slice(2).trim() : '';
+
+  let h1Seen = false;
+  let description = '';
+  for (const line of lines) {
+    if (line.startsWith('# ')) { h1Seen = true; continue; }
+    if (!h1Seen) continue;
+    if (line.startsWith('#')) break;
+    const trimmed = line.trim();
+    if (trimmed) { description = trimmed; break; }
+  }
+
+  const sections = extractSections(content);
+
+  const argsBody = sections.get('Args') ?? '';
+  const args: PromptDoc['args'] = {};
+  for (const line of argsBody.split('\n')) {
+    if (!line.startsWith('- ')) continue;
+    const m = line.match(/^- (\w+) \(([^)]+)\): .+/);
+    if (!m) continue;
+    args[m[1]!] = { type: m[2]!.trim() };
+  }
+
+  const messageBody = sections.get('Message') ?? '';
+  const messages: PromptDoc['messages'] = [];
+  for (const line of messageBody.split('\n')) {
+    if (!line.startsWith('> ')) continue;
+    const colonIdx = line.indexOf(': ', 2);
+    if (colonIdx === -1) continue;
+    const role = line.slice(2, colonIdx).trim();
+    const msgContent = line.slice(colonIdx + 2).trim();
+    messages.push({ role, content: msgContent });
+  }
+
+  return { name, description, args, messages };
+}
+
+export function parseServerDoc(content: string): ServerDoc {
+  const sections = extractSections(content);
+
+  const configBody = sections.get('Config') ?? '';
+  const configStr = extractFencedBlock(configBody, 'json') ?? '{}';
+  const config = JSON.parse(configStr) as ServerDoc['config'];
+
+  const toolsBody = sections.get('Tools') ?? '';
+  const tools = parseToolsSection(toolsBody);
+
+  const promptsBody = sections.get('Prompts') ?? '';
+  const promptsStr = extractFencedBlock(promptsBody, 'json') ?? '[]';
+  const prompts = JSON.parse(promptsStr) as PromptDoc[];
+
+  const resourcesBody = sections.get('Resources') ?? '';
+  const resources = parseResourcesSection(resourcesBody);
+
+  return { config, tools, prompts, resources };
+}
+
+export function parseServerDir(dir: string): ServerDoc {
+  const serverMdContent = readFileSync(join(dir, 'server.md'), 'utf-8');
+  const sections = extractSections(serverMdContent);
+
+  const configBody = sections.get('Config') ?? '';
+  const configKv = parseKvBlock(configBody);
+  const config: ServerDoc['config'] = {
+    name: configKv['name'] ?? '',
+    transport: (configKv['transport'] ?? 'stdio') as 'stdio' | 'http',
+    ...(configKv['port'] ? { port: parseInt(configKv['port'], 10) } : {}),
+  };
+
+  const resourcesBody = sections.get('Resources') ?? '';
+  const resources = parseResourcesSection(resourcesBody);
+
+  const toolsDir = join(dir, 'tools');
+  const tools: ToolDoc[] = [];
+  let toolFiles: string[] = [];
+  try {
+    toolFiles = readdirSync(toolsDir).filter((f) => f.endsWith('.md'));
+  } catch {
+    // tools/ dir doesn't exist — no tools
+  }
+  for (const file of toolFiles) {
+    tools.push(parseToolFile(readFileSync(join(toolsDir, file), 'utf-8')));
+  }
+
+  const promptsDir = join(dir, 'prompts');
+  const prompts: PromptDoc[] = [];
+  let promptFiles: string[] = [];
+  try {
+    promptFiles = readdirSync(promptsDir).filter((f) => f.endsWith('.md'));
+  } catch {
+    // prompts/ dir doesn't exist — no prompts
+  }
+  for (const file of promptFiles) {
+    prompts.push(parsePromptFile(readFileSync(join(promptsDir, file), 'utf-8')));
+  }
+
+  return { config, tools, prompts, resources };
+}

package/src/compiler/serialize.ts

@@ -0,0 +1,100 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import type { ServerDoc, ResourceDoc } from './types.js';
+
+function serializeResources(resources: ResourceDoc[]): string {
+  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');
+}
+
+export function serializeServerDoc(doc: ServerDoc): string {
+  const configSection =
+    `## Config\n\`\`\`json\n${JSON.stringify(doc.config, null, 2)}\n\`\`\``;
+
+  const toolParts = doc.tools.map((tool) => {
+    let part = `### ${tool.name}\n**Description:** ${tool.description}\n\n`;
+    part += `\`\`\`json\n${JSON.stringify(tool.schema, null, 2)}\n\`\`\``;
+    if (tool.handler !== undefined) {
+      part +=
+        `\n\n\`\`\`js\n// @handler:${tool.name}\n${tool.handler}\n// @end-handler:${tool.name}\n\`\`\``;
+    }
+    return part;
+  });
+  const toolsSection =
+    doc.tools.length > 0
+      ? `## Tools\n\n${toolParts.join('\n\n')}`
+      : `## Tools`;
+
+  const promptsSection =
+    `## Prompts\n\`\`\`json\n${JSON.stringify(doc.prompts, null, 2)}\n\`\`\``;
+
+  const resourcesSection =
+    doc.resources.length > 0
+      ? `## Resources\n${serializeResources(doc.resources)}`
+      : `## Resources`;
+
+  return [configSection, toolsSection, promptsSection, resourcesSection].join('\n\n') + '\n';
+}
+
+export function serializeServerDir(doc: ServerDoc, dir: string): void {
+  mkdirSync(join(dir, 'tools'), { recursive: true });
+  mkdirSync(join(dir, 'prompts'), { recursive: true });
+
+  let serverMd = '## Config\n';
+  serverMd += `name: ${doc.config.name}\n`;
+  serverMd += `transport: ${doc.config.transport}\n`;
+  if (doc.config.port !== undefined) serverMd += `port: ${doc.config.port}\n`;
+
+  if (doc.resources.length > 0) {
+    serverMd += `\n## Resources\n${serializeResources(doc.resources)}\n`;
+  } else {
+    serverMd += '\n## Resources\n';
+  }
+
+  writeFileSync(join(dir, 'server.md'), serverMd);
+  console.log('✓ server.md updated');
+
+  for (const tool of doc.tools) {
+    let md = `# ${tool.name}\n\n${tool.description}\n\n## Parameters\n\n`;
+    for (const [pName, pDef] of Object.entries(tool.schema)) {
+      md += `- ${pName} (${pDef.type}): ${pDef.description ?? pName}\n`;
+    }
+    if (tool.handler !== undefined) {
+      const cleanHandler = tool.handler
+        .split('\n')
+        .filter((l) => !l.trim().startsWith('// @handler:') && !l.trim().startsWith('// @end-handler:'))
+        .join('\n')
+        .trim();
+      md += `\n## Handler\n\n\`\`\`js\n${cleanHandler}\n\`\`\`\n`;
+    }
+    writeFileSync(join(dir, 'tools', `${tool.name}.md`), md);
+  }
+
+  for (const prompt of doc.prompts) {
+    let md = `# ${prompt.name}\n\n`;
+    if (prompt.description) md += `${prompt.description}\n\n`;
+    if (Object.keys(prompt.args).length > 0) {
+      md += '## Args\n\n';
+      for (const [argName, argDef] of Object.entries(prompt.args)) {
+        md += `- ${argName} (${argDef.type}): ${argName}\n`;
+      }
+      md += '\n';
+    }
+    if (prompt.messages.length > 0) {
+      md += '## Message\n\n';
+      for (const msg of prompt.messages) {
+        md += `> ${msg.role}: ${msg.content}\n`;
+      }
+    }
+    writeFileSync(join(dir, 'prompts', `${prompt.name}.md`), md);
+  }
+
+  console.log(`✓ tools/ updated (${doc.tools.length} files)`);
+  console.log(`✓ prompts/ updated (${doc.prompts.length} files)`);
+}

package/src/compiler/types.ts

@@ -0,0 +1,27 @@
+export type ToolDoc = {
+  name: string;
+  description: string;
+  schema: Record<string, { type: 'string' | 'number' | 'boolean'; description?: string }>;
+  handler?: string;
+};
+
+export type PromptDoc = {
+  name: string;
+  description?: string;
+  args: Record<string, { type: string }>;
+  messages: Array<{ role: string; content: string }>;
+};
+
+export type ResourceDoc = {
+  uri: string;
+  name?: string;
+  mimeType?: string;
+  content: string;
+};
+
+export type ServerDoc = {
+  config: { name: string; transport: 'stdio' | 'http'; port?: number };
+  tools: ToolDoc[];
+  prompts: PromptDoc[];
+  resources: ResourceDoc[];
+};

package/src/loaders/config.ts

@@ -0,0 +1,25 @@
+import fs from "fs";
+import path from "path";
+
+export type CliConfig = {
+  name: string;
+  transport: "stdio" | "http";
+  port: number;
+};
+
+const defaults: CliConfig = {
+  name: "mcpill-server",
+  transport: "stdio",
+  port: 3333,
+};
+
+export async function loadConfig(mcpillDir: string): Promise<CliConfig> {
+  const configPath = path.join(mcpillDir, "mcpill.config.json");
+  if (!fs.existsSync(configPath)) {
+    return { ...defaults };
+  }
+  const raw = JSON.parse(
+    fs.readFileSync(configPath, "utf-8")
+  ) as Partial<CliConfig>;
+  return { ...defaults, ...raw };
+}