@myvillage/cli 1.83.0 → 1.85.0

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,
+  }));
+}