@hypequery/cli 1.18.2 → 1.19.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAgQD,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAqRD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
+import { mcpCommand } from './commands/mcp.js';
 import { devCommand } from './commands/dev.js';
 import { generateCommand } from './commands/generate.js';
 import { generateDatasetsCommand } from './commands/generate-datasets.js';
@@ -126,6 +127,15 @@ program
     .action(runCommand(async (file, options) => {
     await devCommand(file, options);
 }));
+program
+    .command('mcp [file]')
+    .description('Serve this project\'s datasets to an MCP client over stdio')
+    .option('--path <path>', 'Analytics directory (loads <path>/api.ts or <path>/queries.ts)')
+    .option('--tenant <id>', 'Trusted tenant applied to every tenant-scoped dataset')
+    .option('--self-test', 'Check the entrypoint and exit without speaking MCP')
+    .action(runCommand(async (file, options) => {
+    await mcpCommand(file, options);
+}));
 // Generate command
 addTypeGenerationOptions(program.command('generate'))
     .action(runCommand(async (options) => {
@@ -143,6 +153,9 @@ program
     .option('--tables <names>', 'Only generate for specific tables (comma-separated)')
     .option('--exclude-tables <names>', 'Exclude specific tables (comma-separated)')
     .option('--tenant-column <column>', 'Set tenantKey to this column on tables that have it (requires a trusted runtime tenant scope)')
+    .option('--force', 'Replace an existing output file when generated contents differ')
+    .option('--check', 'Exit with an error when the output file is missing or out of date')
+    .option('--diff', 'Print generated changes without writing them')
     .action(runCommand(async (options) => {
     await generateDatasetsCommand(options);
 }));
@@ -165,6 +178,7 @@ program
     .option('--entrypoint-prefix <prefix>', 'Runtime entrypoint prefix (default: queries)')
     .option('--hash-output <path>', 'Deployment identity sidecar path (default: <output>.sha256)')
     .option('--no-source', 'Exclude project source files from the deployment bundle')
+    .option('--allow-unsupported-config', 'Deploy even though some Serve config will not be honoured in Cloud')
     .action(runCommand(async (api, options) => {
     await buildDeploymentCommand(api, options);
 }));
@@ -203,6 +217,7 @@ program
     .option('--no-source', 'Exclude project source files from the deployment bundle')
     .option('--endpoint <url>', 'HTTPS submission endpoint; requires HYPEQUERY_API_TOKEN')
     .option('--replace-restored', 'Intentionally replace a restored live release')
+    .option('--allow-unsupported-config', 'Deploy even though some Serve config will not be honoured in Cloud')
     .action(runCommand(async (source, options) => {
     await deployCommand(source, options);
 }));

package/dist/commands/deploy.d.ts

@@ -13,6 +13,7 @@ export interface DeployOptions extends SubmitDeploymentOptions {
     bundleOutput?: string;
     releaseOutput?: string;
     source?: boolean;
+    allowUnsupportedConfig?: boolean;
 }
 export interface SubmitDeploymentDependencies {
     readonly env?: Readonly<Record<string, string | undefined>>;

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AASA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAChC,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,uBAAuB;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,mCAAmC,CAAC;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC;CACjD;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACzD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,+BAA+B,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AA4DD,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,uBAA4B,EACrC,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CA0EvC;AAmDD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAqDvC"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AASA,OAAO,EACL,mCAAmC,EAEnC,KAAK,4BAA4B,EAElC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAChC,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,uBAAuB;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,mCAAmC,CAAC;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,mBAAmB,CAAC;CACjD;AAED,MAAM,WAAW,kBAAmB,SAAQ,4BAA4B;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACzD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,+BAA+B,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AA4DD,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,uBAA4B,EACrC,YAAY,GAAE,4BAAiC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CA0EvC;AAmDD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,aAAkB,EAC3B,YAAY,GAAE,kBAAuB,GACpC,OAAO,CAAC,4BAA4B,CAAC,CAyDvC"}

package/dist/commands/deploy.js

@@ -189,7 +189,11 @@ export async function deployCommand(sourcePath, options = {}, dependencies = {})
     // a missing or expired login only surfaces after a full bundle build.
     await resolveDeploymentCredential(options.endpoint, dependencies);
     try {
-        await build(sourcePath, { bundleOutput: bundlePath, source: options.source });
+        await build(sourcePath, {
+            bundleOutput: bundlePath,
+            source: options.source,
+            allowUnsupportedConfig: options.allowUnsupportedConfig,
+        });
     }
     catch (error) {
         throw withRuntimeFlagHint(error);

package/dist/commands/deployment.d.ts

@@ -10,6 +10,7 @@ export interface BuildDeploymentOptions {
     entrypointPrefix?: string;
     hashOutput?: string;
     source?: boolean;
+    allowUnsupportedConfig?: boolean;
 }
 export interface PrepareDeploymentReleaseOptions {
     project?: string;

package/dist/commands/deployment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAe7B,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAI5C,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oCAAoC;IACnD,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAsJrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC;AAiED,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,+BAAoC,EAC7C,YAAY,GAAE,oCAAyC,GACtD,OAAO,CAAC,iCAAiC,CAAC,CAkE5C"}
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAgB7B,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oCAAoC,CAAC;AAI5C,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oCAAoC;IACnD,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAsDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA0JrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC;AAiED,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,GAAE,+BAAoC,EAC7C,YAAY,GAAE,oCAAyC,GACtD,OAAO,CAAC,iCAAiC,CAAC,CAkE5C"}

package/dist/commands/deployment.js

@@ -7,6 +7,7 @@ import { buildNodeRuntimeArtifact, getDeploymentRuntimeEntrypoints, } from '../u
 import { captureDeploymentSourceSnapshot } from '../utils/deployment-source-snapshot.js';
 import { loadApiModule } from '../utils/load-api.js';
 import { logger } from '../utils/logger.js';
+import { reportCloudDiagnostic } from '../utils/cloud-diagnostic.js';
 import { loadCloudCredential, } from '../utils/cloud-credential-store.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const DEFAULT_BUNDLE_OUTPUT = 'analytics/hypequery-deployment';
@@ -103,7 +104,11 @@ export async function buildDeploymentCommand(apiPath, options = {}) {
             };
         }
     }
-    const contract = api.deploymentContract(artifact ? { runtimeArtifact: artifact } : {});
+    const contract = api.deploymentContract({
+        ...(artifact ? { runtimeArtifact: artifact } : {}),
+        ...(options.allowUnsupportedConfig ? { allowUnsupportedConfig: true } : {}),
+        onCloudDiagnostic: diagnostic => reportCloudDiagnostic(diagnostic, options.allowUnsupportedConfig === true),
+    });
     const prepared = prepareProtocolDeploymentContract(contract);
     const { canonical, contract: validated, identity: digest } = prepared;
     if (bundleOutput !== undefined) {

package/dist/commands/generate-datasets.d.ts

@@ -10,6 +10,9 @@ export interface GenerateDatasetsOptions {
     tables?: string;
     excludeTables?: string;
     tenantColumn?: string;
+    force?: boolean;
+    check?: boolean;
+    diff?: boolean;
 }
 export declare function generateDatasetsCommand(options?: GenerateDatasetsOptions): Promise<void>;
 //# sourceMappingURL=generate-datasets.d.ts.map

package/dist/commands/generate-datasets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-datasets.d.ts","sourceRoot":"","sources":["../../src/commands/generate-datasets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAqBD,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,iBA8GlF"}
+{"version":3,"file":"generate-datasets.d.ts","sourceRoot":"","sources":["../../src/commands/generate-datasets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA2BD,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,iBAqKlF"}

package/dist/commands/generate-datasets.js

@@ -11,6 +11,8 @@ import { getTableCount } from '../utils/detect-database.js';
 import { generateDatasets } from '../generators/dataset-generator.js';
 import { redactConnectionUrl } from '../utils/redact-connection-url.js';
 import { logDatasetGenerationWarnings } from '../utils/dataset-generation-warnings.js';
+import { formatGeneratedFileDiff } from '../utils/generated-file-diff.js';
+import { readGeneratedFile, writeGeneratedFileAtomically } from '../utils/generated-file.js';
 /**
  * Turns the written path into something pasteable into an import statement:
  * strips the `.ts` extension and makes it explicitly relative.
@@ -20,6 +22,11 @@ function toImportSpecifier(relativePath) {
     const normalized = withoutExtension.split(path.sep).join('/');
     return normalized.startsWith('.') ? normalized : `./${normalized}`;
 }
+function refuseOverwrite(relativeOutput) {
+    logger.warn(`Refusing to overwrite existing dataset definitions: ${relativeOutput}`);
+    logger.info('Run again with --diff to inspect changes or --force to replace the file.');
+    process.exitCode = 1;
+}
 function parseTableList(value) {
     const parsed = value
         ?.split(',')
@@ -43,6 +50,11 @@ export async function generateDatasetsCommand(options = {}) {
     }
     const parsedTables = parseTableList(options.tables);
     const excludedTables = parseTableList(options.excludeTables);
+    if (options.force && (options.check || options.diff)) {
+        logger.error('--force cannot be combined with --check or --diff.');
+        process.exitCode = 1;
+        return;
+    }
     logger.newline();
     logger.header('hypequery generate datasets');
     const spinner = ora('Connecting to ClickHouse...').start();
@@ -62,13 +74,59 @@ export async function generateDatasetsCommand(options = {}) {
             // Regeneration replaces the whole file, so a tenant boundary configured at
             // init has to be restated here or it is dropped on every refresh.
             tenantColumn: options.tenantColumn,
+            writeOutput: false,
         });
         const generatedTables = generated?.tables ?? parsedTables ?? [];
         const generatedCount = generatedTables.length || tableCount;
         datasetSpinner.succeed(`Generated dataset definitions for ${generatedCount} ${generatedCount === 1 ? 'table' : 'tables'}`);
-        const relativeOutput = path.relative(process.cwd(), outputPath);
-        logger.success(`Created ${relativeOutput}`);
         logDatasetGenerationWarnings(generated?.warnings);
+        const relativeOutput = path.relative(process.cwd(), outputPath);
+        const currentContents = await readGeneratedFile(outputPath);
+        const contentsMatch = currentContents === generated.contents;
+        if (contentsMatch) {
+            logger.success(options.check || options.diff
+                ? `Dataset definitions are up to date: ${relativeOutput}`
+                : `Unchanged ${relativeOutput}`);
+            if (options.check || options.diff) {
+                return;
+            }
+        }
+        else if (options.diff) {
+            logger.raw(formatGeneratedFileDiff(currentContents ?? '', generated.contents, relativeOutput));
+            logger.error(`Generated dataset definitions differ: ${relativeOutput}`);
+            process.exitCode = 1;
+            return;
+        }
+        else if (options.check) {
+            logger.error(currentContents === undefined
+                ? `Dataset definitions are missing: ${relativeOutput}`
+                : `Generated dataset definitions are out of date: ${relativeOutput}`);
+            process.exitCode = 1;
+            return;
+        }
+        else if (currentContents !== undefined && !options.force) {
+            refuseOverwrite(relativeOutput);
+            return;
+        }
+        else {
+            try {
+                // Without --force this is an exclusive create, so a file written
+                // between the read above and here is refused rather than clobbered.
+                await writeGeneratedFileAtomically(outputPath, generated.contents, {
+                    overwrite: options.force === true,
+                });
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    refuseOverwrite(relativeOutput);
+                    return;
+                }
+                throw error;
+            }
+            logger.success(currentContents === undefined
+                ? `Created ${relativeOutput}`
+                : `Updated ${relativeOutput}`);
+        }
         logger.newline();
         logger.header('Next steps:');
         logger.indent('1. Review and customize the generated datasets');

package/dist/commands/mcp.d.ts

@@ -0,0 +1,19 @@
+import { type CloseableMcpServer } from '../utils/mcp-lifecycle.js';
+export interface McpOptions {
+    /** Analytics directory, matching `hypequery dev --path`. */
+    path?: string;
+    /** Trusted tenant applied to every tenant-scoped dataset. */
+    tenant?: string;
+    /** Check the entrypoint and exit instead of speaking MCP over stdio. */
+    selfTest?: boolean;
+}
+export interface McpDependencies {
+    loadApi?: (file: string) => Promise<unknown>;
+    start?: (config: {
+        datasets: Record<string, unknown>;
+        analytics: unknown;
+        tenantId?: string;
+    }) => Promise<CloseableMcpServer>;
+}
+export declare function mcpCommand(file?: string, options?: McpOptions, dependencies?: McpDependencies): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQvF,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnC;AAyCD,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CAgDf"}

package/dist/commands/mcp.js

@@ -0,0 +1,94 @@
+import { runMcpUntilSignal } from '../utils/mcp-lifecycle.js';
+import { routeConsoleOutputToStderr } from '../utils/mcp-console.js';
+import { readServeMcpSource, tenantScopedDatasets } from '../utils/mcp-source.js';
+import path from 'node:path';
+import { findApiFileForPath, findQueriesFile } from '../utils/find-files.js';
+import { loadApiModule } from '../utils/load-api.js';
+import { logger } from '../utils/logger.js';
+function entrypointNotFound() {
+    logger.error('Could not find a hypequery API file to serve over MCP');
+    logger.newline();
+    logger.info('Expected one of:');
+    for (const candidate of [
+        'hypequery.ts', 'analytics/api.ts', 'src/analytics/api.ts',
+        'api.ts', 'src/api.ts', 'analytics/queries.ts', 'src/analytics/queries.ts',
+    ]) {
+        logger.indent(`• ${candidate}`);
+    }
+    logger.newline();
+    logger.info('Or specify the file explicitly:');
+    logger.indent('hypequery mcp ./path/to/api.ts');
+    logger.newline();
+    process.exit(1);
+}
+function noDatasets(file) {
+    logger.error(`${path.relative(process.cwd(), file)} does not register any datasets`);
+    logger.newline();
+    logger.info('MCP exposes datasets and named metrics, so add them to defineServe:');
+    logger.indent('defineServe({ queryBuilder: db, datasets: { orders: Orders } })');
+    logger.newline();
+    process.exit(1);
+}
+async function resolveEntrypoint(file, options) {
+    const resolved = file
+        ? await findQueriesFile(file)
+        : options.path
+            ? await findApiFileForPath(options.path)
+            : await findQueriesFile();
+    return resolved ?? entrypointNotFound();
+}
+function resolveSource(api, file) {
+    return readServeMcpSource(api) ?? noDatasets(file);
+}
+export async function mcpCommand(file, options = {}, dependencies = {}) {
+    const restoreConsole = routeConsoleOutputToStderr();
+    try {
+        const entrypoint = await resolveEntrypoint(file, options);
+        const loadApi = dependencies.loadApi ?? loadApiModule;
+        const source = resolveSource(await loadApi(entrypoint), entrypoint);
+        const datasets = source.datasets;
+        const names = Object.keys(datasets).sort();
+        if (names.length === 0)
+            noDatasets(entrypoint);
+        const scoped = tenantScopedDatasets(datasets);
+        if (scoped.length > 0 && !options.tenant) {
+            // Fail closed rather than serving a tenant-scoped dataset unscoped.
+            logger.error(`--tenant is required for tenant-scoped datasets: ${scoped.join(', ')}`);
+            logger.newline();
+            logger.info('MCP has no request to resolve a tenant from, so it must be given one:');
+            logger.indent('hypequery mcp --tenant acme');
+            logger.newline();
+            process.exit(1);
+        }
+        const analytics = source.resolveAnalytics();
+        if (options.selfTest) {
+            logger.success(`Loaded ${path.relative(process.cwd(), entrypoint)}`);
+            logger.info(`Datasets: ${names.join(', ')}`);
+            logger.info(options.tenant
+                ? `Trusted tenant: ${options.tenant}`
+                : 'Trusted tenant: none (no dataset is tenant-scoped)');
+            logger.newline();
+            logger.info('The entrypoint is ready to serve over MCP.');
+            return;
+        }
+        const start = dependencies.start ?? defaultStart;
+        await runMcpUntilSignal(async () => {
+            const server = await start({
+                datasets,
+                analytics,
+                ...(options.tenant ? { tenantId: options.tenant } : {}),
+            });
+            process.stderr.write(`hypequery MCP serving ${names.length} dataset(s): ${names.join(', ')}\n`);
+            return server;
+        });
+    }
+    finally {
+        restoreConsole();
+    }
+}
+async function defaultStart(config) {
+    // Imported lazily so `--self-test` and the argument errors above do not pay
+    // for the MCP SDK, and so the CLI still loads when it is not installed.
+    const { startStdioMCPServer } = await import('@hypequery/mcp');
+    return startStdioMCPServer(config);
+}

package/dist/generators/dataset-generator.d.ts

@@ -19,6 +19,8 @@ export interface DatasetGeneratorOptions {
      * being silently left unscoped.
      */
     tenantColumn?: string;
+    /** Whether to write the output file. Defaults to true; false renders only. */
+    writeOutput?: boolean;
 }
 export type DatasetGenerationWarning = {
     kind: 'tenant-key-candidate';
@@ -41,5 +43,6 @@ export declare function generateDatasets(options: DatasetGeneratorOptions): Prom
         exportName: string;
     }[];
     warnings: DatasetGenerationWarning[];
+    contents: string;
 }>;
 //# sourceMappingURL=dataset-generator.d.ts.map

package/dist/generators/dataset-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAG1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAkSN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;GAsEtE"}
+{"version":3,"file":"dataset-generator.d.ts","sourceRoot":"","sources":["../../src/generators/dataset-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAG1E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,8BAA8B,CAAC;IACxC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAkSN;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB;;;;;;;;GAyEtE"}

package/dist/generators/dataset-generator.js

@@ -277,11 +277,13 @@ ${tables.map((table) => `  ${table.name}: ${tableToPascalCase(table.name)}Datase
 };
 `;
     const output = header + datasetDefinitions.join('\n') + footer;
-    // Ensure output directory exists
-    const outputDir = path.dirname(path.resolve(options.outputPath));
-    await fs.mkdir(outputDir, { recursive: true });
-    // Write the file
-    await fs.writeFile(path.resolve(options.outputPath), output);
+    if (options.writeOutput !== false) {
+        // Ensure output directory exists
+        const outputDir = path.dirname(path.resolve(options.outputPath));
+        await fs.mkdir(outputDir, { recursive: true });
+        // Write the file
+        await fs.writeFile(path.resolve(options.outputPath), output);
+    }
     // Returned so the CLI can report what it actually generated, and print an
     // example that matches the file rather than a hardcoded placeholder.
     return {
@@ -291,5 +293,6 @@ ${tables.map((table) => `  ${table.name}: ${tableToPascalCase(table.name)}Datase
             exportName: `${tableToPascalCase(table.name)}Dataset`,
         })),
         warnings,
+        contents: output,
     };
 }

package/dist/utils/cloud-diagnostic.d.ts

@@ -0,0 +1,10 @@
+export interface CloudCompatibilityDiagnosticLike {
+    readonly severity: 'error' | 'warning';
+    readonly code: string;
+    readonly subject: string;
+    readonly message: string;
+    readonly remedy: string;
+}
+/** Report warnings and explicitly overridden errors before submitting a release. */
+export declare function reportCloudDiagnostic(diagnostic: CloudCompatibilityDiagnosticLike, allowUnsupportedConfig: boolean): void;
+//# sourceMappingURL=cloud-diagnostic.d.ts.map

package/dist/utils/cloud-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-diagnostic.d.ts","sourceRoot":"","sources":["../../src/utils/cloud-diagnostic.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gCAAgC,EAC5C,sBAAsB,EAAE,OAAO,GAC9B,IAAI,CAMN"}

package/dist/utils/cloud-diagnostic.js

@@ -0,0 +1,10 @@
+import { logger } from './logger.js';
+/** Report warnings and explicitly overridden errors before submitting a release. */
+export function reportCloudDiagnostic(diagnostic, allowUnsupportedConfig) {
+    // Blocking errors are reported by the contract builder's exception.
+    if (diagnostic.severity === 'error' && !allowUnsupportedConfig)
+        return;
+    logger.warn(`${diagnostic.code} (${diagnostic.subject})`);
+    logger.indent(diagnostic.message);
+    logger.indent(`→ ${diagnostic.remedy}`);
+}

package/dist/utils/generated-file-diff.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Formats one unified hunk spanning the changed region, with nearby context.
+ * Generated files are replaced as a unit, so a compact single hunk is easier
+ * to review than treating every regenerated line as an unrelated edit.
+ */
+export declare function formatGeneratedFileDiff(currentContents: string, generatedContents: string, displayPath: string): string;
+//# sourceMappingURL=generated-file-diff.d.ts.map

package/dist/utils/generated-file-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-file-diff.d.ts","sourceRoot":"","sources":["../../src/utils/generated-file-diff.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,EACvB,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,GAClB,MAAM,CA+CR"}

package/dist/utils/generated-file-diff.js

@@ -0,0 +1,52 @@
+function splitLines(contents) {
+    if (contents.length === 0) {
+        return [];
+    }
+    // Keep a trailing empty line so newline-only changes remain visible.
+    return contents.split('\n');
+}
+/**
+ * Formats one unified hunk spanning the changed region, with nearby context.
+ * Generated files are replaced as a unit, so a compact single hunk is easier
+ * to review than treating every regenerated line as an unrelated edit.
+ */
+export function formatGeneratedFileDiff(currentContents, generatedContents, displayPath) {
+    if (currentContents === generatedContents) {
+        return '';
+    }
+    const currentLines = splitLines(currentContents);
+    const generatedLines = splitLines(generatedContents);
+    let sharedPrefix = 0;
+    while (sharedPrefix < currentLines.length
+        && sharedPrefix < generatedLines.length
+        && currentLines[sharedPrefix] === generatedLines[sharedPrefix]) {
+        sharedPrefix += 1;
+    }
+    let sharedSuffix = 0;
+    while (sharedSuffix < currentLines.length - sharedPrefix
+        && sharedSuffix < generatedLines.length - sharedPrefix
+        && currentLines[currentLines.length - sharedSuffix - 1]
+            === generatedLines[generatedLines.length - sharedSuffix - 1]) {
+        sharedSuffix += 1;
+    }
+    const contextLines = 3;
+    const currentStart = Math.max(0, sharedPrefix - contextLines);
+    const generatedStart = Math.max(0, sharedPrefix - contextLines);
+    const currentChangedEnd = currentLines.length - sharedSuffix;
+    const generatedChangedEnd = generatedLines.length - sharedSuffix;
+    const currentEnd = Math.min(currentLines.length, currentChangedEnd + contextLines);
+    const generatedEnd = Math.min(generatedLines.length, generatedChangedEnd + contextLines);
+    const prefixContext = currentLines.slice(currentStart, sharedPrefix);
+    const suffixContext = currentLines.slice(currentChangedEnd, currentEnd);
+    const removedLines = currentLines.slice(sharedPrefix, currentChangedEnd);
+    const addedLines = generatedLines.slice(sharedPrefix, generatedChangedEnd);
+    return [
+        `--- ${displayPath}`,
+        `+++ ${displayPath} (generated)`,
+        `@@ -${currentStart + 1},${currentEnd - currentStart} +${generatedStart + 1},${generatedEnd - generatedStart} @@`,
+        ...prefixContext.map((line) => ` ${line}`),
+        ...removedLines.map((line) => `-${line}`),
+        ...addedLines.map((line) => `+${line}`),
+        ...suffixContext.map((line) => ` ${line}`),
+    ].join('\n');
+}

package/dist/utils/generated-file.d.ts

@@ -0,0 +1,22 @@
+export interface WriteGeneratedFileOptions {
+    /**
+     * Whether an existing destination may be replaced.
+     *
+     * Defaults to `false`, which makes the write an exclusive create: the
+     * existence check and the write are a single filesystem operation, so a file
+     * that appeared since the caller last looked raises
+     * {@link GeneratedFileExistsError} instead of being silently clobbered.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Thrown when a non-overwriting write finds the destination already present.
+ */
+export declare class GeneratedFileExistsError extends Error {
+    readonly filePath: string;
+    readonly code = "EEXIST";
+    constructor(filePath: string);
+}
+export declare function readGeneratedFile(filePath: string): Promise<string | undefined>;
+export declare function writeGeneratedFileAtomically(filePath: string, contents: string, options?: WriteGeneratedFileOptions): Promise<void>;
+//# sourceMappingURL=generated-file.d.ts.map

package/dist/utils/generated-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-file.d.ts","sourceRoot":"","sources":["../../src/utils/generated-file.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAGrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAFrC,QAAQ,CAAC,IAAI,YAAY;gBAEJ,QAAQ,EAAE,MAAM;CAItC;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASrF;AAgCD,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CA4Df"}

package/dist/utils/generated-file.js

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Thrown when a non-overwriting write finds the destination already present.
+ */
+export class GeneratedFileExistsError extends Error {
+    filePath;
+    code = 'EEXIST';
+    constructor(filePath) {
+        super(`Refusing to overwrite existing file: ${filePath}`);
+        this.filePath = filePath;
+        this.name = 'GeneratedFileExistsError';
+    }
+}
+export async function readGeneratedFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Tightest of the permission bits observed on a destination, ignoring the
+ * observations where it did not exist.
+ *
+ * A `chmod` that lands between two observations must not be undone by the
+ * earlier snapshot, and the safe direction is always the more restrictive one:
+ * the replacement is never more permissive than anything the destination was
+ * seen to be.
+ */
+function mostRestrictiveMode(...modes) {
+    const observed = modes.filter((mode) => mode !== undefined);
+    return observed.length > 0 ? observed.reduce((tightest, mode) => tightest & mode) : undefined;
+}
+/**
+ * Permission bits of an existing file, or undefined when it does not exist.
+ */
+async function readExistingMode(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export async function writeGeneratedFileAtomically(filePath, contents, options = {}) {
+    const resolvedPath = path.resolve(filePath);
+    const outputDirectory = path.dirname(resolvedPath);
+    await mkdir(outputDirectory, { recursive: true });
+    if (!options.overwrite) {
+        try {
+            // O_EXCL: the destination is created only if it is still absent, so a
+            // concurrent create between the caller's check and this write is never
+            // lost.
+            await writeFile(resolvedPath, contents, { flag: 'wx' });
+            return;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                throw new GeneratedFileExistsError(resolvedPath);
+            }
+            throw error;
+        }
+    }
+    const temporaryPath = path.join(outputDirectory, `.${path.basename(resolvedPath)}.${process.pid}.${randomUUID()}.tmp`);
+    // Read the destination's mode first: the temporary file must never be created
+    // more permissively than the file it replaces, or its contents are briefly
+    // exposed to other local users in a shared directory.
+    const existingMode = await readExistingMode(resolvedPath);
+    try {
+        await writeFile(temporaryPath, contents, existingMode !== undefined ? { mode: existingMode } : {});
+        // The destination can be chmod'ed — or created — while the contents above
+        // are being written. Renaming with only the pre-write snapshot would undo
+        // that, replacing a file just tightened to 0600 with a 0644 one, so the
+        // tighter of the two observations wins.
+        const destinationMode = mostRestrictiveMode(existingMode, await readExistingMode(resolvedPath));
+        // open() also applies the umask, and rename() swaps in a new inode, so the
+        // destination's exact mode has to be restored explicitly or a customized
+        // mode is silently reset. A chmod landing after this read still races the
+        // rename — rename() cannot be made conditional on the destination's mode —
+        // but the window is now two syscalls rather than the whole write.
+        if (destinationMode !== undefined) {
+            await chmod(temporaryPath, destinationMode);
+        }
+        await rename(temporaryPath, resolvedPath);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/utils/mcp-console.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP speaks its protocol over stdout, so anything an application logs while
+ * loading would corrupt the stream. Route it to stderr before importing the
+ * entrypoint, not after.
+ */
+export declare function routeConsoleOutputToStderr(): () => void;
+//# sourceMappingURL=mcp-console.d.ts.map

package/dist/utils/mcp-console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-console.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-console.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,IAAI,CAavD"}

package/dist/utils/mcp-console.js

@@ -0,0 +1,20 @@
+import { format } from 'node:util';
+/**
+ * MCP speaks its protocol over stdout, so anything an application logs while
+ * loading would corrupt the stream. Route it to stderr before importing the
+ * entrypoint, not after.
+ */
+export function routeConsoleOutputToStderr() {
+    const original = {
+        log: console.log,
+        info: console.info,
+        debug: console.debug,
+    };
+    const write = (...args) => {
+        process.stderr.write(`${format(...args)}\n`);
+    };
+    console.log = write;
+    console.info = write;
+    console.debug = write;
+    return () => Object.assign(console, original);
+}

package/dist/utils/mcp-lifecycle.d.ts

@@ -0,0 +1,6 @@
+export interface CloseableMcpServer {
+    close(): Promise<void>;
+}
+/** Own signal listeners for exactly the lifetime of the stdio server. */
+export declare function runMcpUntilSignal(start: () => Promise<CloseableMcpServer>): Promise<void>;
+//# sourceMappingURL=mcp-lifecycle.d.ts.map

package/dist/utils/mcp-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-lifecycle.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB/F"}

package/dist/utils/mcp-lifecycle.js

@@ -0,0 +1,22 @@
+/** Own signal listeners for exactly the lifetime of the stdio server. */
+export async function runMcpUntilSignal(start) {
+    let stop;
+    const stopped = new Promise(resolve => { stop = resolve; });
+    // Install before awaiting startup so a signal during connection is retained.
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    let server;
+    try {
+        server = await start();
+        await stopped;
+    }
+    finally {
+        try {
+            await server?.close();
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+    }
+}

package/dist/utils/mcp-source.d.ts

@@ -0,0 +1,9 @@
+export interface ServeMcpSource {
+    readonly version: 1;
+    readonly datasets: Readonly<Record<string, unknown>>;
+    readonly resolveAnalytics: () => unknown;
+}
+export declare function readServeMcpSource(value: unknown): ServeMcpSource | undefined;
+/** Datasets a caller cannot query unless a trusted tenant is configured. */
+export declare function tenantScopedDatasets(datasets: Record<string, unknown>): string[];
+//# sourceMappingURL=mcp-source.d.ts.map

package/dist/utils/mcp-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-source.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-source.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,OAAO,CAAC;CAC1C;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAU7E;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAShF"}

package/dist/utils/mcp-source.js

@@ -0,0 +1,28 @@
+/**
+ * Mirrors `@hypequery/serve`'s `ServeMcpSource`. Read through the global symbol
+ * registry rather than by importing serve: serve is a peer dependency that
+ * lives in the user's project, and a static import here would be resolved by
+ * Node before any CLI code runs, breaking even `hypequery --help` on a clean
+ * install. Keep the key in step with `server/mcp-source.ts`.
+ */
+const MCP_SOURCE_SYMBOL = Symbol.for('hypequery.mcp-source.v1');
+export function readServeMcpSource(value) {
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return undefined;
+    }
+    const source = value[MCP_SOURCE_SYMBOL];
+    return source?.version === 1 && typeof source.resolveAnalytics === 'function'
+        ? source
+        : undefined;
+}
+/** Datasets a caller cannot query unless a trusted tenant is configured. */
+export function tenantScopedDatasets(datasets) {
+    return Object.entries(datasets)
+        .filter(([, dataset]) => {
+        const value = dataset;
+        const tenantKey = value?.tenantKey ?? value?.config?.tenantKey;
+        return typeof tenantKey === 'string' && tenantKey.length > 0;
+    })
+        .map(([name]) => name)
+        .sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.18.2",
+  "version": "1.19.0",
   "description": "CLI for scaffolding type-safe ClickHouse analytics, semantic datasets, React manifests, and deployments",
   "keywords": [
     "clickhouse",
@@ -30,22 +30,29 @@
     "open": "^10.0.0",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/deployment": "0.7.4",
-    "@hypequery/protocol": "0.11.1"
+    "@hypequery/deployment": "0.7.5",
+    "@hypequery/protocol": "0.12.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0"
   },
   "peerDependencies": {
+    "@hypequery/mcp": "*",
     "@hypequery/serve": "*"
   },
+  "peerDependenciesMeta": {
+    "@hypequery/mcp": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^20.11.30",
     "@types/prompts": "^2.4.9",
     "@vitest/coverage-v8": "^3.2.6",
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
-    "@hypequery/serve": "0.16.2"
+    "@hypequery/mcp": "0.6.0",
+    "@hypequery/serve": "0.17.0"
   },
   "repository": {
     "type": "git",