mcpmake 0.1.0

package/dist/commands/update.js

@@ -0,0 +1,87 @@
+import { defineCommand } from 'citty';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadOpenApiSpec } from '../parser/openapi-loader.js';
+import { extractOperations } from '../parser/operation-extractor.js';
+import { buildAllTools } from '../transformer/tool-builder.js';
+import { detectAuthSchemes } from '../transformer/auth-detector.js';
+import { buildResources, buildPrompts } from '../transformer/resource-builder.js';
+import { emitProject } from '../emitter/index.js';
+import { pathExists } from '../utils/fs.js';
+import { logger } from '../utils/logger.js';
+import { fail } from '../utils/fail.js';
+export default defineCommand({
+    meta: {
+        name: 'update',
+        description: 'Update a generated project from a changed spec (incremental re-generation)',
+    },
+    args: {
+        spec: {
+            type: 'positional',
+            description: 'Path to the updated OpenAPI spec',
+            required: true,
+        },
+        project: {
+            type: 'string',
+            alias: 'p',
+            description: 'Path to the existing generated project',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        logger.info(`Updating project from spec: ${args.spec}`);
+        const projectDir = args.project;
+        const toolsDir = resolve(projectDir, 'src/tools');
+        if (!(await pathExists(resolve(projectDir, 'package.json')))) {
+            await fail(`Not a valid project directory: ${projectDir}`);
+        }
+        // Load current tool index to see what exists
+        const toolIndexPath = resolve(projectDir, 'src/tools/index.ts');
+        const existingToolIndex = (await pathExists(toolIndexPath))
+            ? await readFile(toolIndexPath, 'utf-8')
+            : '';
+        const existingFileNames = new Set();
+        const importMatches = existingToolIndex.matchAll(/from '\.\/([^']+)\.js'/g);
+        for (const match of importMatches) {
+            existingFileNames.add(match[1]);
+        }
+        // Parse the new spec
+        const { api } = await loadOpenApiSpec(args.spec);
+        const { operations, baseUrl, securitySchemes, info } = extractOperations(api);
+        const tools = buildAllTools(operations);
+        const { authSchemes, envVars } = detectAuthSchemes(securitySchemes);
+        const resources = buildResources(operations);
+        const prompts = buildPrompts(operations);
+        const newFileNames = new Set(tools.map((t) => t.fileName));
+        // Diff
+        const added = tools.filter((t) => !existingFileNames.has(t.fileName));
+        const removed = [...existingFileNames].filter((f) => !newFileNames.has(f));
+        const unchanged = tools.filter((t) => existingFileNames.has(t.fileName));
+        logger.info(`Diff: +${added.length} added, -${removed.length} removed, ${unchanged.length} updated`);
+        if (added.length === 0 && removed.length === 0) {
+            logger.info('No structural changes. Regenerating all tool files to sync schemas.');
+        }
+        // Determine server name from existing package.json
+        const pkgJson = JSON.parse(await readFile(resolve(projectDir, 'package.json'), 'utf-8'));
+        const serverName = pkgJson.name;
+        // Regenerate the full project (force overwrite)
+        await emitProject({
+            serverName,
+            serverVersion: info.version ?? pkgJson.version ?? '1.0.0',
+            baseUrl: baseUrl || 'https://api.example.com',
+            transport: 'stdio',
+            tools,
+            resources,
+            prompts,
+            authSchemes,
+            envVars: [{ name: 'BASE_URL', description: 'API base URL', required: true }, ...envVars],
+        }, { outputDir: projectDir, force: true, dryRun: false });
+        logger.success('Project updated successfully');
+        if (added.length > 0) {
+            logger.info(`New tools: ${added.map((t) => t.name).join(', ')}`);
+        }
+        if (removed.length > 0) {
+            logger.warn(`Removed tools (files may still exist): ${removed.join(', ')}`);
+        }
+    },
+});

package/dist/commands/verify.d.ts

@@ -0,0 +1,14 @@
+declare const _default: import("citty").CommandDef<{
+    spec: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    project: {
+        type: "string";
+        alias: string;
+        description: string;
+        required: true;
+    };
+}>;
+export default _default;

package/dist/commands/verify.js

@@ -0,0 +1,71 @@
+import { defineCommand } from 'citty';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadOpenApiSpec } from '../parser/openapi-loader.js';
+import { extractOperations } from '../parser/operation-extractor.js';
+import { buildAllTools } from '../transformer/tool-builder.js';
+import { logger } from '../utils/logger.js';
+import { fail } from '../utils/fail.js';
+import { pathExists } from '../utils/fs.js';
+export default defineCommand({
+    meta: {
+        name: 'verify',
+        description: 'Verify that a generated MCP server still matches its source spec',
+    },
+    args: {
+        spec: {
+            type: 'positional',
+            description: 'Path to the OpenAPI spec',
+            required: true,
+        },
+        project: {
+            type: 'string',
+            alias: 'p',
+            description: 'Path to the generated project directory',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        logger.info(`Verifying project against spec: ${args.spec}`);
+        // Load and parse the spec
+        const { api } = await loadOpenApiSpec(args.spec);
+        const { operations } = extractOperations(api);
+        const expectedTools = buildAllTools(operations);
+        // Read the generated tool index to find registered tools
+        const toolIndexPath = resolve(args.project, 'src/tools/index.ts');
+        if (!(await pathExists(toolIndexPath))) {
+            await fail(`Tool index not found at: ${toolIndexPath}`);
+        }
+        const toolIndex = await readFile(toolIndexPath, 'utf-8');
+        let missingCount = 0;
+        let extraCount = 0;
+        // Check each expected tool has a file
+        for (const tool of expectedTools) {
+            const toolFile = resolve(args.project, `src/tools/${tool.fileName}.ts`);
+            if (!(await pathExists(toolFile))) {
+                logger.error(`Missing tool file: src/tools/${tool.fileName}.ts (${tool.name})`);
+                missingCount++;
+            }
+            else if (!toolIndex.includes(tool.fileName)) {
+                logger.warn(`Tool file exists but not registered: ${tool.fileName}`);
+                missingCount++;
+            }
+        }
+        // Check for extra tool files not in the spec
+        const expectedFileNames = new Set(expectedTools.map((t) => t.fileName));
+        const importMatches = toolIndex.matchAll(/from '\.\/([^']+)\.js'/g);
+        for (const match of importMatches) {
+            const fileName = match[1];
+            if (!expectedFileNames.has(fileName)) {
+                logger.warn(`Extra tool not in spec: src/tools/${fileName}.ts`);
+                extraCount++;
+            }
+        }
+        if (missingCount === 0 && extraCount === 0) {
+            logger.success(`Verified: all ${expectedTools.length} tools match the spec`);
+        }
+        else {
+            await fail(`Verification failed: ${missingCount} missing, ${extraCount} extra tools`);
+        }
+    },
+});

package/dist/config/configurable-command.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wraps a citty command so it honours `.mcpmake.yaml`: a `--config` flag is
+ * added and config-file values are overlaid onto the parsed args (without
+ * overriding explicit CLI flags) right before the command runs.
+ */
+import { type ArgsDef, type CommandDef } from 'citty';
+/**
+ * Drop-in replacement for `defineCommand` that layers `.mcpmake.yaml` config in.
+ *
+ * @param commandName Name used to look up a per-command override section.
+ * @param def         The command definition (same shape as `defineCommand`).
+ */
+export declare function defineConfigurableCommand<T extends ArgsDef>(commandName: string, def: CommandDef<T>): CommandDef<T>;

package/dist/config/configurable-command.js

@@ -0,0 +1,70 @@
+/**
+ * Wraps a citty command so it honours `.mcpmake.yaml`: a `--config` flag is
+ * added and config-file values are overlaid onto the parsed args (without
+ * overriding explicit CLI flags) right before the command runs.
+ */
+import { defineCommand } from 'citty';
+import { applyConfigToArgs, displayPath } from './mcpmake-config.js';
+import { logger } from '../utils/logger.js';
+import { fail } from '../utils/fail.js';
+const CONFIG_ARG = {
+    type: 'string',
+    description: 'Path to a .mcpmake.yaml config file (default: auto-discovered in the working directory)',
+};
+/**
+ * Drop-in replacement for `defineCommand` that layers `.mcpmake.yaml` config in.
+ *
+ * @param commandName Name used to look up a per-command override section.
+ * @param def         The command definition (same shape as `defineCommand`).
+ */
+export function defineConfigurableCommand(commandName, def) {
+    const originalRun = def.run;
+    const baseArgs = (def.args && typeof def.args === 'object' ? def.args : {});
+    // citty enforces `required` during parsing — before our config overlay runs —
+    // so a required *flag* the user supplied via .mcpmake.yaml would be rejected.
+    // Relax those flags for citty and re-validate after merging config below.
+    // (Required positionals stay enforced: they always belong on the command line.)
+    const requiredFlags = [];
+    const relaxedArgs = {};
+    for (const [name, d] of Object.entries(baseArgs)) {
+        const ad = d;
+        if (ad.required === true && ad.type !== 'positional' && ad.default === undefined) {
+            requiredFlags.push(name);
+            relaxedArgs[name] = { ...d, required: false };
+        }
+        else {
+            relaxedArgs[name] = d;
+        }
+    }
+    const argsWithConfig = { ...relaxedArgs, config: CONFIG_ARG };
+    return defineCommand({
+        ...def,
+        args: argsWithConfig,
+        async run(ctx) {
+            const args = ctx.args;
+            try {
+                const result = applyConfigToArgs(args, ctx.rawArgs, commandName, argsWithConfig, {
+                    configPath: typeof args.config === 'string' ? args.config : undefined,
+                });
+                if (result.path && result.applied.length > 0) {
+                    logger.info(`Loaded ${result.applied.length} setting(s) from ${displayPath(result.path)}: ` +
+                        result.applied.join(', '));
+                }
+            }
+            catch (err) {
+                await fail(`Config error: ${err instanceof Error ? err.message : String(err)}`, err);
+            }
+            // Re-enforce required flags now that config has been applied.
+            const missing = requiredFlags.filter((k) => {
+                const v = args[k];
+                return v === undefined || v === null || v === '';
+            });
+            if (missing.length > 0) {
+                await fail(missing
+                    .map((k) => `Missing required argument: --${k} (set it on the command line or in .mcpmake.yaml)`)
+                    .join('\n'));
+            }
+            return originalRun?.(ctx);
+        },
+    });
+}

package/dist/config/mcpmake-config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `.mcpmake.yaml` project config — kills CLI-flag repetition and enables
+ * team-shared, version-controlled generation settings.
+ *
+ * Schema: top-level keys are global defaults applied to every command; an
+ * optional section keyed by a command name overrides them for that command.
+ *
+ *   # .mcpmake.yaml
+ *   output: ./generated         # global default for all commands
+ *   transport: http
+ *   format: typescript
+ *   openapi:                     # per-command overrides
+ *     base-url: https://api.example.com
+ *     include: [users, repos]    # arrays map to the comma-separated flag form
+ *   deploy:
+ *     url: https://mcpmake.dev
+ *
+ * Precedence (highest wins): explicit CLI flag > per-command section >
+ * global key > the command's built-in default. Positional args (e.g. the spec
+ * path) are never taken from config — they stay on the command line.
+ */
+import type { ArgsDef } from 'citty';
+/** Command names that may appear as config sections (vs. global keys). */
+export declare const KNOWN_COMMANDS: Set<string>;
+export interface LoadedConfig {
+    path: string;
+    data: Record<string, unknown>;
+}
+export interface ConfigEnv {
+    /** Explicit path from a `--config` flag (highest priority). */
+    configPath?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/**
+ * Resolve which config file to use, or null if none.
+ *
+ * Order: explicit `--config` path → `MCPMAKE_CONFIG` env → auto-discovered
+ * `.mcpmake.yaml`/`.yml` in the working directory. An explicit path that does
+ * not exist is an error; auto-discovery silently yields null.
+ */
+export declare function findConfigPath(deps?: ConfigEnv): string | null;
+/** Read + parse the config file, or null when there is none. Throws on malformed YAML. */
+export declare function loadConfig(deps?: ConfigEnv): LoadedConfig | null;
+/** Global keys = every top-level key that is not a command section. */
+export declare function globalConfig(data: Record<string, unknown>): Record<string, unknown>;
+/** The per-command override section, or an empty object. */
+export declare function sectionConfig(data: Record<string, unknown>, commandName: string): Record<string, unknown>;
+/**
+ * Set of arg names explicitly present on the command line (so they win over
+ * config). Scans the raw argv: `--name`, `--name=v`, and `--no-name` all mark
+ * `name`; short aliases (`-o`) resolve through the arg spec. Stops at `--`.
+ */
+export declare function explicitFlags(rawArgs: string[], argSpec: ArgsDef): Set<string>;
+export interface ApplyResult {
+    /** Path of the config file used, or null when none applied. */
+    path: string | null;
+    /** Arg names that were filled from config (not overridden by a CLI flag). */
+    applied: string[];
+}
+/**
+ * Overlay config-file values onto already-parsed citty `args`, mutating it in
+ * place. CLI flags (detected via rawArgs) and positionals are never touched.
+ * Returns which keys were applied so the caller can surface it.
+ */
+export declare function applyConfigToArgs(args: Record<string, unknown>, rawArgs: string[], commandName: string, argSpec: ArgsDef, deps?: ConfigEnv): ApplyResult;
+/** Render a config path relative to cwd for friendly logging. */
+export declare function displayPath(path: string, cwd?: string): string;

package/dist/config/mcpmake-config.js

@@ -0,0 +1,207 @@
+/**
+ * `.mcpmake.yaml` project config — kills CLI-flag repetition and enables
+ * team-shared, version-controlled generation settings.
+ *
+ * Schema: top-level keys are global defaults applied to every command; an
+ * optional section keyed by a command name overrides them for that command.
+ *
+ *   # .mcpmake.yaml
+ *   output: ./generated         # global default for all commands
+ *   transport: http
+ *   format: typescript
+ *   openapi:                     # per-command overrides
+ *     base-url: https://api.example.com
+ *     include: [users, repos]    # arrays map to the comma-separated flag form
+ *   deploy:
+ *     url: https://mcpmake.dev
+ *
+ * Precedence (highest wins): explicit CLI flag > per-command section >
+ * global key > the command's built-in default. Positional args (e.g. the spec
+ * path) are never taken from config — they stay on the command line.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { logger } from '../utils/logger.js';
+/** Command names that may appear as config sections (vs. global keys). */
+export const KNOWN_COMMANDS = new Set([
+    'openapi',
+    'har',
+    'url',
+    'describe',
+    'postman',
+    'website',
+    'deploy',
+    'verify',
+    'update',
+    'publish',
+    'merge',
+    'lint',
+    'diff',
+    'bundle',
+    'ci',
+]);
+const CONFIG_FILENAMES = ['.mcpmake.yaml', '.mcpmake.yml'];
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Resolve which config file to use, or null if none.
+ *
+ * Order: explicit `--config` path → `MCPMAKE_CONFIG` env → auto-discovered
+ * `.mcpmake.yaml`/`.yml` in the working directory. An explicit path that does
+ * not exist is an error; auto-discovery silently yields null.
+ */
+export function findConfigPath(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const explicit = deps.configPath || env.MCPMAKE_CONFIG;
+    if (explicit) {
+        const p = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+        if (!existsSync(p)) {
+            throw new Error(`Config file not found: ${explicit}`);
+        }
+        return p;
+    }
+    for (const name of CONFIG_FILENAMES) {
+        const p = resolve(cwd, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Read + parse the config file, or null when there is none. Throws on malformed YAML. */
+export function loadConfig(deps = {}) {
+    const path = findConfigPath(deps);
+    if (!path)
+        return null;
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (parsed == null)
+        return { path, data: {} };
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Config file ${path} must be a YAML mapping (key: value pairs)`);
+    }
+    return { path, data: parsed };
+}
+/** Global keys = every top-level key that is not a command section. */
+export function globalConfig(data) {
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (KNOWN_COMMANDS.has(k) && isPlainObject(v))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** The per-command override section, or an empty object. */
+export function sectionConfig(data, commandName) {
+    const section = data[commandName];
+    return isPlainObject(section) ? section : {};
+}
+/**
+ * Set of arg names explicitly present on the command line (so they win over
+ * config). Scans the raw argv: `--name`, `--name=v`, and `--no-name` all mark
+ * `name`; short aliases (`-o`) resolve through the arg spec. Stops at `--`.
+ */
+export function explicitFlags(rawArgs, argSpec) {
+    const aliasToName = {};
+    for (const [name, def] of Object.entries(argSpec)) {
+        const alias = def.alias;
+        if (!alias)
+            continue;
+        for (const a of Array.isArray(alias) ? alias : [alias]) {
+            aliasToName[a] = name;
+        }
+    }
+    const set = new Set();
+    for (const tok of rawArgs) {
+        if (tok === '--')
+            break;
+        if (tok.startsWith('--')) {
+            const raw = tok.slice(2).split('=')[0];
+            if (!raw)
+                continue;
+            // `--no-force` negates a boolean `force`, but an arg may also be *named*
+            // `no-resources` (a positive flag). Prefer a literal arg-name match; only
+            // strip `no-` when the bare name is the real arg.
+            if (!(raw in argSpec) && raw.startsWith('no-') && raw.slice(3) in argSpec) {
+                set.add(raw.slice(3));
+            }
+            else {
+                set.add(raw);
+            }
+        }
+        else if (tok.length > 1 && tok[0] === '-' && !/^-\d/.test(tok)) {
+            // Short flag(s): support bundled forms like -fw.
+            for (const ch of tok.slice(1)) {
+                const name = aliasToName[ch];
+                if (name)
+                    set.add(name);
+            }
+        }
+    }
+    return set;
+}
+/** Coerce a YAML value to the type the citty arg expects. */
+function coerceValue(value, type) {
+    if (type === 'boolean') {
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'string') {
+            return value === 'true' || value === '1' || value === 'yes';
+        }
+        return Boolean(value);
+    }
+    if (type === 'string') {
+        if (Array.isArray(value))
+            return value.join(',');
+        return value == null ? value : String(value);
+    }
+    return value;
+}
+/**
+ * Overlay config-file values onto already-parsed citty `args`, mutating it in
+ * place. CLI flags (detected via rawArgs) and positionals are never touched.
+ * Returns which keys were applied so the caller can surface it.
+ */
+export function applyConfigToArgs(args, rawArgs, commandName, argSpec, deps = {}) {
+    const loaded = loadConfig(deps);
+    if (!loaded)
+        return { path: null, applied: [] };
+    const global = globalConfig(loaded.data);
+    const section = sectionConfig(loaded.data, commandName);
+    // Warn on typos in a command-specific section (global keys may legitimately
+    // target other commands, so those are not warned).
+    for (const key of Object.keys(section)) {
+        if (!(key in argSpec)) {
+            logger.warn(`Unknown setting "${commandName}.${key}" in ${loaded.path} — ignored`);
+        }
+    }
+    const merged = { ...global, ...section };
+    const explicit = explicitFlags(rawArgs, argSpec);
+    const applied = [];
+    for (const [key, value] of Object.entries(merged)) {
+        const def = argSpec[key];
+        if (!def)
+            continue; // unknown global key — silently skip (may target another command)
+        if (def.type === 'positional')
+            continue; // positionals stay on the CLI
+        if (explicit.has(key))
+            continue; // explicit CLI flag wins
+        args[key] = coerceValue(value, def.type);
+        applied.push(key);
+    }
+    return { path: loaded.path, applied };
+}
+/** Render a config path relative to cwd for friendly logging. */
+export function displayPath(path, cwd = process.cwd()) {
+    const rel = relative(cwd, path);
+    return rel && !rel.startsWith('..') ? rel : path;
+}