mcpmake 0.1.0

package/dist/emitter/templates/task-handlers.ts.hbs

@@ -0,0 +1,189 @@
+/**
+ * HTTP route handlers for task management.
+ * Provides REST endpoints for querying, waiting on, and cancelling async tasks.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  getTask,
+  updateTask,
+  cancelTask,
+  listTasks,
+  getResult,
+  type Task,
+  type TaskStatus,
+} from './task-manager.js';
+
+const VALID_STATUSES = new Set<string>([
+  'working', 'input_required', 'completed', 'failed', 'cancelled',
+]);
+
+/* ── MCP Tasks extension (2026-07-28) — JSON-RPC over /mcp ────────────────
+ * The 2026-07-28 RC moves Tasks to an extension driven by tasks/get,
+ * tasks/update, and tasks/cancel; tasks/list is removed (it can't be scoped
+ * without sessions). The current SDK doesn't dispatch these, so server-main
+ * peeks the JSON-RPC body and calls handleTaskRpc. Wire shapes are marked
+ * VERIFY — the RC is not final. The REST routes above are retained during the
+ * 12-month grace period. */
+
+/** Serialize a task for the wire (VERIFY field names against the final spec). */
+function taskToWire(task: Task): Record<string, unknown> {
+  return {
+    taskId: task.id,
+    status: task.status,
+    result: task.result,
+    error: task.error,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt,
+  };
+}
+
+function rpcResult(id: unknown, result: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', id: id ?? null, result };
+}
+
+function rpcError(id: unknown, code: number, message: string): Record<string, unknown> {
+  return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
+}
+
+/**
+ * Handle a `tasks/*` JSON-RPC method. Returns a JSON-RPC response object, or
+ * `null` if the method isn't a recognized task method (caller forwards it on).
+ */
+export function handleTaskRpc(
+  method: string,
+  params: unknown,
+  id: unknown,
+): Record<string, unknown> | null {
+  const p = (params ?? {}) as { taskId?: unknown; status?: unknown; result?: unknown; error?: unknown };
+  const taskId = typeof p.taskId === 'string' ? p.taskId : '';
+
+  switch (method) {
+    case 'tasks/get': {
+      const task = getTask(taskId);
+      return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
+    }
+    case 'tasks/update': {
+      const status =
+        typeof p.status === 'string' && VALID_STATUSES.has(p.status)
+          ? (p.status as TaskStatus)
+          : undefined;
+      const task = updateTask(taskId, {
+        status,
+        result: p.result,
+        error: typeof p.error === 'string' ? p.error : undefined,
+      });
+      return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
+    }
+    case 'tasks/cancel': {
+      const task = cancelTask(taskId);
+      return task ? rpcResult(id, taskToWire(task)) : rpcError(id, -32001, `Task ${taskId} not found`);
+    }
+    case 'tasks/list':
+      // Removed in the 2026-07-28 Tasks extension (can't be scoped without sessions).
+      return rpcError(id, -32601, 'tasks/list is not supported (removed in the Tasks extension)');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Route handler for task endpoints. Returns true if the request was handled.
+ */
+export function handleTaskRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+): boolean {
+  const method = req.method ?? 'GET';
+  const path = url.pathname;
+
+  // GET /tasks — list tasks
+  if (path === '/tasks' && method === 'GET') {
+    const statusParam = url.searchParams.get('status') ?? undefined;
+    const limitParam = url.searchParams.get('limit');
+    const limit = limitParam ? parseInt(limitParam, 10) : 50;
+
+    if (statusParam && !VALID_STATUSES.has(statusParam)) {
+      sendJson(res, 400, { error: `Invalid status filter: ${statusParam}` });
+      return true;
+    }
+
+    const tasks = listTasks(statusParam as TaskStatus | undefined, limit);
+    sendJson(res, 200, { tasks });
+    return true;
+  }
+
+  // Match /tasks/:taskId routes
+  const taskIdMatch = path.match(/^\/tasks\/([0-9a-f-]{36})(\/.*)?$/);
+  if (!taskIdMatch) return false;
+
+  const taskId = taskIdMatch[1];
+  const subPath = taskIdMatch[2] ?? '';
+
+  // GET /tasks/:taskId — get task status
+  if (subPath === '' && method === 'GET') {
+    const task = getTask(taskId);
+    if (!task) {
+      sendJson(res, 404, { error: `Task ${taskId} not found` });
+      return true;
+    }
+    sendJson(res, 200, {
+      taskId: task.id,
+      status: task.status,
+      result: task.result,
+      error: task.error,
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt,
+    });
+    return true;
+  }
+
+  // GET /tasks/:taskId/result — wait for task result
+  if (subPath === '/result' && method === 'GET') {
+    const timeoutParam = url.searchParams.get('timeout');
+    const timeoutMs = timeoutParam ? parseInt(timeoutParam, 10) : 30000;
+
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 300000) {
+      sendJson(res, 400, { error: 'timeout must be between 0 and 300000 ms' });
+      return true;
+    }
+
+    getResult(taskId, timeoutMs)
+      .then((task) => {
+        sendJson(res, 200, {
+          taskId: task.id,
+          status: task.status,
+          result: task.result,
+          error: task.error,
+        });
+      })
+      .catch((err: Error) => {
+        if (err.message === 'timeout') {
+          sendJson(res, 408, { error: 'Timed out waiting for task result' });
+        } else {
+          sendJson(res, 404, { error: err.message });
+        }
+      });
+
+    return true;
+  }
+
+  // POST /tasks/:taskId/cancel — cancel a task
+  if (subPath === '/cancel' && method === 'POST') {
+    const task = cancelTask(taskId);
+    if (!task) {
+      sendJson(res, 404, { error: `Task ${taskId} not found` });
+      return true;
+    }
+    sendJson(res, 200, { taskId: task.id, status: task.status });
+    return true;
+  }
+
+  return false;
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}

package/dist/emitter/templates/task-manager.ts.hbs

@@ -0,0 +1,139 @@
+/**
+ * MCP Task state machine for async/long-running operations.
+ *
+ * Tasks are created when a tool returns 202 Accepted. The task manager
+ * tracks state transitions and notifies via SSE when status changes.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+
+export type TaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+
+export interface Task {
+  id: string;
+  toolName: string;
+  status: TaskStatus;
+  result?: unknown;
+  error?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TaskStatusChangeEvent {
+  task: Task;
+  previousStatus: TaskStatus;
+}
+
+const tasks = new Map<string, Task>();
+const MAX_TASKS = 1000;
+
+/**
+ * Event emitter for task status changes.
+ * Emits 'statusChange' events with { task, previousStatus }.
+ */
+export const taskEvents = new EventEmitter();
+
+export function createTask(toolName: string): Task {
+  // Evict oldest if at capacity
+  if (tasks.size >= MAX_TASKS) {
+    const oldest = tasks.keys().next().value;
+    if (oldest) tasks.delete(oldest);
+  }
+
+  const task: Task = {
+    id: randomUUID(),
+    toolName,
+    status: 'working',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  tasks.set(task.id, task);
+  return task;
+}
+
+export function getTask(taskId: string): Task | undefined {
+  return tasks.get(taskId);
+}
+
+export function updateTask(
+  taskId: string,
+  update: { status?: TaskStatus; result?: unknown; error?: string },
+): Task | undefined {
+  const task = tasks.get(taskId);
+  if (!task) return undefined;
+
+  const previousStatus = task.status;
+  if (update.status) task.status = update.status;
+  if (update.result !== undefined) task.result = update.result;
+  if (update.error !== undefined) task.error = update.error;
+  task.updatedAt = new Date().toISOString();
+
+  if (task.status !== previousStatus) {
+    taskEvents.emit('statusChange', { task, previousStatus } as TaskStatusChangeEvent);
+  }
+
+  return task;
+}
+
+export function cancelTask(taskId: string): Task | undefined {
+  const task = tasks.get(taskId);
+  if (!task) return undefined;
+  if (task.status === 'completed' || task.status === 'failed') return task;
+
+  const previousStatus = task.status;
+  task.status = 'cancelled';
+  task.updatedAt = new Date().toISOString();
+
+  taskEvents.emit('statusChange', { task, previousStatus } as TaskStatusChangeEvent);
+
+  return task;
+}
+
+export function listTasks(status?: TaskStatus, limit?: number): Task[] {
+  const all = [...tasks.values()];
+  const filtered = status ? all.filter((t) => t.status === status) : all;
+  return limit !== undefined && limit > 0 ? filtered.slice(0, limit) : filtered;
+}
+
+/**
+ * Returns a promise that resolves with the task when it reaches a terminal
+ * state (completed, failed, cancelled), or rejects if the timeout elapses.
+ */
+export function getResult(taskId: string, timeoutMs: number = 30000): Promise<Task> {
+  return new Promise((resolve, reject) => {
+    const task = tasks.get(taskId);
+    if (!task) {
+      reject(new Error(`Task ${taskId} not found`));
+      return;
+    }
+
+    // Already in a terminal state
+    if (task.status === 'completed' || task.status === 'failed' || task.status === 'cancelled') {
+      resolve(task);
+      return;
+    }
+
+    const cleanup = (): void => {
+      taskEvents.removeListener('statusChange', onChange);
+      clearTimeout(timer);
+    };
+
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error('timeout'));
+    }, timeoutMs);
+
+    const onChange = (event: TaskStatusChangeEvent): void => {
+      if (event.task.id !== taskId) return;
+      const s = event.task.status;
+      if (s === 'completed' || s === 'failed' || s === 'cancelled') {
+        cleanup();
+        resolve(event.task);
+      }
+    };
+
+    taskEvents.on('statusChange', onChange);
+  });
+}

package/dist/emitter/templates/task-sse.ts.hbs

@@ -0,0 +1,105 @@
+/**
+ * Server-Sent Events endpoint for real-time task status notifications.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { taskEvents, type TaskStatusChangeEvent } from './task-manager.js';
+
+interface SseConnection {
+  res: ServerResponse;
+  taskIdFilter: string | null;
+}
+
+const connections = new Set<SseConnection>();
+
+const HEARTBEAT_INTERVAL_MS = 30000;
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+function ensureHeartbeat(): void {
+  if (heartbeatTimer) return;
+  heartbeatTimer = setInterval(() => {
+    for (const conn of connections) {
+      if (!conn.res.writableEnded) {
+        conn.res.write(':ping\n\n');
+      }
+    }
+  }, HEARTBEAT_INTERVAL_MS);
+  heartbeatTimer.unref();
+}
+
+function stopHeartbeatIfEmpty(): void {
+  if (connections.size === 0 && heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+function broadcast(eventName: string, data: unknown, taskId: string): void {
+  const payload = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+  for (const conn of connections) {
+    if (conn.res.writableEnded) continue;
+    if (conn.taskIdFilter && conn.taskIdFilter !== taskId) continue;
+    conn.res.write(payload);
+  }
+}
+
+/* Subscribe to task status changes and broadcast SSE events */
+taskEvents.on('statusChange', (event: TaskStatusChangeEvent) => {
+  const { task } = event;
+
+  broadcast('task.status', {
+    taskId: task.id,
+    status: task.status,
+    updatedAt: task.updatedAt,
+  }, task.id);
+
+  if (task.status === 'completed') {
+    broadcast('task.completed', {
+      taskId: task.id,
+      status: 'completed',
+      result: task.result,
+    }, task.id);
+  } else if (task.status === 'failed') {
+    broadcast('task.failed', {
+      taskId: task.id,
+      status: 'failed',
+      error: task.error,
+    }, task.id);
+  }
+});
+
+/**
+ * Handle the SSE endpoint: GET /tasks/events
+ * Returns true if the request was handled.
+ */
+export function handleTaskSse(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+): boolean {
+  if (url.pathname !== '/tasks/events' || (req.method ?? 'GET') !== 'GET') {
+    return false;
+  }
+
+  const taskIdFilter = url.searchParams.get('taskId') ?? null;
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  });
+
+  // Initial comment to confirm connection
+  res.write(':connected\n\n');
+
+  const conn: SseConnection = { res, taskIdFilter };
+  connections.add(conn);
+  ensureHeartbeat();
+
+  req.on('close', () => {
+    connections.delete(conn);
+    stopHeartbeatIfEmpty();
+  });
+
+  return true;
+}

package/dist/emitter/templates/tool-handler.ts.hbs

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeRequest } from '../http.js';
+import type { AppConfig } from '../config.js';
+{{#if isAsync}}
+import { createTask, updateTask } from '../task-manager.js';
+{{/if}}
+
+const inputSchema = {{{inputSchemaCode}}};
+{{#if outputSchemaCode}}
+const outputSchema = {{{outputSchemaCode}}};
+{{/if}}
+
+/** Execute the HTTP request for this tool and return the (optionally filtered) data. */
+async function runRequest(input: Record<string, unknown>, config: AppConfig): Promise<unknown> {
+  const url = buildUrl(input, config.baseUrl);
+
+  const response = await executeRequest({
+    method: '{{method}}',
+    url,
+{{#if hasRequestBody}}
+    body: input.body,
+    contentType: '{{requestBodyContentType}}',
+{{/if}}
+    headers: {},
+    config,
+  });
+
+{{#if jqFilter}}
+  // Apply x-mcp-jq-filter to trim response before returning to agent
+  let result: unknown = response.data;
+  try {
+    const parts = '{{{jqFilter}}}'.split('.');
+    for (const part of parts) {
+      if (part && result != null && typeof result === 'object') {
+        result = (result as Record<string, unknown>)[part];
+      }
+    }
+  } catch {
+    // Filter failed — return full response
+    result = response.data;
+  }
+  return result;
+{{else}}
+  return response.data;
+{{/if}}
+}
+
+export function register(server: McpServer, config: AppConfig): void {
+  server.registerTool(
+    '{{name}}',
+    {
+      title: '{{title}}',
+      description: `{{{description}}}`,
+      inputSchema,
+{{#if outputSchemaCode}}
+      outputSchema,
+{{/if}}
+{{#if annotations}}
+      annotations: {
+{{#if annotations.readOnlyHint}}
+        readOnlyHint: true,
+{{/if}}
+{{#if annotations.destructiveHint}}
+        destructiveHint: true,
+{{/if}}
+{{#if annotations.idempotentHint}}
+        idempotentHint: true,
+{{/if}}
+      },
+{{/if}}
+    },
+    async (input) => {
+{{#if isAsync}}
+      // Tasks extension (2026-07-28): a long-running tool answers immediately
+      // with a task handle and runs the work in the background; the client
+      // drives it with tasks/get / tasks/update / tasks/cancel. VERIFY the
+      // returned handle envelope against the final spec.
+      const task = createTask('{{name}}');
+      void (async () => {
+        try {
+          const result = await runRequest(input as Record<string, unknown>, config);
+          updateTask(task.id, { status: 'completed', result });
+        } catch (error) {
+          updateTask(task.id, {
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      })();
+      const handle = { taskId: task.id, status: task.status };
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify({ task: handle }, null, 2) }],
+        structuredContent: { task: handle },
+      };
+{{else}}
+      try {
+        const result = await runRequest(input as Record<string, unknown>, config);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+{{/if}}
+    },
+  );
+}
+
+function buildUrl(
+  params: Record<string, unknown>,
+  baseUrl: string,
+): string {
+{{{buildUrlBody}}}
+}

package/dist/emitter/templates/tool-index.ts.hbs

@@ -0,0 +1,11 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppConfig } from '../config.js';
+{{#each tools}}
+import { register as register{{capitalize functionName}} } from './{{fileName}}.js';
+{{/each}}
+
+export function registerAllTools(server: McpServer, config: AppConfig): void {
+{{#each tools}}
+  register{{capitalize functionName}}(server, config);
+{{/each}}
+}

package/dist/emitter/templates/tool-test.ts.hbs

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppConfig } from '../../src/config.js';
+import { register } from '../../src/tools/{{fileName}}.js';
+
+/**
+ * Capture the server.registerTool() call without a real MCP server or any
+ * network access. The tool's HTTP handler is never invoked here.
+ */
+function capture(): { name: string; def: Record<string, unknown>; handler: unknown }[] {
+  const calls: { name: string; def: Record<string, unknown>; handler: unknown }[] = [];
+  const server = {
+    registerTool(name: string, def: Record<string, unknown>, handler: unknown) {
+      calls.push({ name, def, handler });
+    },
+  } as unknown as McpServer;
+  const config = {
+    baseUrl: 'https://example.test',
+    maxRetries: 0,
+    requestIntervalMs: 0,
+  } as unknown as AppConfig;
+  register(server, config);
+  return calls;
+}
+
+describe('{{name}}', () => {
+  // Tool: {{name}} — {{method}} {{pathTemplate}}
+
+  it('registers exactly one tool under its name', () => {
+    const calls = capture();
+    expect(calls).toHaveLength(1);
+    expect(calls[0].name).toBe('{{name}}');
+  });
+
+  it('exposes a title and description', () => {
+    const { def } = capture()[0];
+    expect(def.title).toBeTruthy();
+    expect(typeof def.description).toBe('string');
+  });
+
+  it('registers a callable handler', () => {
+    expect(typeof capture()[0].handler).toBe('function');
+  });
+
+  it('has a well-formed input schema', () => {
+    const raw = capture()[0].def.inputSchema as unknown;
+    // inputSchema is a Zod raw shape (record of validators); it must build into
+    // a usable object schema and run without throwing.
+    const schema =
+      raw && typeof (raw as { safeParse?: unknown }).safeParse === 'function'
+        ? (raw as z.ZodTypeAny)
+        : z.object(raw as z.ZodRawShape);
+    const result = schema.safeParse({});
+    expect(typeof result.success).toBe('boolean');
+  });
+});

package/dist/emitter/templates/trace.ts.hbs

@@ -0,0 +1,79 @@
+/**
+ * W3C Trace Context propagation (https://www.w3.org/TR/trace-context/).
+ *
+ * The HTTP server reads an inbound `traceparent` (joining a distributed trace)
+ * or starts a fresh one, binds it to the request via AsyncLocalStorage, and the
+ * HTTP executor stamps it onto every upstream API call so the trace spans the
+ * API hop. Stdio servers never establish a context, so upstream calls simply
+ * carry no trace headers (the store is empty — `traceHeaders()` returns `{}`).
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+
+export interface TraceContext {
+  /** 32-hex trace id, shared across the whole distributed trace. */
+  traceId: string;
+  /** 16-hex span id for this server's work (the parent of upstream calls). */
+  spanId: string;
+  /** 2-hex trace-flags (`01` = sampled). */
+  flags: string;
+  /** Opaque vendor `tracestate`, propagated verbatim when present. */
+  traceState?: string;
+}
+
+const storage = new AsyncLocalStorage<TraceContext>();
+
+const TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const INVALID_TRACE_ID = '0'.repeat(32);
+
+/** Parse a `traceparent` header; returns its trace id + flags, or null if invalid. */
+export function parseTraceparent(
+  header: string | undefined,
+): { traceId: string; flags: string } | null {
+  if (!header) return null;
+  const match = TRACEPARENT_RE.exec(header.trim().toLowerCase());
+  if (!match) return null;
+  const traceId = match[1];
+  const flags = match[3];
+  if (traceId === INVALID_TRACE_ID) return null;
+  return { traceId, flags };
+}
+
+/**
+ * Build the context for a request: continue a valid inbound trace, otherwise
+ * start a new one. A fresh span id is always minted for this server's work.
+ */
+export function deriveContext(traceparent?: string, tracestate?: string): TraceContext {
+  const parent = parseTraceparent(traceparent);
+  return {
+    traceId: parent?.traceId ?? randomBytes(16).toString('hex'),
+    spanId: randomBytes(8).toString('hex'),
+    flags: parent?.flags ?? '01',
+    traceState: tracestate?.trim() || undefined,
+  };
+}
+
+/** Format a context as a `traceparent` header value. */
+export function formatTraceparent(ctx: TraceContext): string {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.flags}`;
+}
+
+/** Run `fn` with `ctx` bound as the active trace context for its async subtree. */
+export function runWithTrace<T>(ctx: TraceContext, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+/** The active trace context, or undefined outside a traced request. */
+export function currentTrace(): TraceContext | undefined {
+  return storage.getStore();
+}
+
+/** Trace headers to stamp on an upstream request, or `{}` when no trace is active. */
+export function traceHeaders(): Record<string, string> {
+  const ctx = storage.getStore();
+  if (!ctx) return {};
+  const headers: Record<string, string> = { traceparent: formatTraceparent(ctx) };
+  if (ctx.traceState) headers.tracestate = ctx.traceState;
+  return headers;
+}