@myvillage/cli 1.83.0 → 1.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/agent-local.js

@@ -46,11 +46,13 @@ import {
   getLogFilePath,
 } from '../utils/local-agent.js';
 import { scaffoldAgent, TOOL_CATALOG, resolveCatalogEntry } from '../utils/agent-scaffolder.js';
+import { loadAgentRecipe, listAgentRecipes } from '../utils/agent-recipes.js';
 import { formatLocalAgentList, formatLocalAgentStatus } from '../utils/formatters.js';
+import { writeFileSync } from 'fs';
 
 // ── Create Local Agent (wizard) ─────────────────────────
 
-export async function agentCreateLocalCommand() {
+export async function agentCreateLocalCommand(options = {}) {
   if (!isAuthenticated()) {
     console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
     return;
@@ -118,7 +120,7 @@ export async function agentCreateLocalCommand() {
       {
         type: 'checkbox',
         name: 'tools',
-        message: 'Which built-in tools should your agent have? (you can add more later with `agent add-mcp`)',
+        message: 'Which built-in tools should your agent have? (you can add more later with `agent add-connector`)',
         choices: [
           { name: 'MyVillageOS MCP (feed, posts, communities, wallet)', value: 'myvillage', checked: true, disabled: 'always enabled' },
           { name: 'Local Files (read/write a sandboxed workspace)', value: 'filesystem', checked: true },
@@ -223,11 +225,28 @@ export async function agentCreateLocalCommand() {
       writeAgentConfig(answers.name, cfg);
     }
 
-    spinner.succeed('Agent scaffolded!');
+    // If --recipe was passed, fetch the Agent Recipe and materialize its
+    // prompt/tools/schedule over the freshly-scaffolded files. Best-effort:
+    // a fetch failure warns and leaves the blank agent in place — we never
+    // roll back the created agent.
+    let recipeApplied = null;
+    if (options.recipe) {
+      spinner.text = `Applying recipe "${options.recipe}"...`;
+      try {
+        recipeApplied = await applyAgentRecipe(answers.name, options.recipe);
+      } catch (err) {
+        recipeApplied = null;
+        // Downgrade spinner to a warning so the succeed() below still fires.
+        spinner.warn(`Recipe "${options.recipe}" not applied: ${err.message}`);
+        console.log(brand.teal('  Created a blank agent instead — customize it with `myvillage agent edit`.\n'));
+      }
+    }
+
+    spinner.succeed(recipeApplied ? `Agent scaffolded from recipe "${recipeApplied.name || options.recipe}"!` : 'Agent scaffolded!');
 
     console.log(brand.green(`  \u2713 Agent created at ~/.myvillage/agents/${answers.name}/\n`));
     console.log(brand.teal('  Next steps:'));
-    console.log(`    ${brand.gold(`myvillage agent add-mcp ${answers.name}`)}    Add a tool (GitHub, Twilio, your own MCP, etc.)`);
+    console.log(`    ${brand.gold(`myvillage agent add-connector ${answers.name}`)}    Add a tool (GitHub, Twilio, your own MCP, etc.)`);
     console.log(`    ${brand.gold(`myvillage agent grant ${answers.name} <provider>`)}  Authorize Google, Microsoft, or Slack`);
     console.log(`    ${brand.gold(`myvillage agent start ${answers.name}`)}     Launch the agent`);
     console.log(`    ${brand.gold(`myvillage agent edit ${answers.name}`)}      Customize the prompt`);
@@ -241,6 +260,77 @@ export async function agentCreateLocalCommand() {
   }
 }
 
+// ── Agent Recipes (starter templates) ───────────────────
+//
+// Fetch a server-side Agent Recipe and materialize it over the three local
+// files an agent already has: prompt.md (overwritten with recipe.promptMd),
+// tools.yaml (myvillage.allowed_tools set to recipe.myvillageTools), and
+// agent.config.yaml (schedule.check_in_interval / active_hours from
+// recipe.scheduleDefaults, if present). Returns the fetched recipe on success.
+// Throws on a fetch/404/network failure so the caller can warn and continue.
+
+async function applyAgentRecipe(agentName, slug) {
+  const recipe = await loadAgentRecipe(slug);
+
+  // 1. prompt.md — overwrite with the recipe's prompt.
+  if (typeof recipe.promptMd === 'string') {
+    writeFileSync(join(getAgentDir(agentName), 'prompt.md'), recipe.promptMd);
+  }
+
+  // 2. tools.yaml — set the myvillage server's allowed_tools list.
+  if (Array.isArray(recipe.myvillageTools)) {
+    const toolsConfig = readToolsYaml(agentName);
+    toolsConfig.servers = toolsConfig.servers || {};
+    toolsConfig.servers.myvillage = toolsConfig.servers.myvillage
+      || resolveCatalogEntry('myvillage', agentName);
+    toolsConfig.servers.myvillage.allowed_tools = [...recipe.myvillageTools];
+    writeToolsYaml(agentName, toolsConfig);
+  }
+
+  // 3. agent.config.yaml — apply schedule defaults if the recipe carries any.
+  const sched = recipe.scheduleDefaults;
+  if (sched && typeof sched === 'object') {
+    const cfg = readAgentConfig(agentName);
+    cfg.schedule = cfg.schedule || {};
+    if (sched.check_in_interval != null) {
+      cfg.schedule.check_in_interval = sched.check_in_interval;
+    }
+    if (sched.active_hours && typeof sched.active_hours === 'object') {
+      cfg.schedule.active_hours = { ...cfg.schedule.active_hours, ...sched.active_hours };
+    }
+    writeAgentConfig(agentName, cfg);
+  }
+
+  return recipe;
+}
+
+export async function agentRecipesListCommand() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  ✗ Authentication required. Run 'myvillage login' first.\n"));
+    return;
+  }
+
+  let recipes;
+  try {
+    recipes = await listAgentRecipes();
+  } catch (err) {
+    console.log(chalk.red(`  ✗ ${err.message}\n`));
+    return;
+  }
+
+  if (!Array.isArray(recipes) || recipes.length === 0) {
+    console.log(brand.teal('  No agent recipes available yet.\n'));
+    return;
+  }
+
+  console.log(brand.teal('\n  Agent recipes (create with `myvillage agent create --recipe <slug>`):\n'));
+  for (const r of recipes) {
+    console.log(`  ${chalk.bold(r.slug)}  ${chalk.dim(r.name || '')}`);
+    if (r.description) console.log(`    ${chalk.dim(r.description)}`);
+  }
+  console.log('');
+}
+
 // ── Start Agent ─────────────────────────────────────────
 
 export async function agentStartCommand(name) {
@@ -762,7 +852,7 @@ export async function agentAddToolCommand(name, tool) {
   if (!validTools.includes(tool)) {
     console.log(chalk.red(`  \u2717 Unknown built-in tool "${tool}".`));
     console.log(brand.teal(`  Built-in tools: ${validTools.join(', ')}`));
-    console.log(brand.teal(`  For GitHub, Twilio, custom MCPs, etc. use: ${chalk.bold(`myvillage agent add-mcp ${name}`)}`));
+    console.log(brand.teal(`  For GitHub, Twilio, custom MCPs, etc. use: ${chalk.bold(`myvillage agent add-connector ${name}`)}`));
     console.log(brand.teal(`  For Google, Microsoft, or Slack use: ${chalk.bold(`myvillage agent grant ${name} <provider>`)}\n`));
     return;
   }

package/src/commands/agent-mcp.js

@@ -8,24 +8,24 @@ import {
   isDaemonRunning,
 } from '../utils/local-agent.js';
 import {
-  loadRecipe,
-  listRegistryRecipes,
-  recipeToServerEntry,
+  loadConnector,
+  listRegistryConnectors,
+  connectorToServerEntry,
   declaredEnvVars,
-} from '../utils/recipes.js';
+} from '../utils/connectors.js';
 import { isAuthenticated } from '../utils/auth.js';
 
-// ── add-mcp ─────────────────────────────────────────────
+// ── add-connector ───────────────────────────────────────
 //
 // Always interactive. If a source is provided (built-in name, local file,
-// or URL), the recipe's fields pre-fill the prompts but the developer can
+// or URL), the connector's fields pre-fill the prompts but the developer can
 // edit every value before it's written. If no source, the wizard collects
 // the fields from scratch.
 //
-// Use --yes to skip prompts and accept recipe values verbatim (useful for
+// Use --yes to skip prompts and accept connector values verbatim (useful for
 // scripts and CI).
 
-export async function agentAddMcpCommand(agentName, sourceArg, options = {}) {
+export async function agentAddConnectorCommand(agentName, sourceArg, options = {}) {
   if (!agentExists(agentName)) {
     console.log(chalk.red(`  ✗ Agent "${agentName}" not found. Run 'myvillage agent' to see your agents.\n`));
     return;
@@ -34,33 +34,33 @@ export async function agentAddMcpCommand(agentName, sourceArg, options = {}) {
   const source = sourceArg || options.from || null;
   const nonInteractive = options.yes === true;
 
-  let recipe = null;
+  let connector = null;
   if (source) {
     try {
-      recipe = await loadRecipe(source);
-      console.log(brand.teal(`  Loaded recipe: "${recipe.name}"${recipe.description ? ` — ${chalk.dim(recipe.description)}` : ''}\n`));
+      connector = await loadConnector(source);
+      console.log(brand.teal(`  Loaded connector: "${connector.name}"${connector.description ? ` — ${chalk.dim(connector.description)}` : ''}\n`));
     } catch (err) {
       console.log(chalk.red(`  ✗ ${err.message}\n`));
       return;
     }
   }
 
-  if (!recipe && nonInteractive) {
-    console.log(chalk.red('  ✗ --yes requires a recipe source (positional arg or --from). No source = interactive wizard.\n'));
+  if (!connector && nonInteractive) {
+    console.log(chalk.red('  ✗ --yes requires a connector source (positional arg or --from). No source = interactive wizard.\n'));
     return;
   }
 
-  // Walk through prompts. With a recipe, each prompt is pre-filled with the
-  // recipe's value. Without one, the developer fills in each field from
+  // Walk through prompts. With a connector, each prompt is pre-filled with the
+  // connector's value. Without one, the developer fills in each field from
   // scratch starting with the local-vs-remote choice.
   let finalized;
   try {
     finalized = nonInteractive
-      ? recipe
-      : await walkWizard(recipe);
+      ? connector
+      : await walkWizard(connector);
   } catch (err) {
     if (err.isTtyError) {
-      console.log(chalk.red('  ✗ Prompts cannot be rendered in this environment. Use --yes with a recipe source for scripted setup.\n'));
+      console.log(chalk.red('  ✗ Prompts cannot be rendered in this environment. Use --yes with a connector source for scripted setup.\n'));
       return;
     }
     console.log(chalk.red(`  ✗ ${err.message}\n`));
@@ -92,7 +92,7 @@ export async function agentAddMcpCommand(agentName, sourceArg, options = {}) {
     }
   }
 
-  toolsConfig.servers[finalized.name] = recipeToServerEntry(finalized);
+  toolsConfig.servers[finalized.name] = connectorToServerEntry(finalized);
   writeToolsYaml(agentName, toolsConfig);
 
   console.log(brand.green(`  ✓ Added "${finalized.name}" to agent "${agentName}".`));
@@ -120,9 +120,9 @@ export async function agentAddMcpCommand(agentName, sourceArg, options = {}) {
 
 // ── Wizard ──────────────────────────────────────────────
 
-async function walkWizard(recipe) {
-  // If no recipe, ask the developer what kind of MCP they're adding
-  if (!recipe) {
+async function walkWizard(connector) {
+  // If no connector, ask the developer what kind of MCP they're adding
+  if (!connector) {
     const { kind } = await inquirer.prompt([{
       type: 'list',
       name: 'kind',
@@ -132,12 +132,12 @@ async function walkWizard(recipe) {
         { name: 'Remote URL (e.g. https://mcp.example.com)', value: 'remote' },
       ],
     }]);
-    recipe = { name: '', description: '', env: {} };
-    if (kind === 'remote') recipe.url = '';
-    else recipe.command = 'npx';
+    connector = { name: '', description: '', env: {} };
+    if (kind === 'remote') connector.url = '';
+    else connector.command = 'npx';
   }
 
-  const isRemote = !!recipe.url;
+  const isRemote = !!connector.url;
 
   // Common fields
   const baseAnswers = await inquirer.prompt([
@@ -145,7 +145,7 @@ async function walkWizard(recipe) {
       type: 'input',
       name: 'name',
       message: 'Server name (key in tools.yaml):',
-      default: recipe.name || undefined,
+      default: connector.name || undefined,
       validate: v => /^[a-z0-9_-]+$/i.test((v || '').trim()) || 'lowercase letters, digits, dashes, underscores only',
       filter: v => v.trim(),
     },
@@ -153,19 +153,19 @@ async function walkWizard(recipe) {
       type: 'input',
       name: 'description',
       message: 'Description (optional, shown in tools.yaml):',
-      default: recipe.description || '',
+      default: connector.description || '',
       filter: v => v.trim(),
     },
   ]);
 
   if (isRemote) {
-    return await walkRemoteWizard(recipe, baseAnswers);
+    return await walkRemoteWizard(connector, baseAnswers);
   }
-  return await walkLocalWizard(recipe, baseAnswers);
+  return await walkLocalWizard(connector, baseAnswers);
 }
 
-async function walkLocalWizard(recipe, baseAnswers) {
-  const argsDefault = (recipe.args || []).join(' ');
+async function walkLocalWizard(connector, baseAnswers) {
+  const argsDefault = (connector.args || []).join(' ');
   const answers = await inquirer.prompt([
     {
       type: 'input',
@@ -186,7 +186,7 @@ async function walkLocalWizard(recipe, baseAnswers) {
       type: 'input',
       name: 'envNamesRaw',
       message: 'Env vars this MCP needs (comma-separated, leave blank for none):',
-      default: Object.keys(recipe.env || {}).join(', '),
+      default: Object.keys(connector.env || {}).join(', '),
       filter: v => v.trim(),
     },
   ]);
@@ -196,15 +196,15 @@ async function walkLocalWizard(recipe, baseAnswers) {
     ? answers.envNamesRaw.split(',').map(s => s.trim()).filter(Boolean)
     : [];
 
-  // Build env schema — preserve recipe-provided descriptions for known vars,
+  // Build env schema — preserve connector-provided descriptions for known vars,
   // mark new ones the developer added as required-by-default with no description.
   const env = {};
   for (const name of envNames) {
-    env[name] = recipe.env?.[name] || { description: '', required: true };
+    env[name] = connector.env?.[name] || { description: '', required: true };
   }
 
   return {
-    ...recipe,
+    ...connector,
     ...baseAnswers,
     command: answers.command,
     args,
@@ -212,8 +212,8 @@ async function walkLocalWizard(recipe, baseAnswers) {
   };
 }
 
-async function walkRemoteWizard(recipe, baseAnswers) {
-  const headerEntries = Object.entries(recipe.headers || {});
+async function walkRemoteWizard(connector, baseAnswers) {
+  const headerEntries = Object.entries(connector.headers || {});
   const defaultAuth = headerEntries.some(([k]) => /^authorization$/i.test(k)) ? 'bearer'
     : headerEntries.length > 0 ? 'custom' : 'none';
 
@@ -247,12 +247,12 @@ async function walkRemoteWizard(recipe, baseAnswers) {
       type: 'input',
       name: 'envVarName',
       message: 'Env var name that will hold the token:',
-      default: pickFirstEnvVarName(recipe) || 'MY_MCP_TOKEN',
+      default: pickFirstEnvVarName(connector) || 'MY_MCP_TOKEN',
       validate: v => /^[A-Z_][A-Z0-9_]*$/i.test(v) || 'must be a valid env-var name (letters, digits, underscores)',
       filter: v => v.trim(),
     }]);
     headers = { Authorization: `Bearer \${${envVarName}}` };
-    env = { [envVarName]: recipe.env?.[envVarName] || { description: 'Bearer token', required: true } };
+    env = { [envVarName]: connector.env?.[envVarName] || { description: 'Bearer token', required: true } };
   } else if (answers.authKind === 'custom') {
     const { headersRaw } = await inquirer.prompt([{
       type: 'input',
@@ -270,23 +270,23 @@ async function walkRemoteWizard(recipe, baseAnswers) {
       for (const m of matches) envNamesFromHeaders.add(m[1]);
     }
     for (const name of envNamesFromHeaders) {
-      env[name] = recipe.env?.[name] || { description: '', required: true };
+      env[name] = connector.env?.[name] || { description: '', required: true };
     }
   }
 
   return {
-    ...recipe,
+    ...connector,
     ...baseAnswers,
     url: answers.url,
-    transport: recipe.transport || 'http',
+    transport: connector.transport || 'http',
     headers,
     env,
   };
 }
 
-function pickFirstEnvVarName(recipe) {
-  if (!recipe.env || typeof recipe.env !== 'object') return null;
-  return Object.keys(recipe.env)[0] || null;
+function pickFirstEnvVarName(connector) {
+  if (!connector.env || typeof connector.env !== 'object') return null;
+  return Object.keys(connector.env)[0] || null;
 }
 
 function parseHeaderList(raw) {
@@ -324,34 +324,34 @@ export async function agentListMcpCommand(agentName) {
   console.log('');
 }
 
-// ── recipes ─────────────────────────────────────────────
+// ── connectors ──────────────────────────────────────────
 
-export async function recipesListCommand() {
+export async function connectorsListCommand() {
   if (!isAuthenticated()) {
     console.log(chalk.red("  ✗ Authentication required. Run 'myvillage login' first.\n"));
     return;
   }
 
-  let recipes;
+  let connectors;
   try {
-    recipes = await listRegistryRecipes();
+    connectors = await listRegistryConnectors();
   } catch (err) {
     console.log(chalk.red(`  ✗ ${err.message}\n`));
     return;
   }
 
-  if (recipes.length === 0) {
-    console.log(brand.teal('  The recipe registry is empty.\n'));
+  if (connectors.length === 0) {
+    console.log(brand.teal('  The connector registry is empty.\n'));
     return;
   }
 
-  console.log(brand.teal('\n  MyVillage curated MCP recipes (install with `agent add-mcp <agent> <name>`):\n'));
-  for (const r of recipes) {
-    const kind = r.kind === 'remote' ? 'remote' : 'local';
-    console.log(`  ${chalk.bold(r.name.padEnd(14))}${chalk.dim(`(${kind})`)} ${chalk.dim(r.description || '')}`);
-    if (r.envVars && r.envVars.length > 0) {
-      console.log(`  ${' '.repeat(14)}${chalk.dim('env: ' + r.envVars.join(', '))}`);
+  console.log(brand.teal('\n  MyVillage curated MCP connectors (install with `agent add-connector <agent> <name>`):\n'));
+  for (const c of connectors) {
+    const kind = c.kind === 'remote' ? 'remote' : 'local';
+    console.log(`  ${chalk.bold(c.name.padEnd(14))}${chalk.dim(`(${kind})`)} ${chalk.dim(c.description || '')}`);
+    if (c.envVars && c.envVars.length > 0) {
+      console.log(`  ${' '.repeat(14)}${chalk.dim('env: ' + c.envVars.join(', '))}`);
     }
   }
-  console.log(brand.teal('\n  External recipes: install with `--from <path-or-url>`.\n'));
+  console.log(brand.teal('\n  External connectors: install with `--from <path-or-url>`.\n'));
 }

package/src/commands/agent.js

@@ -66,13 +66,19 @@ export async function agentCommand(handle) {
   }
 }
 
-export async function agentCreateCommand() {
+export async function agentCreateCommand(options = {}) {
   if (!isAuthenticated()) {
     console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
     return;
   }
 
   try {
+    // A --recipe implies a local agent (recipes materialize prompt.md / tools.yaml
+    // / agent.config.yaml, which only local agents have) \u2014 skip the gate question.
+    if (options.recipe) {
+      return agentCreateLocalCommand(options);
+    }
+
     // Gate question: local or external?
     const { agentType } = await inquirer.prompt([{
       type: 'list',
@@ -85,7 +91,7 @@ export async function agentCreateCommand() {
     }]);
 
     if (agentType === 'local') {
-      return agentCreateLocalCommand();
+      return agentCreateLocalCommand(options);
     }
 
     // Fetch the caller's existing agents to offer as parent choices for the

package/src/index.js

@@ -70,6 +70,7 @@ import {
   agentMemoryCommand,
   agentRecallCommand,
   agentRememberCommand,
+  agentRecipesListCommand,
 } from './commands/agent-local.js';
 import {
   agentRegisterClientCommand,
@@ -80,9 +81,9 @@ import {
   agentRotateClientKeyCommand,
 } from './commands/agent-client.js';
 import {
-  agentAddMcpCommand,
+  agentAddConnectorCommand,
   agentListMcpCommand,
-  recipesListCommand,
+  connectorsListCommand,
 } from './commands/agent-mcp.js';
 import {
   agentGrantCommand,
@@ -444,7 +445,8 @@ export function run() {
   agentCmd
     .command('create')
     .description('Create a new agent (interactive)')
-    .action(agentCreateCommand);
+    .option('--recipe <slug>', 'Start from an Agent Recipe template (prompt + preselected MyVillageOS tools). Implies a local agent. List them with `myvillage agent recipes`.')
+    .action((options) => agentCreateCommand(options));
 
   agentCmd
     .command('view <handle>')
@@ -536,7 +538,7 @@ export function run() {
 
   agentCmd
     .command('add-tool <name> <tool>')
-    .description('Add a built-in tool (filesystem, browser) — for custom MCPs use `add-mcp`, for Google/Microsoft/Slack use `grant`')
+    .description('Add a built-in tool (filesystem, browser) — for custom MCPs use `add-connector`, for Google/Microsoft/Slack use `grant`')
     .action(agentAddToolCommand);
 
   agentCmd
@@ -544,14 +546,16 @@ export function run() {
     .description('Remove an MCP server tool from a local agent')
     .action(agentRemoveToolCommand);
 
-  // Generic add-mcp — interactive wizard, optionally pre-filled by a recipe
-  // (built-in name, local YAML file, or URL).
+  // Generic add-connector — interactive wizard, optionally pre-filled by a
+  // connector (built-in name, local YAML file, or URL). `add-mcp` stays as a
+  // hidden deprecated alias so already-documented invocations keep working.
   agentCmd
-    .command('add-mcp <name> [recipe]')
-    .description('Interactively add any MCP server to an agent. Optional recipe pre-fills the wizard (built-in name, ./path.yaml, or https://url/recipe.yaml).')
-    .option('--from <source>', 'Recipe source — same as the positional [recipe] arg')
-    .option('--yes', 'Skip prompts and accept recipe values verbatim (requires a recipe source)')
-    .action((name, recipe, options) => agentAddMcpCommand(name, recipe, options));
+    .command('add-connector <name> [connector]')
+    .alias('add-mcp')
+    .description('Interactively add any MCP server (connector) to an agent. Optional connector pre-fills the wizard (built-in name, ./path.yaml, or https://url/connector.yaml).')
+    .option('--from <source>', 'Connector source — same as the positional [connector] arg')
+    .option('--yes', 'Skip prompts and accept connector values verbatim (requires a connector source)')
+    .action((name, connector, options) => agentAddConnectorCommand(name, connector, options));
 
   agentCmd
     .command('list-mcp <name>')
@@ -577,9 +581,16 @@ export function run() {
     .action(agentGrantsListCommand);
 
   program
+    .command('connectors')
+    .alias('recipes')
+    .description('List the curated MCP connectors in the MyVillage registry')
+    .action(connectorsListCommand);
+
+  // List available Agent Recipes (starter templates for `agent create --recipe`).
+  agentCmd
     .command('recipes')
-    .description('List the MCP recipes bundled with the CLI')
-    .action(recipesListCommand);
+    .description('List available Agent Recipes (starter templates: prompt + preselected tools)')
+    .action(agentRecipesListCommand);
 
   // Task queue commands — assign and inspect work for a developer's agent
   agentCmd

package/src/utils/agent-recipes.js

@@ -0,0 +1,83 @@
+// ── Agent Recipes ───────────────────────────────────────
+//
+// An "Agent Recipe" is a get-started template for creating an agent: a
+// `prompt.md` plus a pre-selected set of MyVillageOS tools (and optional
+// schedule defaults). Recipes are DB-backed and served by the ed-platform;
+// the CLI materializes them into the three local agent files at create time.
+//
+// Distinct from a "Connector" (see connectors.js), which installs an external
+// MCP server. Recipes carry no credentials.
+//
+// API (auth: bearer token, any session):
+//   GET ${apiBaseUrl}/agent-recipes         -> { recipes: AgentRecipeSummary[] }
+//   GET ${apiBaseUrl}/agent-recipes/{slug}  -> { recipe: AgentRecipe }
+//
+// AgentRecipe {
+//   slug, name, description, promptMd,
+//   myvillageTools: string[],
+//   scheduleDefaults?: { check_in_interval?, active_hours? }
+// }
+
+import { getConfig } from './config.js';
+import { getAccessToken } from './auth.js';
+
+async function authedFetch(url, options = {}) {
+  const token = getAccessToken();
+  const headers = { ...(options.headers || {}) };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+  return fetch(url, { ...options, headers });
+}
+
+async function recipeError(response, action) {
+  let detail = '';
+  try {
+    const body = await response.json();
+    if (body?.error) detail = body.error;
+    if (body?.hint) detail += detail ? ` — ${body.hint}` : body.hint;
+  } catch {
+    // non-JSON body, ignore
+  }
+  if (response.status === 401) {
+    return new Error(`Could not ${action}: authentication required. Run 'myvillage login' first.`);
+  }
+  if (response.status === 404) {
+    return new Error(`Could not ${action}: not found.`);
+  }
+  return new Error(`Could not ${action}: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`);
+}
+
+/**
+ * Fetch a single Agent Recipe by slug. Returns the recipe object
+ * ({ slug, name, description, promptMd, myvillageTools, scheduleDefaults? }).
+ * Throws with a friendly message on 404 / auth / network failure.
+ */
+export async function loadAgentRecipe(slug) {
+  if (!slug) throw new Error('No agent recipe slug provided');
+  const url = `${getConfig().apiBaseUrl}/agent-recipes/${encodeURIComponent(slug)}`;
+  let res;
+  try {
+    res = await authedFetch(url);
+  } catch (err) {
+    throw new Error(`Could not fetch recipe "${slug}": ${err.message}`);
+  }
+  if (!res.ok) {
+    throw await recipeError(res, `fetch recipe "${slug}"`);
+  }
+  const body = await res.json();
+  // Accept either { recipe: {...} } (spec shape) or a bare recipe object.
+  return body.recipe || body;
+}
+
+/**
+ * List available Agent Recipes. Returns an array of summaries
+ * ({ slug, name, description, ... }). Requires `myvillage login`.
+ */
+export async function listAgentRecipes() {
+  const url = `${getConfig().apiBaseUrl}/agent-recipes`;
+  const res = await authedFetch(url);
+  if (!res.ok) {
+    throw await recipeError(res, 'list agent recipes');
+  }
+  const body = await res.json();
+  return body.recipes || body.data || [];
+}

package/src/utils/agent-scaffolder.js

@@ -12,10 +12,10 @@ import { stringify as stringifyYaml } from 'yaml';
 // themselves).
 //
 // Everything else — Twilio, custom remote MCPs, anything new the community
-// ships — lives as a "recipe" the developer installs via `myvillage agent
-// add-mcp` after creation (see src/utils/recipes.js). OAuth providers (Google,
-// Microsoft, Slack) instead connect once and are authorized per-agent with
-// `myvillage agent grant`.
+// ships — lives as a "connector" the developer installs via `myvillage agent
+// add-connector` after creation (see src/utils/connectors.js). OAuth providers
+// (Google, Microsoft, Slack) instead connect once and are authorized per-agent
+// with `myvillage agent grant`.
 
 const TOOL_CATALOG = {
 
@@ -100,7 +100,7 @@ export function scaffoldAgent(agentDir, options) {
     generateToolsYaml(tools, name),
   );
 
-  // A starter .env file for the developer to populate. Tools/recipes that
+  // A starter .env file for the developer to populate. Tools/connectors that
   // need credentials (Twilio SID/auth, custom headers for remote MCPs) read env
   // vars from this file at agent start. OAuth providers (Google, Microsoft,
   // Slack) are NOT env vars — they connect once and are authorized per-agent
@@ -123,7 +123,7 @@ function starterEnvFile() {
     '# environment of every MCP subprocess it spawns. Use it for tokens, API',
     '# keys, and any other secret your tools (or remote MCPs) need.',
     '#',
-    '# Examples (the curated recipes — install with `myvillage agent add-mcp`):',
+    '# Examples (the curated connectors — install with `myvillage agent add-connector`):',
     '#   GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx',
     '#   TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxx',
     '#   TWILIO_API_KEY=SKxxxxxxxxxxxx',

package/src/utils/connectors.js

@@ -0,0 +1,285 @@
+// ── MCP Connectors ──────────────────────────────────────
+//
+// A "connector" is a small declarative YAML file describing how to plug an
+// MCP server into an agent. Connectors are NOT bundled with the CLI — they
+// live in the MyVillage connector registry (auth-gated) and any other URL a
+// developer points at via `--from`.
+//
+// (Formerly called "recipes." The name moved to "connector" so "recipe" could
+// be reused for agent starter templates — see agent-recipes.js. The old
+// `recipes.js` module re-exports these symbols under their previous names for
+// back-compat with the published package's consumers, e.g. myvillage-studio.)
+//
+// `loadConnector(source)` accepts:
+//   - a bare name like "github" → fetches from the MyVillage registry,
+//     attaches the developer's bearer token, requires `myvillage login`
+//   - a local file path (./connector.yaml or absolute) → reads from disk
+//   - a remote URL (http(s)://...) → fetches; bearer token attached only
+//     when the host is a MyVillage host (never leaked to third parties)
+//
+// Connector format — same two shapes the daemon's `tools.yaml` already
+// supports:
+//
+//   Local subprocess MCP:
+//     name: string
+//     description: string (optional)
+//     command: string                 # e.g. "npx"
+//     args: [string, string, ...]     # passed to command; ${VAR} ok
+//     env:                             # optional schema for the wizard
+//       NAME:
+//         description: string
+//         required: bool
+//     setup_help: string (optional URL)
+//
+//   Remote URL MCP:
+//     name: string
+//     description: string (optional)
+//     url: string
+//     transport: "http" | "sse" (optional, default "http")
+//     headers:                         # optional; values may use ${ENV}
+//       Authorization: "Bearer ${MY_TOKEN}"
+//     env:                             # optional schema for the wizard
+//       MY_TOKEN:
+//         description: string
+//         required: bool
+//     setup_help: string (optional URL)
+
+import { readFileSync, existsSync } from 'fs';
+import { join, isAbsolute } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { getConfig } from './config.js';
+import { getAccessToken } from './auth.js';
+
+// ── Deprecated registry connectors ──────────────────────
+//
+// Curated connectors retired in favor of one-click OAuth provider connect
+// (`myvillage agent grant <agent> <provider>`). We hide them from the registry
+// listing and block a direct fetch so there's a single, obvious path — even if
+// the backend registry still serves the old entry. Keyed by registry connector
+// name → the provider slug that replaces it. Only affects bare-name registry
+// loads; a developer's own `--from ./slack.yaml` is untouched.
+const DEPRECATED_REGISTRY_CONNECTORS = {
+  slack: 'slack', // bot-token Slack MCP → "Sign in with Slack" (acts as you)
+};
+
+function deprecationMessage(name, providerSlug) {
+  const label = name.charAt(0).toUpperCase() + name.slice(1);
+  return (
+    `The "${name}" bot-token tool has been replaced by one-click ${label} sign-in. ` +
+    `Connect ${label} in MyVillage Studio (or at myvillageproject.ai), then run ` +
+    `\`myvillage agent grant <agent> ${providerSlug}\` — no token to copy.`
+  );
+}
+
+// ── Public API ──────────────────────────────────────────
+
+/**
+ * Resolve any connector source (bare name | local path | URL) to a parsed,
+ * validated connector object. Throws with a friendly message if the source
+ * can't be read, the request fails, or the YAML is invalid.
+ */
+export async function loadConnector(source) {
+  if (!source) throw new Error('No connector source provided');
+
+  // URL — fetch (auth attached if MyVillage host)
+  if (/^https?:\/\//i.test(source)) {
+    return loadConnectorFromUrl(source);
+  }
+
+  // Looks like a path — read from disk
+  if (source.includes('/') || source.includes('\\') || /\.(yaml|yml)$/i.test(source)) {
+    return loadConnectorFromFile(source);
+  }
+
+  // Bare name — pull from the MyVillage curated registry
+  return loadConnectorFromRegistry(source);
+}
+
+/**
+ * List curated connectors available in the MyVillage registry. Requires
+ * `myvillage login`. Returns an array of summaries:
+ *   { name, description, kind, envVars, setup_help? }
+ */
+export async function listRegistryConnectors() {
+  const url = `${getConfig().apiBaseUrl}/connectors`;
+  const res = await authedFetch(url);
+  if (!res.ok) {
+    throw await registryError(res, 'list connectors');
+  }
+  const body = await res.json();
+  // Back-compat: the endpoint returns `{ connectors: [...] }`; older/deprecated
+  // deploys may still return `{ recipes: [...] }`. Accept either.
+  const items = body.connectors || body.recipes || [];
+  // Hide retired connectors (e.g. the bot-token Slack MCP) so they never show up
+  // as an option — the OAuth provider path supersedes them.
+  return items.filter(
+    (r) => !Object.hasOwn(DEPRECATED_REGISTRY_CONNECTORS, String(r?.name || '').toLowerCase()),
+  );
+}
+
+// ── Loaders ─────────────────────────────────────────────
+
+async function loadConnectorFromRegistry(name) {
+  const slug = String(name || '').toLowerCase();
+  if (Object.hasOwn(DEPRECATED_REGISTRY_CONNECTORS, slug)) {
+    throw new Error(deprecationMessage(slug, DEPRECATED_REGISTRY_CONNECTORS[slug]));
+  }
+  const url = `${getConfig().apiBaseUrl}/connectors/${encodeURIComponent(name)}`;
+  const res = await authedFetch(url);
+  if (!res.ok) {
+    throw await registryError(res, `fetch connector "${name}"`);
+  }
+  const text = await res.text();
+  return validateConnector(parseYaml(text), `registry:${name}`);
+}
+
+function loadConnectorFromFile(path) {
+  const abs = isAbsolute(path) ? path : join(process.cwd(), path);
+  if (!existsSync(abs)) {
+    throw new Error(`Connector file not found: ${abs}`);
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(readFileSync(abs, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to parse connector at ${abs}: ${err.message}`);
+  }
+  return validateConnector(parsed, abs);
+}
+
+async function loadConnectorFromUrl(url) {
+  // Attach the bearer token only if this URL is on a MyVillage host —
+  // sending it to a third-party URL would leak the developer's
+  // platform credentials.
+  const fetcher = isMyVillageHost(url) ? authedFetch : fetch;
+  let response;
+  try {
+    response = await fetcher(url, { redirect: 'follow' });
+  } catch (err) {
+    throw new Error(`Failed to fetch connector from ${url}: ${err.message}`);
+  }
+  if (!response.ok) {
+    if (isMyVillageHost(url) && (response.status === 401 || response.status === 403)) {
+      throw new Error(`Connector at ${url} requires authentication. Run 'myvillage login' first.`);
+    }
+    throw new Error(`Failed to fetch connector from ${url}: HTTP ${response.status}`);
+  }
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = parseYaml(text);
+  } catch (err) {
+    throw new Error(`Failed to parse connector from ${url}: ${err.message}`);
+  }
+  return validateConnector(parsed, url);
+}
+
+// ── Auth ────────────────────────────────────────────────
+
+function isMyVillageHost(urlString) {
+  try {
+    const host = new URL(urlString).hostname;
+    return host === 'myvillageproject.ai' || host.endsWith('.myvillageproject.ai');
+  } catch {
+    return false;
+  }
+}
+
+async function authedFetch(url, options = {}) {
+  const token = getAccessToken();
+  const headers = { ...(options.headers || {}) };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+  return fetch(url, { ...options, headers });
+}
+
+async function registryError(response, action) {
+  let detail = '';
+  try {
+    const body = await response.json();
+    if (body?.error) detail = body.error;
+    if (body?.hint) detail += detail ? ` — ${body.hint}` : body.hint;
+  } catch {
+    // non-JSON body, ignore
+  }
+  if (response.status === 401) {
+    return new Error(`Could not ${action}: authentication required. Run 'myvillage login' first.`);
+  }
+  if (response.status === 404) {
+    return new Error(`Could not ${action}: not found in the MyVillage connector registry.`);
+  }
+  return new Error(`Could not ${action}: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`);
+}
+
+// ── Validation ──────────────────────────────────────────
+
+function validateConnector(connector, sourceLabel) {
+  if (!connector || typeof connector !== 'object') {
+    throw new Error(`Connector at ${sourceLabel} is empty or not a YAML object`);
+  }
+  if (!connector.name || typeof connector.name !== 'string') {
+    throw new Error(`Connector at ${sourceLabel} is missing a "name" field`);
+  }
+
+  const hasCommand = typeof connector.command === 'string' && connector.command.length > 0;
+  const hasUrl = typeof connector.url === 'string' && connector.url.length > 0;
+  if (hasCommand && hasUrl) {
+    throw new Error(`Connector "${connector.name}" has both "command" and "url" — pick one`);
+  }
+  if (!hasCommand && !hasUrl) {
+    throw new Error(`Connector "${connector.name}" needs either a "command" (for local subprocess) or "url" (for remote MCP)`);
+  }
+
+  if (hasCommand && connector.args && !Array.isArray(connector.args)) {
+    throw new Error(`Connector "${connector.name}": "args" must be an array of strings`);
+  }
+  if (hasUrl && connector.transport && !['http', 'sse'].includes(connector.transport)) {
+    throw new Error(`Connector "${connector.name}": "transport" must be "http" or "sse"`);
+  }
+
+  if (connector.env != null) {
+    if (typeof connector.env !== 'object' || Array.isArray(connector.env)) {
+      throw new Error(`Connector "${connector.name}": "env" must be a mapping of env-var-name to descriptor`);
+    }
+  }
+
+  return connector;
+}
+
+// ── Connector → tools.yaml entry ────────────────────────
+
+/**
+ * Translate a finalized connector (with developer edits already applied)
+ * into the server entry that goes under `servers:` in tools.yaml.
+ */
+export function connectorToServerEntry(connector) {
+  if (connector.url) {
+    const entry = { url: connector.url };
+    if (connector.transport) entry.transport = connector.transport;
+    if (connector.headers && Object.keys(connector.headers).length > 0) {
+      entry.headers = { ...connector.headers };
+    }
+    if (connector.description) entry.description = connector.description;
+    return entry;
+  }
+
+  const entry = { command: connector.command };
+  if (connector.args && connector.args.length > 0) entry.args = [...connector.args];
+  if (connector.env_vars && Object.keys(connector.env_vars).length > 0) {
+    entry.env = { ...connector.env_vars };
+  }
+  if (connector.description) entry.description = connector.description;
+  return entry;
+}
+
+/**
+ * List of env-var names a connector declares as needed. The wizard prints
+ * these so the developer knows what to set in their .env / shell.
+ */
+export function declaredEnvVars(connector) {
+  if (!connector.env || typeof connector.env !== 'object') return [];
+  return Object.entries(connector.env).map(([name, schema]) => ({
+    name,
+    description: schema?.description || '',
+    required: schema?.required !== false,
+  }));
+}

package/src/utils/recipes.js

@@ -1,277 +1,20 @@
-// ── MCP Recipes ─────────────────────────────────────────
+// ── Back-compat shim: recipes → connectors ──────────────
 //
-// A "recipe" is a small declarative YAML file describing how to plug an
-// MCP server into an agent. Recipes are NOT bundled with the CLI — they
-// live in the MyVillage recipe registry (auth-gated) and any other URL a
-// developer points at via `--from`.
+// "Recipes" were renamed to "Connectors" (see connectors.js and the
+// Agent Recipes & Connectors spec). The published `@myvillage/cli` package is
+// imported by sibling repos (notably myvillage-studio) under the OLD names,
+// so this module stays as a thin re-export that maps the new symbol names
+// back to the old ones. Do NOT add logic here — edit connectors.js instead.
 //
-// `loadRecipe(source)` accepts:
-//   - a bare name like "gmail" → fetches from the MyVillage registry,
-//     attaches the developer's bearer token, requires `myvillage login`
-//   - a local file path (./recipe.yaml or absolute) → reads from disk
-//   - a remote URL (http(s)://...) → fetches; bearer token attached only
-//     when the host is a MyVillage host (never leaked to third parties)
-//
-// Recipe format — same two shapes the daemon's `tools.yaml` already
-// supports:
-//
-//   Local subprocess MCP:
-//     name: string
-//     description: string (optional)
-//     command: string                 # e.g. "npx"
-//     args: [string, string, ...]     # passed to command; ${VAR} ok
-//     env:                             # optional schema for the wizard
-//       NAME:
-//         description: string
-//         required: bool
-//     setup_help: string (optional URL)
-//
-//   Remote URL MCP:
-//     name: string
-//     description: string (optional)
-//     url: string
-//     transport: "http" | "sse" (optional, default "http")
-//     headers:                         # optional; values may use ${ENV}
-//       Authorization: "Bearer ${MY_TOKEN}"
-//     env:                             # optional schema for the wizard
-//       MY_TOKEN:
-//         description: string
-//         required: bool
-//     setup_help: string (optional URL)
-
-import { readFileSync, existsSync } from 'fs';
-import { join, isAbsolute } from 'path';
-import { parse as parseYaml } from 'yaml';
-import { getConfig } from './config.js';
-import { getAccessToken } from './auth.js';
-
-// ── Deprecated registry recipes ─────────────────────────
-//
-// Curated recipes retired in favor of one-click OAuth provider connect
-// (`myvillage agent grant <agent> <provider>`). We hide them from the registry
-// listing and block a direct fetch so there's a single, obvious path — even if
-// the backend registry still serves the old entry. Keyed by registry recipe
-// name → the provider slug that replaces it. Only affects bare-name registry
-// loads; a developer's own `--from ./slack.yaml` is untouched.
-const DEPRECATED_REGISTRY_RECIPES = {
-  slack: 'slack', // bot-token Slack MCP → "Sign in with Slack" (acts as you)
-};
-
-function deprecationMessage(name, providerSlug) {
-  const label = name.charAt(0).toUpperCase() + name.slice(1);
-  return (
-    `The "${name}" bot-token tool has been replaced by one-click ${label} sign-in. ` +
-    `Connect ${label} in MyVillage Studio (or at myvillageproject.ai), then run ` +
-    `\`myvillage agent grant <agent> ${providerSlug}\` — no token to copy.`
-  );
-}
-
-// ── Public API ──────────────────────────────────────────
-
-/**
- * Resolve any recipe source (bare name | local path | URL) to a parsed,
- * validated recipe object. Throws with a friendly message if the source
- * can't be read, the request fails, or the YAML is invalid.
- */
-export async function loadRecipe(source) {
-  if (!source) throw new Error('No recipe source provided');
-
-  // URL — fetch (auth attached if MyVillage host)
-  if (/^https?:\/\//i.test(source)) {
-    return loadRecipeFromUrl(source);
-  }
-
-  // Looks like a path — read from disk
-  if (source.includes('/') || source.includes('\\') || /\.(yaml|yml)$/i.test(source)) {
-    return loadRecipeFromFile(source);
-  }
-
-  // Bare name — pull from the MyVillage curated registry
-  return loadRecipeFromRegistry(source);
-}
-
-/**
- * List curated recipes available in the MyVillage registry. Requires
- * `myvillage login`. Returns an array of summaries:
- *   { name, description, kind, envVars, setup_help? }
- */
-export async function listRegistryRecipes() {
-  const url = `${getConfig().apiBaseUrl}/recipes`;
-  const res = await authedFetch(url);
-  if (!res.ok) {
-    throw await registryError(res, 'list recipes');
-  }
-  const body = await res.json();
-  // Hide retired recipes (e.g. the bot-token Slack MCP) so they never show up
-  // as an option — the OAuth provider path supersedes them.
-  return (body.recipes || []).filter(
-    (r) => !Object.hasOwn(DEPRECATED_REGISTRY_RECIPES, String(r?.name || '').toLowerCase()),
-  );
-}
-
-// ── Loaders ─────────────────────────────────────────────
-
-async function loadRecipeFromRegistry(name) {
-  const slug = String(name || '').toLowerCase();
-  if (Object.hasOwn(DEPRECATED_REGISTRY_RECIPES, slug)) {
-    throw new Error(deprecationMessage(slug, DEPRECATED_REGISTRY_RECIPES[slug]));
-  }
-  const url = `${getConfig().apiBaseUrl}/recipes/${encodeURIComponent(name)}`;
-  const res = await authedFetch(url);
-  if (!res.ok) {
-    throw await registryError(res, `fetch recipe "${name}"`);
-  }
-  const text = await res.text();
-  return validateRecipe(parseYaml(text), `registry:${name}`);
-}
-
-function loadRecipeFromFile(path) {
-  const abs = isAbsolute(path) ? path : join(process.cwd(), path);
-  if (!existsSync(abs)) {
-    throw new Error(`Recipe file not found: ${abs}`);
-  }
-  let parsed;
-  try {
-    parsed = parseYaml(readFileSync(abs, 'utf-8'));
-  } catch (err) {
-    throw new Error(`Failed to parse recipe at ${abs}: ${err.message}`);
-  }
-  return validateRecipe(parsed, abs);
-}
-
-async function loadRecipeFromUrl(url) {
-  // Attach the bearer token only if this URL is on a MyVillage host —
-  // sending it to a third-party URL would leak the developer's
-  // platform credentials.
-  const fetcher = isMyVillageHost(url) ? authedFetch : fetch;
-  let response;
-  try {
-    response = await fetcher(url, { redirect: 'follow' });
-  } catch (err) {
-    throw new Error(`Failed to fetch recipe from ${url}: ${err.message}`);
-  }
-  if (!response.ok) {
-    if (isMyVillageHost(url) && (response.status === 401 || response.status === 403)) {
-      throw new Error(`Recipe at ${url} requires authentication. Run 'myvillage login' first.`);
-    }
-    throw new Error(`Failed to fetch recipe from ${url}: HTTP ${response.status}`);
-  }
-  const text = await response.text();
-  let parsed;
-  try {
-    parsed = parseYaml(text);
-  } catch (err) {
-    throw new Error(`Failed to parse recipe from ${url}: ${err.message}`);
-  }
-  return validateRecipe(parsed, url);
-}
-
-// ── Auth ────────────────────────────────────────────────
-
-function isMyVillageHost(urlString) {
-  try {
-    const host = new URL(urlString).hostname;
-    return host === 'myvillageproject.ai' || host.endsWith('.myvillageproject.ai');
-  } catch {
-    return false;
-  }
-}
-
-async function authedFetch(url, options = {}) {
-  const token = getAccessToken();
-  const headers = { ...(options.headers || {}) };
-  if (token) headers['Authorization'] = `Bearer ${token}`;
-  return fetch(url, { ...options, headers });
-}
-
-async function registryError(response, action) {
-  let detail = '';
-  try {
-    const body = await response.json();
-    if (body?.error) detail = body.error;
-    if (body?.hint) detail += detail ? ` — ${body.hint}` : body.hint;
-  } catch {
-    // non-JSON body, ignore
-  }
-  if (response.status === 401) {
-    return new Error(`Could not ${action}: authentication required. Run 'myvillage login' first.`);
-  }
-  if (response.status === 404) {
-    return new Error(`Could not ${action}: not found in the MyVillage recipe registry.`);
-  }
-  return new Error(`Could not ${action}: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`);
-}
-
-// ── Validation ──────────────────────────────────────────
-
-function validateRecipe(recipe, sourceLabel) {
-  if (!recipe || typeof recipe !== 'object') {
-    throw new Error(`Recipe at ${sourceLabel} is empty or not a YAML object`);
-  }
-  if (!recipe.name || typeof recipe.name !== 'string') {
-    throw new Error(`Recipe at ${sourceLabel} is missing a "name" field`);
-  }
-
-  const hasCommand = typeof recipe.command === 'string' && recipe.command.length > 0;
-  const hasUrl = typeof recipe.url === 'string' && recipe.url.length > 0;
-  if (hasCommand && hasUrl) {
-    throw new Error(`Recipe "${recipe.name}" has both "command" and "url" — pick one`);
-  }
-  if (!hasCommand && !hasUrl) {
-    throw new Error(`Recipe "${recipe.name}" needs either a "command" (for local subprocess) or "url" (for remote MCP)`);
-  }
-
-  if (hasCommand && recipe.args && !Array.isArray(recipe.args)) {
-    throw new Error(`Recipe "${recipe.name}": "args" must be an array of strings`);
-  }
-  if (hasUrl && recipe.transport && !['http', 'sse'].includes(recipe.transport)) {
-    throw new Error(`Recipe "${recipe.name}": "transport" must be "http" or "sse"`);
-  }
-
-  if (recipe.env != null) {
-    if (typeof recipe.env !== 'object' || Array.isArray(recipe.env)) {
-      throw new Error(`Recipe "${recipe.name}": "env" must be a mapping of env-var-name to descriptor`);
-    }
-  }
-
-  return recipe;
-}
-
-// ── Recipe → tools.yaml entry ───────────────────────────
-
-/**
- * Translate a finalized recipe (with developer edits already applied)
- * into the server entry that goes under `servers:` in tools.yaml.
- */
-export function recipeToServerEntry(recipe) {
-  if (recipe.url) {
-    const entry = { url: recipe.url };
-    if (recipe.transport) entry.transport = recipe.transport;
-    if (recipe.headers && Object.keys(recipe.headers).length > 0) {
-      entry.headers = { ...recipe.headers };
-    }
-    if (recipe.description) entry.description = recipe.description;
-    return entry;
-  }
-
-  const entry = { command: recipe.command };
-  if (recipe.args && recipe.args.length > 0) entry.args = [...recipe.args];
-  if (recipe.env_vars && Object.keys(recipe.env_vars).length > 0) {
-    entry.env = { ...recipe.env_vars };
-  }
-  if (recipe.description) entry.description = recipe.description;
-  return entry;
-}
-
-/**
- * List of env-var names a recipe declares as needed. The wizard prints
- * these so the developer knows what to set in their .env / shell.
- */
-export function declaredEnvVars(recipe) {
-  if (!recipe.env || typeof recipe.env !== 'object') return [];
-  return Object.entries(recipe.env).map(([name, schema]) => ({
-    name,
-    description: schema?.description || '',
-    required: schema?.required !== false,
-  }));
-}
+// Old name              → New name (in connectors.js)
+//   loadRecipe          → loadConnector
+//   recipeToServerEntry → connectorToServerEntry
+//   listRegistryRecipes → listRegistryConnectors
+//   declaredEnvVars     → declaredEnvVars (unchanged)
+
+export {
+  loadConnector as loadRecipe,
+  connectorToServerEntry as recipeToServerEntry,
+  listRegistryConnectors as listRegistryRecipes,
+  declaredEnvVars,
+} from './connectors.js';