@tsdevstack/cli-mcp 0.1.4

package/dist/index.js

@@ -0,0 +1,1211 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+let context;
+function initContext(ctx) {
+    context = ctx;
+}
+function wrapCommand(fn) {
+    return context.wrapCommand(fn);
+}
+function registerListServicesTool(server) {
+    server.tool('list_services', 'List all services in the project with their types and ports. Use this first to understand the project.', {}, {
+        title: 'List Services',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>{
+        try {
+            const configPath = join(process.cwd(), '.tsdevstack', 'config.json');
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(config.services, null, 2)
+                    }
+                ]
+            };
+        } catch  {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'config.json not found. Run `npx tsdevstack init` to create a project.'
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+}
+function registerListEnvironmentsTool(server) {
+    server.tool('list_environments', 'List configured cloud environments (dev, staging, prod) and their providers.', {}, {
+        title: 'List Environments',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>{
+        try {
+            const tsdevstackDir = join(process.cwd(), '.tsdevstack');
+            const files = readdirSync(tsdevstackDir);
+            const credentialFiles = files.filter((f)=>f.startsWith('.credentials.') && f.endsWith('.json'));
+            if (0 === credentialFiles.length) return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No cloud environments configured. Run `npx tsdevstack cloud:init --gcp|--aws|--azure` to initialize a provider.'
+                    }
+                ]
+            };
+            const environments = [];
+            for (const file of credentialFiles){
+                const provider = file.replace('.credentials.', '').replace('.json', '');
+                const content = JSON.parse(readFileSync(join(tsdevstackDir, file), 'utf-8'));
+                const envNames = Object.keys(content);
+                environments.push({
+                    provider,
+                    environments: envNames
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(environments, null, 2)
+                    }
+                ]
+            };
+        } catch  {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Could not read credential files. Ensure .tsdevstack/ directory exists.'
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+}
+function registerGetProjectConfigTool(server) {
+    server.tool('get_project_config', 'Full project configuration including service names, types, and workspace setup.', {}, {
+        title: 'Get Project Config',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>{
+        try {
+            const configPath = join(process.cwd(), '.tsdevstack', 'config.json');
+            const content = readFileSync(configPath, 'utf-8');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: content
+                    }
+                ]
+            };
+        } catch  {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'config.json not found. Run `npx tsdevstack init` to create a project.'
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+}
+function registerGetInfrastructureConfigTool(server) {
+    server.tool('get_infrastructure_config', 'Per-environment infrastructure settings: DB tiers, domains, scaling, custom overrides. This is a user-created file.', {}, {
+        title: 'Get Infrastructure Config',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>{
+        try {
+            const configPath = join(process.cwd(), '.tsdevstack', 'infrastructure.json');
+            const content = readFileSync(configPath, 'utf-8');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: content
+                    }
+                ]
+            };
+        } catch  {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'infrastructure.json not found. This is a user-created file — see the guide/config resource for how to create it.'
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+}
+const DEFAULT_TIMEOUT_MS = 600000;
+function runCommand(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve)=>{
+        execFile('npx', [
+            'tsdevstack',
+            ...args
+        ], {
+            cwd: process.cwd(),
+            timeout: timeoutMs,
+            maxBuffer: 10485760
+        }, (error, stdout, stderr)=>{
+            const output = [
+                stdout,
+                stderr
+            ].filter(Boolean).join('\n');
+            resolve({
+                content: [
+                    {
+                        type: 'text',
+                        text: output || 'Command completed.'
+                    }
+                ],
+                isError: null !== error
+            });
+        });
+    });
+}
+function registerGetServiceStatusTool(server) {
+    server.tool('get_service_status', 'Cloud resource status for a specific service (running, image tag, URL, health).', {
+        service: z.string().describe('Service name to check status for'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Get Service Status',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env })=>runCommand([
+            'infra:service-status',
+            service,
+            '--env',
+            env
+        ]));
+}
+function registerListDeployedServicesTool(server) {
+    server.tool('list_deployed_services', 'All deployed services in a cloud environment with their current status.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'List Deployed Services',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:list-deployed',
+            '--env',
+            env
+        ]));
+}
+function registerListSecretsTool(server) {
+    server.tool('list_secrets', "Secret names stored in a cloud environment's secret manager. Does NOT return values.", {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'List Secrets',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'cloud-secrets:list',
+            '--env',
+            env
+        ]));
+}
+function registerDiffSecretsTool(server) {
+    server.tool('diff_secrets', "Compare local secret names vs cloud — shows what's missing or extra. Run before deploying to catch mismatches.", {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Diff Secrets',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'cloud-secrets:diff',
+            '--env',
+            env
+        ]));
+}
+function registerGetSecretTool(server) {
+    server.tool('get_secret', 'Get a single secret value from cloud. Use to check if a secret is set (e.g., DOMAIN). Returns the value — use with care.', {
+        key: z.string().describe('Secret key name (e.g., DOMAIN, RESEND_API_KEY)'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Get Secret',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ key, env })=>runCommand([
+            'cloud-secrets:get',
+            key,
+            '--env',
+            env
+        ]));
+}
+function registerListSchedulersTool(server) {
+    server.tool('list_schedulers', 'Scheduled jobs (cron tasks) and their deployment status.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'List Schedulers',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:list-schedulers',
+            '--env',
+            env
+        ]));
+}
+function registerPlanDbMigrateTool(server) {
+    server.tool('plan_db_migrate', 'Show pending Prisma database migrations for a service. Run before `run_db_migrate` to preview changes.', {
+        service: z.string().describe('Service name (must have a database)'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Plan DB Migrate',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env })=>runCommand([
+            'infra:plan-db-migrate',
+            '--service',
+            service,
+            '--env',
+            env
+        ]));
+}
+function registerInfraPlanTool(server) {
+    server.tool('infra_plan', 'Terraform plan — preview infrastructure changes without applying. Always run before `infra_deploy`.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Plan',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:plan',
+            '--env',
+            env
+        ]));
+}
+function registerInfraStatusTool(server) {
+    server.tool('infra_status', 'Check if infrastructure configuration is in sync (Terraform state vs config files).', {}, {
+        title: 'Infra Status',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'infra:status'
+        ]));
+}
+function registerQueryTools(server) {
+    registerListServicesTool(server);
+    registerListEnvironmentsTool(server);
+    registerGetProjectConfigTool(server);
+    registerGetInfrastructureConfigTool(server);
+    registerGetServiceStatusTool(server);
+    registerListDeployedServicesTool(server);
+    registerListSecretsTool(server);
+    registerDiffSecretsTool(server);
+    registerGetSecretTool(server);
+    registerListSchedulersTool(server);
+    registerPlanDbMigrateTool(server);
+    registerInfraPlanTool(server);
+    registerInfraStatusTool(server);
+}
+function registerSyncTool(server) {
+    server.tool('sync', 'Regenerate all local config: secrets, docker-compose, kong, migrations. Run after adding services or changing secrets.', {}, {
+        title: 'Sync',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'sync'
+        ]));
+}
+function registerGenerateSecretsTool(server) {
+    server.tool('generate_secrets', 'Regenerate local secrets files. Run after editing .secrets.user.json. Preserves existing JWT keys and passwords.', {}, {
+        title: 'Generate Secrets',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'generate-secrets'
+        ]));
+}
+function registerGenerateKongTool(server) {
+    server.tool('generate_kong', 'Regenerate Kong gateway config from OpenAPI specs. Run after adding/changing API endpoints or decorators.', {}, {
+        title: 'Generate Kong',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'generate-kong'
+        ]));
+}
+function registerGenerateDockerComposeTool(server) {
+    server.tool('generate_docker_compose', 'Regenerate docker-compose.yml from current config. Run after adding services.', {}, {
+        title: 'Generate Docker Compose',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'generate-docker-compose'
+        ]));
+}
+function registerAddServiceTool(server) {
+    server.tool('add_service', 'Add a new service (nestjs, nextjs, or spa). After this, run sync to regenerate all config. Types: nestjs (backend API), nextjs (SSR frontend), spa (Rsbuild SPA).', {
+        name: z.string().describe('Service name (kebab-case, e.g. "billing-service")'),
+        type: z["enum"]([
+            'nestjs',
+            'nextjs',
+            'spa'
+        ]).describe('Service type')
+    }, {
+        title: 'Add Service',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ name, type })=>runCommand([
+            'add-service',
+            '--name',
+            name,
+            '--type',
+            type
+        ]));
+}
+function registerRemoveServiceTool(server) {
+    server.tool('remove_service', 'Remove a service from the local project (deletes files, updates config). Does NOT remove from cloud — use remove_service_cloud for that.', {
+        service: z.string().describe('Service name to remove')
+    }, {
+        title: 'Remove Service',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ service })=>runCommand([
+            'remove-service',
+            service
+        ]));
+}
+function registerGenerateClientTool(server) {
+    server.tool('generate_client', "Generate TypeScript HTTP client + DTOs from a service's OpenAPI spec. Other services import this for type-safe API calls.", {
+        service: z.string().describe('Service name to generate client for')
+    }, {
+        title: 'Generate Client',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service })=>runCommand([
+            'generate-client',
+            service
+        ]));
+}
+function registerRegisterDetachedWorkerTool(server) {
+    server.tool('register_detached_worker', "Register a detached worker in config.json. Only updates config — does NOT scaffold files. User must create worker.ts, worker.module.ts, and processor files manually using nest-common's startWorker(). After registering, run sync then infra_deploy.", {
+        name: z.string().describe('Worker name (kebab-case)'),
+        baseService: z.string().describe('Base NestJS service this worker belongs to')
+    }, {
+        title: 'Register Detached Worker',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ name, baseService })=>runCommand([
+            'register-detached-worker',
+            '--name',
+            name,
+            '--base-service',
+            baseService
+        ]));
+}
+function registerUnregisterDetachedWorkerTool(server) {
+    server.tool('unregister_detached_worker', 'Remove a detached worker entry from config.json. Does NOT remove from cloud — use remove_detached_worker for that.', {
+        worker: z.string().describe('Worker name to unregister')
+    }, {
+        title: 'Unregister Detached Worker',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ worker })=>runCommand([
+            'unregister-detached-worker',
+            '--worker',
+            worker
+        ]));
+}
+function registerCloudSecretsPushTool(server) {
+    server.tool('cloud_secrets_push', 'Push secrets to cloud. Generates framework secrets, prompts for DOMAIN/RESEND_API_KEY/EMAIL_FROM, auto-derives the rest. Run once per environment during initial setup.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Cloud Secrets Push',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'cloud-secrets:push',
+            '--env',
+            env
+        ]));
+}
+function registerCloudSecretsSetTool(server) {
+    server.tool('cloud_secrets_set', 'Set or update a single secret in cloud. Use for overrides or adding new third-party API keys.', {
+        key: z.string().describe('Secret key name (e.g. DOMAIN, STRIPE_KEY)'),
+        value: z.string().describe('Secret value'),
+        env: z.string().describe('Target environment (dev, staging, prod)'),
+        service: z.string().optional().describe('Service scope (defaults to shared)')
+    }, {
+        title: 'Cloud Secrets Set',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ key, value, env, service })=>{
+        const args = [
+            'cloud-secrets:set',
+            key,
+            '--value',
+            value,
+            '--env',
+            env,
+            '--overwrite'
+        ];
+        if (service) args.push('--service', service);
+        return runCommand(args);
+    });
+}
+function registerCloudSecretsRemoveTool(server) {
+    server.tool('cloud_secrets_remove', 'Remove a secret from cloud secret manager. Verify the secret is unused before removing.', {
+        key: z.string().describe('Secret key name to remove'),
+        env: z.string().describe('Target environment (dev, staging, prod)'),
+        service: z.string().optional().describe('Service scope (defaults to shared)')
+    }, {
+        title: 'Cloud Secrets Remove',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ key, env, service })=>{
+        const args = [
+            'cloud-secrets:remove',
+            key,
+            '--env',
+            env,
+            '--force'
+        ];
+        if (service) args.push('--service', service);
+        return runCommand(args);
+    });
+}
+function registerInfraDeployTool(server) {
+    server.tool('infra_deploy', 'Full deployment: Terraform infra + build + push + deploy all services + Kong + LB. Required when adding new services. Long-running (30+ min) — advise the user to run `npx tsdevstack infra:deploy --env {env}` in their terminal instead.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Deploy',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:deploy',
+            '--env',
+            env,
+            '--auto-approve'
+        ]));
+}
+function registerDeployServicesTool(server) {
+    server.tool('deploy_services', 'Deploy code changes to existing services only. Faster than full deploy. Use for code updates when no infrastructure changes are needed. Supports optional service filter.', {
+        env: z.string().describe('Target environment (dev, staging, prod)'),
+        service: z.string().optional().describe('Optional: deploy only this service (or comma-separated list)')
+    }, {
+        title: 'Deploy Services',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env, service })=>{
+        const args = [
+            'infra:deploy-services',
+            '--env',
+            env
+        ];
+        if (service) args.push('--service', service);
+        return runCommand(args);
+    });
+}
+function registerDeployKongTool(server) {
+    server.tool('deploy_kong', 'Rebuild and deploy Kong gateway. Run after changing routes (adding endpoints, changing auth decorators).', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Deploy Kong',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:deploy-kong',
+            '--env',
+            env
+        ]));
+}
+function registerDeployLbTool(server) {
+    server.tool('deploy_lb', 'Deploy/update the load balancer. Run after changing domains or adding frontend apps. Outputs DNS records and SSL validation info.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Deploy Load Balancer',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:deploy-lb',
+            '--env',
+            env,
+            '--auto-approve'
+        ]));
+}
+function registerRunDbMigrateTool(server) {
+    server.tool('run_db_migrate', 'Apply pending Prisma migrations for a service in cloud. Run plan_db_migrate first to preview changes.', {
+        service: z.string().describe('Service name with database'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Run DB Migrate',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env })=>runCommand([
+            'infra:run-db-migrate',
+            '--service',
+            service,
+            '--env',
+            env
+        ]));
+}
+function registerDeploySchedulersTool(server) {
+    server.tool('deploy_schedulers', 'Deploy all scheduled jobs (cron tasks) to cloud.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Deploy Schedulers',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:deploy-schedulers',
+            '--env',
+            env,
+            '--auto-approve'
+        ]));
+}
+function registerRemoveServiceCloudTool(server) {
+    server.tool('remove_service_cloud', 'Remove a service from cloud (deletes container, secrets, database). Cannot be undone. Data is permanently lost.', {
+        service: z.string().describe('Service name to remove from cloud'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Remove Service (Cloud)',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ service, env })=>runCommand([
+            'infra:remove-service',
+            service,
+            '--env',
+            env,
+            '--confirm'
+        ]));
+}
+function registerRemoveDetachedWorkerTool(server) {
+    server.tool('remove_detached_worker', 'Remove a detached worker from cloud. Cannot be undone.', {
+        worker: z.string().describe('Worker name to remove'),
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Remove Detached Worker (Cloud)',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ worker, env })=>runCommand([
+            'infra:remove-detached-worker',
+            '--worker',
+            worker,
+            '--env',
+            env,
+            '--confirm'
+        ]));
+}
+function registerInfraDestroyTool(server) {
+    server.tool('infra_destroy', 'Destroy ALL cloud infrastructure for an environment. Permanently deletes databases, services, and all data. Cannot be undone. Use with extreme caution.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Destroy',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:destroy',
+            '--env',
+            env,
+            '--auto-approve'
+        ]));
+}
+function registerCloudInitTool(server) {
+    server.tool('cloud_init', 'Initialize cloud provider credentials for a specific provider (gcp, aws, azure). One-time setup per provider. Provider must be passed as flag to skip interactive prompt.', {
+        provider: z["enum"]([
+            'gcp',
+            'aws',
+            'azure'
+        ]).describe('Cloud provider to initialize')
+    }, {
+        title: 'Cloud Init',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ provider })=>runCommand([
+            'cloud:init',
+            `--${provider}`
+        ]));
+}
+function registerInfraBootstrapTool(server) {
+    server.tool('infra_bootstrap', 'Bootstrap cloud project (enable APIs, add roles). One-time setup per environment.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Bootstrap',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:bootstrap',
+            '--env',
+            env
+        ]));
+}
+function registerInfraInitTool(server) {
+    server.tool('infra_init', 'Initialize infrastructure (creates Terraform state bucket). One-time setup per environment.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Init',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:init',
+            '--env',
+            env
+        ]));
+}
+function registerInfraGenerateTool(server) {
+    server.tool('infra_generate', 'Generate Terraform files from config. Usually called internally by deploy, but useful for previewing generated output.', {
+        env: z.string().describe('Target environment (dev, staging, prod)')
+    }, {
+        title: 'Infra Generate',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>runCommand([
+            'infra:generate',
+            '--env',
+            env
+        ]));
+}
+function registerInfraGenerateDockerTool(server) {
+    server.tool('infra_generate_docker', 'Generate Dockerfiles for services. Usually called internally by deploy. Supports optional service filter.', {
+        service: z.string().optional().describe('Generate for specific service only (optional)')
+    }, {
+        title: 'Generate Dockerfiles',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service })=>{
+        const args = [
+            'infra:generate-docker'
+        ];
+        if (service) args.push('--service', service);
+        return runCommand(args);
+    });
+}
+function registerInfraBuildDockerTool(server) {
+    server.tool('infra_build_docker', 'Build Docker images with BuildKit. Usually called internally by deploy. Supports --service for single build, --tag for custom tag (defaults to git SHA).', {
+        service: z.string().optional().describe('Build specific service only (optional)'),
+        env: z.string().optional().describe('Target environment (optional)'),
+        tag: z.string().optional().describe('Image tag (defaults to git SHA)')
+    }, {
+        title: 'Build Docker Images',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env, tag })=>{
+        const args = [
+            'infra:build-docker'
+        ];
+        if (service) args.push('--service', service);
+        if (env) args.push('--env', env);
+        if (tag) args.push('--tag', tag);
+        return runCommand(args);
+    });
+}
+function registerInfraPushDockerTool(server) {
+    server.tool('infra_push_docker', 'Push Docker images to registry. Usually called internally by deploy. Supports --service for single push.', {
+        service: z.string().optional().describe('Push specific service only (optional)'),
+        env: z.string().optional().describe('Target environment (optional)'),
+        tag: z.string().optional().describe('Image tag (defaults to git SHA)')
+    }, {
+        title: 'Push Docker Images',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env, tag })=>{
+        const args = [
+            'infra:push-docker'
+        ];
+        if (service) args.push('--service', service);
+        if (env) args.push('--env', env);
+        if (tag) args.push('--tag', tag);
+        return runCommand(args);
+    });
+}
+function registerInfraBuildKongTool(server) {
+    server.tool('infra_build_kong', 'Build Kong Docker image. Usually called internally by deploy-kong.', {
+        env: z.string().optional().describe('Target environment (optional)'),
+        tag: z.string().optional().describe('Image tag (defaults to git SHA)')
+    }, {
+        title: 'Build Kong Image',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env, tag })=>{
+        const args = [
+            'infra:build-kong'
+        ];
+        if (env) args.push('--env', env);
+        if (tag) args.push('--tag', tag);
+        return runCommand(args);
+    });
+}
+function registerInfraInitCiTool(server) {
+    server.tool('infra_init_ci', 'Initialize CI/CD workflows (GitHub Actions). One-time setup.', {}, {
+        title: 'Init CI/CD',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ()=>runCommand([
+            'infra:init-ci',
+            '--github'
+        ]));
+}
+function registerInfraGenerateCiTool(server) {
+    server.tool('infra_generate_ci', 'Regenerate CI workflows from ci.json.', {
+        env: z.string().optional().describe('Target environment (optional)')
+    }, {
+        title: 'Generate CI Workflows',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ env })=>{
+        const args = [
+            'infra:generate-ci'
+        ];
+        if (env) args.push('--env', env);
+        return runCommand(args);
+    });
+}
+function registerDeployServiceTool(server) {
+    server.tool('deploy_service', 'Build, push, deploy a single service (full workflow). Alternative to deploy_services --service. Supports optional tag override.', {
+        service: z.string().describe('Service name to deploy'),
+        env: z.string().optional().describe('Target environment (optional)'),
+        tag: z.string().optional().describe('Image tag to deploy (defaults to current git SHA)')
+    }, {
+        title: 'Deploy Service',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service, env, tag })=>{
+        const args = [
+            'infra:deploy-service',
+            service
+        ];
+        if (env) args.push('--env', env);
+        if (tag) args.push('--tag', tag);
+        return runCommand(args);
+    });
+}
+function registerDeploySchedulerTool(server) {
+    server.tool('deploy_scheduler', 'Deploy a single scheduled job. Alternative to batch deploy_schedulers.', {
+        job: z.string().optional().describe('Scheduled job name to deploy (optional)'),
+        env: z.string().optional().describe('Target environment (optional)')
+    }, {
+        title: 'Deploy Scheduler',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ job, env })=>{
+        const args = [
+            'infra:deploy-scheduler'
+        ];
+        if (job) args.push('--job', job);
+        if (env) args.push('--env', env);
+        args.push('--auto-approve');
+        return runCommand(args);
+    });
+}
+function registerRemoveSchedulerTool(server) {
+    server.tool('remove_scheduler', 'Remove a single scheduled job from cloud. Cannot be undone.', {
+        job: z.string().optional().describe('Job name to remove (optional)'),
+        env: z.string().optional().describe('Target environment (optional)')
+    }, {
+        title: 'Remove Scheduler',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+    }, async ({ job, env })=>{
+        const args = [
+            'infra:remove-scheduler'
+        ];
+        if (job) args.push('--job', job);
+        if (env) args.push('--env', env);
+        args.push('--confirm');
+        return runCommand(args);
+    });
+}
+function registerValidateServiceTool(server) {
+    server.tool('validate_service', 'Validate a service follows naming conventions and structure.', {
+        service: z.string().optional().describe('Service name to validate (optional, auto-detects from cwd)')
+    }, {
+        title: 'Validate Service',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+    }, async ({ service })=>{
+        const args = [
+            'validate-service'
+        ];
+        if (service) args.push(service);
+        return runCommand(args);
+    });
+}
+function registerActionTools(server) {
+    registerSyncTool(server);
+    registerGenerateSecretsTool(server);
+    registerGenerateKongTool(server);
+    registerGenerateDockerComposeTool(server);
+    registerAddServiceTool(server);
+    registerRemoveServiceTool(server);
+    registerGenerateClientTool(server);
+    registerRegisterDetachedWorkerTool(server);
+    registerUnregisterDetachedWorkerTool(server);
+    registerCloudSecretsPushTool(server);
+    registerCloudSecretsSetTool(server);
+    registerCloudSecretsRemoveTool(server);
+    registerInfraDeployTool(server);
+    registerDeployServicesTool(server);
+    registerDeployKongTool(server);
+    registerDeployLbTool(server);
+    registerRunDbMigrateTool(server);
+    registerDeploySchedulersTool(server);
+    registerRemoveServiceCloudTool(server);
+    registerRemoveDetachedWorkerTool(server);
+    registerInfraDestroyTool(server);
+    registerCloudInitTool(server);
+    registerInfraBootstrapTool(server);
+    registerInfraInitTool(server);
+    registerInfraGenerateTool(server);
+    registerInfraGenerateDockerTool(server);
+    registerInfraBuildDockerTool(server);
+    registerInfraPushDockerTool(server);
+    registerInfraBuildKongTool(server);
+    registerInfraInitCiTool(server);
+    registerInfraGenerateCiTool(server);
+    registerDeployServiceTool(server);
+    registerDeploySchedulerTool(server);
+    registerRemoveSchedulerTool(server);
+    registerValidateServiceTool(server);
+}
+function registerTools(server) {
+    registerQueryTools(server);
+    registerActionTools(server);
+}
+function readProjectFile(relativePath) {
+    try {
+        return readFileSync(join(process.cwd(), relativePath), 'utf-8');
+    } catch  {
+        return null;
+    }
+}
+function registerProjectStateResources(server) {
+    server.resource('config', 'tsdevstack://config', {
+        description: 'Project name, services, types, ports — the main project configuration.'
+    }, async (uri)=>{
+        const content = readProjectFile('.tsdevstack/config.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'config.json not found. Run `npx tsdevstack init` to create a project.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    server.resource('infrastructure', 'tsdevstack://infrastructure', {
+        description: 'Per-environment infrastructure settings (DB tiers, domains, scaling). User-created file.'
+    }, async (uri)=>{
+        const content = readProjectFile('.tsdevstack/infrastructure.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'infrastructure.json not found. This is a user-created file — see the guide/config resource for how to create it.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    server.resource('infrastructure-schema', 'tsdevstack://infrastructure-schema', {
+        description: 'Valid fields and values for infrastructure.json. Generated by `infra:init`. Only exists after initialization.'
+    }, async (uri)=>{
+        const content = readProjectFile('.tsdevstack/infrastructure.schema.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'infrastructure.schema.json not found. Run `npx tsdevstack infra:init --env <env>` to generate the schema.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    server.resource('ci', 'tsdevstack://ci', {
+        description: 'CI/CD configuration — environments, provider, workflow settings.'
+    }, async (uri)=>{
+        const content = readProjectFile('.tsdevstack/ci.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'ci.json not found. Run `npx tsdevstack infra:init-ci --github` to initialize CI/CD.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+}
+function secrets_context_readProjectFile(relativePath) {
+    try {
+        return readFileSync(join(process.cwd(), relativePath), 'utf-8');
+    } catch  {
+        return null;
+    }
+}
+function registerSecretsContextResources(server) {
+    server.resource('secrets-map', 'tsdevstack://secrets/map', {
+        description: 'Which secrets are assigned to which services. Critical for debugging "service X doesn\'t have secret Y" issues.'
+    }, async (uri)=>{
+        const content = secrets_context_readProjectFile('.tsdevstack/secret-map.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'secret-map.json not found. Run `npx tsdevstack generate-secrets` to generate it.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    server.resource('secrets-names', 'tsdevstack://secrets/names', {
+        description: 'Secret names, scopes, and values (local dev only — no cloud credentials). Full content of the merged secrets file.'
+    }, async (uri)=>{
+        const content = secrets_context_readProjectFile('.secrets.local.json');
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? '.secrets.local.json not found. Run `npx tsdevstack generate-secrets` to generate it.',
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+    server.resource('secrets-user', 'tsdevstack://secrets/user', {
+        description: 'User secret definitions and service assignments (keys only, no values). Shows which secrets the user has defined and which services they are assigned to.'
+    }, async (uri)=>{
+        const raw = secrets_context_readProjectFile('.secrets.user.json');
+        if (!raw) return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: '.secrets.user.json not found. This file is created when the user adds custom secrets.'
+                }
+            ]
+        };
+        const parsed = JSON.parse(raw);
+        const keysOnly = {};
+        for (const [key, value] of Object.entries(parsed))if ('secrets' === key && 'object' == typeof value && null !== value) keysOnly[key] = Object.keys(value);
+        else keysOnly[key] = value;
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(keysOnly, null, 2),
+                    mimeType: 'application/json'
+                }
+            ]
+        };
+    });
+}
+function registerKongRoutesResource(server) {
+    server.resource('kong-routes', 'tsdevstack://kong/routes', {
+        description: 'Current Kong gateway routing config (services, routes, plugins). Shows which endpoints exist, their auth requirements, and which service handles each route.'
+    }, async (uri)=>{
+        const cwd = process.cwd();
+        let content = null;
+        for (const filename of [
+            'kong.tsdevstack.yml',
+            'kong.yml'
+        ])try {
+            content = readFileSync(join(cwd, filename), 'utf-8');
+            break;
+        } catch  {}
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content ?? 'Kong config not found. Run `npx tsdevstack generate-kong` to generate it.',
+                    mimeType: 'text/yaml'
+                }
+            ]
+        };
+    });
+}
+const GUIDE_CONTENT = "# tsdevstack Framework Guide\n\n## Project Structure\n- `apps/` — Microservices and frontends (NestJS, Next.js, SPA)\n- `packages/` — Shared libraries and CLI packages (new packages go here, scaffold with rslib)\n- `.tsdevstack/` — Framework configuration (config.json, infrastructure.json, credentials, secret-map)\n- `docs/` — Documentation\n- `infrastructure/` — GENERATED Terraform and Kong files (never edit directly)\n\n## Service Types\n- `nestjs` — Backend API service. Has globalPrefix, optional database, OpenAPI spec, Kong routes.\n- `nextjs` — Server-rendered frontend (Next.js App Router).\n- `spa` — Single-page application (Rsbuild). No server-side rendering.\n- `worker` — Detached background job processor. Shares Docker image with its base NestJS service, runs with different entrypoint (`dist/worker.js`).\n\n## Key Principles\n- **Single source of truth:** Service names come from `package.json`. Config derives from `.tsdevstack/config.json`. No magic strings.\n- **Convention over configuration:** Strict naming (kebab-case), everything derived automatically.\n- **Generated files are read-only:** Files in `infrastructure/`, `docker-compose.yml`, `kong.tsdevstack.yml`, `.secrets.tsdevstack.json` are all generated by CLI commands. Edit the generators or config, not the output.\n- **Override files are yours:** `kong.user.yml`, `docker-compose.user.yml`, `.secrets.user.json` — these are merged with generated files and preserved across regenerations.\n\n## Anti-Patterns (DO NOT DO THESE)\n- NEVER edit `config.json` directly to add services or workers — use `add_service` or `register_detached_worker`\n- NEVER edit files in `infrastructure/terraform/` or `infrastructure/kong/` — they're generated. Edit the generators in `packages/cli-infra/src/utils/*/terraform-generate/`\n- NEVER install npm packages for things nest-common already provides (Redis, auth guards, logging, rate limiting, observability, BullMQ config, service clients)\n- NEVER create a worker by copying service boilerplate — use `register_detached_worker` to add to config, then create `worker.ts` and `worker.module.ts` using nest-common's `startWorker()` wrapper\n- NEVER deploy a new service/worker with `deploy_services` — new services need `infra_deploy` (Terraform must create the container runtime first)\n- NEVER shell out to `aws`, `gcloud`, or `az` CLI tools in source code — use cloud provider SDKs. CLI tools are only available locally.\n- NEVER use `process.env` to read secrets in NestJS services — inject `SecretsService` and use `await this.secrets.get('KEY')`\n- NEVER edit `.secrets.tsdevstack.json` — it's auto-generated. Put your secrets in `.secrets.user.json`\n\n## OpenAPI Decorators Drive Everything\nNestJS OpenAPI/Swagger decorators are NOT just for documentation — they drive the entire gateway:\n1. `@ApiOperation()` on a controller method → the endpoint exists in OpenAPI spec\n2. `generate_kong` reads the OpenAPI spec → generates Kong routes\n3. `@ApiBearerAuth()` + `@UseGuards(AuthGuard)` → Kong adds JWT validation to that route\n4. `@PartnerApi()` → Kong exposes route under `/api/` prefix with API key auth\n5. `generate_client` reads the OpenAPI spec → generates TypeScript HTTP client + DTOs\n\nThis means: if you add an endpoint without proper decorators, it won't appear in Kong routes, won't be accessible from outside, and won't generate client types. Decorators are the source of truth for the API contract.\n\n## Secrets System\n- Three-file merge: `.secrets.tsdevstack.json` (framework, auto-generated) + `.secrets.user.json` (yours) → `.secrets.local.json` (merged output)\n- Framework secrets (JWT keys, DB passwords, service API keys, service URLs) are auto-generated — don't touch them\n- User secrets (third-party API keys, custom config) go in `.secrets.user.json`\n- Each service only sees secrets assigned to it (scoping via `secret-map.json`)\n- Cloud: `cloud_secrets_push` prompts for 3 values (DOMAIN, RESEND_API_KEY, EMAIL_FROM) and auto-derives everything else\n\n## Docs-Site Reference\nThe framework has a documentation site with detailed guides. When deployed, reference these for deeper reading:\n- **Local development:** `/local-development/tech-stack`, `/local-development/debugging`, `/local-development/adding-apps`\n- **Secrets:** `/secrets/how-secrets-work`, `/secrets/local-secrets`, `/secrets/user-vs-framework`, `/secrets/cloud-secrets`\n- **Authentication:** `/authentication/overview`, `/authentication/jwt-tokens`, `/authentication/protected-routes`, `/authentication/session-management`\n- **Building APIs:** `/building-apis/openapi-decorators`, `/building-apis/gateway-routing`, `/building-apis/dto-generation`, `/building-apis/swagger-docs`\n- **Infrastructure:** `/infrastructure/cicd-setup`, `/infrastructure/domain-setup`, `/infrastructure/environments`, `/infrastructure/service-configuration`\n- **Observability:** `/features/observability`\n- **Customization:** `/customization/kong-customization`, `/customization/docker-overrides`, `/customization/framework-files`, `/customization/escape-hatches`\n- **Provider-specific:** `/infrastructure/providers/gcp/`, `/infrastructure/providers/aws/`, `/infrastructure/providers/azure/`\n\n## Deployment Model\n- `infra_deploy` = full deploy (Terraform infra + build Docker + push + deploy all services + Kong + LB). Required for new services/workers.\n- `deploy_services` = code push only (build + push + deploy). For code updates to existing services. Supports `--service` for single service.\n- `deploy_kong` = rebuild and deploy Kong gateway. After changing routes/decorators.\n- `deploy_lb` = deploy/update load balancer. After changing domains.\n- New services/workers ALWAYS require `infra_deploy` because Terraform must create the container runtime.\n- Code updates to existing services: `deploy_services` is faster.";
+function registerGuideResource(server) {
+    server.resource('guide', 'tsdevstack://guide', {
+        description: 'Core framework concepts: project structure, service types, key principles, anti-patterns, secrets system, deployment model.'
+    }, async (uri)=>({
+            contents: [
+                {
+                    uri: uri.href,
+                    text: GUIDE_CONTENT,
+                    mimeType: 'text/markdown'
+                }
+            ]
+        }));
+}
+const WORKFLOWS_CONTENT = '# tsdevstack Workflow Reference\n\n## "Add a new backend service"\n1. `add_service` with name and type=nestjs → scaffolds app in `apps/{name}/`, updates config.json\n2. `sync` → regenerates secrets, docker-compose, kong config, migrations\n3. Tell user to run `npm run dev` to start locally\n4. For cloud: `infra_deploy --env {env}` (Terraform must create Cloud Run service)\n\n## "Add a new frontend"\n1. `add_service` with name and type=nextjs (or spa for React SPA)\n2. `sync` → regenerates docker-compose\n3. Tell user to run `npm run dev`\n4. For cloud: `infra_deploy --env {env}`\n\n## "Add a background job processor (detached worker)"\nWorkers run as separate containers sharing their base service\'s Docker image.\n1. `register_detached_worker` with name and base-service → adds worker entry to config.json\n2. User creates these files manually:\n   - `apps/{base-service}/src/worker.ts` — entry point using `startWorker()` from nest-common\n   - `apps/{base-service}/src/worker.module.ts` — NestJS module importing `BullConfigModule.forRoot()` and registering queues\n   - `apps/{base-service}/src/processors/{queue-name}.processor.ts` — BullMQ processor classes\n3. Import `BullModule.registerQueue({ name: \'queue-name\' })` in the main app module too (so the app can add jobs to the queue)\n4. `sync` → regenerates config\n5. `infra_deploy --env {env}` (Terraform must create the worker container)\n6. After first deploy, code updates: `deploy_services --service {base-service}` (deploys both app and worker)\n\n## "Add an API endpoint"\nNo CLI command needed — this is code:\n1. Add method to NestJS controller\n2. Add OpenAPI decorators: `@ApiOperation({ summary: \'...\' })`, `@ApiResponse({ ... })`\n3. For authentication: add `@ApiBearerAuth()` + `@UseGuards(AuthGuard)`\n4. For partner API access: add `@PartnerApi()` (can combine with `@ApiBearerAuth()` for dual access)\n5. For public endpoints: add `@Public()` decorator (or just don\'t add auth decorators)\n6. `generate_kong` → regenerates gateway routes from OpenAPI spec\n7. `generate_client` → regenerates TypeScript client so other services have the new endpoint typed\n\n## "Add a secret to a service"\n1. Read `tsdevstack://secrets/map` to see current assignments\n2. User adds key+value to `.secrets.user.json` under `secrets` object\n3. User adds the key name to the service\'s `secrets` array in `.secrets.user.json`\n4. `generate_secrets` → regenerates merged `.secrets.local.json`\n5. For cloud: `cloud_secrets_set` with the key and env, then `deploy_services --service {name}` to restart with new secret\n\n## "Assign a domain to a frontend app"\nOnly `nextjs` and `spa` apps can have domains. Backend services are NOT publicly available — they\'re behind Kong. Kong already has a fixed `api.{DOMAIN}` URL.\n1. `get_secret DOMAIN --env {env}` → check if DOMAIN is set in cloud\n2. If DOMAIN is not set: tell user to set it first (`cloud_secrets_set DOMAIN example.com --env {env}` or via `cloud_secrets_push`)\n3. If DOMAIN is set: edit `infrastructure.json` → add `"domain": "example.com"` to the frontend app\'s env entry\n   - If the app doesn\'t have an entry in the env config yet, create one: `"frontend": { "domain": "example.com" }`\n4. For redirect domains (alternate domains that redirect to canonical): add `"loadBalancer": { "redirectDomains": ["alt.com"] }` to the env config\n5. `deploy_lb --env {env}` → deploys/updates load balancer, outputs DNS records and SSL validation info\n6. User adds DNS records at their domain registrar (A/CNAME records from the output)\n7. Check DNS propagation: `dig {domain}` — wait for it to point to the LB IP\n8. SSL certificate auto-provisions after DNS propagates\n\n## "Generate a typed HTTP client for service-to-service calls"\n1. Ensure target service has proper OpenAPI decorators on all endpoints\n2. `generate_client` for the target service → generates TypeScript client + DTOs in `packages/{service}-client/`\n3. In the calling service, create a client class extending `BaseServiceClient` from nest-common\n4. Inject `SecretsService` to get the target service URL and API key\n5. The generated client provides full type safety for all endpoints, request bodies, and responses\n\n## "Create infrastructure.json for a new environment"\nThis file is user-created — the framework does NOT generate it. Only create it if needed (e.g., to override defaults).\nMost projects WILL need this because `minInstances: 0` (scale to zero) is a common non-prod setting that saves costs.\n1. Read `tsdevstack://config` to get the list of services\n2. Read `tsdevstack://infrastructure-schema` to know valid fields and values (only available after `infra_init`)\n3. Create `.tsdevstack/infrastructure.json` with:\n   - `"$schema": "./infrastructure.schema.json"` (REQUIRED — enables IDE validation)\n   - `"version": "1.0.0"`\n   - Environment key (e.g., `"dev"`) containing:\n     - Per-service overrides (CPU, memory, minInstances, maxInstances) — service names must match config.json\n     - `database` settings (tier, deletionProtection, etc.)\n     - `redis` settings (tier, memoryGb)\n     - `kong` settings (minInstances, maxInstances, cpu, memory)\n     - `accessControl` (protected, noIndex)\n     - `loadBalancer` (apiDomain, redirectDomains) — if domains are configured\n     - `scheduledJobs` array — if cron jobs exist\n4. For additional environments (staging, prod), add sibling keys with appropriate values\n5. **Advise users:** Non-prod environments should typically use `minInstances: 0` (scale to zero) to save costs. Prod should have `minInstances: 1` or higher for availability.\n\n## "Set up a new cloud environment (first deploy)"\nThe project already exists (created via `tsdevstack init`). This is for deploying to a new environment.\n1. `cloud_init --{provider}` → checks local credentials + bootstraps the cloud project (enables APIs, creates roles, terraform state bucket)\n2. Configure `infrastructure.json` with environment settings (see "Create infrastructure.json" workflow above)\n3. `cloud_secrets_push --env {env}` → prompts for DOMAIN, RESEND_API_KEY, EMAIL_FROM; auto-generates framework secrets\n4. `infra_deploy --env {env}` → the big deploy: Terraform infra + build Docker + push + deploy all services + Kong + LB. This does everything.\n5. Set DNS records on domain registrar portal (from deploy output)\n6. `deploy_schedulers --env {env}` (can run in parallel with DNS setup)\n7. Check domain propagation: `dig {domain}` — wait for DNS to point to LB IP\n8. `list_deployed_services --env {env}` → verify everything is running\n\n**Step-by-step alternative:** If the user wants more control, they can run individual steps: `infra_generate` → `infra_plan` → review → `infra_deploy` → `deploy_kong` → `deploy_lb` → `deploy_schedulers`.\n\n## "Deploy to a cloud environment (subsequent deploys)"\n1. `infra_plan --env {env}` → preview infrastructure changes (always do this first)\n2. Review the plan output\n3. `infra_deploy --env {env}` → full deployment\n4. `list_deployed_services --env {env}` → verify everything is running\n\n## "Deploy code changes only (no infra changes)"\n1. `deploy_services --env {env}` → build, push, deploy all services\n2. Or for single service: `deploy_services --env {env} --service {name}`\n\n## "Update Kong routes after API changes"\n1. `deploy_kong --env {env}` → rebuild and deploy Kong with new routes\n\n## "Check what\'s deployed"\n1. `list_deployed_services --env {env}` → all services with status\n2. `get_service_status --service {name} --env {env}` → specific service details (URL, image tag, health)\n\n## "Debug a missing secret"\n1. Read `tsdevstack://secrets/map` — is the secret assigned to the service?\n2. Read `tsdevstack://secrets/user` — is the secret defined in `.secrets.user.json`?\n3. If cloud: `diff_secrets --env {env}` → compare local vs cloud (shows what\'s missing or extra)\n\n## "Debug a 404 on an API endpoint"\n1. Read `tsdevstack://kong/routes` — does the route exist in Kong config?\n2. If missing: check OpenAPI decorators on the controller method → `generate_kong`\n3. If present in Kong but still 404: check the service\'s `globalPrefix` in config.json\n4. If cloud: `deploy_kong --env {env}` to push updated routes\n\n## "Add a scheduled job"\nScheduled jobs are cron triggers that call service endpoints over HTTPS. They don\'t execute code directly — they trigger an HTTP endpoint on an existing service. The service must be deployed before the scheduler can be deployed.\n1. Create the endpoint in the target NestJS service:\n   - Add a controller method (e.g., `@Post(\'jobs/cleanup-tokens\')`)\n   - Add `@UseGuards(SchedulerGuard)` from nest-common (validates requests come from the cloud scheduler)\n   - Add OpenAPI decorators as usual\n2. Deploy the service so the endpoint exists in cloud\n3. Add the job to `infrastructure.json` under the environment\'s `scheduledJobs` array:\n   ```json\n   {\n     "name": "cleanup-tokens",\n     "schedule": "0 */4 * * *",\n     "targetService": "auth-service",\n     "endpoint": "/auth/jobs/cleanup-tokens",\n     "method": "POST",\n     "httpTimeout": 300\n   }\n   ```\n4. `deploy_schedulers --env {env}` (or `deploy_scheduler --env {env} --scheduler cleanup-tokens`)\n\n**Important:** Services must be deployed before schedulers. Schedulers only make HTTPS calls — they don\'t run code or access databases directly.\n\n## "Change the database schema (Prisma)"\nPrisma commands are run directly — no framework wrapper locally.\n1. Edit `apps/{service}/prisma/schema.prisma`\n2. Run `cd apps/{service} && npx prisma migrate dev --name {migration-name}` — creates migration + applies to local DB\n3. Run `cd apps/{service} && npx prisma generate` — regenerates the Prisma client types\n4. Restart the service to pick up the new schema\n5. For cloud: `plan_db_migrate --service {name} --env {env}` → review → `run_db_migrate --service {name} --env {env}`\n\n**Note:** `npx prisma studio` (from the service directory) opens a visual data browser at http://localhost:5555.\n\n**Runtime:** nest-common provides `createPrismaConnection()` — a factory that creates a pg Pool + Prisma adapter with connection pooling. Services extend `PrismaClient` with this config. Don\'t create raw PrismaClient instances.\n\n## "Run database migrations in cloud"\n1. `plan_db_migrate --service {name} --env {env}` → preview pending migrations\n2. Review the output\n3. `run_db_migrate --service {name} --env {env}` → apply migrations\n\n## "Add a new shared package"\nShared packages live in `packages/`. User preference: scaffold with rslib, select what\'s needed.\n1. User creates the package in `packages/{name}/` (rslib scaffold or manual)\n2. Add to workspace in root `package.json`\n3. Other packages/apps import via `@tsdevstack/{name}`\n\n## "Set up CI/CD"\n1. `infra_init_ci --github` → generates `.github/workflows/` and `.tsdevstack/ci.json`\n2. User adds GitHub secrets in repo Settings > Secrets and variables > Actions:\n   - Secrets use **environment suffix** pattern (e.g., `GCP_WIF_DEV`, `GCP_WIF_PROD`)\n   - **GCP:** `GCP_WIF_{ENV}`, `GCP_SA_{ENV}`, `GCP_REGION_{ENV}`\n   - **AWS:** `AWS_ROLE_ARN_{ENV}`, `AWS_REGION_{ENV}`\n   - **Azure:** `AZURE_CLIENT_ID_{ENV}`, `AZURE_TENANT_ID_{ENV}`, `AZURE_SUBSCRIPTION_ID_{ENV}`, `AZURE_LOCATION_{ENV}`\n3. `cloud_secrets_push --env {env}` BEFORE first CI deploy (DOMAIN, RESEND_API_KEY, EMAIL_FROM + framework secrets)\n4. Workflows are triggered by users on GitHub Actions UI — nice env/service selection available\n5. PR workflow runs automatically on PRs against main (build, lint, tsc, test)\n6. To add a new environment: update `ci.json` environments array → `infra_generate_ci` → add GitHub secrets → push cloud secrets → deploy\n\n**CLI vs CI/CD:** Both can co-exist and either can manage everything independently. If a user wants CI-only deployments (no local CLI for cloud operations), they still need to set user secrets (DOMAIN, RESEND_API_KEY, EMAIL_FROM) manually via `cloud_secrets_set` with the correct naming — the CI workflow handles framework secrets but can\'t prompt for user values.\n\n## "Start local development"\n1. `npm install` (if fresh clone)\n2. `sync` → generates all config: secrets, docker-compose, kong config, env files, secret-map\n3. Tell user to run `npm run dev` — this starts Docker Compose (PostgreSQL, Redis, Kong, pgAdmin, Prometheus, Grafana, Jaeger, Redis Commander) + all services in parallel via Lerna\n\n### Local URLs\n| Service | URL | Purpose |\n|---------|-----|---------|\n| Frontend | http://localhost:3000 | Next.js application |\n| Kong Proxy | http://localhost:8000 | API gateway (all API calls go through here) |\n| Kong Admin | http://localhost:8001 | Gateway management API |\n| pgAdmin | http://localhost:5050 | Database management (login: admin@localhost.com / admin) |\n| Redis Commander | http://localhost:8081 | Redis data browser |\n| Prometheus | http://localhost:9090 | Metrics storage and queries |\n| Grafana | http://localhost:4001 | Dashboards (login: admin / admin) |\n| Jaeger | http://localhost:16686 | Distributed tracing UI |\n| Prisma Studio | http://localhost:5555 | Visual database editor (run `cd apps/{service} && npx prisma studio`) |\n\nBackend services run on their configured ports (3001, 3002, 3003, etc.) — access them through Kong at `:8000` for authenticated requests, or directly for health/metrics.\n\n### Email in local development\nLocally, `EMAIL_PROVIDER` defaults to `console` — emails are logged to the terminal with sender, recipient, subject, and body. No real emails are sent.\n\n**For the auth flow to work** (signup, password reset, email verification), watch the terminal output for the email log block containing the verification/reset link. Copy the link or token from there.\n\n### Key things to know\n- **Docker Compose is infrastructure**: PostgreSQL, Redis, Kong, monitoring — all started by `npm run dev`\n- **Services run natively**: NestJS and Next.js run via `nest start --watch` / `next dev` (hot reload)\n- **Secrets system**: Three-file merge (`.secrets.tsdevstack.json` + `.secrets.user.json` → `.secrets.local.json`). Edit `.secrets.user.json`, then `generate_secrets`\n- **pgAdmin has pre-configured databases** — all service databases appear in the sidebar, no setup needed\n- **Each service with a database** gets its own PostgreSQL container (separate ports: 5432, 5433, ...)\n\n### Common issues\n- **Port in use**: `lsof -i :{port}` to find the process\n- **Kong 502**: Service not running — check `docker compose ps`, then `sync` + restart\n- **Missing secrets**: Run `generate_secrets` to regenerate all config files\n\n## "Add a custom secret to a service"\n1. Edit `.secrets.user.json`:\n   - Add key + value to `"secrets"` object (top level)\n   - Add the key name to the target service\'s `"secrets"` array\n2. `generate_secrets` → regenerates merged `.secrets.local.json`\n3. Restart services (or they\'ll pick up on next restart)\n4. For cloud: `cloud_secrets_set KEY --value VALUE --env {env}` then `deploy_services --service {name}` to restart with new secret\n\n**Example** — adding STRIPE_KEY to offers-service:\n```json\n{\n  "secrets": {\n    "STRIPE_SECRET_KEY": "sk_test_..."\n  },\n  "offers-service": {\n    "secrets": ["STRIPE_SECRET_KEY"]\n  }\n}\n```\n\n## "Remove a service"\n1. `remove_service` for local removal (deletes files, updates config)\n2. For cloud removal: `remove_service_cloud --service {name} --env {env}` (deletes container, secrets, database — PERMANENT)\n\n## "Remove a detached worker"\n1. `unregister_detached_worker --worker {name}` → removes from config.json\n2. For cloud removal: `remove_detached_worker --env {env} --worker {name}` (deletes container — PERMANENT)';
+function registerGuideWorkflowsResource(server) {
+    server.resource('guide-workflows', 'tsdevstack://guide/workflows', {
+        description: 'Step-by-step workflow chains for common tasks: adding services, deploying, debugging secrets, setting up CI/CD, local development, and more.'
+    }, async (uri)=>({
+            contents: [
+                {
+                    uri: uri.href,
+                    text: WORKFLOWS_CONTENT,
+                    mimeType: 'text/markdown'
+                }
+            ]
+        }));
+}
+const NEST_COMMON_CONTENT = "# nest-common — Practical Notes\n\n**Full reference:** See the docs-site at `/packages/nest-common`\n\nThese notes supplement the docs-site with AI-agent-specific guidance.\n\n## Key rule: always import from nest-common\nNEVER install third-party packages for features nest-common already provides:\n- Authentication → `AuthModule` (not passport, not custom JWT)\n- Redis → `RedisModule` (not raw ioredis)\n- Logging → `ObservabilityModule` (not winston, not pino directly)\n- Metrics → `ObservabilityModule` (not prom-client directly)\n- Rate limiting → `RateLimitModule` (not express-rate-limit)\n- Background jobs → `BullConfigModule` (not raw bullmq setup)\n- Email → `NotificationModule` (not nodemailer, not resend directly)\n- Database pooling → `createPrismaConnection()` (not raw pg Pool)\n\n## NEVER use process.env\nAlways use `SecretsService` to read secrets. The secrets system handles provider detection (local/gcp/aws/azure), caching, and service-scoped access.\n\n## generateSwaggerDocs(AppModule)\nGenerates OpenAPI spec without starting the server. Used internally by CLI commands:\n- `generate_kong` reads the spec → generates Kong gateway routes\n- `generate_client` reads the spec → generates TypeScript HTTP client + DTOs\nNot typically called by user code, but important to know it exists — this is why OpenAPI decorators drive everything.";
+function registerGuideNestCommonResource(server) {
+    server.resource('guide-nest-common', 'tsdevstack://guide/nest-common', {
+        description: 'Shared library reference: all modules, decorators, bootstrap functions from nest-common, and when to use them.'
+    }, async (uri)=>({
+            contents: [
+                {
+                    uri: uri.href,
+                    text: NEST_COMMON_CONTENT,
+                    mimeType: 'text/markdown'
+                }
+            ]
+        }));
+}
+const CONFIG_CONTENT = '# tsdevstack Configuration Reference\n\n## `.tsdevstack/config.json`\nMain project configuration. Source of truth for services.\n\n**Managed by:** `add_service`, `remove_service`, `register_detached_worker`, `unregister_detached_worker`\n**Never edit directly** — use CLI commands.\n\nStructure:\n- `project` — name, version, description\n- `framework` — version, packageScope (@tsdevstack), template\n- `cloud.provider` — active cloud provider (gcp, aws, azure)\n- `services[]` — all services and workers:\n  - NestJS: `{ name, type: "nestjs", port, globalPrefix, hasDatabase?, databaseType? }`\n  - Next.js: `{ name, type: "nextjs", port, hasDatabase: false }`\n  - SPA: `{ name, type: "spa", port, hasDatabase: false }`\n  - Worker: `{ name, type: "worker", baseService: "parent-service-name" }`\n\n## `.tsdevstack/infrastructure.json`\nPer-environment infrastructure settings. **This is a user-created file** — NOT generated by the framework.\n\n**Created by:** The user (or AI when asked). Used by `infra:generate` and `infra:deploy`.\n**Never generated** — unlike config.json (managed by CLI commands), the user creates and edits this file directly.\n\n### How to create it\n```json\n{\n  "$schema": "./infrastructure.schema.json",\n  "version": "1.0.0",\n  "dev": {\n    "accessControl": { "protected": true, "noIndex": true },\n    "auth-service": { "minInstances": 0, "maxInstances": 5, "cpu": "1", "memory": "512Mi" },\n    "frontend": { "domain": "example.com", "minInstances": 0, "maxInstances": 5, "cpu": "1", "memory": "512Mi" },\n    "kong": { "minInstances": 0, "maxInstances": 5, "cpu": "1", "memory": "1Gi" },\n    "database": { "tier": "db-f1-micro", "deletionProtection": false },\n    "redis": { "memoryGb": 1, "tier": "BASIC" }\n  }\n}\n```\n\n**Key rules:**\n- `$schema` MUST reference `./infrastructure.schema.json` (for IDE autocomplete + validation)\n- `version` is always `"1.0.0"`\n- Top-level keys after version are environment names: `dev`, `staging`, `prod`\n- Within each env: named service overrides + `database`, `redis`, `kong`, `loadBalancer`, `accessControl`, `security`, `scheduledJobs`\n- Service names must match services in `config.json`\n\n### Valid values\nRead `infrastructure.schema.json` for the definitive list. Key values:\n- **CPU:** `"0.25"`, `"0.5"`, `"1"`, `"2"`, `"4"`, `"8"`\n- **Memory:** `"256Mi"`, `"512Mi"`, `"0.5Gi"`, `"1Gi"`, `"2Gi"`, `"4Gi"`, `"8Gi"`\n- **DB tier (GCP):** `"db-f1-micro"`, `"db-g1-small"`, `"db-n1-standard-1"`, `"db-n1-standard-2"`, `"db-n1-standard-4"`\n- **Redis tier (GCP):** `"BASIC"`, `"STANDARD_HA"`\n- Provider-specific values differ — check the schema or provider override files\n\n### Access control & security\n- **`accessControl.protected`** — Restricts access (e.g., IP allowlist). Common for non-prod environments to prevent public access.\n- **`accessControl.noIndex`** — Adds `X-Robots-Tag: noindex, nofollow` header to all responses. Use on non-prod to prevent search engine indexing.\n- **`security.waf.customRules`** — Custom Cloud Armor WAF rules for rate limiting, IP blocking, or traffic filtering. Each rule has a `name`, `priority` (use 800-899 for custom), `action` (`allow`, `deny(403)`, `deny(404)`, `deny(429)`, `throttle`), and a CEL `expression`. For `throttle` actions, add `rateLimit: { count, intervalSec }`. Read the schema for full options.\n\n### Provider-specific overrides\n`infrastructure.gcp.json`, `infrastructure.aws.json`, `infrastructure.azure.json` — same structure as `infrastructure.json` but provider-specific values (different DB tiers, Redis tiers, etc.). Base config is merged with provider config at deploy time.\n\n## `.tsdevstack/infrastructure.schema.json`\nJSON Schema defining all valid fields and values for `infrastructure.json`. **Generated by `infra:init`** — only exists after infrastructure initialization. The schema documents every field, enum value, min/max, and description. AI agents should read this for definitive valid values.\n\n## `.tsdevstack/secret-map.json`\nMaps secrets to services. Auto-generated by `generate-secrets`.\n\nShows which environment variables each service receives. Critical for debugging "service X doesn\'t have secret Y" issues.\n\n## `.tsdevstack/ci.json`\nCI/CD workflow configuration. Provider (github), environments to deploy.\n\n## `.tsdevstack/.credentials.{provider}.json` (gitignored)\nCloud provider credentials per environment. Created by `cloud:init`. Contains keys for dev/staging/prod environments.\n\n## `.secrets.user.json` (gitignored)\nUser-defined secrets and service assignments. This is the file users edit.\n\nStructure:\n- `secrets` — key-value pairs for custom secrets (DOMAIN, RESEND_API_KEY, etc.)\n- Per-service entries with `secrets` array listing which keys that service needs\n\n## `.secrets.tsdevstack.json` (gitignored, auto-generated)\nFramework-generated secrets. NEVER edit — regenerated by `generate-secrets`.\nContains JWT keys, database passwords, service API keys, service URLs.\n\n## `.secrets.local.json` (gitignored, auto-generated)\nMerged output of `.secrets.tsdevstack.json` + `.secrets.user.json`. Injected into Docker containers.\n\n## Generated Files (NEVER edit)\n| File | Generated by | Purpose |\n|------|-------------|---------|\n| `docker-compose.yml` | `generate_docker_compose` | Local development containers |\n| `kong.tsdevstack.yml` | `generate_kong` | Kong gateway routes (from OpenAPI specs) |\n| `.secrets.tsdevstack.json` | `generate_secrets` | Framework secrets |\n| `.secrets.local.json` | `generate_secrets` | Merged secrets for Docker |\n| `.secrets.user.example.json` | `generate_secrets` | Stripped copy of user secrets (empty values) — committed to git, acts like `.env.example` |\n| `infrastructure/terraform/{env}/` | `infra:generate` | Terraform configs |\n| `infrastructure/kong/{env}/` | `infra:generate-kong` | Cloud Kong config |\n\n## Override Files (edit these)\n| File | Merged with | Purpose |\n|------|-------------|---------|\n| `kong.user.yml` | `kong.tsdevstack.yml` | Custom Kong routes |\n| `docker-compose.user.yml` | `docker-compose.yml` | Custom Docker config |\n| `.secrets.user.json` | `.secrets.tsdevstack.json` | Your secrets and assignments |';
+function registerGuideConfigResource(server) {
+    server.resource('guide-config', 'tsdevstack://guide/config', {
+        description: 'Config files reference: every config file, its structure, how to extend it, and which CLI command manages it.'
+    }, async (uri)=>({
+            contents: [
+                {
+                    uri: uri.href,
+                    text: CONFIG_CONTENT,
+                    mimeType: 'text/markdown'
+                }
+            ]
+        }));
+}
+function registerResources(server) {
+    registerProjectStateResources(server);
+    registerSecretsContextResources(server);
+    registerKongRoutesResource(server);
+    registerGuideResource(server);
+    registerGuideWorkflowsResource(server);
+    registerGuideNestCommonResource(server);
+    registerGuideConfigResource(server);
+}
+function createServer() {
+    const server = new McpServer({
+        name: 'tsdevstack',
+        version: '1.0.0'
+    });
+    registerTools(server);
+    registerResources(server);
+    return server;
+}
+async function mcpServe() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function registerMcpPlugin(program) {
+    program.command('mcp:serve').description('Start MCP server for AI agent integration (stdio transport)').action(wrapCommand(async ()=>{
+        await mcpServe();
+    }));
+}
+export { initContext, registerMcpPlugin };