mcpmake 0.1.0

package/dist/registry/official-registry.js

@@ -0,0 +1,129 @@
+/**
+ * Official MCP Registry (registry.modelcontextprotocol.io) publishing support.
+ *
+ * Builds a `server.json` that conforms to the official server schema and the
+ * metadata the `mcp-publisher` CLI uploads via `POST /v0/publish`. mcpmake does
+ * not re-implement the registry's GitHub/DNS auth — it produces a correct
+ * `server.json` (+ the npm `mcpName` validation marker) and hands off to
+ * `mcp-publisher login` / `publish`.
+ *
+ * Schema + flow primary-verified against modelcontextprotocol.io/registry
+ * (schema 2025-12-11) on 2026-06-18.
+ */
+/** Canonical server.json schema (pin the verified revision). */
+export const OFFICIAL_SCHEMA_URL = 'https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json';
+/** Official registry host the `mcp-publisher` CLI publishes to. */
+export const OFFICIAL_REGISTRY_URL = 'https://registry.modelcontextprotocol.io';
+/**
+ * Validate a registry server name. Must be `<reverse.dns.namespace>/<name>`
+ * (the namespace carries at least one dot). Returns an error string, or null
+ * when valid.
+ */
+export function validateServerName(name) {
+    if (!name.includes('/')) {
+        return `Registry name must be "<namespace>/<name>" (e.g. io.github.you/my-server), got "${name}"`;
+    }
+    const [namespace, server, ...rest] = name.split('/');
+    if (rest.length > 0) {
+        return `Registry name must contain exactly one "/", got "${name}"`;
+    }
+    if (!namespace || !/^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(namespace)) {
+        return `Namespace "${namespace}" must be reverse-DNS (e.g. io.github.you)`;
+    }
+    if (!server || !/^[a-z0-9._-]+$/i.test(server)) {
+        return `Server segment "${server}" may only contain letters, digits, ".", "_", "-"`;
+    }
+    return null;
+}
+/** Parse `owner`/`repo` out of a GitHub repository URL (https or ssh). */
+export function parseGitHubRepo(url) {
+    const match = url.match(/github\.com[:/]+([^/]+)\/([^/?#]+?)(?:\.git)?\/?$/i);
+    if (!match)
+        return null;
+    return { owner: match[1], repo: match[2] };
+}
+/**
+ * Determine the registry server name.
+ * Priority: an explicit (already-namespaced) name → derived from the GitHub
+ * repository URL as `io.github.<owner>/<repo>`. Returns null when undeterminable.
+ */
+export function deriveServerName(opts) {
+    if (opts.explicit)
+        return opts.explicit;
+    if (opts.repositoryUrl) {
+        const gh = parseGitHubRepo(opts.repositoryUrl);
+        if (gh)
+            return `io.github.${gh.owner.toLowerCase()}/${gh.repo}`;
+    }
+    return null;
+}
+const SECRET_HINT = /(token|key|secret|password|passwd|credential|auth)/i;
+/**
+ * Parse a `.env.example` file into registry env-var specs. A comment line
+ * immediately above a `VAR=` line becomes its description; names hinting at
+ * credentials are flagged `isSecret`.
+ */
+export function parseEnvExample(content) {
+    const out = [];
+    let pendingComment;
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line) {
+            pendingComment = undefined;
+            continue;
+        }
+        if (line.startsWith('#')) {
+            pendingComment = line.replace(/^#+\s*/, '').trim() || undefined;
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq <= 0) {
+            pendingComment = undefined;
+            continue;
+        }
+        const name = line
+            .slice(0, eq)
+            .trim()
+            .replace(/^export\s+/, '');
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            pendingComment = undefined;
+            continue;
+        }
+        out.push({
+            name,
+            description: pendingComment,
+            isRequired: true,
+            isSecret: SECRET_HINT.test(name),
+            format: 'string',
+        });
+        pendingComment = undefined;
+    }
+    return out;
+}
+/** Build a schema-conformant server.json for the official registry. */
+export function buildServerJson(input) {
+    const pkg = {
+        registryType: 'npm',
+        identifier: input.packageIdentifier,
+        version: input.packageVersion,
+        transport: { type: 'stdio' },
+    };
+    if (input.environmentVariables && input.environmentVariables.length > 0) {
+        pkg.environmentVariables = input.environmentVariables;
+    }
+    const server = {
+        $schema: OFFICIAL_SCHEMA_URL,
+        name: input.name,
+        version: input.version,
+        packages: [pkg],
+    };
+    if (input.description)
+        server.description = input.description;
+    if (input.repositoryUrl) {
+        server.repository = { url: input.repositoryUrl, source: 'github' };
+    }
+    if (input.remoteUrl) {
+        server.remotes = [{ type: 'streamable-http', url: input.remoteUrl }];
+    }
+    return server;
+}

package/dist/rescan/diff-engine.d.ts

@@ -0,0 +1,5 @@
+import type { SiteDescriptor, RescanResult } from '../types/site.js';
+/**
+ * Compare two SiteDescriptors and produce a structured diff of changes.
+ */
+export declare function diffSiteDescriptors(oldSite: SiteDescriptor, newSite: SiteDescriptor): RescanResult;

package/dist/rescan/diff-engine.js

@@ -0,0 +1,312 @@
+/**
+ * Compare two SiteDescriptors and produce a structured diff of changes.
+ */
+export function diffSiteDescriptors(oldSite, newSite) {
+    const changes = [];
+    const brokenSelectors = [];
+    const now = new Date().toISOString();
+    const oldPagesByUrl = new Map(oldSite.pages.map((p) => [p.url, p]));
+    const newPagesByUrl = new Map(newSite.pages.map((p) => [p.url, p]));
+    // Detect added pages
+    for (const [url, page] of newPagesByUrl) {
+        if (!oldPagesByUrl.has(url)) {
+            changes.push({
+                changeType: 'added',
+                elementType: 'page',
+                elementId: page.pageId,
+                pageId: page.pageId,
+                description: `Page added: ${url}`,
+                timestamp: now,
+                newValue: url,
+            });
+        }
+    }
+    // Detect removed pages
+    for (const [url, page] of oldPagesByUrl) {
+        if (!newPagesByUrl.has(url)) {
+            changes.push({
+                changeType: 'removed',
+                elementType: 'page',
+                elementId: page.pageId,
+                pageId: page.pageId,
+                description: `Page removed: ${url}`,
+                timestamp: now,
+                oldValue: url,
+            });
+        }
+    }
+    // Compare matching pages
+    for (const [url, oldPage] of oldPagesByUrl) {
+        const newPage = newPagesByUrl.get(url);
+        if (!newPage)
+            continue;
+        diffForms(oldPage, newPage, changes, brokenSelectors, now);
+        diffButtons(oldPage, newPage, changes, brokenSelectors, now);
+        diffLinks(oldPage, newPage, changes, brokenSelectors, now);
+    }
+    const newVersion = oldSite.version + 1;
+    const updatedSite = {
+        ...newSite,
+        version: newVersion,
+    };
+    return {
+        previousVersion: oldSite.version,
+        newVersion,
+        changes,
+        brokenSelectors,
+        newSiteDescriptor: updatedSite,
+        timestamp: now,
+    };
+}
+function diffForms(oldPage, newPage, changes, brokenSelectors, timestamp) {
+    const oldFormsById = new Map(oldPage.forms.map((f) => [f.formId, f]));
+    const newFormsById = new Map(newPage.forms.map((f) => [f.formId, f]));
+    for (const [id, form] of newFormsById) {
+        if (!oldFormsById.has(id)) {
+            changes.push({
+                changeType: 'added',
+                elementType: 'form',
+                elementId: id,
+                pageId: newPage.pageId,
+                description: `Form added: ${form.semanticName ?? id}`,
+                timestamp,
+                newValue: form.semanticName,
+            });
+        }
+    }
+    for (const [id, form] of oldFormsById) {
+        if (!newFormsById.has(id)) {
+            changes.push({
+                changeType: 'removed',
+                elementType: 'form',
+                elementId: id,
+                pageId: oldPage.pageId,
+                description: `Form removed: ${form.semanticName ?? id}`,
+                timestamp,
+                oldValue: form.semanticName,
+            });
+        }
+    }
+    for (const [id, oldForm] of oldFormsById) {
+        const newForm = newFormsById.get(id);
+        if (!newForm)
+            continue;
+        // Check for field changes
+        diffFormFields(oldForm, newForm, oldPage.pageId, changes, timestamp);
+        // Check for broken selectors
+        if (oldForm.selector.primary !== newForm.selector.primary) {
+            if (newForm.selector.confidence < 0.5) {
+                brokenSelectors.push({
+                    toolName: newForm.semanticName ?? id,
+                    selector: oldForm.selector,
+                });
+                changes.push({
+                    changeType: 'selector-broken',
+                    elementType: 'form',
+                    elementId: id,
+                    pageId: oldPage.pageId,
+                    description: `Form selector changed with low confidence: ${oldForm.selector.primary}`,
+                    timestamp,
+                    oldValue: oldForm.selector.primary,
+                    newValue: newForm.selector.primary,
+                });
+            }
+            else {
+                changes.push({
+                    changeType: 'modified',
+                    elementType: 'form',
+                    elementId: id,
+                    pageId: oldPage.pageId,
+                    description: `Form selector updated: ${oldForm.selector.primary} → ${newForm.selector.primary}`,
+                    timestamp,
+                    oldValue: oldForm.selector.primary,
+                    newValue: newForm.selector.primary,
+                });
+            }
+        }
+    }
+}
+function diffFormFields(oldForm, newForm, pageId, changes, timestamp) {
+    const oldFieldsByName = new Map(oldForm.fields.map((f) => [f.name, f]));
+    const newFieldsByName = new Map(newForm.fields.map((f) => [f.name, f]));
+    for (const [name] of newFieldsByName) {
+        if (!oldFieldsByName.has(name)) {
+            changes.push({
+                changeType: 'added',
+                elementType: 'field',
+                elementId: `${oldForm.formId}:${name}`,
+                pageId,
+                description: `Field added to form ${oldForm.semanticName ?? oldForm.formId}: ${name}`,
+                timestamp,
+                newValue: name,
+            });
+        }
+    }
+    for (const [name] of oldFieldsByName) {
+        if (!newFieldsByName.has(name)) {
+            changes.push({
+                changeType: 'removed',
+                elementType: 'field',
+                elementId: `${oldForm.formId}:${name}`,
+                pageId,
+                description: `Field removed from form ${oldForm.semanticName ?? oldForm.formId}: ${name}`,
+                timestamp,
+                oldValue: name,
+            });
+        }
+    }
+    for (const [name, oldField] of oldFieldsByName) {
+        const newField = newFieldsByName.get(name);
+        if (!newField)
+            continue;
+        if (oldField.fieldType !== newField.fieldType) {
+            changes.push({
+                changeType: 'modified',
+                elementType: 'field',
+                elementId: `${oldForm.formId}:${name}`,
+                pageId,
+                description: `Field type changed in ${oldForm.semanticName ?? oldForm.formId}: ${oldField.fieldType} → ${newField.fieldType}`,
+                timestamp,
+                oldValue: oldField.fieldType,
+                newValue: newField.fieldType,
+            });
+        }
+        if (oldField.required !== newField.required) {
+            changes.push({
+                changeType: 'modified',
+                elementType: 'field',
+                elementId: `${oldForm.formId}:${name}`,
+                pageId,
+                description: `Field required changed in ${oldForm.semanticName ?? oldForm.formId}: ${oldField.required} → ${newField.required}`,
+                timestamp,
+                oldValue: oldField.required,
+                newValue: newField.required,
+            });
+        }
+    }
+}
+function diffButtons(oldPage, newPage, changes, brokenSelectors, timestamp) {
+    const oldById = new Map(oldPage.buttons.map((b) => [b.buttonId, b]));
+    const newById = new Map(newPage.buttons.map((b) => [b.buttonId, b]));
+    for (const [id, btn] of newById) {
+        if (!oldById.has(id)) {
+            changes.push({
+                changeType: 'added',
+                elementType: 'button',
+                elementId: id,
+                pageId: newPage.pageId,
+                description: `Button added: ${btn.text ?? btn.semanticAction ?? id}`,
+                timestamp,
+                newValue: btn.text,
+            });
+        }
+    }
+    for (const [id, btn] of oldById) {
+        if (!newById.has(id)) {
+            changes.push({
+                changeType: 'removed',
+                elementType: 'button',
+                elementId: id,
+                pageId: oldPage.pageId,
+                description: `Button removed: ${btn.text ?? btn.semanticAction ?? id}`,
+                timestamp,
+                oldValue: btn.text,
+            });
+        }
+    }
+    for (const [id, oldBtn] of oldById) {
+        const newBtn = newById.get(id);
+        if (!newBtn)
+            continue;
+        if (oldBtn.text !== newBtn.text) {
+            changes.push({
+                changeType: 'modified',
+                elementType: 'button',
+                elementId: id,
+                pageId: oldPage.pageId,
+                description: `Button text changed: "${oldBtn.text}" → "${newBtn.text}"`,
+                timestamp,
+                oldValue: oldBtn.text,
+                newValue: newBtn.text,
+            });
+        }
+        checkBrokenSelector(oldBtn.selector, newBtn.selector, oldBtn.semanticAction ?? id, id, 'button', oldPage.pageId, changes, brokenSelectors, timestamp);
+    }
+}
+function diffLinks(oldPage, newPage, changes, brokenSelectors, timestamp) {
+    const oldById = new Map(oldPage.links.map((l) => [l.linkId, l]));
+    const newById = new Map(newPage.links.map((l) => [l.linkId, l]));
+    for (const [id, link] of newById) {
+        if (!oldById.has(id)) {
+            changes.push({
+                changeType: 'added',
+                elementType: 'link',
+                elementId: id,
+                pageId: newPage.pageId,
+                description: `Link added: ${link.text ?? link.href}`,
+                timestamp,
+                newValue: link.href,
+            });
+        }
+    }
+    for (const [id, link] of oldById) {
+        if (!newById.has(id)) {
+            changes.push({
+                changeType: 'removed',
+                elementType: 'link',
+                elementId: id,
+                pageId: oldPage.pageId,
+                description: `Link removed: ${link.text ?? link.href}`,
+                timestamp,
+                oldValue: link.href,
+            });
+        }
+    }
+    for (const [id, oldLink] of oldById) {
+        const newLink = newById.get(id);
+        if (!newLink)
+            continue;
+        if (oldLink.href !== newLink.href) {
+            changes.push({
+                changeType: 'modified',
+                elementType: 'link',
+                elementId: id,
+                pageId: oldPage.pageId,
+                description: `Link href changed: "${oldLink.href}" → "${newLink.href}"`,
+                timestamp,
+                oldValue: oldLink.href,
+                newValue: newLink.href,
+            });
+        }
+        checkBrokenSelector(oldLink.selector, newLink.selector, oldLink.semanticAction ?? id, id, 'link', oldPage.pageId, changes, brokenSelectors, timestamp);
+    }
+}
+function checkBrokenSelector(oldSelector, newSelector, toolName, elementId, elementType, pageId, changes, brokenSelectors, timestamp) {
+    if (oldSelector.primary !== newSelector.primary) {
+        if (newSelector.confidence < 0.5) {
+            brokenSelectors.push({ toolName, selector: oldSelector });
+            changes.push({
+                changeType: 'selector-broken',
+                elementType,
+                elementId,
+                pageId,
+                description: `${elementType} selector changed with low confidence: ${oldSelector.primary}`,
+                timestamp,
+                oldValue: oldSelector.primary,
+                newValue: newSelector.primary,
+            });
+        }
+        else {
+            changes.push({
+                changeType: 'modified',
+                elementType,
+                elementId,
+                pageId,
+                description: `${elementType} selector updated: ${oldSelector.primary} → ${newSelector.primary}`,
+                timestamp,
+                oldValue: oldSelector.primary,
+                newValue: newSelector.primary,
+            });
+        }
+    }
+}

package/dist/rescan/index.d.ts

@@ -0,0 +1,3 @@
+export { diffSiteDescriptors } from './diff-engine.js';
+export { RescanScheduler, computeNextRun } from './rescan-scheduler.js';
+export type { ScheduleEntry, RescanCallback } from './rescan-scheduler.js';

package/dist/rescan/index.js

@@ -0,0 +1,2 @@
+export { diffSiteDescriptors } from './diff-engine.js';
+export { RescanScheduler, computeNextRun } from './rescan-scheduler.js';

package/dist/rescan/rescan-runner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure helpers for the `mcpmake rescan` command: collecting fragile selectors
+ * to heal and summarizing a diff. Kept free of Playwright/LLM/IO so they can be
+ * unit-tested directly; the browser + LLM orchestration lives in the command.
+ */
+import type { SiteDescriptor, SelectorSet, RescanResult } from '../types/site.js';
+/** A low-confidence selector flagged for healing, with a live object reference. */
+export interface LowConfidenceSelector {
+    /** URL of the page this selector lives on (for navigation during healing). */
+    pageUrl: string;
+    /** Human-readable description used in the heal prompt. */
+    description: string;
+    /**
+     * The actual SelectorSet object inside the descriptor. Mutating this (via
+     * Object.assign) updates the descriptor in place so regeneration picks up
+     * the healed selector.
+     */
+    selector: SelectorSet;
+}
+/**
+ * Walk a SiteDescriptor and collect every selector whose confidence is below
+ * `threshold` (default 0.5 — i.e. the brittle css-path / xpath fallbacks).
+ */
+export declare function collectLowConfidenceSelectors(site: SiteDescriptor, threshold?: number): LowConfidenceSelector[];
+export interface ChangeCounts {
+    page: number;
+    form: number;
+    field: number;
+    button: number;
+    link: number;
+}
+export interface RescanSummary {
+    previousVersion: number;
+    newVersion: number;
+    added: ChangeCounts;
+    removed: ChangeCounts;
+    modified: ChangeCounts;
+    brokenSelectors: number;
+    totalChanges: number;
+}
+/** Summarize a RescanResult into per-kind change counts for reporting. */
+export declare function summarizeRescan(result: RescanResult): RescanSummary;

package/dist/rescan/rescan-runner.js

@@ -0,0 +1,69 @@
+/**
+ * Pure helpers for the `mcpmake rescan` command: collecting fragile selectors
+ * to heal and summarizing a diff. Kept free of Playwright/LLM/IO so they can be
+ * unit-tested directly; the browser + LLM orchestration lives in the command.
+ */
+/**
+ * Walk a SiteDescriptor and collect every selector whose confidence is below
+ * `threshold` (default 0.5 — i.e. the brittle css-path / xpath fallbacks).
+ */
+export function collectLowConfidenceSelectors(site, threshold = 0.5) {
+    const out = [];
+    const consider = (selector, pageUrl, description) => {
+        if (selector && selector.confidence < threshold) {
+            out.push({ pageUrl, description, selector });
+        }
+    };
+    for (const page of site.pages) {
+        for (const form of page.forms) {
+            const formName = form.semanticName ?? form.formId;
+            consider(form.selector, page.url, `form "${formName}"`);
+            consider(form.submitButton, page.url, `submit button of form "${formName}"`);
+            for (const field of form.fields) {
+                consider(field.selector, page.url, `field "${field.name}" (${field.label ?? field.fieldType}) in form "${formName}"`);
+            }
+        }
+        for (const button of page.buttons) {
+            consider(button.selector, page.url, `button "${button.text ?? button.semanticAction ?? button.buttonId}"`);
+        }
+        for (const link of page.links) {
+            consider(link.selector, page.url, `link "${link.text ?? link.href}"`);
+        }
+    }
+    return out;
+}
+function emptyCounts() {
+    return { page: 0, form: 0, field: 0, button: 0, link: 0 };
+}
+/** Summarize a RescanResult into per-kind change counts for reporting. */
+export function summarizeRescan(result) {
+    const added = emptyCounts();
+    const removed = emptyCounts();
+    const modified = emptyCounts();
+    const bump = (counts, elementType) => {
+        counts[elementType] += 1;
+    };
+    for (const change of result.changes) {
+        switch (change.changeType) {
+            case 'added':
+                bump(added, change.elementType);
+                break;
+            case 'removed':
+                bump(removed, change.elementType);
+                break;
+            case 'modified':
+                bump(modified, change.elementType);
+                break;
+            // 'selector-broken' is reported separately via brokenSelectors.
+        }
+    }
+    return {
+        previousVersion: result.previousVersion,
+        newVersion: result.newVersion,
+        added,
+        removed,
+        modified,
+        brokenSelectors: result.brokenSelectors.length,
+        totalChanges: result.changes.length,
+    };
+}

package/dist/rescan/rescan-scheduler.d.ts

@@ -0,0 +1,41 @@
+export interface ScheduleEntry {
+    slug: string;
+    cronExpr: string;
+    partial: boolean;
+    nextRunAt: Date;
+    createdAt: Date;
+}
+export type RescanCallback = (slug: string, partial: boolean) => void | Promise<void>;
+/**
+ * In-memory scheduler for periodic site rescans.
+ * Checks every 60 seconds for due rescans and invokes the callback.
+ */
+export declare class RescanScheduler {
+    private schedules;
+    private timer;
+    private callback;
+    private running;
+    constructor(callback: RescanCallback);
+    /** Register or update a rescan schedule for a site slug. */
+    scheduleRescan(slug: string, cronExpr: string, partial?: boolean): void;
+    /** Cancel a pending rescan schedule. */
+    cancelRescan(slug: string): boolean;
+    /** Start the periodic checker (every 60s). */
+    start(): void;
+    /** Stop the periodic checker. */
+    stop(): void;
+    /** Visible for testing: run a single check cycle. */
+    tick(): Promise<void>;
+    /** Get all registered schedules (for introspection / testing). */
+    getSchedules(): ReadonlyMap<string, ScheduleEntry>;
+}
+/**
+ * Parse a simplified cron expression and compute the next run time after `after`.
+ *
+ * Supported format: "minute hour dayOfMonth month dayOfWeek"
+ *   - Each field can be a number or '*'
+ *   - Ranges (1-5), lists (1,3,5), and step values (*\/10) are supported for minute/hour
+ *
+ * Returns null if the expression is invalid.
+ */
+export declare function computeNextRun(cronExpr: string, after: Date): Date | null;