@1tool/js-boost 1.1.0 → 1.3.0

package/README.md

@@ -13,9 +13,11 @@ Instead of manually maintaining separate instruction files for each AI agent, yo
 ├── guidelines/
 │   ├── general.md       ← coding conventions
 │   └── testing.md       ← testing standards
-└── skills/
-    └── my-skill/
-        └── SKILL.md     ← on-demand skill (loaded when relevant)
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md     ← on-demand skill (loaded when relevant)
+└── mcp/
+    └── mcp.json         ← MCP server definitions
 ```
 
 Run `npx @1tool/js-boost generate` and get the right file for each configured agent:
@@ -70,37 +72,43 @@ npx @1tool/js-boost agents
 
 ### `@1tool/js-boost mcp`
 
-Interactive wizard to add, remove, or toggle MCP servers. Changes are saved to `js-boost.config.json` — run `generate` afterwards to apply them to agent files.
+Interactive wizard for managing MCP servers. Team server definitions are stored in `.ai/mcp/mcp.json` (committed). Per-developer enable/disable state is stored in `.js-boost.json` (gitignored). Run `generate` afterwards to apply changes to agent files.
 
 ```bash
 npx @1tool/js-boost mcp
 ```
 
-**Add a remote server:**
+The wizard offers three actions:
+
+**Add a remote server** — HTTP/SSE endpoint with optional auth headers:
 ```
-✔ Server key: my-api
-✔ Server type: Remote (HTTP / SSE url)
-✔ URL: https://my-mcp.com/mcp
-✔ Description (optional): Internal API tools
+✔ Server key     my-api
+✔ Server type    Remote (HTTP / SSE url)
+✔ URL            https://my-mcp.com/mcp
+✔ Headers        Authorization: Bearer YOUR_TOKEN_HERE
+✔ Description    Internal API tools
 ```
 
-**Add a local (stdio) server:**
+**Add a local server** — stdio process with optional args and env vars:
 ```
-✔ Server key: local-tools
-✔ Server type: Local (stdio process)
-✔ Command: node
-✔ Arguments: ./mcp-server.js --port 3000
-✔ Environment variables: API_KEY=secret,NODE_ENV=production
+✔ Server key              local-tools
+✔ Server type             Local (stdio process)
+✔ Command                 node
+✔ Arguments               ./mcp-server.js --port 3000
+✔ Environment variables   API_KEY=secret,NODE_ENV=production
 ```
 
+**Enable / disable servers locally** — multiselect over all configured servers. Unchecked servers are added to `disabledMcpServers` in `.js-boost.json` and excluded from your generated files without affecting teammates.
+
 ### `@1tool/js-boost generate`
 
-Reads `.ai/guidelines/*.md` and `.ai/skills/*/SKILL.md`, then generates files for all selected agents. Falls back to generating all supported formats if no agents are configured.
+Reads `.ai/guidelines/*.md` and `.ai/skills/*/SKILL.md`, then generates files for all selected agents. On first run (no `.js-boost.json`), prompts for agent selection inline.
 
 ```bash
 npx @1tool/js-boost generate
-npx @1tool/js-boost gen             # alias
-npx @1tool/js-boost generate --verbose
+npx @1tool/js-boost gen                              # alias
+npx @1tool/js-boost generate --verbose               # show skipped files
+npx @1tool/js-boost generate --agents claude_code,cursor  # CI one-off, not saved
 ```
 
 ### `@1tool/js-boost watch`
@@ -141,36 +149,71 @@ During `init` (and `agents`), installed agents are pre-selected automatically ba
 
 ## Configuration
 
-`js-boost.config.json` is managed by the CLI commands (`init`, `agents`, `mcp`) and committed to your repo.
+### `.ai/mcp/mcp.json` — team MCP servers
+
+Committed to the repo. Defines the MCP servers available to the whole team. Managed by `js-boost mcp`.
 
 ```json
 {
-  "projectName": "my-app",
-  "projectDescription": "",
-  "agents": ["claude_code", "cursor", "codex"],
   "mcpServers": {
-    "my-api": {
-      "type": "remote",
+    "my-remote": {
+      "type": "http",
       "url": "https://my-mcp.com/mcp",
-      "description": "Internal API tools"
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN_HERE"
+      }
     },
-    "local-tools": {
-      "type": "stdio",
+    "my-local": {
       "command": "node",
-      "args": ["./mcp-server.js"],
-      "env": { "API_KEY": "secret" }
+      "args": ["./mcp-server.js", "--port", "3000"],
+      "env": {
+        "API_KEY": "secret"
+      }
+    },
+    "npm-package": {
+      "command": "npx",
+      "args": ["-y", "@some/mcp-server"]
     }
-  },
-  "disableMcpServers": []
+  }
 }
 ```
 
-MCP servers are written to the right format per agent:
+Server types:
 
-| Agent | Format | Remote servers |
-|---|---|---|
-| Claude Code, Codex | `.mcp.json` | wrapped in `mcp-remote` |
-| Junie | `.junie/mcp.json` | referenced by URL directly |
+| Field | When to use |
+|---|---|
+| `type: "http"` + `url` | Remote HTTP/SSE server |
+| `command` (no type) | Local stdio process |
+| `headers` | Auth headers for remote servers (e.g. `Authorization`) |
+| `args` | Command-line arguments |
+| `env` | Environment variables injected into the process |
+
+Remote servers are written differently per agent:
+
+| Agent file | Remote format |
+|---|---|
+| `.mcp.json` (Claude Code, Codex) | Wrapped in `mcp-remote` with `--header` args |
+| `.junie/mcp.json` | URL referenced directly |
+
+### `.js-boost.json` — per-developer config
+
+Gitignored. Created by `js-boost init`, updated by `js-boost agents` and `js-boost mcp`.
+
+```json
+{
+  "agents": ["claude_code", "cursor", "codex"],
+  "guidelines": true,
+  "skills": ["example-skill"],
+  "disabledMcpServers": ["my-remote"]
+}
+```
+
+| Field | Description |
+|---|---|
+| `agents` | Which agents to generate files for |
+| `guidelines` | Set to `true` after first successful generate |
+| `skills` | Snapshot of skill names at last generate |
+| `disabledMcpServers` | Server keys to exclude from your generated files |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1tool/js-boost",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Laravel Boost-inspired CLI for JavaScript projects — generates agent files from your .ai/ folder",
   "main": "src/index.js",
   "type": "module",

package/src/cli.js

@@ -7,13 +7,13 @@ import { watch } from './watch.js';
 
 program
   .name('js-boost')
-  .description('Generate agent files (AGENTS.md, CLAUDE.md, .mcp.json, Junie, Cursor) from your .ai/ folder')
-  .version('1.0.0');
+  .description('Generate agent files from your .ai/ folder')
+  .version('1.2.0');
 
 // ─── js-boost init ───────────────────────────────────────────────────────────
 program
   .command('init')
-  .description('Scaffold the .ai/ folder with example guidelines and skills')
+  .description('Scaffold .ai/ folder, select agents, create .js-boost.json')
   .option('--force', 'Overwrite existing files')
   .option('--dir <path>', 'Project directory', process.cwd())
   .action(async (options) => {
@@ -25,13 +25,14 @@ program
 program
   .command('generate')
   .alias('gen')
-  .description('Generate all agent files from .ai/guidelines/ and .ai/skills/')
+  .description('Generate agent files from .ai/guidelines/ and .ai/skills/')
   .option('--dir <path>', 'Project directory', process.cwd())
+  .option('--agents <list>', 'Comma-separated agent keys — one-off override, not saved (e.g. claude_code,cursor)')
   .option('--verbose', 'Show skipped files')
   .action(async (options) => {
     const projectDir = path.resolve(options.dir);
     try {
-      await generate(projectDir, { verbose: options.verbose });
+      await generate(projectDir, { verbose: options.verbose, agents: options.agents });
     } catch (err) {
       console.error(chalk.red('Error:'), err.message);
       process.exit(1);
@@ -51,29 +52,26 @@ program
 // ─── js-boost agents ─────────────────────────────────────────────────────────
 program
   .command('agents')
-  .description('Select which AI agents to configure (updates js-boost.config.json)')
+  .description('Re-select AI agents and update .js-boost.json')
   .option('--dir <path>', 'Project directory', process.cwd())
   .action(async (options) => {
     const projectDir = path.resolve(options.dir);
-    const { readConfig, writeFile } = await import('./utils/reader.js');
-    const configPath = `${projectDir}/js-boost.config.json`;
-    const config = readConfig(projectDir);
+    const { readLocalConfig, writeLocalConfig } = await import('./utils/reader.js');
+    const localConfig = readLocalConfig(projectDir);
 
-    const selected = await selectAgents(projectDir, config.agents ?? null);
-    config.agents = selected;
+    const selected = await selectAgents(projectDir, localConfig.agents ?? null);
+    writeLocalConfig(projectDir, { ...localConfig, agents: selected });
 
-    writeFile(configPath, JSON.stringify(config, null, 2));
     console.log('');
-    console.log(chalk.green('  ✓ Agent configuration saved to js-boost.config.json'));
-    console.log('');
-    console.log(chalk.dim(`  Selected: ${selected.join(', ')}`));
+    console.log(chalk.green('  ✓ Saved to .js-boost.json'));
+    console.log(chalk.dim(`  Agents: ${selected.join(', ')}`));
     console.log('');
   });
 
 // ─── js-boost mcp ────────────────────────────────────────────────────────────
 program
   .command('mcp')
-  .description('Configure MCP servers — add, remove, or toggle built-in defaults')
+  .description('Configure MCP servers — add/remove team servers or toggle built-in defaults')
   .option('--dir <path>', 'Project directory', process.cwd())
   .action(async (options) => {
     const projectDir = path.resolve(options.dir);
@@ -84,22 +82,22 @@ program
 // ─── js-boost status ─────────────────────────────────────────────────────────
 program
   .command('status')
-  .description('Show what .ai/ contains and what would be generated')
+  .description('Show configured agents, guidelines, skills, MCP servers, and output files')
   .option('--dir <path>', 'Project directory', process.cwd())
   .action(async (options) => {
     const projectDir = path.resolve(options.dir);
-    const { readGuidelines, readSkills, readConfig } = await import('./utils/reader.js');
+    const { readGuidelines, readSkills, readLocalConfig, readMcpConfig } = await import('./utils/reader.js');
     const { buildMcpServers } = await import('./utils/mcp.js');
     const { AGENTS, AGENTS_MD_CONSUMERS, MCP_JSON_CONSUMERS } = await import('./agents.js');
     const aiDir = path.join(projectDir, '.ai');
-    const config = readConfig(projectDir);
 
+    const localConfig = readLocalConfig(projectDir);
     const guidelines = await readGuidelines(aiDir);
     const skills = await readSkills(aiDir);
-    const mcpServers = buildMcpServers(config);
+    const mcpServers = buildMcpServers(readMcpConfig(aiDir), localConfig);
 
     const allAgentKeys = Object.keys(AGENTS);
-    const activeAgents = new Set(config.agents ?? allAgentKeys);
+    const activeAgents = new Set(localConfig.agents ?? allAgentKeys);
     const has = (key) => activeAgents.has(key);
     const hasAny = (keys) => keys.some(k => activeAgents.has(k));
 
@@ -113,12 +111,12 @@ program
       const active = activeAgents.has(key);
       const icon = active ? chalk.green('✓') : chalk.dim('–');
       const label = active ? chalk.cyan(agent.name) : chalk.dim(agent.name);
-      const hint = chalk.dim(`(${agent.hint})`);
-      console.log(`    ${icon} ${label} ${hint}`);
+      console.log(`    ${icon} ${label} ${chalk.dim(`(${agent.hint})`)}`);
     }
-    if (config.agents == null) console.log(chalk.dim('    (all agents — run `js-boost agents` to configure)'));
+    if (!localConfig.agents) console.log(chalk.dim('    (none configured — run `js-boost init` or `js-boost agents`)'));
     console.log('');
 
+    // Guidelines
     console.log(chalk.bold('  Guidelines') + chalk.dim(` (${guidelines.length})`));
     for (const g of guidelines) {
       console.log(`    ${chalk.green('•')} ${chalk.cyan(g.filename)} — ${chalk.dim(g.title)}`);
@@ -126,6 +124,7 @@ program
     if (guidelines.length === 0) console.log(chalk.dim('    none — add .ai/guidelines/*.md'));
     console.log('');
 
+    // Skills
     console.log(chalk.bold('  Skills') + chalk.dim(` (${skills.length})`));
     for (const s of skills) {
       console.log(`    ${chalk.green('•')} ${chalk.cyan(s.name)} — ${chalk.dim(s.description || s.dir)}`);
@@ -133,21 +132,24 @@ program
     if (skills.length === 0) console.log(chalk.dim('    none — add .ai/skills/<name>/SKILL.md'));
     console.log('');
 
+    // MCP servers
     console.log(chalk.bold('  MCP Servers') + chalk.dim(` (${Object.keys(mcpServers).length})`));
     for (const [key, srv] of Object.entries(mcpServers)) {
-      const url = srv.url || `${srv.command} ${(srv.args || []).join(' ')}`;
-      console.log(`    ${chalk.green('•')} ${chalk.cyan(key)} — ${chalk.dim(url)}`);
+      const addr = srv.type === 'http' ? srv.url : `${srv.command} ${(srv.args || []).join(' ')}`;
+      console.log(`    ${chalk.green('•')} ${chalk.cyan(key)} — ${chalk.dim(addr)}`);
     }
+    if (Object.keys(mcpServers).length === 0) console.log(chalk.dim('    none — run `js-boost mcp` to configure'));
     console.log('');
 
+    // Will generate
     console.log(chalk.bold('  Will generate:'));
     const willGenerate = [
-      hasAny(AGENTS_MD_CONSUMERS) && ['AGENTS.md', 'Amp, Codex, Copilot, Gemini, OpenCode'],
-      has('claude_code')          && ['CLAUDE.md', 'Claude Code'],
-      hasAny(MCP_JSON_CONSUMERS)  && ['.mcp.json', 'Claude Code + Codex MCP'],
+      hasAny(AGENTS_MD_CONSUMERS) && ['AGENTS.md',                              'Amp, Codex, Copilot, Gemini, OpenCode'],
+      has('claude_code')          && ['CLAUDE.md',                              'Claude Code'],
+      hasAny(MCP_JSON_CONSUMERS)  && ['.mcp.json',                              'Claude Code + Codex'],
       has('junie')                && ['.junie/guidelines.md + .junie/mcp.json', 'JetBrains Junie'],
       has('cursor')               && ['.cursor/rules/js-boost.mdc + .cursorrules', 'Cursor'],
-      has('kiro')                 && ['.kiro/steering/guidelines.md', 'Kiro'],
+      has('kiro')                 && ['.kiro/steering/guidelines.md',           'Kiro'],
     ].filter(Boolean);
 
     for (const [file, label] of willGenerate) {

package/src/configure/mcp.js

@@ -2,11 +2,11 @@ import path from 'path';
 import chalk from 'chalk';
 import { text, select, multiselect, isCancel } from '@clack/prompts';
 import { DEFAULT_MCP_SERVERS } from '../utils/mcp.js';
-import { readConfig, writeFile } from '../utils/reader.js';
+import { readMcpConfig, writeMcpConfig, readLocalConfig, writeLocalConfig } from '../utils/reader.js';
 
-function displayServers(config) {
-  const userServers = config.mcpServers || {};
-  const disabled = new Set(config.disableMcpServers || []);
+function displayServers(mcpConfig, localConfig) {
+  const userServers = mcpConfig.mcpServers || {};
+  const disabled = new Set(localConfig.disabledMcpServers || []);
   const builtinKeys = Object.keys(DEFAULT_MCP_SERVERS);
 
   if (builtinKeys.length > 0) {
@@ -19,28 +19,29 @@ function displayServers(config) {
     console.log('');
   }
 
-  console.log(chalk.bold('  Custom'));
+  console.log(chalk.bold('  Custom') + chalk.dim('  →  .ai/mcp/mcp.json'));
   const userEntries = Object.entries(userServers);
   if (userEntries.length === 0) {
     console.log(chalk.dim('    (none)'));
   } else {
     for (const [key, srv] of userEntries) {
-      const addr = srv.type === 'remote'
+      const addr = srv.type === 'http'
         ? srv.url
         : `${srv.command}${srv.args?.length ? ' ' + srv.args.join(' ') : ''}`;
-      console.log(`    ${chalk.cyan(key.padEnd(18))} ${chalk.dim(addr)}  ${chalk.dim(`(${srv.type})`)}`);
+      const type = srv.type === 'http' ? 'remote' : 'stdio';
+      console.log(`    ${chalk.cyan(key.padEnd(18))} ${chalk.dim(addr)}  ${chalk.dim(`(${type})`)}`);
     }
   }
   console.log('');
 }
 
-async function addServer(config) {
+async function addServer(mcpConfig) {
   const name = await text({
     message: 'Server key',
     placeholder: 'my-api',
     validate: (v) => {
       if (!v.trim()) return 'Key is required';
-      if ((config.mcpServers || {})[v.trim()]) return `"${v.trim()}" already exists`;
+      if ((mcpConfig.mcpServers || {})[v.trim()]) return `"${v.trim()}" already exists`;
       if (DEFAULT_MCP_SERVERS[v.trim()]) return `"${v.trim()}" is a built-in — use "Toggle built-ins" to enable/disable it`;
       if (!/^[a-z0-9_-]+$/.test(v.trim())) return 'Use only lowercase letters, numbers, hyphens, underscores';
     },
@@ -50,15 +51,15 @@ async function addServer(config) {
   const type = await select({
     message: 'Server type',
     options: [
-      { value: 'remote', label: 'Remote', hint: 'HTTP / SSE url' },
-      { value: 'stdio',  label: 'Local',  hint: 'stdio process (node, python, etc.)' },
+      { value: 'http',  label: 'Remote', hint: 'HTTP / SSE url' },
+      { value: 'stdio', label: 'Local',  hint: 'stdio process (node, python, etc.)' },
     ],
   });
   if (isCancel(type)) return;
 
   const key = name.trim();
 
-  if (type === 'remote') {
+  if (type === 'http') {
     const url = await text({
       message: 'URL',
       placeholder: 'https://my-mcp.com/mcp',
@@ -66,15 +67,34 @@ async function addServer(config) {
     });
     if (isCancel(url)) return;
 
+    const headersRaw = await text({
+      message: 'Headers (Key: Value, comma-separated, optional)',
+      placeholder: 'Authorization: Bearer TOKEN',
+    });
+    if (isCancel(headersRaw)) return;
+
     const description = await text({
       message: 'Description (optional)',
       placeholder: 'What does this server provide?',
     });
     if (isCancel(description)) return;
 
-    config.mcpServers[key] = {
-      type: 'remote',
+    const headers = {};
+    if (headersRaw.trim()) {
+      for (const pair of headersRaw.trim().split(',')) {
+        const colon = pair.indexOf(':');
+        if (colon > 0) {
+          const k = pair.slice(0, colon).trim();
+          const v = pair.slice(colon + 1).trim();
+          if (k) headers[k] = v;
+        }
+      }
+    }
+
+    mcpConfig.mcpServers[key] = {
+      type: 'http',
       url: url.trim(),
+      ...(Object.keys(headers).length ? { headers } : {}),
       ...(description.trim() ? { description: description.trim() } : {}),
     };
   } else {
@@ -111,19 +131,18 @@ async function addServer(config) {
       }
     }
 
-    config.mcpServers[key] = {
-      type: 'stdio',
+    mcpConfig.mcpServers[key] = {
       command: command.trim(),
       ...(args.length ? { args } : {}),
       ...(Object.keys(env).length ? { env } : {}),
     };
   }
 
-  console.log(`  ${chalk.green('✓')} Added ${chalk.cyan(key)}`);
+  console.log(`  ${chalk.green('✓')} Added ${chalk.cyan(key)} → ${chalk.dim('.ai/mcp/mcp.json')}`);
 }
 
-async function removeServer(config) {
-  const keys = Object.keys(config.mcpServers);
+async function removeServer(mcpConfig) {
+  const keys = Object.keys(mcpConfig.mcpServers);
   if (keys.length === 0) {
     console.log(chalk.dim('  No custom servers to remove.'));
     return;
@@ -132,8 +151,8 @@ async function removeServer(config) {
   const toRemove = await multiselect({
     message: 'Select servers to remove',
     options: keys.map((k) => {
-      const srv = config.mcpServers[k];
-      const addr = srv.type === 'remote'
+      const srv = mcpConfig.mcpServers[k];
+      const addr = srv.type === 'http'
         ? srv.url
         : `${srv.command}${srv.args?.length ? ' ' + srv.args.join(' ') : ''}`;
       return { value: k, label: k, hint: addr };
@@ -142,45 +161,56 @@ async function removeServer(config) {
   });
   if (isCancel(toRemove)) return;
 
-  for (const k of toRemove) {
-    delete config.mcpServers[k];
-  }
+  for (const k of toRemove) delete mcpConfig.mcpServers[k];
 
   if (toRemove.length) {
     console.log(`  ${chalk.green('✓')} Removed: ${toRemove.map(k => chalk.cyan(k)).join(', ')}`);
   }
 }
 
-async function toggleDefaults(config) {
-  const keys = Object.keys(DEFAULT_MCP_SERVERS);
-  if (keys.length === 0) {
-    console.log(chalk.dim('  No built-in servers configured.'));
+async function toggleServers(mcpConfig, localConfig) {
+  const builtinKeys = Object.keys(DEFAULT_MCP_SERVERS);
+  const customKeys = Object.keys(mcpConfig.mcpServers || {});
+  const allKeys = [...builtinKeys, ...customKeys];
+
+  if (allKeys.length === 0) {
+    console.log(chalk.dim('  No servers to toggle.'));
     return;
   }
 
-  const disabled = new Set(config.disableMcpServers || []);
+  const disabled = new Set(localConfig.disabledMcpServers || []);
 
-  const enabled = await multiselect({
-    message: 'Which built-in servers should be enabled?',
-    options: keys.map((k) => ({
+  const options = [
+    ...builtinKeys.map((k) => ({
       value: k,
       label: k,
-      hint: DEFAULT_MCP_SERVERS[k].url,
+      hint: `${DEFAULT_MCP_SERVERS[k].url}  (built-in)`,
     })),
-    initialValues: keys.filter((k) => !disabled.has(k)),
+    ...customKeys.map((k) => {
+      const srv = mcpConfig.mcpServers[k];
+      const addr = srv.type === 'http' ? srv.url : `${srv.command}${srv.args?.length ? ' ' + srv.args.join(' ') : ''}`;
+      return { value: k, label: k, hint: addr };
+    }),
+  ];
+
+  const enabled = await multiselect({
+    message: 'Which servers should be enabled locally?',
+    options,
+    initialValues: allKeys.filter((k) => !disabled.has(k)),
     required: false,
   });
   if (isCancel(enabled)) return;
 
   const enabledSet = new Set(enabled);
-  config.disableMcpServers = keys.filter((k) => !enabledSet.has(k));
+  localConfig.disabledMcpServers = allKeys.filter((k) => !enabledSet.has(k));
+  console.log(`  ${chalk.green('✓')} Updated → ${chalk.dim('.js-boost.json')}`);
 }
 
 export async function configureMcp(projectDir) {
-  const configPath = path.join(projectDir, 'js-boost.config.json');
-  const config = readConfig(projectDir);
-  config.mcpServers = config.mcpServers || {};
-  config.disableMcpServers = config.disableMcpServers || [];
+  const aiDir = path.join(projectDir, '.ai');
+  const mcpConfig = readMcpConfig(aiDir);
+  const localConfig = readLocalConfig(projectDir);
+  localConfig.disabledMcpServers = localConfig.disabledMcpServers || [];
 
   console.log('');
   console.log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — MCP server configuration'));
@@ -189,16 +219,16 @@ export async function configureMcp(projectDir) {
   let running = true;
 
   while (running) {
-    displayServers(config);
+    displayServers(mcpConfig, localConfig);
 
-    const hasCustom = Object.keys(config.mcpServers).length > 0;
-    const hasBuiltins = Object.keys(DEFAULT_MCP_SERVERS).length > 0;
+    const hasCustom = Object.keys(mcpConfig.mcpServers).length > 0;
+    const hasAny = hasCustom || Object.keys(DEFAULT_MCP_SERVERS).length > 0;
 
     const options = [
-      { value: 'add', label: 'Add a server' },
-      ...(hasCustom   ? [{ value: 'remove', label: 'Remove a server' }] : []),
-      ...(hasBuiltins ? [{ value: 'toggle', label: 'Disable / enable built-in servers' }] : []),
-      { value: 'done', label: 'Save and exit' },
+      { value: 'add',    label: 'Add a server' },
+      ...(hasCustom ? [{ value: 'remove', label: 'Remove a server' }] : []),
+      ...(hasAny    ? [{ value: 'toggle', label: 'Enable / disable servers locally' }] : []),
+      { value: 'done',   label: 'Save and exit' },
     ];
 
     const action = await select({ message: 'What would you like to do?', options });
@@ -209,15 +239,18 @@ export async function configureMcp(projectDir) {
     }
 
     console.log('');
-    if (action === 'add')    await addServer(config);
-    if (action === 'remove') await removeServer(config);
-    if (action === 'toggle') await toggleDefaults(config);
+    if (action === 'add')    await addServer(mcpConfig);
+    if (action === 'remove') await removeServer(mcpConfig);
+    if (action === 'toggle') await toggleServers(mcpConfig, localConfig);
     console.log('');
   }
 
-  writeFile(configPath, JSON.stringify(config, null, 2));
+  writeMcpConfig(aiDir, mcpConfig);
+  writeLocalConfig(projectDir, localConfig);
   console.log('');
-  console.log(chalk.green('  ✓ Saved to js-boost.config.json'));
-  console.log(chalk.dim('  Run `js-boost generate` to apply changes to agent files.'));
+  console.log(chalk.green('  ✓ Saved'));
+  console.log(chalk.dim('    team config  →  .ai/mcp/mcp.json'));
+  console.log(chalk.dim('    local config →  .js-boost.json'));
+  console.log(chalk.dim('  Run `npx @1tool/js-boost generate` to apply changes.'));
   console.log('');
 }

package/src/index.js

@@ -1,6 +1,6 @@
 import path from 'path';
 import chalk from 'chalk';
-import { readGuidelines, readSkills, readConfig, writeFile } from './utils/reader.js';
+import { readGuidelines, readSkills, readLocalConfig, writeLocalConfig, readMcpConfig, writeFile } from './utils/reader.js';
 import { buildMcpServers, generateMcpJson, generateJunieMcpJson } from './utils/mcp.js';
 import { AGENTS_MD_CONSUMERS, MCP_JSON_CONSUMERS } from './agents.js';
 import { generateAgentsMd } from './generators/agents.js';
@@ -11,29 +11,43 @@ import { generateKiroSteering } from './generators/kiro.js';
 
 export async function generate(projectDir, options = {}) {
   const aiDir = path.join(projectDir, '.ai');
-  const config = readConfig(projectDir);
   const verbose = options.verbose ?? false;
 
-  // Determine active agents — fall back to all agents if none configured
-  const activeAgents = new Set(config.agents ?? Object.keys(
-    { amp: 1, claude_code: 1, codex: 1, copilot: 1, cursor: 1, gemini: 1, junie: 1, kiro: 1, opencode: 1 }
-  ));
-
-  const has = (key) => activeAgents.has(key);
-  const hasAny = (keys) => keys.some(k => activeAgents.has(k));
-
   const log = (msg) => console.log(msg);
   const info = (label, file) => log(`  ${chalk.green('✓')} ${chalk.dim(label.padEnd(30))} ${chalk.cyan(file)}`);
   const skip = (label, reason) => verbose && log(`  ${chalk.yellow('–')} ${chalk.dim(label.padEnd(30))} ${chalk.yellow(reason)}`);
 
+  // Resolve agents — flag (one-off) > local config > inline prompt
+  let localConfig = readLocalConfig(projectDir);
+  let activeAgentsList;
+  let isOneOff = false;
+
+  if (options.agents) {
+    activeAgentsList = options.agents.split(',').map(a => a.trim()).filter(Boolean);
+    isOneOff = true;
+  } else if (localConfig.agents?.length) {
+    activeAgentsList = localConfig.agents;
+  } else {
+    log('');
+    log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — first run setup'));
+    const { selectAgents } = await import('./init.js');
+    activeAgentsList = await selectAgents(projectDir, null);
+    localConfig.agents = activeAgentsList;
+    writeLocalConfig(projectDir, localConfig);
+  }
+
+  const activeAgents = new Set(activeAgentsList);
+  const has = (key) => activeAgents.has(key);
+  const hasAny = (keys) => keys.some(k => activeAgents.has(k));
+
   log('');
   log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — generating agent files'));
   log('');
 
-  // 1. Read source files
+  // Read source files
   const guidelines = await readGuidelines(aiDir);
   const skills = await readSkills(aiDir);
-  const mcpServers = buildMcpServers(config);
+  const mcpServers = buildMcpServers(readMcpConfig(aiDir), localConfig);
 
   if (guidelines.length === 0 && skills.length === 0) {
     log(chalk.yellow('  ⚠ No guidelines or skills found in .ai/'));
@@ -41,15 +55,15 @@ export async function generate(projectDir, options = {}) {
     log('');
   } else {
     log(chalk.dim(`  Found ${guidelines.length} guideline(s), ${skills.length} skill(s), ${Object.keys(mcpServers).length} MCP server(s)`));
-    log(chalk.dim(`  Agents: ${[...activeAgents].join(', ')}`));
+    log(chalk.dim(`  Agents: ${activeAgentsList.join(', ')}`));
     log('');
   }
 
   const generatedFiles = [];
 
-  // 2. AGENTS.md — shared format for Codex, Copilot, Gemini, Amp, OpenCode
+  // AGENTS.md — Amp, Codex, Copilot, Gemini, OpenCode
   if (hasAny(AGENTS_MD_CONSUMERS)) {
-    const agentsMd = generateAgentsMd(guidelines, skills, mcpServers, config);
+    const agentsMd = generateAgentsMd(guidelines, skills, mcpServers, {});
     writeFile(path.join(projectDir, 'AGENTS.md'), agentsMd);
     info('AGENTS.md', 'AGENTS.md');
     generatedFiles.push('AGENTS.md');
@@ -57,9 +71,9 @@ export async function generate(projectDir, options = {}) {
     skip('AGENTS.md', 'no AGENTS.md consumers selected');
   }
 
-  // 3. CLAUDE.md — Claude Code
+  // CLAUDE.md — Claude Code
   if (has('claude_code')) {
-    const claudeMd = generateClaudeMd(guidelines, skills, mcpServers, config);
+    const claudeMd = generateClaudeMd(guidelines, skills, mcpServers, {});
     writeFile(path.join(projectDir, 'CLAUDE.md'), claudeMd);
     info('Claude Code', 'CLAUDE.md');
     generatedFiles.push('CLAUDE.md');
@@ -67,7 +81,7 @@ export async function generate(projectDir, options = {}) {
     skip('Claude Code', 'not selected');
   }
 
-  // 4. .mcp.json — Claude Code + Codex
+  // .mcp.json — Claude Code + Codex
   if (hasAny(MCP_JSON_CONSUMERS)) {
     const mcpJson = generateMcpJson(mcpServers);
     writeFile(path.join(projectDir, '.mcp.json'), mcpJson);
@@ -77,9 +91,9 @@ export async function generate(projectDir, options = {}) {
     skip('MCP', 'no MCP consumers selected');
   }
 
-  // 5. .junie/ — JetBrains Junie
+  // .junie/ — JetBrains Junie
   if (has('junie')) {
-    const junieGuidelines = generateJunieGuidelines(guidelines, skills, config);
+    const junieGuidelines = generateJunieGuidelines(guidelines, skills, {});
     writeFile(path.join(projectDir, '.junie', 'guidelines.md'), junieGuidelines);
     info('Junie guidelines', '.junie/guidelines.md');
     generatedFiles.push('.junie/guidelines.md');
@@ -92,14 +106,14 @@ export async function generate(projectDir, options = {}) {
     skip('Junie', 'not selected');
   }
 
-  // 6. Cursor — .cursor/rules/ + legacy .cursorrules
+  // Cursor
   if (has('cursor')) {
-    const cursorRules = generateCursorRules(guidelines, skills, config);
+    const cursorRules = generateCursorRules(guidelines, skills, {});
     writeFile(path.join(projectDir, '.cursor', 'rules', 'js-boost.mdc'), cursorRules);
     info('Cursor (modern)', '.cursor/rules/js-boost.mdc');
     generatedFiles.push('.cursor/rules/js-boost.mdc');
 
-    const cursorLegacy = generateCursorRulesLegacy(guidelines, skills, config);
+    const cursorLegacy = generateCursorRulesLegacy(guidelines, skills, {});
     writeFile(path.join(projectDir, '.cursorrules'), cursorLegacy);
     info('Cursor (legacy)', '.cursorrules');
     generatedFiles.push('.cursorrules');
@@ -107,9 +121,9 @@ export async function generate(projectDir, options = {}) {
     skip('Cursor', 'not selected');
   }
 
-  // 7. Kiro — .kiro/steering/guidelines.md
+  // Kiro
   if (has('kiro')) {
-    const kiroSteering = generateKiroSteering(guidelines, skills, config);
+    const kiroSteering = generateKiroSteering(guidelines, skills, {});
     writeFile(path.join(projectDir, '.kiro', 'steering', 'guidelines.md'), kiroSteering);
     info('Kiro', '.kiro/steering/guidelines.md');
     generatedFiles.push('.kiro/steering/guidelines.md');
@@ -121,5 +135,12 @@ export async function generate(projectDir, options = {}) {
   log(chalk.green.bold(`  ✓ Generated ${generatedFiles.length} files successfully`));
   log('');
 
+  // Write state back to local config (skip for one-off --agents flag)
+  if (!isOneOff) {
+    localConfig.guidelines = true;
+    localConfig.skills = skills.map(s => s.name);
+    writeLocalConfig(projectDir, localConfig);
+  }
+
   return generatedFiles;
-}
+}

package/src/init.js

@@ -2,7 +2,7 @@ import path from 'path';
 import fs from 'fs';
 import chalk from 'chalk';
 import { multiselect, isCancel, cancel } from '@clack/prompts';
-import { writeFile } from './utils/reader.js';
+import { writeFile, writeMcpConfig, writeLocalConfig } from './utils/reader.js';
 import { AGENTS } from './agents.js';
 import { detectInstalledAgents } from './utils/detect.js';
 
@@ -39,6 +39,15 @@ TODO: describe the steps, patterns, or conventions the agent should follow.
 `
 };
 
+function addToGitignore(projectDir, entry) {
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) return false;
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  if (content.split('\n').some(line => line.trim() === entry)) return false;
+  fs.appendFileSync(gitignorePath, `\n# js-boost local config\n${entry}\n`, 'utf8');
+  return true;
+}
+
 export async function selectAgents(projectDir, currentAgents = null) {
   const detected = detectInstalledAgents(projectDir);
 
@@ -102,26 +111,33 @@ export async function init(projectDir, options = {}) {
     }
   }
 
-  // Create js-boost.config.json with defaults (or read existing)
-  const configPath = path.join(projectDir, 'js-boost.config.json');
-  let existingConfig = {};
-  if (fs.existsSync(configPath) && !force) {
-    try { existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  // Create .ai/mcp/mcp.json
+  const mcpJsonPath = path.join(aiDir, 'mcp', 'mcp.json');
+  if (!fs.existsSync(mcpJsonPath) || force) {
+    writeMcpConfig(aiDir, { mcpServers: {} });
+    console.log(`  ${chalk.green('✓')} ${chalk.cyan('.ai/mcp/mcp.json')}`);
   }
 
   // Agent selection
-  const selectedAgents = await selectAgents(projectDir, existingConfig.agents);
+  const localConfigPath = path.join(projectDir, '.js-boost.json');
+  let existingLocal = {};
+  if (fs.existsSync(localConfigPath)) {
+    try { existingLocal = JSON.parse(fs.readFileSync(localConfigPath, 'utf8')); } catch {}
+  }
 
-  const config = {
-    projectName: existingConfig.projectName || path.basename(projectDir),
-    projectDescription: existingConfig.projectDescription || '',
+  const selectedAgents = await selectAgents(projectDir, existingLocal.agents ?? null);
+
+  writeLocalConfig(projectDir, {
     agents: selectedAgents,
-    mcpServers: existingConfig.mcpServers || {},
-    disableMcpServers: existingConfig.disableMcpServers || [],
-  };
+    disabledMcpServers: existingLocal.disabledMcpServers ?? [],
+  });
+  console.log(`  ${chalk.green('✓')} ${chalk.cyan('.js-boost.json')}`);
 
-  writeFile(configPath, JSON.stringify(config, null, 2));
-  console.log(`  ${chalk.green('✓')} ${chalk.cyan('js-boost.config.json')}`);
+  // Ensure .js-boost.json is gitignored
+  const added = addToGitignore(projectDir, '.js-boost.json');
+  if (added) {
+    console.log(`  ${chalk.green('✓')} ${chalk.cyan('.js-boost.json')} added to ${chalk.cyan('.gitignore')}`);
+  }
 
   console.log('');
   console.log(chalk.green.bold('  ✓ .ai/ folder initialized'));
@@ -129,6 +145,6 @@ export async function init(projectDir, options = {}) {
   console.log(chalk.dim('  Next steps:'));
   console.log(chalk.dim('  1. Edit .ai/guidelines/*.md with your project conventions'));
   console.log(chalk.dim('  2. Add skills in .ai/skills/<name>/SKILL.md'));
-  console.log(chalk.dim('  3. Run: npx js-boost generate'));
+  console.log(chalk.dim('  3. Run: npx @1tool/js-boost generate'));
   console.log('');
 }

package/src/utils/mcp.js

@@ -1,53 +1,51 @@
-/**
- * Default MCP servers pre-configured for js-boost
- */
-export const DEFAULT_MCP_SERVERS = {
-};
+export const DEFAULT_MCP_SERVERS = {};
 
 /**
- * Build the MCP servers object, merging defaults with user-defined servers
- * from js-boost.config.json
+ * Merge team servers (.ai/mcp/mcp.json) with per-developer disabled list (.js-boost.json)
  */
-export function buildMcpServers(config = {}) {
-  const userServers = config.mcpServers || {};
-  const disabledDefaults = config.disableMcpServers || [];
+export function buildMcpServers(mcpConfig = {}, localConfig = {}) {
+  const userServers = mcpConfig.mcpServers || {};
+  const disabled = new Set(localConfig.disabledMcpServers || []);
 
   const servers = {};
 
-  // Add default servers (unless disabled)
   for (const [key, server] of Object.entries(DEFAULT_MCP_SERVERS)) {
-    if (!disabledDefaults.includes(key)) {
+    if (!disabled.has(key)) {
       servers[key] = server;
     }
   }
 
-  // Merge user-defined servers (can override defaults)
   for (const [key, server] of Object.entries(userServers)) {
-    servers[key] = server;
+    if (!disabled.has(key)) {
+      servers[key] = server;
+    }
   }
 
   return servers;
 }
 
 /**
- * Generate .mcp.json (used by Claude Code and Codex)
- * Supports both stdio and remote (HTTP/SSE) server types
+ * Generate .mcp.json (Claude Code + Codex)
+ * - stdio: detected by presence of `command` (no type field)
+ * - remote: type === 'http', wrapped in mcp-remote, headers passed as --header args
  */
 export function generateMcpJson(servers) {
   const mcpServers = {};
 
   for (const [key, server] of Object.entries(servers)) {
-    if (server.type === 'stdio') {
+    if (server.type === 'http') {
+      const args = ['-y', 'mcp-remote', server.url];
+      if (server.headers) {
+        for (const [k, v] of Object.entries(server.headers)) {
+          args.push('--header', `${k}: ${v}`);
+        }
+      }
+      mcpServers[key] = { command: 'npx', args };
+    } else if (server.command) {
       mcpServers[key] = {
         command: server.command,
         args: server.args || [],
-        ...(server.env ? { env: server.env } : {})
-      };
-    } else if (server.type === 'remote') {
-      // Claude Code uses mcp-remote wrapper for HTTP/SSE servers
-      mcpServers[key] = {
-        command: 'npx',
-        args: ['-y', 'mcp-remote', server.url]
+        ...(server.env ? { env: server.env } : {}),
       };
     }
   }
@@ -56,21 +54,19 @@ export function generateMcpJson(servers) {
 }
 
 /**
- * Generate .junie/mcp.json (Junie format — supports URL directly)
+ * Generate .junie/mcp.json — remote servers referenced by URL directly
  */
 export function generateJunieMcpJson(servers) {
   const mcpServers = {};
 
   for (const [key, server] of Object.entries(servers)) {
-    if (server.type === 'stdio') {
+    if (server.type === 'http') {
+      mcpServers[key] = { url: server.url };
+    } else if (server.command) {
       mcpServers[key] = {
         command: server.command,
         args: server.args || [],
-        ...(server.env ? { env: server.env } : {})
-      };
-    } else if (server.type === 'remote') {
-      mcpServers[key] = {
-        url: server.url
+        ...(server.env ? { env: server.env } : {}),
       };
     }
   }
@@ -88,8 +84,8 @@ export function buildMcpMarkdownSection(servers) {
   for (const [key, server] of Object.entries(servers)) {
     lines.push(`### ${key}`);
     if (server.description) lines.push(`> ${server.description}`);
-    if (server.type === 'remote') lines.push(`- **URL:** \`${server.url}\``);
-    if (server.type === 'stdio') lines.push(`- **Command:** \`${server.command} ${(server.args || []).join(' ')}\``);
+    if (server.type === 'http') lines.push(`- **URL:** \`${server.url}\``);
+    if (server.command) lines.push(`- **Command:** \`${server.command} ${(server.args || []).join(' ')}\``);
     lines.push('');
   }
 

package/src/utils/reader.js

@@ -41,7 +41,6 @@ export async function readSkills(aiDir) {
     const content = fs.readFileSync(fullPath, 'utf8').trim();
     const dir = path.dirname(file);
 
-    // Parse YAML frontmatter: ---\nname: ...\ndescription: ...\n---
     let name = dir;
     let description = '';
     const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
@@ -52,7 +51,6 @@ export async function readSkills(aiDir) {
       if (nameMatch) name = nameMatch[1].trim();
       if (descMatch) description = descMatch[1].trim();
     } else {
-      // Fallback: try first heading
       const headingMatch = content.match(/^#+\s*(.+)$/m);
       if (headingMatch) name = headingMatch[1].trim();
     }
@@ -62,10 +60,11 @@ export async function readSkills(aiDir) {
 }
 
 /**
- * Read js-boost.config.json if it exists
+ * Read .js-boost.json — per-developer local config (gitignored)
+ * Returns { agents, guidelines, skills, disabledMcpServers }
  */
-export function readConfig(projectDir) {
-  const configPath = path.join(projectDir, 'js-boost.config.json');
+export function readLocalConfig(projectDir) {
+  const configPath = path.join(projectDir, '.js-boost.json');
   if (!fs.existsSync(configPath)) return {};
   try {
     return JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -74,6 +73,35 @@ export function readConfig(projectDir) {
   }
 }
 
+/**
+ * Write .js-boost.json
+ */
+export function writeLocalConfig(projectDir, config) {
+  writeFile(path.join(projectDir, '.js-boost.json'), JSON.stringify(config, null, 2));
+}
+
+/**
+ * Read .ai/mcp/mcp.json — team MCP server definitions
+ * Returns { mcpServers: {} }
+ */
+export function readMcpConfig(aiDir) {
+  const mcpPath = path.join(aiDir, 'mcp', 'mcp.json');
+  if (!fs.existsSync(mcpPath)) return { mcpServers: {} };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    return { mcpServers: parsed.mcpServers || {} };
+  } catch {
+    return { mcpServers: {} };
+  }
+}
+
+/**
+ * Write .ai/mcp/mcp.json
+ */
+export function writeMcpConfig(aiDir, mcpConfig) {
+  writeFile(path.join(aiDir, 'mcp', 'mcp.json'), JSON.stringify(mcpConfig, null, 2));
+}
+
 /**
  * Ensure a directory exists
  */

package/src/watch.js

@@ -5,7 +5,7 @@ import { generate } from './index.js';
 
 export function watch(projectDir) {
   const aiDir = path.join(projectDir, '.ai');
-  const configPath = path.join(projectDir, 'js-boost.config.json');
+  const configPath = path.join(projectDir, '.js-boost.json');
 
   console.log('');
   console.log(chalk.bold.blue('⚡ js-boost') + chalk.dim(' — watch mode'));