factoryhub 0.0.0-stage → 0.1.0

package/factories/outreach-pack/flow.yaml

@@ -0,0 +1,42 @@
+flow: mindburn.flow/v1
+title: Outreach pack
+version: "1.0.0"
+author: Mindburn Labs
+license: MIT
+tags: [sales, launch]
+inputs:
+  research:
+    type: longtext
+    help: Source-linked market research with uncertainties preserved.
+  launch_materials:
+    type: longtext
+    help: Approved positioning and checked launch materials.
+  contact_role:
+    type: text
+    optional: true
+    help: The role you want to reach.
+steps:
+  angles:
+    title: Find the outreach angle
+    agent: writer
+    kind: work
+    task: |
+      Use the supplied launch_materials and research to identify two honest reasons the contact_role might care. Each must tie to a supported problem, the approved promise, and a source when based on market research. Never invent a prospect, a personal fact, a customer result, a contact address or a claim.
+  pack:
+    title: Write the outreach pack
+    agent: writer
+    kind: deliver
+    needs: [angles]
+    task: |
+      Produce a reusable outreach pack with: the chosen angle and evidence; two subject lines of at most four words; a first email under 110 words with one small question; a follow-up under 60 words adding a supported point; a short direct message under 60 words; and a before-sending checklist. Use explicit [ADD: ...] placeholders for the real recipient, their verified situation and missing facts. Preserve the approved product promise. State that no messages have been sent and no contacts have been collected. This is a draft for human review, not an active campaign.
+  review:
+    title: Check the outreach pack
+    agent: reviewer
+    kind: check
+    needs: [pack]
+    checks: pack
+    task: |
+      Every product claim matches launch_materials. Every market claim matches research and keeps its source. No personal detail, email address, customer result or recipient-specific claim is invented. Required sections and word limits are met. Placeholders remain explicit. The pack says messages have not been sent.
+done:
+  - Every claim is supported by the supplied research or launch materials.
+  - Recipient details that are not known remain explicit placeholders.

package/factories/prospect-brief/README.md

@@ -0,0 +1,3 @@
+# Prospect brief and first email
+
+Give it a company and what you sell. It reads the company's own site and recent public news, finds the reasons they might care right now, lets you pick the angle, and writes an email a person would actually answer. Nothing is sent: you get the drafts.

package/factories/prospect-brief/agents/researcher/agent.md

@@ -0,0 +1,11 @@
+---
+description: Finds and reads the sources, and reports only what they say.
+agentType: CUSTOM
+---
+
+You are the researcher. You find the right pages, read them carefully and write down what they actually say.
+
+- Quote headlines, prices and claims exactly, and put the page address after every fact.
+- Read the pages you were asked for before looking further. Stay within the page budget you are given.
+- A gap is a finding. When a page cannot be read or a fact is not published, write that down plainly instead of filling it from memory.
+- You do not judge or recommend. The analyst and the writer do that from your notes.

package/factories/prospect-brief/agents/reviewer/agent.md

@@ -0,0 +1,10 @@
+---
+description: Checks work against stated criteria and sends weak work back.
+agentType: REVIEW
+---
+
+You are the reviewer. You hold one piece of work against the criteria you are given and decide whether it passes.
+
+- You judge only what is on the page and only against the stated criteria.
+- You fail work for a clear, specific breach you can point to. You never fail it for taste, or for something nobody asked for.
+- When you send work back, each reason is one concrete sentence the author can act on.

package/factories/prospect-brief/agents/strategist/agent.md

@@ -0,0 +1,10 @@
+---
+description: Chooses the angle: what to say, to whom, and why it should work.
+agentType: CUSTOM
+---
+
+You are the strategist. From the facts in hand you choose the angle: who this is for, what to promise, and which facts make it believable.
+
+- You offer a clear first choice and real alternatives, and you say which facts you are least sure of.
+- You use only facts from the inputs and earlier steps. A stronger claim that the facts do not support is not an option.
+- The person decides. You make their decision easy to take.

package/factories/prospect-brief/agents/writer/agent.md

@@ -0,0 +1,11 @@
+---
+description: Writes the finished words the person will use or send.
+agentType: CUSTOM
+---
+
+You are the writer. You write the finished thing the person will use: the brief, the message, the page, the report.
+
+- Plain words, short sentences, the reader's own vocabulary. No filler and no hype.
+- You keep to the sections, word limits and order the step asks for.
+- You add no fact that is not in the inputs or earlier results. Where a real asset or decision is missing, you mark the gap clearly instead of inventing it.
+- What you write should be usable as it stands.

package/factories/prospect-brief/factory.yaml

@@ -0,0 +1,11 @@
+schemaVersion: v1alpha1
+name: prospect-brief
+description: |
+  Researches one company you want to sell to and writes a one-page brief plus
+  a first email and follow-up that mention real, checkable facts about them.
+  Use before reaching out to an account that matters.
+repositories: []
+agentDefaults:
+  harness:
+    type: claude
+    model: sonnet

package/factories/prospect-brief/flow.yaml

@@ -0,0 +1,79 @@
+flow: mindburn.flow/v1
+title: Prospect brief and first email
+author: Mindburn Labs
+version: "1.1.0"
+license: MIT
+tags: [sales, research]
+time: about 4 minutes
+inputs:
+  prospect:
+    type: url
+    help: "The website of the company you want to reach."
+  what_you_sell:
+    type: longtext
+    help: "What you offer and who it helps, in a few sentences. Include one real result if you have one."
+  contact_role:
+    type: text
+    optional: true
+    help: "Who you plan to write to, for example \"head of operations\"."
+steps:
+  company_facts:
+    title: Read the company's own site
+    agent: researcher
+    kind: work
+    tools: [web_fetch]
+    task: |
+      Read the prospect's home page and, from its links, the about page and one product or careers page.
+
+      Write: what the company does and for whom, its size signals (team size, locations, customers named), and what it says it cares about now (launches, hiring, expansion, stated priorities). Put the page address after every fact. If you find little, say so; do not pad.
+  recent_news:
+    title: Find recent news
+    agent: researcher
+    kind: work
+    tools: [web_search, web_fetch]
+    needs: []
+    task: |
+      Search for news about the prospect company from the last twelve months and read up to two results. Prefer the company's own announcements and established publications.
+
+      List each item with its date, what happened in one sentence, and the page address. Leave out anything you cannot date or that is about a different company with a similar name. If there is no recent news, say so plainly.
+  angles:
+    title: Find the angle
+    agent: strategist
+    kind: work
+    needs: [company_facts, recent_news]
+    task: |
+      From the company facts, the recent news and what_you_sell, propose three angles for a first message. For each: the trigger (a specific fact about them, with its link), why it plausibly matters to the contact_role, and the one-sentence bridge to what you sell. Rank them, strongest first, and say which facts you are least sure of. If the research supports fewer than three honest angles, give fewer.
+  approve_angles:
+    title: Pick the angle
+    kind: approve
+    needs: [angles]
+    shows: angles
+    task: |
+      Choose the angle to write from. Approve to use the first one, or say which one you want and anything you know about this company that the research missed.
+  email:
+    title: Write the email
+    agent: writer
+    kind: work
+    needs: [approve_angles]
+    task: |
+      Write the first email using the chosen angle. Rules: under 110 words, plain text, no greeting clichés, first sentence is about them and names the trigger fact, one sentence on what you do, one concrete result only if what_you_sell gave one, and one small question as the ask. Then write a follow-up of under 60 words for four days later that adds one new fact instead of repeating. Give two subject lines of four words or fewer.
+  brief:
+    title: Assemble the brief
+    agent: writer
+    kind: deliver
+    needs: [email]
+    task: |
+      Write one page with these sections: **Company in three lines**, **Why now** (the chosen angle and its source link), **Email** (subject lines, first email, follow-up, ready to paste), **If they reply** (three likely questions and a one-line honest answer to each, using only what_you_sell), **Sources** (every page used, as links).
+  check_email:
+    title: Check the brief
+    agent: reviewer
+    kind: check
+    needs: [brief]
+    checks: brief
+    task: |
+      Every fact about the prospect in the entire brief appears in the company facts or recent news and has a source link. Seller claims and answers use only what_you_sell. The chosen angle is preserved. The first email and follow-up meet their word limits, with one ask each and subject lines of four words or fewer. No flattery, greeting cliches or exclamation marks. All requested sections and sources are present.
+
+done:
+  - "Every fact about the prospect has a source link."
+  - "The email could be sent as it stands."
+  - "Nothing claims a result the seller did not state."

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "factoryhub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "AI factories, shared: the open factory format, its engine, a CLI and a local MCP server, with the house factories.",
+  "keywords": [
+    "factoryhub",
+    "ai-factories",
+    "ai-agents",
+    "agent-skills",
+    "human-in-the-loop",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "cli",
+    "anthropic",
+    "openai",
+    "openrouter",
+    "ollama"
+  ],
+  "license": "Apache-2.0",
+  "author": "Mindburn Labs (https://mindburn.org)",
+  "type": "module",
+  "homepage": "https://github.com/Mindburn-Labs/factoryhub#readme",
+  "bugs": "https://github.com/Mindburn-Labs/factoryhub/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mindburn-Labs/factoryhub.git"
+  },
+  "mcpName": "io.github.Mindburn-Labs/factoryhub",
+  "engines": {
+    "node": ">=22"
+  },
+  "workspaces": [
+    "packages/engine",
+    "packages/cli",
+    "packages/mcp"
+  ],
+  "bin": {
+    "factoryhub": "packages/cli/bin/factoryhub.mjs",
+    "factoryhub-mcp": "packages/mcp/bin/factoryhub-mcp.mjs"
+  },
+  "files": [
+    "packages/engine/package.json",
+    "packages/engine/src",
+    "packages/engine/lib",
+    "packages/cli/package.json",
+    "packages/cli/bin",
+    "packages/cli/src",
+    "packages/mcp/package.json",
+    "packages/mcp/bin",
+    "packages/mcp/src",
+    "factories",
+    "NOTICE",
+    "spec/*.md",
+    "spec/schema"
+  ],
+  "scripts": {
+    "test": "node --test \"packages/*/test/*.test.mjs\" \"spec/test/*.test.mjs\" \"test/*.test.mjs\"",
+    "lint": "eslint . && node scripts/check-links.mjs",
+    "validate": "node packages/cli/bin/factoryhub.mjs validate factories/*/",
+    "generate": "node scripts/generate.mjs",
+    "check": "npm run lint && npm test && npm run validate && node scripts/generate.mjs --check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/client": "2.4.0",
+    "ajv": "8.20.0",
+    "eslint": "10.15.0",
+    "globals": "17.14.0",
+    "yaml": "2.9.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/packages/cli/bin/factoryhub.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { main } from '../src/main.mjs';
+
+// A reader that stops early, such as `| head`, is not an error.
+process.stdout.on('error', (error) => { if (error.code === 'EPIPE') process.exit(0); throw error; });
+
+process.exitCode = await main(process.argv.slice(2));

package/packages/cli/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@factoryhub/cli",
+  "version": "0.1.0",
+  "description": "The factoryhub command line: validate, inspect, scaffold, pack, run and export AI factories, and find them on factoryhub.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mindburn-Labs/factoryhub.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "factoryhub": "bin/factoryhub.mjs"
+  },
+  "exports": {
+    ".": "./src/main.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}

package/packages/cli/src/args.mjs

@@ -0,0 +1,47 @@
+// A small argument parser: positional words, --name value, --name=value,
+// boolean switches and repeatable options. Unknown options are an error, so a
+// misspelt option never silently changes what a command does.
+
+/**
+ * @param {string[]} argv
+ * @param {{ boolean?: string[], string?: string[], repeat?: string[], alias?: Record<string,string> }} spec
+ */
+export function parseArgs(argv, spec = {}) {
+  const booleans = new Set(['help', ...(spec.boolean || [])]);
+  const strings = new Set(spec.string || []);
+  const repeats = new Set(spec.repeat || []);
+  const alias = { h: 'help', ...(spec.alias || {}) };
+  const flags = {};
+  const positional = [];
+  for (const name of repeats) flags[name] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') { positional.push(...argv.slice(i + 1)); break; }
+    if (!arg.startsWith('-') || arg === '-') { positional.push(arg); continue; }
+    let name;
+    let value;
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      name = eq > 0 ? arg.slice(2, eq) : arg.slice(2);
+      if (eq > 0) value = arg.slice(eq + 1);
+    } else {
+      name = alias[arg.slice(1)];
+      if (!name) throw new Error(`Unknown option ${arg}.`);
+    }
+    name = alias[name] || name;
+    if (booleans.has(name)) {
+      if (value !== undefined) throw new Error(`--${name} takes no value.`);
+      flags[name] = true;
+      continue;
+    }
+    if (name.startsWith('no-') && booleans.has(name.slice(3))) { flags[name.slice(3)] = false; continue; }
+    if (!strings.has(name) && !repeats.has(name)) throw new Error(`Unknown option --${name}.`);
+    if (value === undefined) {
+      if (i + 1 >= argv.length) throw new Error(`--${name} needs a value.`);
+      value = argv[i += 1];
+    }
+    if (repeats.has(name)) flags[name].push(value);
+    else flags[name] = value;
+  }
+  return { flags, positional };
+}

package/packages/cli/src/commands/export.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { resolve, relative, join } from 'node:path';
+import { readFactory, writeFiles, out, err, styles, usage } from '../util.mjs';
+import { exportSkill, checkSkill } from '../../../engine/lib/skill.mjs';
+import { DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
+
+export default {
+  name: 'export',
+  summary: 'Export a factory as an Agent Skill folder (SKILL.md plus the factory).',
+  usage: `Usage: factoryhub export <factory> --as skill [--out dir] [--id id] [--force]
+
+Writes <dir>/<id>/SKILL.md and <dir>/<id>/factory/, following
+spec/skill-export.md. SKILL.md tells an agent what the factory produces, which
+inputs to collect, every step in order with who does it, where to stop and
+ask the person to approve, and how to run it with this CLI or by hand.
+factory/ holds the factory's files unchanged, plus the foreman written from
+the flow when the author wrote none.
+
+Copy the folder into your agent's skills directory, for example
+~/.claude/skills/ for Claude Code.
+
+Options:
+  --as     the export format; "skill" is the only one
+  --out    the parent folder (default: the current folder)
+  --id     the skill name and factoryhub id (default: the factory's name)
+  --hub    the factoryhub address used for the source link (default: ${DEFAULT_HUB})
+  --force  replace an earlier export of the same factory`,
+  options: { boolean: ['force'], string: ['as', 'out', 'id', 'hub'] },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name a factory to export.');
+    if (flags.as !== 'skill') throw usage('Choose the export format: --as skill');
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    const skill = await exportSkill(read.files, { id: flags.id, hub: flags.hub || DEFAULT_HUB });
+    const folder = resolve(io.cwd, flags.out || '.', skill.id);
+    const s = styles(io);
+    // Checked before anything is written: a failing export leaves no files.
+    const problems = await checkSkill(skill.files, { folder: skill.id, hub: flags.hub || DEFAULT_HUB });
+    if (problems.length) {
+      err(io, `${s.red('not exported')}  ${skill.id}: the export fails its checks`);
+      for (const problem of problems) err(io, `  - ${problem}`);
+      return 1;
+    }
+    if (existsSync(folder)) {
+      if (!flags.force) throw usage(`${folder} already exists. Pass --force to replace it.`);
+      // Replace an earlier export as a whole, so no stale file stays behind.
+      if (!existsSync(join(folder, 'SKILL.md'))) throw usage(`${folder} is not an earlier skill export, so it was left alone.`);
+      await rm(folder, { recursive: true, force: true });
+    }
+    await writeFiles(folder, skill.files, { allow: (path) => path === 'SKILL.md' || path.startsWith('factory/') });
+    out(io, `${s.green('exported')}  ${relative(io.cwd, folder) || folder}/SKILL.md and factory/ (${Object.keys(skill.files).length - 1} files), sha256 ${skill.sha256}`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/get.mjs

@@ -0,0 +1,38 @@
+import { existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { engine, writeFiles, out, styles, usage } from '../util.mjs';
+import { hubClient, DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
+import { HUB_NOTE } from './search.mjs';
+
+export default {
+  name: 'get',
+  summary: 'Download a published factory from factoryhub into a folder, checking every file.',
+  usage: `Usage: factoryhub get <id> [--out dir] [--base-url url] [--force]
+
+Downloads the factory's transfer bundle, checks every file against its
+recorded SHA-256, and writes the files to <dir>/<id>/.
+
+${HUB_NOTE}
+
+Options:
+  --out       the parent folder (default: the current folder)
+  --base-url  the factoryhub address (default: FACTORYHUB_BASE_URL or ${DEFAULT_HUB})
+  --force     write into an existing folder`,
+  options: { boolean: ['force'], string: ['out', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id] = positional;
+    if (!id) throw usage('Name the factory to get: factoryhub get <id>');
+    const hub = hubClient({ baseUrl: flags['base-url'], env: io.env, fetchImpl: io.fetch });
+    const factory = await hub.get(id);
+    const folder = resolve(io.cwd, flags.out || '.', id);
+    if (existsSync(folder) && !flags.force) throw usage(`${folder} already exists. Pass --force to write into it.`);
+    await writeFiles(folder, factory.files);
+    const parsed = engine.parseBundle(factory.files);
+    const s = styles(io);
+    const state = !parsed.ok ? s.red('invalid') : parsed.factory.runnable ? s.green('runs here') : s.yellow('does not run here');
+    out(io, `${s.green('saved')}  ${relative(io.cwd, folder) || folder}/  ${parsed.factory.title} v${parsed.factory.version}, ${Object.keys(factory.files).length} files, ${state}`);
+    if (factory.leftOut.length) out(io, `Not part of the factory, so not written: ${factory.leftOut.join(', ')}`);
+    out(io, `Source: ${factory.source}`);
+    return parsed.ok ? 0 : 1;
+  },
+};

package/packages/cli/src/commands/inspect.mjs

@@ -0,0 +1,66 @@
+import { engine, readFactory, summarize, out, json, table, plural, styles, usage, canonicalFiles } from '../util.mjs';
+
+export default {
+  name: 'inspect',
+  summary: 'Show what a factory does: inputs, steps in order, agents, tools, checks.',
+  usage: `Usage: factoryhub inspect <factory> [--json]
+
+Prints a factory's inputs, its steps stage by stage (steps in one stage can
+run at the same time), who does each, its agents, tools, and the
+statements its deliverable is checked against. A factory is a folder, a
+bundle .json file, an https address of a bundle, or a house factory id.
+
+Options:
+  --json   print the full summary as JSON, including the JSON Schema of the inputs`,
+  options: { boolean: ['json'] },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name a factory to inspect.');
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    const summary = await summarize(read.files, { id: read.source.id });
+    if (flags.json) { json(io, summary); return summary.valid ? 0 : 1; }
+    const s = styles(io);
+    if (!summary.valid) {
+      out(io, `${s.red('invalid')}  ${target}`);
+      for (const error of summary.errors) out(io, `  - ${error}`);
+      return 1;
+    }
+    const { factory } = engine.parseBundle(canonicalFiles(read.files));
+    out(io, `${s.bold(summary.title)}  ${s.dim(`v${summary.version}${summary.license ? `, ${summary.license}` : ''}${summary.author ? `, by ${summary.author}` : ''}`)}`);
+    out(io, summary.description);
+    out(io, s.dim(`${summary.name}  sha256 ${summary.sha256}${summary.time ? `  ${summary.time}` : ''}  ${summary.runnable ? 'runs here' : 'does not run here'}`));
+    out(io);
+    out(io, s.bold('Inputs'));
+    out(io, summary.inputs.length ? table(summary.inputs.map((input) => [`  ${input.key}`, input.type, input.required ? 'required' : 'optional', input.help])) : '  none');
+    out(io);
+    if (factory.steps.length) {
+      const { columns } = engine.layout(factory);
+      out(io, s.bold(`Steps (${plural(factory.steps.length, 'step')} in ${plural(columns.length, 'stage')})`));
+      const rows = [];
+      columns.forEach((ids, stage) => {
+        for (const id of ids) {
+          const step = factory.steps.find((item) => item.id === id);
+          const who = step.kind === 'approve' ? 'the person' : step.agent;
+          const detail = step.kind === 'check' ? `checks ${step.target}` : step.kind === 'approve' ? `shows ${step.target}, waits for a decision` : step.needs.length ? `after ${step.needs.join(', ')}` : 'first';
+          const tools = [...step.tools, ...step.missing];
+          rows.push([`  ${stage + 1}`, step.id, step.kind, who, `${detail}${tools.length ? `; tools ${tools.join(', ')}` : ''}`]);
+        }
+      });
+      out(io, table(rows));
+    } else out(io, `${s.bold('Steps')}\n  none: this factory has no flow`);
+    out(io);
+    out(io, s.bold('Agents'));
+    out(io, table(summary.agents.map((agent) => [`  ${agent.name}`, agent.type === 'FOREMAN' ? 'coordinates the flow (generated from it)' : agent.description])));
+    if (summary.done.length) {
+      out(io);
+      out(io, s.bold('Done when'));
+      for (const line of summary.done) out(io, `  - ${line}`);
+    }
+    if (summary.blockers.length) {
+      out(io);
+      out(io, s.bold('Cannot run here'));
+      for (const blocker of summary.blockers) out(io, `  - ${blocker}`);
+    }
+    return 0;
+  },
+};

package/packages/cli/src/commands/list.mjs

@@ -0,0 +1,29 @@
+import { resolve } from 'node:path';
+import { readFolder, listFactoryDirs, summarize, matches, out, json, table, HOUSE_FACTORIES } from '../util.mjs';
+
+export default {
+  name: 'list',
+  summary: 'List the house factories, or the factory folders in a directory.',
+  usage: `Usage: factoryhub list [directory] [--query words] [--json]
+
+Lists the factory folders directly inside a directory. With no directory,
+lists the house factories that ship with factoryhub.
+
+Options:
+  --query  keep factories whose id, title, description or tags contain every word
+  --json   print the summaries as JSON`,
+  options: { boolean: ['json'], string: ['query'] },
+  async run({ positional, flags }, io) {
+    const dir = positional[0] ? resolve(io.cwd, positional[0]) : HOUSE_FACTORIES;
+    const entries = [];
+    for (const id of await listFactoryDirs(dir)) {
+      const { files } = await readFolder(resolve(dir, id));
+      entries.push(await summarize(files, { id }));
+    }
+    const kept = entries.filter((entry) => matches(entry, flags.query));
+    if (flags.json) { json(io, kept); return 0; }
+    if (!kept.length) { out(io, entries.length ? 'No factory matches.' : `No factory folders in ${dir}.`); return 0; }
+    out(io, table([['ID', 'VERSION', 'STEPS', 'INPUTS', 'TITLE'], ...kept.map((entry) => [entry.id, entry.version, entry.steps.length, entry.inputs.length, entry.valid ? entry.title : `${entry.title} (invalid)`])]));
+    return 0;
+  },
+};

package/packages/cli/src/commands/mcp.mjs

@@ -0,0 +1,26 @@
+// Starts the local MCP server on stdio: the same server as the factoryhub-mcp bin.
+// It exists so one published package starts its MCP server with
+// `npx factoryhub mcp`, the form MCP registries and clients build from
+// server.json (identifier + version, then the package arguments).
+// stdout carries MCP only; the server logs to stderr.
+
+export default {
+  name: 'mcp',
+  summary: 'Start the local MCP server on stdio, for MCP clients.',
+  usage: `Usage: factoryhub mcp
+
+Starts the factoryhub MCP server on stdin and stdout, the same server as the
+factoryhub-mcp command. An MCP client starts it; it is not meant to be typed.
+Model keys and folders come from the environment: ANTHROPIC_API_KEY,
+OPENAI_API_KEY or OPENROUTER_API_KEY (only to run factories), FACTORYHUB_MODEL,
+FACTORYHUB_FACTORIES and FACTORYHUB_RUNS_DIR.`,
+  options: {},
+  async run() {
+    // Loaded here, not at the top, so other commands do not pay for the MCP SDK.
+    const { serveStdio } = await import('@modelcontextprotocol/server/stdio');
+    const { createServer } = await import('../../../mcp/src/server.mjs');
+    serveStdio(() => createServer());
+    // The open stdin keeps the process alive until the client closes it.
+    return 0;
+  },
+};