@myvillage/cli 1.46.1 → 1.48.3

package/package.json

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

package/src/agent-runtime/daemon-entry.js

@@ -17,7 +17,7 @@ process.on('beforeExit', (code) => {
   process.stderr.write(`[daemon-entry] BEFORE EXIT code=${code} — event loop emptied (likely a hung await inside agent setup)\n`);
 });
 
-import { writeFileSync, unlinkSync, existsSync, mkdirSync, appendFileSync } from 'fs';
+import { writeFileSync, unlinkSync, existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { agentLoop } from './loop.js';
@@ -33,6 +33,47 @@ const agentDir = join(homedir(), '.myvillage', 'agents', agentName);
 const pidFile = join(agentDir, 'daemon.pid');
 const logsDir = join(agentDir, 'logs');
 
+// Load per-agent .env file BEFORE anything reads tools.yaml / spawns MCPs.
+// MCP server env blocks reference these via ${ENV_VAR} substitution; the
+// mcp-client passes process.env into each subprocess, so loading them here
+// makes them visible to every MCP this agent spawns. Existing process.env
+// values (shell exports, parent process) take precedence — .env only fills
+// in what's missing, matching the conventional dotenv behavior.
+loadEnvFile(join(agentDir, '.env'));
+
+function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  let text;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch (err) {
+    process.stderr.write(`[daemon-entry] Could not read ${path}: ${err.message}\n`);
+    return;
+  }
+  // Minimal dotenv parser: KEY=value lines, # comments, blank lines.
+  // Values may be unquoted, single-quoted, or double-quoted. Backslash
+  // escapes are honored only inside double quotes.
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      const quote = value[0];
+      value = value.slice(1, -1);
+      if (quote === '"') {
+        value = value.replace(/\\n/g, '\n').replace(/\\r/g, '\r').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+      }
+    }
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+
 // Ensure logs dir exists
 if (!existsSync(logsDir)) {
   mkdirSync(logsDir, { recursive: true });

package/src/agent-runtime/mcp-client.js

@@ -110,9 +110,17 @@ export async function getMCPTools(agentDir, agentConfig) {
         // `/mcp-stdio` subpath and pass the instance.
         const { Experimental_StdioMCPTransport } =
           await import('@ai-sdk/mcp/mcp-stdio');
+        // Expand `${VAR}` in args too — some MCPs (e.g. @twilio-alpha/mcp)
+        // expect credentials as a positional CLI argument rather than env
+        // vars. Same substitution rules as `env` and `headers`.
+        const resolvedArgs = (server.args || []).map(arg =>
+          typeof arg === 'string'
+            ? arg.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] || '')
+            : arg,
+        );
         const stdioTransport = new Experimental_StdioMCPTransport({
           command: server.command,
-          args: server.args || [],
+          args: resolvedArgs,
           env: { ...process.env, ...resolveEnvVars(server.env || {}) },
         });
         client = await withTimeout(

package/src/commands/agent-local.js

@@ -116,13 +116,10 @@ export async function agentCreateLocalCommand() {
       {
         type: 'checkbox',
         name: 'tools',
-        message: 'Which tools should your agent have?',
+        message: 'Which built-in tools should your agent have? (you can add more later with `agent add-mcp`)',
         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 },
-          { name: 'Gmail', value: 'gmail' },
-          { name: 'Calendar', value: 'calendar' },
-          { name: 'GitHub', value: 'github' },
           { name: 'Browser (Puppeteer — downloads Chromium on first run)', value: 'browser' },
         ],
       },
@@ -211,9 +208,10 @@ export async function agentCreateLocalCommand() {
 
     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 start ${answers.name}`)}   Launch the agent`);
-    console.log(`    ${brand.gold(`myvillage agent edit ${answers.name}`)}    Customize the prompt`);
-    console.log(`    ${brand.gold(`myvillage agent logs ${answers.name}`)}    View activity\n`);
+    console.log(`    ${brand.gold(`myvillage agent add-mcp ${answers.name}`)}    Add a tool (Gmail, Slack, your own MCP, etc.)`);
+    console.log(`    ${brand.gold(`myvillage agent start ${answers.name}`)}     Launch the agent`);
+    console.log(`    ${brand.gold(`myvillage agent edit ${answers.name}`)}      Customize the prompt`);
+    console.log(`    ${brand.gold(`myvillage agent logs ${answers.name}`)}      View activity\n`);
   } catch (err) {
     if (err.isTtyError) {
       console.log(chalk.red('  \u2717 Prompts cannot be rendered in this environment.\n'));
@@ -736,8 +734,9 @@ export async function agentAddToolCommand(name, tool) {
 
   const validTools = Object.keys(TOOL_CATALOG).filter(t => t !== 'myvillage');
   if (!validTools.includes(tool)) {
-    console.log(chalk.red(`  \u2717 Unknown tool "${tool}".`));
-    console.log(brand.teal(`  Available tools: ${validTools.join(', ')}\n`));
+    console.log(chalk.red(`  \u2717 Unknown built-in tool "${tool}".`));
+    console.log(brand.teal(`  Built-in tools: ${validTools.join(', ')}`));
+    console.log(brand.teal(`  For Gmail, Slack, Twilio, custom MCPs, etc. use: ${chalk.bold(`myvillage agent add-mcp ${name}`)}\n`));
     return;
   }
 
@@ -758,9 +757,6 @@ export async function agentAddToolCommand(name, tool) {
     const workspace = join(homedir(), '.myvillage', 'agents', name, 'workspace');
     console.log(brand.teal(`  Workspace: ${workspace}`));
   }
-  if (tool === 'github') {
-    console.log(brand.teal('  Note: Set GITHUB_TOKEN in your environment for GitHub access.'));
-  }
 
   if (isDaemonRunning(name)) {
     console.log(chalk.yellow('  Restart the agent to apply: myvillage agent stop ' + name + ' && myvillage agent start ' + name));

package/src/commands/agent-mcp.js

@@ -0,0 +1,357 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { brand } from '../utils/brand.js';
+import {
+  agentExists,
+  readToolsYaml,
+  writeToolsYaml,
+  isDaemonRunning,
+} from '../utils/local-agent.js';
+import {
+  loadRecipe,
+  listRegistryRecipes,
+  recipeToServerEntry,
+  declaredEnvVars,
+} from '../utils/recipes.js';
+import { isAuthenticated } from '../utils/auth.js';
+
+// ── add-mcp ─────────────────────────────────────────────
+//
+// 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
+// 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
+// scripts and CI).
+
+export async function agentAddMcpCommand(agentName, sourceArg, options = {}) {
+  if (!agentExists(agentName)) {
+    console.log(chalk.red(`  ✗ Agent "${agentName}" not found. Run 'myvillage agent' to see your agents.\n`));
+    return;
+  }
+
+  const source = sourceArg || options.from || null;
+  const nonInteractive = options.yes === true;
+
+  let recipe = null;
+  if (source) {
+    try {
+      recipe = await loadRecipe(source);
+      console.log(brand.teal(`  Loaded recipe: "${recipe.name}"${recipe.description ? ` — ${chalk.dim(recipe.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'));
+    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
+  // scratch starting with the local-vs-remote choice.
+  let finalized;
+  try {
+    finalized = nonInteractive
+      ? recipe
+      : await walkWizard(recipe);
+  } 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'));
+      return;
+    }
+    console.log(chalk.red(`  ✗ ${err.message}\n`));
+    return;
+  }
+
+  if (!finalized) {
+    console.log(brand.teal('  Cancelled.\n'));
+    return;
+  }
+
+  // Check for name collisions in tools.yaml
+  const toolsConfig = readToolsYaml(agentName);
+  toolsConfig.servers = toolsConfig.servers || {};
+  if (toolsConfig.servers[finalized.name]) {
+    if (!nonInteractive) {
+      const { overwrite } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Server "${finalized.name}" already exists in this agent's tools.yaml. Overwrite?`,
+        default: false,
+      }]);
+      if (!overwrite) {
+        console.log(brand.teal('  Cancelled.\n'));
+        return;
+      }
+    } else {
+      console.log(chalk.yellow(`  Overwriting existing server "${finalized.name}".`));
+    }
+  }
+
+  toolsConfig.servers[finalized.name] = recipeToServerEntry(finalized);
+  writeToolsYaml(agentName, toolsConfig);
+
+  console.log(brand.green(`  ✓ Added "${finalized.name}" to agent "${agentName}".`));
+
+  const envVars = declaredEnvVars(finalized);
+  if (envVars.length > 0) {
+    console.log(brand.teal('\n  Env vars this MCP expects:'));
+    for (const v of envVars) {
+      const reqLabel = v.required ? chalk.bold('required') : 'optional';
+      const desc = v.description ? ` — ${v.description}` : '';
+      console.log(`    ${chalk.cyan(v.name)} (${reqLabel})${desc}`);
+    }
+    console.log(brand.teal(`\n  Set them in ~/.myvillage/agents/${agentName}/.env (recommended) or your shell.`));
+  }
+
+  if (finalized.setup_help) {
+    console.log(brand.teal(`  Setup help: ${finalized.setup_help}`));
+  }
+
+  if (isDaemonRunning(agentName)) {
+    console.log(chalk.yellow(`\n  Restart the agent to apply: myvillage agent stop ${agentName} && myvillage agent start ${agentName}`));
+  }
+  console.log('');
+}
+
+// ── Wizard ──────────────────────────────────────────────
+
+async function walkWizard(recipe) {
+  // If no recipe, ask the developer what kind of MCP they're adding
+  if (!recipe) {
+    const { kind } = await inquirer.prompt([{
+      type: 'list',
+      name: 'kind',
+      message: 'Is this MCP a local subprocess (npm package, binary) or a remote URL?',
+      choices: [
+        { name: 'Local subprocess (most npm-distributed MCPs like @some/mcp-thing)', value: 'local' },
+        { name: 'Remote URL (e.g. https://mcp.example.com)', value: 'remote' },
+      ],
+    }]);
+    recipe = { name: '', description: '', env: {} };
+    if (kind === 'remote') recipe.url = '';
+    else recipe.command = 'npx';
+  }
+
+  const isRemote = !!recipe.url;
+
+  // Common fields
+  const baseAnswers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Server name (key in tools.yaml):',
+      default: recipe.name || undefined,
+      validate: v => /^[a-z0-9_-]+$/i.test((v || '').trim()) || 'lowercase letters, digits, dashes, underscores only',
+      filter: v => v.trim(),
+    },
+    {
+      type: 'input',
+      name: 'description',
+      message: 'Description (optional, shown in tools.yaml):',
+      default: recipe.description || '',
+      filter: v => v.trim(),
+    },
+  ]);
+
+  if (isRemote) {
+    return await walkRemoteWizard(recipe, baseAnswers);
+  }
+  return await walkLocalWizard(recipe, baseAnswers);
+}
+
+async function walkLocalWizard(recipe, baseAnswers) {
+  const argsDefault = (recipe.args || []).join(' ');
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'command',
+      message: 'Command:',
+      default: recipe.command || 'npx',
+      validate: v => v.trim().length > 0 || 'command is required',
+      filter: v => v.trim(),
+    },
+    {
+      type: 'input',
+      name: 'argsRaw',
+      message: 'Args (space-separated):',
+      default: argsDefault,
+      filter: v => v.trim(),
+    },
+    {
+      type: 'input',
+      name: 'envNamesRaw',
+      message: 'Env vars this MCP needs (comma-separated, leave blank for none):',
+      default: Object.keys(recipe.env || {}).join(', '),
+      filter: v => v.trim(),
+    },
+  ]);
+
+  const args = answers.argsRaw ? answers.argsRaw.split(/\s+/) : [];
+  const envNames = answers.envNamesRaw
+    ? answers.envNamesRaw.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
+
+  // Build env schema — preserve recipe-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 };
+  }
+
+  return {
+    ...recipe,
+    ...baseAnswers,
+    command: answers.command,
+    args,
+    env,
+  };
+}
+
+async function walkRemoteWizard(recipe, baseAnswers) {
+  const headerEntries = Object.entries(recipe.headers || {});
+  const defaultAuth = headerEntries.some(([k]) => /^authorization$/i.test(k)) ? 'bearer'
+    : headerEntries.length > 0 ? 'custom' : 'none';
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'url',
+      message: 'URL:',
+      default: recipe.url || '',
+      validate: v => /^https?:\/\//i.test((v || '').trim()) || 'must start with http:// or https://',
+      filter: v => v.trim(),
+    },
+    {
+      type: 'list',
+      name: 'authKind',
+      message: 'Authentication:',
+      choices: [
+        { name: 'None', value: 'none' },
+        { name: 'Bearer token (Authorization: Bearer ${VAR})', value: 'bearer' },
+        { name: 'Custom header(s)', value: 'custom' },
+      ],
+      default: defaultAuth,
+    },
+  ]);
+
+  let headers = {};
+  let env = {};
+
+  if (answers.authKind === 'bearer') {
+    const { envVarName } = await inquirer.prompt([{
+      type: 'input',
+      name: 'envVarName',
+      message: 'Env var name that will hold the token:',
+      default: pickFirstEnvVarName(recipe) || '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 } };
+  } else if (answers.authKind === 'custom') {
+    const { headersRaw } = await inquirer.prompt([{
+      type: 'input',
+      name: 'headersRaw',
+      message: 'Headers (comma-separated "Header-Name=value-or-\\${ENV}"):',
+      default: headerEntries.map(([k, v]) => `${k}=${v}`).join(', '),
+      filter: v => v.trim(),
+    }]);
+    headers = parseHeaderList(headersRaw);
+
+    // Any ${VAR} reference in the values implies that env var is needed
+    const envNamesFromHeaders = new Set();
+    for (const v of Object.values(headers)) {
+      const matches = String(v).matchAll(/\$\{([A-Z_][A-Z0-9_]*)\}/gi);
+      for (const m of matches) envNamesFromHeaders.add(m[1]);
+    }
+    for (const name of envNamesFromHeaders) {
+      env[name] = recipe.env?.[name] || { description: '', required: true };
+    }
+  }
+
+  return {
+    ...recipe,
+    ...baseAnswers,
+    url: answers.url,
+    transport: recipe.transport || 'http',
+    headers,
+    env,
+  };
+}
+
+function pickFirstEnvVarName(recipe) {
+  if (!recipe.env || typeof recipe.env !== 'object') return null;
+  return Object.keys(recipe.env)[0] || null;
+}
+
+function parseHeaderList(raw) {
+  const headers = {};
+  if (!raw) return headers;
+  for (const piece of raw.split(',')) {
+    const [k, ...rest] = piece.split('=');
+    const name = (k || '').trim();
+    const value = rest.join('=').trim();
+    if (name && value) headers[name] = value;
+  }
+  return headers;
+}
+
+// ── list-mcp ────────────────────────────────────────────
+
+export async function agentListMcpCommand(agentName) {
+  if (!agentExists(agentName)) {
+    console.log(chalk.red(`  ✗ Agent "${agentName}" not found.\n`));
+    return;
+  }
+  const toolsConfig = readToolsYaml(agentName);
+  const servers = Object.entries(toolsConfig.servers || {});
+  if (servers.length === 0) {
+    console.log(brand.teal(`  No MCP servers configured for "${agentName}".\n`));
+    return;
+  }
+  console.log(brand.teal(`\n  MCP servers for "${agentName}":\n`));
+  for (const [name, server] of servers) {
+    const kind = server.url ? `remote (${server.url})` : `local (${server.command} ${(server.args || []).join(' ')})`;
+    console.log(`  ${chalk.bold(name)}`);
+    console.log(`    ${chalk.dim(kind)}`);
+    if (server.description) console.log(`    ${chalk.dim(server.description)}`);
+  }
+  console.log('');
+}
+
+// ── recipes ─────────────────────────────────────────────
+
+export async function recipesListCommand() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  ✗ Authentication required. Run 'myvillage login' first.\n"));
+    return;
+  }
+
+  let recipes;
+  try {
+    recipes = await listRegistryRecipes();
+  } catch (err) {
+    console.log(chalk.red(`  ✗ ${err.message}\n`));
+    return;
+  }
+
+  if (recipes.length === 0) {
+    console.log(brand.teal('  The recipe 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  External recipes: install with `--from <path-or-url>`.\n'));
+}

package/src/index.js

@@ -66,11 +66,6 @@ import {
   agentRecallCommand,
   agentRememberCommand,
 } from './commands/agent-local.js';
-import {
-  agentGrantCommand,
-  agentRevokeCommand,
-  agentGrantsCommand,
-} from './commands/agent-grant.js';
 import {
   agentRegisterClientCommand,
   agentListClientsCommand,
@@ -79,6 +74,11 @@ import {
   agentDeactivateClientCommand,
   agentRotateClientKeyCommand,
 } from './commands/agent-client.js';
+import {
+  agentAddMcpCommand,
+  agentListMcpCommand,
+  recipesListCommand,
+} from './commands/agent-mcp.js';
 import {
   gameUpdateCommand,
   gameUploadThumbnailCommand,
@@ -467,7 +467,7 @@ export function run() {
 
   agentCmd
     .command('add-tool <name> <tool>')
-    .description('Add an MCP server tool to a local agent')
+    .description('Add a built-in tool (filesystem, browser) — for everything else (Gmail, GitHub, Slack, custom MCPs) use `add-mcp`')
     .action(agentAddToolCommand);
 
   agentCmd
@@ -475,6 +475,25 @@ 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).
+  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));
+
+  agentCmd
+    .command('list-mcp <name>')
+    .description('List the MCP servers currently configured for an agent')
+    .action(agentListMcpCommand);
+
+  program
+    .command('recipes')
+    .description('List the MCP recipes bundled with the CLI')
+    .action(recipesListCommand);
+
   // Task queue commands — assign and inspect work for a developer's agent
   agentCmd
     .command('task-list <name>')
@@ -523,21 +542,6 @@ export function run() {
     .option('--sharing <option>', 'PRIVATE | VILLAGE_ONLY | PUBLIC', 'PRIVATE')
     .action(agentRememberCommand);
 
-  // Per-agent OAuth credential grants
-  agentCmd
-    .command('grants <name>')
-    .description('List active OAuth credential grants for a local agent')
-    .action(agentGrantsCommand);
-
-  agentCmd
-    .command('grant <name> <provider>')
-    .description('Grant the agent access to a connected OAuth provider (google|microsoft|zoom)')
-    .action(agentGrantCommand);
-
-  agentCmd
-    .command('revoke <name> <provider>')
-    .description('Revoke an OAuth provider grant from the agent')
-    .action(agentRevokeCommand);
 
   // Client agent registration commands
   agentCmd

package/src/utils/agent-scaffolder.js

@@ -5,44 +5,39 @@ import { stringify as stringifyYaml } from 'yaml';
 
 // ── MCP Tool Catalog ────────────────────────────────────
 //
-// Static-shape entries. The `filesystem` entry's allow-listed root is
-// resolved per-agent at scaffold/add-tool time — see
-// resolveCatalogEntry() — so each agent gets its own sandboxed workspace.
+// Minimal entries the scaffold wizard surfaces by default. These are the
+// MCPs that need no third-party credential at all (myvillage uses the
+// developer's existing platform OAuth session; filesystem/browser use
+// local-machine resources only; github uses an env var the developer sets
+// themselves).
+//
+// Everything else — Gmail, Slack, Twilio, custom remote MCPs, anything new
+// the community ships — lives as a "recipe" under src/recipes/ that the
+// developer installs via `myvillage agent add-mcp` after creation. See
+// src/utils/recipes.js.
 
 const TOOL_CATALOG = {
+
   myvillage: {
     url: 'https://mcp.myvillageproject.ai',
     description: 'MyVillageOS platform access (feed, posts, communities, wallet, knowledge)',
     always_enabled: true,
   },
+
   filesystem: {
     command: 'npx',
     // Last arg is a placeholder; replaced with `<agentDir>/workspace`
-    // by resolveCatalogEntry().
+    // by resolveCatalogEntry() at scaffold time.
     args: ['-y', '@modelcontextprotocol/server-filesystem', '__AGENT_WORKSPACE__'],
     description: 'Read/write files under the agent\'s sandboxed workspace',
   },
-  gmail: {
-    command: 'npx',
-    args: ['-y', '@anthropic/mcp-gmail'],
-    description: 'Read and search Gmail',
-  },
-  calendar: {
-    command: 'npx',
-    args: ['-y', '@anthropic/mcp-google-calendar'],
-    description: 'Read events, check availability, create reminders',
-  },
-  github: {
-    command: 'npx',
-    args: ['-y', '@modelcontextprotocol/server-github'],
-    env: { GITHUB_TOKEN: '${GITHUB_TOKEN}' },
-    description: 'GitHub repository access',
-  },
+
   browser: {
     command: 'npx',
     args: ['-y', '@modelcontextprotocol/server-puppeteer'],
     description: 'Navigate web pages, extract content (downloads Chromium on first run)',
   },
+
 };
 
 export { TOOL_CATALOG };
@@ -50,12 +45,9 @@ export { TOOL_CATALOG };
 // ── Catalog Resolution ──────────────────────────────────
 
 /**
- * Returns a deep-copied catalog entry with per-agent placeholders
- * resolved (e.g. the filesystem workspace path). Also creates any
- * directories the entry depends on (the workspace dir for filesystem).
- *
- * Use this anywhere you'd otherwise do `{ ...TOOL_CATALOG[toolId] }`
- * to write into a tools.yaml.
+ * Returns a deep-copied catalog entry with per-agent placeholders resolved
+ * (e.g. the filesystem workspace path). Also creates any directories the
+ * entry depends on (the workspace dir for filesystem).
  */
 export function resolveCatalogEntry(toolId, agentName) {
   const entry = TOOL_CATALOG[toolId];
@@ -89,32 +81,55 @@ const INTERVAL_MAP = {
 export function scaffoldAgent(agentDir, options) {
   const { name, displayName, description, tools, checkInInterval, provider, model } = options;
 
-  // Create directories
   mkdirSync(join(agentDir, 'routines'), { recursive: true });
   mkdirSync(join(agentDir, 'logs'), { recursive: true });
 
-  // Write agent.config.yaml
   writeFileSync(
     join(agentDir, 'agent.config.yaml'),
-    generateAgentConfig({ name, displayName, description, checkInInterval, provider, model })
+    generateAgentConfig({ name, displayName, description, checkInInterval, provider, model }),
   );
 
-  // Write prompt.md
   writeFileSync(
     join(agentDir, 'prompt.md'),
-    generatePromptMd()
+    generatePromptMd(),
   );
 
-  // Write tools.yaml
   writeFileSync(
     join(agentDir, 'tools.yaml'),
-    generateToolsYaml(tools, name)
+    generateToolsYaml(tools, name),
+  );
+
+  // A starter .env file for the developer to populate. Tools/recipes that
+  // need credentials (Gmail token, Slack bot token, Twilio SID/auth, custom
+  // headers for remote MCPs) read env vars from this file at agent start.
+  // Gitignore-able by convention — it's plaintext on the developer's machine
+  // and isn't transmitted anywhere.
+  writeFileSync(
+    join(agentDir, '.env'),
+    starterEnvFile(),
+    { mode: 0o600 },
   );
 
-  // Write logs/.gitkeep
   writeFileSync(join(agentDir, 'logs', '.gitkeep'), '');
 }
 
+function starterEnvFile() {
+  return [
+    '# Agent-scoped environment variables.',
+    '# The daemon loads this file at startup and merges its values into the',
+    '# environment of every MCP subprocess it spawns. Use it for tokens, API',
+    '# keys, and any other secret your tools (or remote MCPs) need.',
+    '#',
+    '# Examples:',
+    '#   GITHUB_TOKEN=ghp_xxxxxxxxxxxx',
+    '#   GMAIL_TOKEN=xxxxxxxxxxxx',
+    '#   SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx',
+    '#',
+    '# This file is plaintext — keep it out of version control.',
+    '',
+  ].join('\n');
+}
+
 // ── Config Generation ───────────────────────────────────
 
 function generateAgentConfig({ name, displayName, description, checkInInterval, provider, model }) {
@@ -159,10 +174,6 @@ function generateAgentConfig({ name, displayName, description, checkInInterval,
 // ── Prompt Generation ───────────────────────────────────
 
 function generatePromptMd() {
-  // Identity (display name + description) lives in agent.config.yaml and is
-  // prepended automatically by the runtime loop on every iteration. This file
-  // is the persona body only — Voice, behavior rules, examples. To change the
-  // agent's name or one-line description, edit agent.config.yaml and restart.
   return `<!-- Starter prompt — replace the specifics below with what makes this agent
      yours. Keep the section structure (Voice / What you do / What you don't
      do / Examples) — it follows the recommended shape in the docs:

package/src/utils/recipes.js

@@ -0,0 +1,248 @@
+// ── MCP Recipes ─────────────────────────────────────────
+//
+// 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`.
+//
+// `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';
+
+// ── 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();
+  return body.recipes || [];
+}
+
+// ── Loaders ─────────────────────────────────────────────
+
+async function loadRecipeFromRegistry(name) {
+  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,
+  }));
+}

package/src/commands/agent-grant.js

@@ -1,131 +0,0 @@
-import chalk from 'chalk';
-import { isAuthenticated } from '../utils/auth.js';
-import { readAgentConfig } from '../utils/local-agent.js';
-import { getPlatformClient } from '../utils/api.js';
-
-const VALID_PROVIDERS = ['google', 'microsoft', 'zoom'];
-
-function ensureAuthed() {
-  if (!isAuthenticated()) {
-    console.log(chalk.red("  ✗ Authentication required. Run 'myvillage login' first."));
-    return false;
-  }
-  return true;
-}
-
-function resolveAgentId(name) {
-  const config = readAgentConfig(name);
-  if (!config) {
-    console.log(chalk.red(`  ✗ Local agent "${name}" not found`));
-    return null;
-  }
-  const agentId = config?.man?.agent_id;
-  if (!agentId) {
-    console.log(
-      chalk.red(
-        `  ✗ Agent "${name}" has not been registered on the platform yet. ` +
-          `Run 'myvillage agent start ${name}' once to register it.`,
-      ),
-    );
-    return null;
-  }
-  return agentId;
-}
-
-function normalizeProvider(provider) {
-  const lc = (provider || '').toLowerCase();
-  if (!VALID_PROVIDERS.includes(lc)) {
-    console.log(
-      chalk.red(`  ✗ Invalid provider "${provider}". Must be one of: ${VALID_PROVIDERS.join(', ')}`),
-    );
-    return null;
-  }
-  return lc.toUpperCase();
-}
-
-function printApiError(err, fallback) {
-  const status = err?.response?.status;
-  const data = err?.response?.data;
-  const code = data?.code ? ` (${data.code})` : '';
-  const message = data?.error || err?.message || fallback;
-  console.log(chalk.red(`  ✗ ${message}${code}${status ? ` [HTTP ${status}]` : ''}`));
-}
-
-// ── List grants ────────────────────────────────────────────
-
-export async function agentGrantsCommand(name) {
-  if (!ensureAuthed()) return;
-  const agentId = resolveAgentId(name);
-  if (!agentId) return;
-
-  const client = getPlatformClient();
-  try {
-    const response = await client.get(`/agents/${agentId}/credential-grants`);
-    const grants = response.data?.data ?? [];
-    if (grants.length === 0) {
-      console.log(chalk.dim(`  No active credential grants for agent "${name}".`));
-      console.log(chalk.dim(`  Grant one with: myvillage agent grant ${name} <google|microsoft|zoom>`));
-      return;
-    }
-    console.log(chalk.bold(`Active credential grants for "${name}" (${agentId}):\n`));
-    for (const g of grants) {
-      const granted = new Date(g.grantedAt).toISOString().slice(0, 10);
-      console.log(`  - ${chalk.cyan(g.provider)}  granted ${granted}`);
-    }
-  } catch (err) {
-    printApiError(err, 'Failed to list grants');
-  }
-}
-
-// ── Grant a provider ───────────────────────────────────────
-
-export async function agentGrantCommand(name, provider) {
-  if (!ensureAuthed()) return;
-  const agentId = resolveAgentId(name);
-  if (!agentId) return;
-  const upperProvider = normalizeProvider(provider);
-  if (!upperProvider) return;
-
-  const client = getPlatformClient();
-  try {
-    await client.post(`/agents/${agentId}/credential-grants`, { provider: upperProvider });
-    console.log(
-      chalk.green(`  ✓ Granted ${upperProvider} to agent "${name}".`) +
-        chalk.dim(`\n    The agent can now use ${upperProvider}-backed tools (e.g. gmail_send).`),
-    );
-  } catch (err) {
-    if (err?.response?.status === 404 && err?.response?.data?.code === 'CREDENTIAL_NOT_CONNECTED') {
-      console.log(
-        chalk.yellow(
-          `  ⚠ You haven't connected ${upperProvider} yet. ` +
-            `Connect it from the mobile app or web portal, then re-run this command.`,
-        ),
-      );
-      return;
-    }
-    printApiError(err, 'Failed to grant provider');
-  }
-}
-
-// ── Revoke a provider ──────────────────────────────────────
-
-export async function agentRevokeCommand(name, provider) {
-  if (!ensureAuthed()) return;
-  const agentId = resolveAgentId(name);
-  if (!agentId) return;
-  const upperProvider = normalizeProvider(provider);
-  if (!upperProvider) return;
-
-  const client = getPlatformClient();
-  try {
-    await client.delete(`/agents/${agentId}/credential-grants/${upperProvider}`);
-    console.log(
-      chalk.green(`  ✓ Revoked ${upperProvider} from agent "${name}".`) +
-        chalk.dim(
-          `\n    Tools using ${upperProvider} will fail within ~60 seconds (cache TTL).`,
-        ),
-    );
-  } catch (err) {
-    printApiError(err, 'Failed to revoke provider');
-  }
-}