@wacht/bench 0.1.0 → 0.1.1

package/dist/commands.js

@@ -1,11 +1,24 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
+const PKG_VERSION = (() => {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 import { completionScript } from './completion.js';
 import { configApply, configDiff, configPull, configSchemaCommand, printConfigTemplate, } from './config-workflow.js';
 import { clearDeployment, createDeploymentCommand, createProjectCommand, currentDeployment, selectDeployment, } from './deployment-context.js';
 import { initProject, initStarter } from './init.js';
 import { apiCommand, listProjects } from './machine-api.js';
 import { openApiCall, openApiDescribe, openApiList, openApiRefresh } from './openapi.js';
-import { printMcpConfig } from './mcp.js';
+import { installMcp, listMcp, printMcpConfig, uninstallMcp } from './mcp.js';
 import { authStatus, login, logout } from './oauth.js';
 import { createOrg, createUser, createWorkspace, getOrg, getUser, getWorkspace, listOrgs, listUsers, listWorkspaces, } from './resources.js';
 import { installSkills } from './skills.js';
@@ -34,14 +47,8 @@ function initArgs(options) {
         args.push('--install-skills');
     if (options.skipAgents)
         args.push('--skip-agents');
-    if (options.skipConfig)
-        args.push('--skip-config');
     if (options.skipEnv)
         args.push('--skip-env');
-    if (options.skipGuide)
-        args.push('--skip-guide');
-    if (options.skipTemplates)
-        args.push('--skip-templates');
     return args;
 }
 export async function runCli(args) {
@@ -49,6 +56,7 @@ export async function runCli(args) {
     program
         .name('wacht')
         .description('AI development workbench for Wacht')
+        .version(PKG_VERSION, '-v, --version', 'print Wacht Bench CLI version')
         .showHelpAfterError()
         .option('--json', 'emit machine-readable JSON where supported')
         .option('--quiet', 'suppress nonessential human output')
@@ -69,10 +77,7 @@ export async function runCli(args) {
         .option('--target <dir>', 'target directory when using --starter (defaults to ./wacht-<framework>-starter)')
         .option('--install-skills', 'run npx skills add after writing config')
         .option('--skip-agents', 'do not create or update AGENTS.md')
-        .option('--skip-config', 'do not write .wacht/bench.json')
         .option('--skip-env', 'do not write .env.wacht.example')
-        .option('--skip-guide', 'do not write .wacht/BOOTSTRAP.md')
-        .option('--skip-templates', 'do not write starter templates under .wacht/templates')
         .action(async (options) => {
         const ctx = context(program);
         if (options.starter) {
@@ -168,11 +173,36 @@ export async function runCli(args) {
         .action(async (options) => {
         await installSkills(options.skill);
     });
-    const mcp = program.command('mcp').description('print Wacht Docs MCP configuration');
+    const mcp = program.command('mcp').description('configure Wacht Docs MCP across AI clients');
+    mcp
+        .command('list')
+        .alias('ls')
+        .description('list known MCP clients with detection + install status')
+        .action(async () => {
+        await listMcp(context(program));
+    });
+    mcp
+        .command('install')
+        .description('install Wacht Docs MCP into one or more clients (interactive by default)')
+        .option('--client <ids>', 'comma-separated target ids; skips the picker', (value) => value.split(',').map((s) => s.trim()).filter(Boolean))
+        .option('--all', 'install into every known target without prompting')
+        .option('--yes', 'do not ask to confirm before writing')
+        .action(async (options) => {
+        await installMcp(context(program), { clients: options.client, all: options.all, yes: options.yes });
+    });
+    mcp
+        .command('uninstall')
+        .description('remove Wacht Docs MCP from one or more clients')
+        .option('--client <ids>', 'comma-separated target ids; skips the picker', (value) => value.split(',').map((s) => s.trim()).filter(Boolean))
+        .option('--all', 'remove from every known target without prompting')
+        .option('--yes', 'do not ask to confirm before writing')
+        .action(async (options) => {
+        await uninstallMcp(context(program), { clients: options.client, all: options.all, yes: options.yes });
+    });
     mcp
         .command('config')
-        .description('print MCP config JSON for an assistant client')
-        .option('--client <client>', 'cursor, claude, or codex', 'cursor')
+        .description('print raw MCP config JSON for a client (no file write)')
+        .option('--client <client>', 'claude-desktop, cursor, vscode, codex, windsurf, claude-code', 'cursor')
         .action((options) => {
         printMcpConfig(options.client);
     });

package/dist/init.js

@@ -1,8 +1,7 @@
 import { spawn } from 'node:child_process';
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { MACHINE_API_URL, MCP_URL, OAUTH_CLIENT_ID, OAUTH_ISSUER, OAUTH_SCOPES, REDIRECT_URI, SKILLS_SOURCE, PLATFORM_OPENAPI_URL, } from './config.js';
-import { readBenchContext } from './context-store.js';
+import { MCP_URL } from './config.js';
 import { detectProject } from './project-detect.js';
 import { installSkills } from './skills.js';
 import { command, field, log, printBannerFor, printJson, section, success } from './ui.js';
@@ -20,10 +19,7 @@ export function parseInitOptions(args) {
         client: valueAfter(args, '--client') ?? 'cursor',
         installSkills: hasFlag(args, '--install-skills'),
         skipAgents: hasFlag(args, '--skip-agents'),
-        skipConfig: hasFlag(args, '--skip-config'),
         skipEnv: hasFlag(args, '--skip-env'),
-        skipGuide: hasFlag(args, '--skip-guide'),
-        skipTemplates: hasFlag(args, '--skip-templates'),
     };
 }
 async function readOptional(filePath) {
@@ -47,8 +43,17 @@ This project is configured for AI-assisted Wacht development.
 - Detected project shape: \`${frameworks}\`.
 - Suggested Wacht skills for this project: \`${skills}\`.
 - Active skill router: \`wacht\` (always start there). For CLI work specifically, use the \`wacht-bench-cli\` skill.
-- Before coding Wacht behavior, consult Wacht Docs MCP at \`${MCP_URL}\`.
-- Install or update skills with \`npx skills add ${SKILLS_SOURCE}\`.
+- Install or update skills with \`wacht skills add\`.
+
+### Where to look (single source of truth)
+
+| Need | Source |
+| --- | --- |
+| Framework wiring patterns (provider, middleware, loaders) | Skills: \`${skills}\`. Always load before editing SDK code — never freelance the wiring. |
+| Endpoint contracts, request/response shapes, errors | Wacht Docs MCP at \`${MCP_URL}\`. Required before calling any Machine API operation by hand. |
+| Live deployment context (project id, deployment id, hosts) | \`wacht deployments current\` — re-run every time, never cache. |
+| Available CLI surface | \`wacht --help\` and \`wacht <command> --help\`. |
+| Any Machine API operation by name | \`wacht api ls --search <text>\` → \`wacht api describe <op>\` → \`wacht api call <op>\`. |
 
 ### Default CLI workflow
 
@@ -59,9 +64,14 @@ This project is configured for AI-assisted Wacht development.
 | Manage users | \`wacht users list\` · \`wacht users get <id>\` · \`wacht users create --field …\` |
 | Manage orgs / workspaces | \`wacht orgs list\` · \`wacht workspaces list --org <id>\` |
 | Pull / diff / apply config | \`wacht config pull\` · \`wacht config diff\` · \`wacht config apply --yes\` |
-| Discover any Machine API operation | \`wacht api ls --search <text>\` · \`wacht api describe <op>\` · \`wacht api call <op>\` |
+| Configure Docs MCP across clients | \`wacht mcp install\` (interactive picker) · \`wacht mcp list\` |
 
-Always pass \`--json\` and \`--no-interactive\` when running commands inside an agent loop. Confirm the active deployment with \`wacht deployments current\` before any deployment-scoped change. Production config applies require \`--production --confirm <deployment_id> --yes\`.
+### Rules for agent loops
+
+- Pass \`--json --no-interactive\` to every CLI invocation inside an agent loop.
+- Confirm the active deployment with \`wacht deployments current\` before any deployment-scoped change.
+- Production config applies require \`--production --confirm <deployment_id> --yes\` — never bypass.
+- Do not write on-disk snapshots of deployment state; query it live.
 
 ${AGENTS_END}`;
 }
@@ -85,325 +95,28 @@ async function upsertAgentsBlock(root, profile) {
     await writeFile(agentsPath, `${existing.trimEnd()}\n\n${nextBlock}\n`, 'utf8');
     return agentsPath;
 }
-async function writeBenchConfig(root, profile, options) {
-    const wachtDir = path.join(root, '.wacht');
-    await mkdir(wachtDir, { recursive: true });
-    const configPath = path.join(wachtDir, 'bench.json');
-    const config = {
-        version: 1,
-        client: options.client,
-        skillsSource: SKILLS_SOURCE,
-        docsMcpUrl: MCP_URL,
-        machineApiUrl: MACHINE_API_URL,
-        openApiUrl: PLATFORM_OPENAPI_URL,
-        oauth: {
-            issuer: OAUTH_ISSUER,
-            clientId: OAUTH_CLIENT_ID,
-            redirectUri: REDIRECT_URI,
-            scopes: OAUTH_SCOPES.split(' '),
-        },
-        project: {
-            packageManager: profile.packageManager,
-            frameworks: profile.frameworks,
-            suggestedSkills: profile.suggestedSkills,
-        },
-    };
-    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-    return configPath;
-}
-function frameworkChecklist(profile) {
-    const frameworks = new Set(profile.frameworks);
-    if (frameworks.has('Next.js')) {
-        return [
-            'Review `.wacht/templates/nextjs/wacht-provider.tsx` as a provider reference only.',
-            'Review `.wacht/templates/nextjs/middleware.ts` as a protected-route reference only.',
-            'Use `wacht-nextjs-patterns` and Wacht Docs MCP before making app edits.',
-            'Let the assistant adapt the template to the existing layout, route groups, and Next.js version.',
-            'Keep publishable/frontend values separate from server-only secrets.',
-        ];
-    }
-    if (frameworks.has('React Router')) {
-        return [
-            'Review `.wacht/templates/react-router/wacht-provider.tsx` as a provider reference only.',
-            'Review `.wacht/templates/react-router/protected-loader.ts` as a loader/action reference only.',
-            'Use `wacht-react-router-patterns` and Wacht Docs MCP before making app edits.',
-            'Let the assistant adapt the template to the existing root route and data APIs.',
-        ];
-    }
-    if (frameworks.has('TanStack Router')) {
-        return [
-            'Review `.wacht/templates/tanstack-router/wacht-provider.tsx` as a provider reference only.',
-            'Review `.wacht/templates/tanstack-router/protected-request.ts` as a request-auth reference only.',
-            'Use `wacht-tanstack-router-patterns` and Wacht Docs MCP before making app edits.',
-            'Let the assistant adapt the template to the existing router context and route tree.',
-        ];
-    }
-    return [
-        'Review `.wacht/templates/wacht-contract.ts` for deployment/env assumptions.',
-        'Select an active deployment with `wacht deployments select`.',
-        'Use Wacht Docs MCP and the suggested skills before choosing framework-specific app edits.',
-    ];
-}
-async function writeEnvTemplate(root) {
-    const context = await readBenchContext();
+async function writeEnvTemplate(root, profile) {
     const envPath = path.join(root, '.env.wacht.example');
+    const frameworks = new Set(profile.frameworks);
+    const isVite = frameworks.has('React Router') || frameworks.has('TanStack Router');
+    const publishableKeyVar = frameworks.has('Next.js')
+        ? 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY'
+        : isVite
+            ? 'VITE_WACHT_PUBLISHABLE_KEY'
+            : 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY';
     const lines = [
-        '# Generated by Wacht Bench. Copy values into your local env file as needed.',
-        `WACHT_MACHINE_API_URL=${MACHINE_API_URL}`,
-        `WACHT_OPENAPI_URL=${PLATFORM_OPENAPI_URL}`,
-        `WACHT_PROJECT_ID=${context?.project_id ?? ''}`,
-        `WACHT_DEPLOYMENT_ID=${context?.deployment_id ?? ''}`,
-        `WACHT_DEPLOYMENT_MODE=${context?.deployment_mode ?? ''}`,
-        `WACHT_BACKEND_HOST=${context?.deployment_backend_host ?? ''}`,
-        `WACHT_FRONTEND_HOST=${context?.deployment_frontend_host ?? ''}`,
+        '# Wacht SDK environment. Fill these from your Wacht deployment.',
         '',
-        '# Framework SDK keys. Fill the publishable key from your Wacht deployment.',
-        'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY=',
-        'VITE_WACHT_PUBLISHABLE_KEY=',
+        '# Client-safe publishable key. Encodes deployment + frontend host.',
+        `${publishableKeyVar}=`,
+        '',
+        '# Server-only API key for backend SDK calls. Never expose to the client.',
         'WACHT_API_KEY=',
         '',
     ];
     await writeFile(envPath, lines.join('\n'), 'utf8');
     return envPath;
 }
-async function writeBootstrapGuide(root, profile) {
-    const guidePath = path.join(root, '.wacht', 'BOOTSTRAP.md');
-    await mkdir(path.dirname(guidePath), { recursive: true });
-    const context = await readBenchContext();
-    const checklist = frameworkChecklist(profile).map((item) => `- ${item}`).join('\n');
-    const active = context
-        ? `- Active project: ${context.project_name} (${context.project_id})
-- Active deployment: ${context.deployment_mode} (${context.deployment_id})
-- Backend host: ${context.deployment_backend_host ?? ''}
-- Frontend host: ${context.deployment_frontend_host ?? ''}`
-        : '- No active deployment selected. Run `wacht deployments select`.';
-    const content = `# Wacht Bootstrap
-
-## Project
-
-- Detected frameworks: ${profile.frameworks.length ? profile.frameworks.join(', ') : 'unknown'}
-- Package manager: ${profile.packageManager}
-- Suggested skills: ${profile.suggestedSkills.join(', ')}
-
-## Active Deployment
-
-${active}
-
-## Checklist
-
-${checklist}
-
-## Templates
-
-Bench writes framework starter templates under \`.wacht/templates\`. These files are not integrated into the app automatically. Use the suggested Wacht skills and Docs MCP to adapt them to the existing project structure.
-
-## Useful Commands
-
-\`\`\`bash
-npx skills add ${SKILLS_SOURCE}
-wacht login
-wacht deployments select
-wacht deployments current
-wacht api ls --search users
-wacht api describe createUser
-wacht api call createUser --body '{"email_address":"person@example.com"}'
-\`\`\`
-
-## API Discovery
-
-Bench reads the Wacht Platform OpenAPI schema from:
-
-\`\`\`text
-${PLATFORM_OPENAPI_URL}
-\`\`\`
-
-Schema cache TTL is 24 hours. Refresh it with:
-
-\`\`\`bash
-wacht api schema refresh
-\`\`\`
-`;
-    await writeFile(guidePath, content, 'utf8');
-    return guidePath;
-}
-function nextProviderTemplate() {
-    return `'use client';
-
-/**
- * Template only. Bench does not import this file or patch your layout.
- * Adapt it with the wacht-nextjs-patterns skill after checking Docs MCP.
- */
-
-import type { ReactNode } from 'react';
-import { DeploymentInitialized, DeploymentProvider } from '@wacht/nextjs';
-
-export function WachtProvider({ children }: { children: ReactNode }) {
-  return (
-    <DeploymentProvider publicKey={process.env.NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY!}>
-      <DeploymentInitialized>{children}</DeploymentInitialized>
-    </DeploymentProvider>
-  );
-}
-`;
-}
-function nextMiddlewareTemplate() {
-    return `/**
- * Template only. Bench does not install this file into the app.
- * For Next.js 16, adapt this into proxy.ts. For older Next.js, adapt into middleware.ts.
- */
-
-import { NextResponse } from 'next/server';
-import { createRouteMatcher, wachtMiddleware } from '@wacht/nextjs/server';
-
-const isProtected = createRouteMatcher(['/account(.*)', '/dashboard(.*)']);
-
-export default wachtMiddleware(
-  async (auth, req) => {
-    if (!isProtected(req)) return NextResponse.next();
-    await auth.protect();
-    return NextResponse.next();
-  },
-  { apiRoutePrefixes: ['/api', '/trpc'] },
-);
-
-export const config = {
-  matcher: [
-    '/((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
-    '/(api|trpc)(.*)',
-  ],
-};
-`;
-}
-function reactProviderTemplate(adapterImport) {
-    return `/**
- * Template only. Bench does not import this file or patch your route root.
- * Adapt it with the framework skill after checking Docs MCP.
- */
-
-import type { ReactNode } from 'react';
-import { DeploymentProvider } from '${adapterImport}';
-
-export function WachtDeploymentProvider({ children }: { children: ReactNode }) {
-  return (
-    <DeploymentProvider publicKey={import.meta.env.VITE_WACHT_PUBLISHABLE_KEY}>
-      {children}
-    </DeploymentProvider>
-  );
-}
-`;
-}
-function reactRouterMiddlewareTemplate() {
-    return `/**
- * Template only. Bench does not attach this loader to any route.
- * Adapt it with the wacht-react-router-patterns skill after checking Docs MCP.
- */
-
-import { redirect, type LoaderFunctionArgs } from 'react-router';
-import { authenticateRequest } from '@wacht/react-router/server';
-
-export async function protectedLoader({ request }: LoaderFunctionArgs) {
-  const result = await authenticateRequest(request);
-
-  if (!result.auth.isAuthenticated) {
-    throw redirect('/sign-in', { headers: result.headers });
-  }
-
-  return Response.json({ userId: result.auth.userId }, { headers: result.headers });
-}
-`;
-}
-function tanstackMiddlewareTemplate() {
-    return `/**
- * Template only. Bench does not attach this helper to any route.
- * Adapt it with the wacht-tanstack-router-patterns skill after checking Docs MCP.
- */
-
-import { authenticateRequest } from '@wacht/tanstack-router/server';
-
-export async function getProtectedUserId(request: Request) {
-  const result = await authenticateRequest(request);
-
-  if (!result.auth.isAuthenticated) {
-    throw new Response(null, {
-      status: 302,
-      headers: {
-        ...Object.fromEntries(result.headers.entries()),
-        Location: '/sign-in',
-      },
-    });
-  }
-
-  return result.auth.userId;
-}
-`;
-}
-function contractWrapperTemplate(profile) {
-    const framework = profile.frameworks[0] ?? 'unknown';
-    return `/**
- * Wacht contract wrapper template.
- *
- * This file is generated for AI-assisted development. It is not imported
- * anywhere by Bench. Move/adapt it into a server-only module after reading
- * the active Wacht skill and Wacht Docs MCP pages for this framework.
- */
-
-export type WachtRuntimeContract = {
-  framework: string;
-  deploymentId: string;
-  deploymentMode: string;
-  backendHost: string;
-  frontendHost: string;
-  openApiUrl: string;
-};
-
-export function readWachtRuntimeContract(env: Record<string, string | undefined> = process.env): WachtRuntimeContract {
-  return {
-    framework: '${framework}',
-    deploymentId: env.WACHT_DEPLOYMENT_ID ?? '',
-    deploymentMode: env.WACHT_DEPLOYMENT_MODE ?? '',
-    backendHost: env.WACHT_BACKEND_HOST ?? '',
-    frontendHost: env.WACHT_FRONTEND_HOST ?? '',
-    openApiUrl: env.WACHT_OPENAPI_URL ?? '${PLATFORM_OPENAPI_URL}',
-  };
-}
-
-export function assertWachtRuntimeContract(contract = readWachtRuntimeContract()): WachtRuntimeContract {
-  const missing = Object.entries(contract)
-    .filter(([key, value]) => key !== 'framework' && key !== 'openApiUrl' && !value)
-    .map(([key]) => key);
-
-  if (missing.length) {
-    throw new Error(\`Missing Wacht runtime config: \${missing.join(', ')}\`);
-  }
-
-  return contract;
-}
-`;
-}
-async function writeTemplate(root, relativePath, content) {
-    const filePath = path.join(root, relativePath);
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, content, 'utf8');
-    return filePath;
-}
-async function writeStarterTemplates(root, profile) {
-    const frameworks = new Set(profile.frameworks);
-    const written = [];
-    if (frameworks.has('Next.js')) {
-        written.push(await writeTemplate(root, '.wacht/templates/nextjs/wacht-provider.tsx', nextProviderTemplate()));
-        written.push(await writeTemplate(root, '.wacht/templates/nextjs/middleware.ts', nextMiddlewareTemplate()));
-    }
-    else if (frameworks.has('React Router')) {
-        written.push(await writeTemplate(root, '.wacht/templates/react-router/wacht-provider.tsx', reactProviderTemplate('@wacht/react-router')));
-        written.push(await writeTemplate(root, '.wacht/templates/react-router/protected-loader.ts', reactRouterMiddlewareTemplate()));
-    }
-    else if (frameworks.has('TanStack Router')) {
-        written.push(await writeTemplate(root, '.wacht/templates/tanstack-router/wacht-provider.tsx', reactProviderTemplate('@wacht/tanstack-router')));
-        written.push(await writeTemplate(root, '.wacht/templates/tanstack-router/protected-request.ts', tanstackMiddlewareTemplate()));
-    }
-    written.push(await writeTemplate(root, '.wacht/templates/wacht-contract.ts', contractWrapperTemplate(profile)));
-    return written;
-}
 export async function initProject(args, ctx) {
     const options = parseInitOptions(args);
     const root = process.cwd();
@@ -415,17 +128,8 @@ export async function initProject(args, ctx) {
     log(ctx, field('Detected', profile.frameworks.length ? profile.frameworks.join(', ') : 'unknown project shape'));
     log(ctx, field('Suggested skills', profile.suggestedSkills.join(', ')));
     log(ctx, '');
-    if (!options.skipConfig) {
-        written.push(await writeBenchConfig(root, profile, options));
-    }
     if (!options.skipEnv) {
-        written.push(await writeEnvTemplate(root));
-    }
-    if (!options.skipGuide) {
-        written.push(await writeBootstrapGuide(root, profile));
-    }
-    if (!options.skipTemplates) {
-        written.push(...await writeStarterTemplates(root, profile));
+        written.push(await writeEnvTemplate(root, profile));
     }
     if (!options.skipAgents) {
         written.push(await upsertAgentsBlock(root, profile));
@@ -440,7 +144,7 @@ export async function initProject(args, ctx) {
     }
     else {
         log(ctx, '');
-        log(ctx, field('Skills', `run ${command(`npx skills add ${SKILLS_SOURCE}`)} when you want to install/update the pack`));
+        log(ctx, field('Skills', `run ${command('wacht skills add')} when you want to install/update the pack`));
     }
     if (ctx.json) {
         printJson({

package/dist/mcp-clients.js

@@ -0,0 +1,225 @@
+import { readFile, stat, mkdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { MCP_URL } from './config.js';
+export const SERVER_NAME = 'wacht-docs';
+const HOME = os.homedir();
+const PLATFORM = process.platform;
+function fileExists(p) {
+    return stat(p).then(() => true).catch(() => false);
+}
+async function looksLikeProjectRoot() {
+    const cwd = process.cwd();
+    for (const marker of ['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.git']) {
+        if (await fileExists(path.join(cwd, marker)))
+            return true;
+    }
+    return false;
+}
+function claudeDesktopPath() {
+    if (PLATFORM === 'darwin') {
+        return path.join(HOME, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    if (PLATFORM === 'win32') {
+        return path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+    }
+    return path.join(process.env.XDG_CONFIG_HOME ?? path.join(HOME, '.config'), 'Claude', 'claude_desktop_config.json');
+}
+function vscodeUserDir() {
+    if (PLATFORM === 'darwin')
+        return path.join(HOME, 'Library', 'Application Support', 'Code', 'User');
+    if (PLATFORM === 'win32')
+        return path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code', 'User');
+    return path.join(process.env.XDG_CONFIG_HOME ?? path.join(HOME, '.config'), 'Code', 'User');
+}
+export async function listTargets() {
+    const cwd = process.cwd();
+    const inProject = await looksLikeProjectRoot();
+    const targets = [
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            scope: 'user',
+            client: 'claude-desktop',
+            configPath: claudeDesktopPath(),
+            format: 'json-mcpServers',
+            detect: async () => fileExists(path.dirname(claudeDesktopPath())),
+        },
+        {
+            id: 'claude-code-user',
+            label: 'Claude Code (user)',
+            scope: 'user',
+            client: 'claude-code',
+            configPath: path.join(HOME, '.claude.json'),
+            format: 'json-mcpServers',
+            detect: async () => (await fileExists(path.join(HOME, '.claude.json'))) || (await fileExists(path.join(HOME, '.claude'))),
+        },
+        {
+            id: 'cursor-user',
+            label: 'Cursor (user)',
+            scope: 'user',
+            client: 'cursor',
+            configPath: path.join(HOME, '.cursor', 'mcp.json'),
+            format: 'json-mcpServers',
+            detect: async () => fileExists(path.join(HOME, '.cursor')),
+        },
+        {
+            id: 'vscode-user',
+            label: 'VS Code (user)',
+            scope: 'user',
+            client: 'vscode',
+            configPath: path.join(vscodeUserDir(), 'mcp.json'),
+            format: 'json-vscode',
+            detect: async () => fileExists(vscodeUserDir()),
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf',
+            scope: 'user',
+            client: 'windsurf',
+            configPath: path.join(HOME, '.codeium', 'windsurf', 'mcp_config.json'),
+            format: 'json-mcpServers',
+            detect: async () => fileExists(path.join(HOME, '.codeium', 'windsurf')),
+        },
+        {
+            id: 'codex',
+            label: 'Codex CLI (OpenAI)',
+            scope: 'user',
+            client: 'codex',
+            configPath: path.join(HOME, '.codex', 'config.toml'),
+            format: 'toml-codex',
+            detect: async () => fileExists(path.join(HOME, '.codex')),
+        },
+    ];
+    if (inProject) {
+        targets.push({
+            id: 'claude-code-project',
+            label: 'Claude Code (project)',
+            scope: 'project',
+            client: 'claude-code',
+            configPath: path.join(cwd, '.mcp.json'),
+            format: 'json-mcpServers',
+            detect: async () => fileExists(path.join(cwd, '.mcp.json')),
+        }, {
+            id: 'cursor-project',
+            label: 'Cursor (project)',
+            scope: 'project',
+            client: 'cursor',
+            configPath: path.join(cwd, '.cursor', 'mcp.json'),
+            format: 'json-mcpServers',
+            detect: async () => fileExists(path.join(cwd, '.cursor')),
+        }, {
+            id: 'vscode-project',
+            label: 'VS Code (project)',
+            scope: 'project',
+            client: 'vscode',
+            configPath: path.join(cwd, '.vscode', 'mcp.json'),
+            format: 'json-vscode',
+            detect: async () => fileExists(path.join(cwd, '.vscode')),
+        });
+    }
+    return targets;
+}
+export async function findTarget(id) {
+    const targets = await listTargets();
+    return targets.find((t) => t.id === id);
+}
+// ─── JSON helpers ─────────────────────────────────────────────────────
+function stripJsonComments(text) {
+    // Remove /* ... */ and // line comments, plus trailing commas before } or ].
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^:])\/\/.*$/gm, '$1')
+        .replace(/,(\s*[}\]])/g, '$1');
+}
+async function readJson(filePath) {
+    const raw = await readFile(filePath, 'utf8').catch(() => '');
+    if (!raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return JSON.parse(stripJsonComments(raw));
+    }
+}
+async function writeJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+function stdioServer() {
+    return { command: 'npx', args: ['-y', 'mcp-remote', MCP_URL] };
+}
+// ─── Per-format readers/writers ───────────────────────────────────────
+async function applyMcpServersJson(target, action) {
+    const config = await readJson(target.configPath);
+    const servers = config.mcpServers ?? {};
+    if (action === 'install') {
+        // Claude Desktop is stdio-only; Claude Code/Cursor/Windsurf accept HTTP url.
+        servers[SERVER_NAME] = target.client === 'claude-desktop'
+            ? stdioServer()
+            : { url: MCP_URL };
+    }
+    else {
+        delete servers[SERVER_NAME];
+    }
+    config.mcpServers = servers;
+    await writeJson(target.configPath, config);
+}
+async function applyVscodeJson(target, action) {
+    const config = await readJson(target.configPath);
+    const servers = config.servers ?? {};
+    if (action === 'install') {
+        servers[SERVER_NAME] = { type: 'http', url: MCP_URL };
+    }
+    else {
+        delete servers[SERVER_NAME];
+    }
+    config.servers = servers;
+    await writeJson(target.configPath, config);
+}
+async function applyCodexToml(target, action) {
+    const existing = await readFile(target.configPath, 'utf8').catch(() => '');
+    const sectionHeader = `[mcp_servers.${SERVER_NAME}]`;
+    const blockRegex = new RegExp(`(^|\\n)\\[mcp_servers\\.${SERVER_NAME}\\][\\s\\S]*?(?=\\n\\[|$)`, 'm');
+    let next = existing.replace(blockRegex, '').replace(/\n{3,}/g, '\n\n').trimEnd();
+    if (action === 'install') {
+        const block = [
+            sectionHeader,
+            `command = "npx"`,
+            `args = ["-y", "mcp-remote", "${MCP_URL}"]`,
+        ].join('\n');
+        next = next ? `${next}\n\n${block}\n` : `${block}\n`;
+    }
+    else if (next) {
+        next = `${next}\n`;
+    }
+    await mkdir(path.dirname(target.configPath), { recursive: true });
+    await writeFile(target.configPath, next, 'utf8');
+}
+export async function applyTarget(target, action) {
+    switch (target.format) {
+        case 'json-mcpServers':
+            return applyMcpServersJson(target, action);
+        case 'json-vscode':
+            return applyVscodeJson(target, action);
+        case 'toml-codex':
+            return applyCodexToml(target, action);
+    }
+}
+export async function isInstalled(target) {
+    const exists = await fileExists(target.configPath);
+    if (!exists)
+        return false;
+    if (target.format === 'toml-codex') {
+        const raw = await readFile(target.configPath, 'utf8').catch(() => '');
+        return raw.includes(`[mcp_servers.${SERVER_NAME}]`);
+    }
+    const config = await readJson(target.configPath);
+    if (target.format === 'json-vscode') {
+        const servers = config.servers;
+        return !!servers?.[SERVER_NAME];
+    }
+    const servers = config.mcpServers;
+    return !!servers?.[SERVER_NAME];
+}

package/dist/mcp.js

@@ -1,9 +1,12 @@
 import { MCP_URL } from './config.js';
+import { applyTarget, isInstalled, listTargets, SERVER_NAME } from './mcp-clients.js';
+import { promptConfirm, promptMultiSelect } from './prompts.js';
+import { field, log, printJson, section, success, warning } from './ui.js';
 export function printMcpConfig(client) {
-    if (client === 'claude') {
+    if (client === 'claude' || client === 'claude-desktop') {
         console.log(JSON.stringify({
             mcpServers: {
-                'wacht-docs': {
+                [SERVER_NAME]: {
                     command: 'npx',
                     args: ['-y', 'mcp-remote', MCP_URL],
                 },
@@ -11,11 +14,131 @@ export function printMcpConfig(client) {
         }, null, 2));
         return;
     }
+    if (client === 'vscode') {
+        console.log(JSON.stringify({
+            servers: { [SERVER_NAME]: { type: 'http', url: MCP_URL } },
+        }, null, 2));
+        return;
+    }
+    if (client === 'codex') {
+        console.log(`[mcp_servers.${SERVER_NAME}]\ncommand = "npx"\nargs = ["-y", "mcp-remote", "${MCP_URL}"]`);
+        return;
+    }
     console.log(JSON.stringify({
-        mcpServers: {
-            'wacht-docs': {
-                url: MCP_URL,
-            },
-        },
+        mcpServers: { [SERVER_NAME]: { url: MCP_URL } },
     }, null, 2));
 }
+function homeRelative(filePath) {
+    const home = process.env.HOME ?? '';
+    if (home && filePath.startsWith(home))
+        return `~${filePath.slice(home.length)}`;
+    return filePath;
+}
+async function selectTargets(ctx, options, action) {
+    const all = await listTargets();
+    if (options.clients && options.clients.length) {
+        const ids = new Set(options.clients);
+        const matched = all.filter((t) => ids.has(t.id));
+        const missing = [...ids].filter((id) => !matched.find((t) => t.id === id));
+        if (missing.length) {
+            throw new Error(`Unknown client targets: ${missing.join(', ')}. Run \`wacht mcp list\` to see valid ids.`);
+        }
+        return matched;
+    }
+    if (options.all)
+        return all;
+    // Detect + multi-select.
+    const detection = await Promise.all(all.map(async (t) => ({ target: t, detected: await t.detect() })));
+    const items = detection.map(({ target, detected }) => ({
+        value: target.id,
+        label: target.label,
+        hint: detected ? `detected · ${homeRelative(target.configPath)}` : `not detected · ${homeRelative(target.configPath)}`,
+        preselected: detected,
+    }));
+    log(ctx, section(action === 'install' ? 'Install Wacht Docs MCP' : 'Remove Wacht Docs MCP'));
+    log(ctx, field('Server URL', MCP_URL));
+    log(ctx, '');
+    const ids = await promptMultiSelect(ctx, items, action === 'install' ? 'Install to which clients?' : 'Remove from which clients?');
+    return all.filter((t) => ids.includes(t.id));
+}
+export async function installMcp(ctx, options) {
+    const targets = await selectTargets(ctx, options, 'install');
+    if (!targets.length) {
+        log(ctx, warning('No MCP clients selected. Nothing to do.'));
+        if (ctx.json)
+            printJson({ ok: true, written: [] });
+        return;
+    }
+    if (!options.yes && !options.clients && ctx.interactive) {
+        log(ctx, '');
+        log(ctx, 'Will write to:');
+        for (const target of targets) {
+            log(ctx, `  - ${target.label}  ${homeRelative(target.configPath)}`);
+        }
+        const ok = await promptConfirm(ctx, 'Proceed?', true);
+        if (!ok) {
+            log(ctx, warning('Aborted.'));
+            return;
+        }
+    }
+    const written = [];
+    for (const target of targets) {
+        await applyTarget(target, 'install');
+        written.push({ id: target.id, path: target.configPath });
+        log(ctx, field('Wrote', `${target.label} · ${homeRelative(target.configPath)}`));
+    }
+    if (ctx.json) {
+        printJson({ ok: true, server: SERVER_NAME, url: MCP_URL, written });
+        return;
+    }
+    log(ctx, '');
+    log(ctx, success(`Installed Wacht Docs MCP into ${written.length} client${written.length === 1 ? '' : 's'}.`));
+    log(ctx, 'Restart the affected clients for the change to take effect.');
+}
+export async function uninstallMcp(ctx, options) {
+    const targets = await selectTargets(ctx, options, 'remove');
+    if (!targets.length) {
+        log(ctx, warning('No MCP clients selected. Nothing to do.'));
+        if (ctx.json)
+            printJson({ ok: true, removed: [] });
+        return;
+    }
+    const removed = [];
+    for (const target of targets) {
+        await applyTarget(target, 'remove');
+        removed.push({ id: target.id, path: target.configPath });
+        log(ctx, field('Updated', `${target.label} · ${homeRelative(target.configPath)}`));
+    }
+    if (ctx.json) {
+        printJson({ ok: true, server: SERVER_NAME, removed });
+        return;
+    }
+    log(ctx, '');
+    log(ctx, success(`Removed Wacht Docs MCP from ${removed.length} client${removed.length === 1 ? '' : 's'}.`));
+}
+export async function listMcp(ctx) {
+    const all = await listTargets();
+    const rows = await Promise.all(all.map(async (target) => ({
+        id: target.id,
+        label: target.label,
+        scope: target.scope,
+        configPath: target.configPath,
+        detected: await target.detect(),
+        installed: await isInstalled(target),
+    })));
+    if (ctx.json) {
+        printJson({ server: SERVER_NAME, url: MCP_URL, targets: rows });
+        return;
+    }
+    log(ctx, section('MCP client targets'));
+    log(ctx, field('Server URL', MCP_URL));
+    log(ctx, '');
+    for (const row of rows) {
+        const detect = row.detected ? 'detected' : 'not detected';
+        const status = row.installed ? 'installed' : 'not installed';
+        log(ctx, `  ${row.id.padEnd(22)} ${row.label}`);
+        log(ctx, `  ${''.padEnd(22)} ${detect} · ${status} · ${homeRelative(row.configPath)}`);
+    }
+    log(ctx, '');
+    log(ctx, `Use ${'`wacht mcp install`'} to bulk-apply, ${'`wacht mcp install --client <id,...>`'} to target specific entries.`);
+}

package/dist/prompts.js

@@ -72,3 +72,72 @@ export async function promptOptionalList(ctx, values, question) {
         return [];
     return answer.split(',').map((item) => item.trim()).filter(Boolean);
 }
+function expandRange(token, max) {
+    const range = token.match(/^(\d+)-(\d+)$/);
+    if (range) {
+        const start = Math.max(1, Number.parseInt(range[1], 10));
+        const end = Math.min(max, Number.parseInt(range[2], 10));
+        const result = [];
+        for (let i = start; i <= end; i += 1)
+            result.push(i - 1);
+        return result;
+    }
+    const single = Number.parseInt(token, 10);
+    if (Number.isInteger(single) && single >= 1 && single <= max)
+        return [single - 1];
+    return [];
+}
+export async function promptMultiSelect(ctx, items, question) {
+    if (!canPrompt(ctx)) {
+        return items.filter((item) => item.preselected).map((item) => item.value);
+    }
+    const selected = new Set();
+    items.forEach((item, index) => {
+        if (item.preselected)
+            selected.add(index);
+    });
+    while (true) {
+        console.log('');
+        items.forEach((item, index) => {
+            const mark = selected.has(index) ? '[x]' : '[ ]';
+            const hint = item.hint ? ` ${item.hint}` : '';
+            console.log(`  ${mark} ${index + 1}. ${item.label}${hint}`);
+        });
+        console.log('');
+        console.log('  Toggle by number/range (e.g. "1,3-5"), "all", "none", or press Enter to confirm.');
+        const answer = (await ask(`${question} `)).trim();
+        if (!answer)
+            break;
+        const lower = answer.toLowerCase();
+        if (lower === 'all') {
+            items.forEach((_, index) => selected.add(index));
+            continue;
+        }
+        if (lower === 'none' || lower === 'clear') {
+            selected.clear();
+            continue;
+        }
+        if (lower === 'done' || lower === 'ok')
+            break;
+        const tokens = answer.split(/[\s,]+/).filter(Boolean);
+        for (const token of tokens) {
+            const indices = expandRange(token, items.length);
+            for (const idx of indices) {
+                if (selected.has(idx))
+                    selected.delete(idx);
+                else
+                    selected.add(idx);
+            }
+        }
+    }
+    return [...selected].map((idx) => items[idx].value);
+}
+export async function promptConfirm(ctx, question, defaultYes = true) {
+    if (!canPrompt(ctx))
+        return defaultYes;
+    const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+    const answer = (await ask(`${question}${suffix}`)).trim().toLowerCase();
+    if (!answer)
+        return defaultYes;
+    return answer === 'y' || answer === 'yes';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacht/bench",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for Wacht Bench, the AI development workbench for Wacht.",
   "type": "module",
   "bin": {