mcpmake 0.1.0 → 0.2.0

package/dist/emitter/python-templates/server.py.hbs

@@ -1,77 +0,0 @@
-"""{{serverName}} MCP Server — generated by mcpmake."""
-
-import os
-import json
-import httpx
-from dotenv import load_dotenv
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
-from mcp.types import TextContent
-
-load_dotenv()
-
-BASE_URL = os.environ.get("BASE_URL", "{{{baseUrl}}}").rstrip("/")
-{{#each authSchemes}}
-{{#if (eq type "http-bearer")}}
-BEARER_TOKEN = os.environ.get("BEARER_TOKEN", "")
-{{/if}}
-{{#if (eq type "apiKey")}}
-API_KEY = os.environ.get("API_KEY", "")
-{{/if}}
-{{/each}}
-
-server = Server("{{serverName}}")
-client = httpx.AsyncClient(timeout=30.0)
-
-
-def _headers() -> dict[str, str]:
-    headers: dict[str, str] = {}
-{{#each authSchemes}}
-{{#if (eq type "http-bearer")}}
-    if BEARER_TOKEN:
-        headers["Authorization"] = f"Bearer {BEARER_TOKEN}"
-{{/if}}
-{{#if (eq type "apiKey")}}
-    if API_KEY:
-        headers["{{headerName}}"] = API_KEY
-{{/if}}
-{{/each}}
-    return headers
-
-
-{{#each tools}}
-@server.tool()
-async def {{functionName}}({{#each pathParams}}{{this}}: str, {{/each}}{{#each queryParams}}{{this}}: str = "", {{/each}}{{#if hasRequestBody}}body: dict | None = None{{/if}}) -> list[TextContent]:
-    """{{pyDocstring description}}"""
-    url = f"{BASE_URL}{{{pathTemplate}}}"
-    {{#if queryParams.length}}
-    params = { {{#each queryParams}}"{{this}}": {{this}}, {{/each}} }
-    params = {k: v for k, v in params.items() if v}
-    {{/if}}
-    try:
-        resp = await client.request(
-            "{{method}}",
-            url,
-            headers=_headers(),
-            {{#if queryParams.length}}
-            params=params,
-            {{/if}}
-            {{#if hasRequestBody}}
-            json=body,
-            {{/if}}
-        )
-        data = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else resp.text
-        return [TextContent(type="text", text=json.dumps(data, indent=2) if isinstance(data, (dict, list)) else str(data))]
-    except Exception as e:
-        return [TextContent(type="text", text=f"Error: {e}")]
-
-
-{{/each}}
-async def main():
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(read_stream, write_stream, server.create_initialization_options())
-
-
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())

package/dist/emitter/site-scaffolder.d.ts

@@ -1,13 +0,0 @@
-/**
- * Scaffolds the project files and shared modules for a site (Playwright-based) MCP server.
- */
-import type { SiteProjectManifest } from '../types/site.js';
-import type { CodeUnit } from './code-writer.js';
-/**
- * Generate project skeleton files (package.json, tsconfig, Dockerfile, etc.)
- */
-export declare function scaffoldSiteProjectFiles(manifest: SiteProjectManifest): CodeUnit[];
-/**
- * Generate shared source modules (server entry, config, browser manager).
- */
-export declare function scaffoldSiteSharedModules(manifest: SiteProjectManifest): CodeUnit[];

package/dist/emitter/site-scaffolder.js

@@ -1,70 +0,0 @@
-/**
- * Scaffolds the project files and shared modules for a site (Playwright-based) MCP server.
- */
-import { renderSiteTemplate } from './site-template-loader.js';
-import { renderTemplate } from './template-loader.js';
-/**
- * Generate project skeleton files (package.json, tsconfig, Dockerfile, etc.)
- */
-export function scaffoldSiteProjectFiles(manifest) {
-    const units = [
-        {
-            filePath: 'package.json',
-            content: renderSiteTemplate('package.json', manifest),
-        },
-        {
-            filePath: 'tsconfig.json',
-            // Reuse the existing tsconfig template — it's the same for both server types
-            content: renderTemplate('tsconfig.json', manifest),
-        },
-        {
-            filePath: '.env.example',
-            content: renderSiteTemplate('env.example', manifest),
-        },
-        {
-            filePath: '.gitignore',
-            content: renderTemplate('gitignore', manifest),
-        },
-        {
-            filePath: 'Dockerfile',
-            content: renderSiteTemplate('dockerfile', manifest),
-        },
-        {
-            // Regeneration metadata for `mcpmake rescan` (see SiteRegenMetadata).
-            filePath: 'mcpmake.site.json',
-            content: JSON.stringify({
-                serverName: manifest.serverName,
-                serverVersion: manifest.serverVersion,
-                transport: manifest.transport,
-                baseUrl: manifest.baseUrl,
-                envVars: manifest.envVars,
-                browserConfig: manifest.browserConfig,
-            }, null, 2),
-        },
-    ];
-    return units;
-}
-/**
- * Generate shared source modules (server entry, config, browser manager).
- */
-export function scaffoldSiteSharedModules(manifest) {
-    const serverMainTemplate = manifest.transport === 'http' ? 'server-main-http.ts' : 'server-main.ts';
-    return [
-        {
-            filePath: 'src/index.ts',
-            content: renderSiteTemplate(serverMainTemplate, manifest),
-        },
-        {
-            filePath: 'src/config.ts',
-            content: renderSiteTemplate('config.ts', manifest),
-        },
-        {
-            filePath: 'src/browser-manager.ts',
-            content: renderSiteTemplate('browser-manager.ts', manifest),
-        },
-        {
-            filePath: 'src/site-descriptor.json',
-            content: JSON.stringify(manifest.siteDescriptor, null, 2),
-        },
-    ];
-}

package/dist/emitter/site-template-loader.d.ts

@@ -1,5 +0,0 @@
-/**
- * Template loader for site (Playwright-based) MCP server templates.
- * Parallel to template-loader.ts but reads from site-templates/.
- */
-export declare function renderSiteTemplate(name: string, data: any): string;

package/dist/emitter/site-template-loader.js

@@ -1,47 +0,0 @@
-/**
- * Template loader for site (Playwright-based) MCP server templates.
- * Parallel to template-loader.ts but reads from site-templates/.
- */
-import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import Handlebars from 'handlebars';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SITE_TEMPLATE_DIR = resolve(__dirname, 'site-templates');
-const siteTemplateCache = new Map();
-// Register helpers (same as template-loader.ts — Handlebars helpers are global)
-// These may already be registered; Handlebars silently overwrites, which is fine.
-Handlebars.registerHelper('eq', function (a, b) {
-    return a === b;
-});
-Handlebars.registerHelper('capitalize', function (str) {
-    if (!str)
-        return str;
-    return str.charAt(0).toUpperCase() + str.slice(1);
-});
-// Escape a value for safe interpolation inside a SINGLE-QUOTED JS/TS string
-// literal in generated code. Critical for any string derived from crawled
-// (untrusted) site DOM — selectors, hrefs, field-name keys — so it can never
-// break out of the literal and inject code into the generated server.
-Handlebars.registerHelper('jsString', function (value) {
-    const s = value === null || value === undefined ? '' : String(value);
-    return (s
-        .replace(/\\/g, '\\\\')
-        .replace(/'/g, "\\'")
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        // Drop any remaining control chars that could terminate the literal.
-        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, ''));
-});
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function renderSiteTemplate(name, data) {
-    if (!siteTemplateCache.has(name)) {
-        const templatePath = resolve(SITE_TEMPLATE_DIR, `${name}.hbs`);
-        if (!templatePath.startsWith(SITE_TEMPLATE_DIR + '/')) {
-            throw new Error(`Invalid site template name: ${name}`);
-        }
-        const raw = readFileSync(templatePath, 'utf-8');
-        siteTemplateCache.set(name, Handlebars.compile(raw, { noEscape: true }));
-    }
-    return siteTemplateCache.get(name)(data);
-}

package/dist/emitter/site-templates/browser-manager.ts.hbs

@@ -1,233 +0,0 @@
-/**
- * Browser lifecycle management for the site MCP server.
- * Handles launching, closing, idle timeout, and screenshots.
- */
-
-import { chromium } from 'playwright';
-import type { Browser, BrowserContext, Page } from 'playwright';
-import type { BrowserConfig } from './config.js';
-
-interface BrowserSession {
-  context: BrowserContext;
-  page: Page;
-  lastAccessedAt: number;
-}
-
-let browser: Browser | undefined;
-const sessions = new Map<string, BrowserSession>();
-let idleTimer: ReturnType<typeof setInterval> | undefined;
-let config: BrowserConfig;
-
-const DEFAULT_SESSION = '__default__';
-
-/**
- * Initialize the browser manager with configuration.
- */
-export function initBrowserManager(browserConfig: BrowserConfig): void {
-  config = browserConfig;
-}
-
-/**
- * Resolve the first selector that attaches to the page, trying the primary
- * selector first and then any fallbacks. This gives generated tools runtime
- * resilience: when a site's DOM shifts and the primary selector breaks, a
- * fallback (id, aria-label, name, CSS path, XPath, ...) can still match,
- * instead of the tool failing outright.
- *
- * Throws a descriptive error if none of the candidates resolve.
- */
-export async function resolveSelector(
-  page: Page,
-  candidates: Array<string | undefined>,
-  options: { timeoutMs?: number } = {},
-): Promise<string> {
-  const valid = candidates.filter(
-    (c): c is string => typeof c === 'string' && c.trim().length > 0,
-  );
-  if (valid.length === 0) {
-    throw new Error('No selector candidates were provided');
-  }
-
-  // Fast path: return the first candidate already attached to the DOM.
-  for (const selector of valid) {
-    try {
-      const handle = await page.$(selector);
-      if (handle) {
-        await handle.dispose();
-        return selector;
-      }
-    } catch {
-      // Invalid selector syntax — skip and try the next candidate.
-    }
-  }
-
-  // Slow path: the element may not have rendered yet. Wait for the first
-  // candidate to attach, racing all of them under a single timeout budget.
-  const timeoutMs = options.timeoutMs ?? 5000;
-  try {
-    return await Promise.any(
-      valid.map(async (selector) => {
-        await page.waitForSelector(selector, { state: 'attached', timeout: timeoutMs });
-        return selector;
-      }),
-    );
-  } catch {
-    throw new Error(
-      `None of the selectors resolved on the page (the page structure may have changed): ${valid.join(', ')}`,
-    );
-  }
-}
-
-/**
- * Get or create a browser session.
- * If sessionId is provided, reuses an existing session or creates one with that ID.
- * If not, creates a new session with a generated ID.
- * Throws if the session pool is at capacity (maxSessions).
- */
-export async function getOrCreateSession(sessionId?: string): Promise<{ page: Page; sessionId: string }> {
-  const id = sessionId ?? DEFAULT_SESSION;
-
-  // Reuse existing session
-  const existing = sessions.get(id);
-  if (existing) {
-    existing.lastAccessedAt = Date.now();
-    resetIdleTimer();
-    return { page: existing.page, sessionId: id };
-  }
-
-  // Check capacity before creating a new session
-  const maxSessions = config.maxSessions ?? 10;
-  if (sessions.size >= maxSessions) {
-    throw new Error(
-      `Session pool at capacity (${maxSessions}). ` +
-      'Close an existing session before creating a new one.'
-    );
-  }
-
-  // Launch browser if not running
-  if (!browser || !browser.isConnected()) {
-    // Only disable sandbox when running as root in a container
-    const isRoot = process.getuid?.() === 0;
-    browser = await chromium.launch({
-      headless: config.headless,
-      args: isRoot ? ['--no-sandbox', '--disable-setuid-sandbox'] : [],
-    });
-  }
-
-  // Create new session
-  const context = await browser.newContext({
-    viewport: config.viewport,
-    ...(config.userAgent ? { userAgent: config.userAgent } : {}),
-  });
-  const page = await context.newPage();
-
-  // Generate final session ID upfront to avoid race conditions
-  const finalId = id === DEFAULT_SESSION
-    ? `session_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`
-    : id;
-
-  sessions.set(finalId, {
-    context,
-    page,
-    lastAccessedAt: Date.now(),
-  });
-
-  resetIdleTimer();
-
-  return { page, sessionId: finalId };
-}
-
-/**
- * Close a specific session or the default session.
- */
-export async function closeSession(sessionId?: string): Promise<void> {
-  const id = sessionId ?? DEFAULT_SESSION;
-  const session = sessions.get(id);
-  if (!session) return;
-
-  await session.context.close().catch(() => {});
-  sessions.delete(id);
-
-  // If no sessions remain, close the browser
-  if (sessions.size === 0) {
-    await closeBrowser();
-  }
-}
-
-/**
- * Close the browser and all sessions.
- */
-export async function closeBrowser(): Promise<void> {
-  clearIdleTimer();
-
-  for (const [id, session] of sessions) {
-    await session.context.close().catch(() => {});
-    sessions.delete(id);
-  }
-
-  if (browser) {
-    await browser.close().catch(() => {});
-    browser = undefined;
-  }
-}
-
-/**
- * Take a screenshot of the current page in a session.
- */
-export async function takeScreenshot(
-  sessionId?: string,
-  fullPage = false,
-): Promise<Buffer> {
-  const id = sessionId ?? DEFAULT_SESSION;
-  const session = sessions.get(id);
-  if (!session) {
-    throw new Error(`No active session: ${id}`);
-  }
-  session.lastAccessedAt = Date.now();
-  return session.page.screenshot({ type: 'png', fullPage });
-}
-
-/**
- * List active session IDs.
- */
-export function listSessions(): string[] {
-  return Array.from(sessions.keys());
-}
-
-/**
- * Check if the browser is running.
- */
-export function isBrowserRunning(): boolean {
-  return browser !== undefined && browser.isConnected();
-}
-
-// ─── Idle Timer ─────────────────────────────────────────────────────
-
-function resetIdleTimer(): void {
-  clearIdleTimer();
-  idleTimer = setInterval(() => {
-    const now = Date.now();
-    // Close idle sessions
-    for (const [id, session] of sessions) {
-      if (now - session.lastAccessedAt > config.idleTimeoutMs) {
-        session.context.close().catch(() => {});
-        sessions.delete(id);
-      }
-    }
-    // Close browser if no sessions
-    if (sessions.size === 0) {
-      closeBrowser();
-    }
-  }, 30_000); // Check every 30 seconds
-}
-
-function clearIdleTimer(): void {
-  if (idleTimer) {
-    clearInterval(idleTimer);
-    idleTimer = undefined;
-  }
-}
-
-// Clean up on process exit
-process.on('SIGTERM', () => closeBrowser());
-process.on('SIGINT', () => closeBrowser());

package/dist/emitter/site-templates/config.ts.hbs

@@ -1,28 +0,0 @@
-export interface BrowserConfig {
-  headless: boolean;
-  idleTimeoutMs: number;
-  viewport: { width: number; height: number };
-  userAgent?: string;
-  maxSessions: number;
-}
-
-export interface AppConfig {
-  baseUrl: string;
-  browser: BrowserConfig;
-}
-
-export function loadConfig(): AppConfig {
-  return {
-    baseUrl: process.env.BASE_URL ?? '{{{baseUrl}}}',
-    browser: {
-      headless: process.env.HEADLESS !== 'false',
-      idleTimeoutMs: parseInt(process.env.IDLE_TIMEOUT_MS ?? '{{browserConfig.idleTimeoutMs}}', 10),
-      viewport: {
-        width: parseInt(process.env.VIEWPORT_WIDTH ?? '{{browserConfig.viewport.width}}', 10),
-        height: parseInt(process.env.VIEWPORT_HEIGHT ?? '{{browserConfig.viewport.height}}', 10),
-      },
-      userAgent: process.env.USER_AGENT || undefined,
-      maxSessions: parseInt(process.env.MAX_SESSIONS ?? '{{browserConfig.maxSessions}}', 10) || 10,
-    },
-  };
-}

package/dist/emitter/site-templates/dockerfile.hbs

@@ -1,31 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.50.0-noble AS builder
-
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY tsconfig.json ./
-COPY src/ src/
-RUN npm run build
-
-FROM mcr.microsoft.com/playwright:v1.50.0-noble
-
-LABEL org.opencontainers.image.title="{{serverName}}"
-ENV NODE_ENV=production
-ENV TRANSPORT=http
-ENV PORT=3000
-ENV HEADLESS=true
-
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci --omit=dev
-
-COPY --from=builder /app/dist dist/
-
-USER pwuser
-
-EXPOSE 3000
-
-HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
-  CMD node -e "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
-
-CMD ["node", "dist/index.js"]

package/dist/emitter/site-templates/env.example.hbs

@@ -1,19 +0,0 @@
-# {{serverName}} configuration
-
-# Target website URL
-BASE_URL={{{baseUrl}}}
-
-# Browser settings
-HEADLESS=true
-IDLE_TIMEOUT_MS={{browserConfig.idleTimeoutMs}}
-VIEWPORT_WIDTH={{browserConfig.viewport.width}}
-VIEWPORT_HEIGHT={{browserConfig.viewport.height}}
-# USER_AGENT=
-{{#if (eq transport "http")}}
-
-# Transport: "stdio" or "http"
-TRANSPORT=http
-PORT=3000
-# Allowed origin for CORS/DNS-rebinding protection
-ALLOWED_ORIGIN=
-{{/if}}

package/dist/emitter/site-templates/package.json.hbs

@@ -1,26 +0,0 @@
-{
-  "name": "{{serverName}}",
-  "version": "{{serverVersion}}",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "playwright": "^1.50.0",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0",
-    "tsx": "^4.19.0",
-    "vitest": "^3.1.0"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}

package/dist/emitter/site-templates/server-main-http.ts.hbs

@@ -1,108 +0,0 @@
-import http from 'node:http';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { loadConfig } from './config.js';
-import { initBrowserManager, closeBrowser, isBrowserRunning } from './browser-manager.js';
-import { registerAllTools } from './tools/index.js';
-
-function log(level: string, message: string, data?: Record<string, unknown>): void {
-  const entry = { timestamp: new Date().toISOString(), level, message, ...data };
-  process.stderr.write(JSON.stringify(entry) + '\n');
-}
-
-const config = loadConfig();
-initBrowserManager(config.browser);
-
-const server = new McpServer({
-  name: '{{serverName}}',
-  version: '{{serverVersion}}',
-});
-
-registerAllTools(server, config);
-
-let isReady = false;
-
-if (process.env.TRANSPORT === 'http') {
-  const port = parseInt(process.env.PORT ?? '3000', 10);
-  const allowedOrigin = process.env.ALLOWED_ORIGIN;
-
-  const httpServer = http.createServer(async (req, res) => {
-    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
-
-    if (url.pathname === '/health') {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok', browser: isBrowserRunning() }));
-      return;
-    }
-
-    if (url.pathname === '/ready') {
-      res.writeHead(isReady ? 200 : 503, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ready: isReady }));
-      return;
-    }
-
-    if (url.pathname === '/mcp') {
-      if (allowedOrigin) {
-        // Compare host-to-host exactly (DNS-rebinding protection). A substring
-        // match would let "evil-{ALLOWED_ORIGIN}.attacker.com" through.
-        const originHeader = req.headers.origin;
-        let originHost = '';
-        if (originHeader) {
-          try {
-            originHost = new URL(originHeader).host;
-          } catch {
-            originHost = '';
-          }
-        } else if (req.headers.host) {
-          originHost = req.headers.host;
-        }
-        // ALLOWED_ORIGIN may be a full origin (https://app.example.com) or a bare host.
-        let allowedHost = allowedOrigin;
-        try {
-          allowedHost = new URL(allowedOrigin).host;
-        } catch {
-          // already a bare host
-        }
-        // Hosts are case-insensitive; normalize both sides (URL.host already lowercases).
-        if (originHost.toLowerCase() !== allowedHost.toLowerCase()) {
-          res.writeHead(403);
-          res.end('Forbidden');
-          return;
-        }
-      }
-
-      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-      await server.connect(transport);
-      await transport.handleRequest(req, res);
-      return;
-    }
-
-    res.writeHead(404);
-    res.end('Not Found');
-  });
-
-  httpServer.listen(port, () => {
-    isReady = true;
-    log('info', `MCP server listening on port ${port}`);
-  });
-
-  const shutdown = async () => {
-    log('info', 'Shutting down...');
-    await closeBrowser();
-    httpServer.close();
-    setTimeout(() => process.exit(0), 5000);
-  };
-
-  process.on('SIGTERM', shutdown);
-  process.on('SIGINT', shutdown);
-} else {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  isReady = true;
-
-  process.on('SIGTERM', async () => {
-    await closeBrowser();
-    process.exit(0);
-  });
-}

package/dist/emitter/site-templates/server-main.ts.hbs

@@ -1,23 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadConfig } from './config.js';
-import { initBrowserManager, closeBrowser } from './browser-manager.js';
-import { registerAllTools } from './tools/index.js';
-
-const config = loadConfig();
-initBrowserManager(config.browser);
-
-const server = new McpServer({
-  name: '{{serverName}}',
-  version: '{{serverVersion}}',
-});
-
-registerAllTools(server, config);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-process.on('SIGTERM', async () => {
-  await closeBrowser();
-  process.exit(0);
-});