factoryhub 0.0.0-stage → 0.1.0

package/packages/mcp/src/server.mjs

@@ -0,0 +1,280 @@
+// The factoryhub MCP server: find, read, validate, export and run AI
+// factories from any MCP client. It runs locally over stdio. Runs use the
+// model key in this process's environment, never one of ours, and stop at
+// every human decision: the client must ask the person and call resume_run.
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, delimiter } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { parseBundle, toEnvelope, sha256 } from '../../engine/src/factory-engine.mjs';
+import { readFactory, readFolder, listFactoryDirs, writeFiles, HOUSE_FACTORIES } from '../../engine/lib/node.mjs';
+import { summarize, matches, canonicalFiles } from '../../engine/lib/catalog.mjs';
+import { exportSkill, checkSkill } from '../../engine/lib/skill.mjs';
+import { hubClient } from '../../engine/lib/hub.mjs';
+import { chooseProvider } from '../../engine/lib/providers.mjs';
+import { nodeHost, prepareRun, continueRun, pendingDecision, decide, restoreRun } from '../../engine/lib/run.mjs';
+
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const SPEC_PATH = new URL('../../../spec/factory-format.md', import.meta.url);
+export const TOOL_NAMES = ['list_factories', 'get_factory', 'validate_factory', 'export_skill', 'run_factory', 'resume_run'];
+
+const INSTRUCTIONS = `factoryhub serves AI factories: small teams of AI agents written as plain files (factory.yaml, flow.yaml, agents/<name>/agent.md).
+- list_factories and get_factory find and read factories; validate_factory checks one; export_skill turns one into an Agent Skill folder.
+- run_factory runs one with the model key configured for this server. It returns when the run finishes or reaches a human decision.
+- At a decision, show the person the full text, ask them to approve, reject, or say what to change, and call resume_run with their answer. Never decide for them.
+- The prompt "factory_format" holds the format specification for writing a new factory.`;
+
+const ID = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).max(64);
+
+function text(value) {
+  return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+}
+
+function result(value, summary) {
+  return { structuredContent: value, content: [{ type: 'text', text: summary ? `${summary}\n\n${text(value)}` : text(value) }] };
+}
+
+function failure(error) {
+  return { isError: true, content: [{ type: 'text', text: String(error?.message || error) }] };
+}
+
+/**
+ * Creates the server. Options exist for tests and embedding:
+ * env (keys, FACTORYHUB_FACTORIES, FACTORYHUB_RUNS_DIR), fetchImpl, factoryDirs, runsDir.
+ */
+export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs, runsDir } = {}) {
+  const dirs = factoryDirs || [HOUSE_FACTORIES, ...String(env.FACTORYHUB_FACTORIES || '').split(delimiter).filter(Boolean).map((dir) => resolve(dir))];
+  const runs = new Map();
+  const runFolder = runsDir || env.FACTORYHUB_RUNS_DIR || join(homedir(), '.factoryhub', 'runs');
+
+  async function localIds() {
+    const seen = new Map();
+    for (const dir of dirs) for (const id of await listFactoryDirs(dir)) if (!seen.has(id)) seen.set(id, join(dir, id));
+    return seen;
+  }
+
+  async function resolveFactory({ id, path, source = 'local' }) {
+    if (path) {
+      const read = await readFactory(path, { fetchImpl });
+      return { id: read.source.id, files: read.files, location: read.source.location, leftOut: read.leftOut };
+    }
+    if (!id) throw new Error('Give a factory id, or a path to a factory folder or bundle.');
+    if (source === 'hub') {
+      const got = await hubClient({ env, fetchImpl }).get(id);
+      return { id, files: got.files, location: got.source, leftOut: got.leftOut };
+    }
+    const location = (await localIds()).get(id);
+    if (!location) throw new Error(`No local factory "${id}". Call list_factories to see the ids, or pass source "hub" or a path.`);
+    const { files, skipped } = await readFolder(location);
+    return { id, files, location, leftOut: skipped };
+  }
+
+  async function saveRun(state) {
+    await mkdir(runFolder, { recursive: true });
+    const file = join(runFolder, `${state.id}.json`);
+    await writeFile(file, `${JSON.stringify(state)}\n`);
+    return file;
+  }
+
+  async function loadRun(runId) {
+    if (runs.has(runId)) return runs.get(runId);
+    const file = join(runFolder, `${runId}.json`);
+    if (!/^[A-Za-z0-9_-]{1,80}$/.test(runId) || !existsSync(file)) throw new Error(`No saved run "${runId}".`);
+    const state = restoreRun(JSON.parse(await readFile(file, 'utf8')));
+    runs.set(runId, state);
+    return state;
+  }
+
+  function progress(ctx) {
+    const token = ctx?.mcpReq?._meta?.progressToken;
+    let count = 0;
+    return (event) => {
+      if (token === undefined || !['step_started', 'step_done', 'check', 'approval_needed', 'run_failed'].includes(event.type)) return;
+      count += 1;
+      const message = event.type === 'step_started' ? `Started: ${event.title}` : event.type === 'step_done' ? `Finished step ${event.step}` : event.type === 'check' ? `Check ${event.step}: ${event.status}` : event.type === 'approval_needed' ? `Waiting for a decision at ${event.step}` : `Stopped: ${event.error}`;
+      ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: token, progress: count, message } }).catch(() => {});
+    };
+  }
+
+  async function report(state) {
+    runs.set(state.id, state);
+    const stateFile = await saveRun(state);
+    if (state.status === 'waiting') {
+      const decision = await pendingDecision(state);
+      return result({
+        run_id: state.id, status: 'waiting', decision, state_file: stateFile,
+        next: 'Show the person the full decision text and ask them to approve, reject, or say what to change. Then call resume_run with run_id, their decision, seen_sha256 and approval_id. Never decide for them.',
+      }, `The run is waiting for the person to decide at "${decision.title}".`);
+    }
+    if (state.status === 'done') {
+      const deliverableFile = join(runFolder, `${state.id}.md`);
+      await writeFile(deliverableFile, state.deliverable);
+      await writeFile(join(runFolder, `${state.id}.receipt.json`), `${JSON.stringify(state.receipt, null, 2)}\n`);
+      return result({ run_id: state.id, status: 'done', deliverable: state.deliverable, review: state.receipt.deliverable_review.status, flags: state.receipt.flags, deliverable_file: deliverableFile, receipt_file: join(runFolder, `${state.id}.receipt.json`), usage: { calls: state.usage.llmCalls, input_tokens: state.usage.input, output_tokens: state.usage.output } }, 'The run is done.');
+    }
+    if (state.status === 'stopped') return result({ run_id: state.id, status: 'stopped', step: state.stopped.step, note: state.stopped.note || '' }, 'The person rejected the result, so the run stopped with no deliverable.');
+    return result({ run_id: state.id, status: state.status, error: state.error, failure: state.failure || null }, 'The run did not finish.');
+  }
+
+  const server = new McpServer({ name: 'factoryhub', version: VERSION }, { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: INSTRUCTIONS });
+
+  server.registerTool('list_factories', {
+    title: 'List factories',
+    description: 'Lists AI factories: the house factories and folders named in FACTORYHUB_FACTORIES (source "local"), or the published catalogue on factoryhub (source "hub", which needs FACTORYHUB_ACCESS_KEY while the site is in private preview). Filters by words in the id, title, description or tags.',
+    inputSchema: z.object({ query: z.string().max(200).optional(), source: z.enum(['local', 'hub']).optional() }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async ({ query, source = 'local' }) => {
+    try {
+      let entries;
+      if (source === 'hub') entries = (await hubClient({ env, fetchImpl }).search(query || '')).map((entry) => ({ id: entry.id, title: entry.title, description: entry.description, version: entry.version, tags: entry.tags || [], runnable: entry.runnable, source: 'hub' }));
+      else {
+        entries = [];
+        for (const [id, location] of await localIds()) {
+          const summary = await summarize((await readFolder(location)).files, { id });
+          if (matches(summary, query)) entries.push({ id, title: summary.title, description: summary.description, version: summary.version, tags: summary.tags, runnable: summary.runnable, inputs: summary.inputs.map((input) => input.key), steps: summary.steps.length, source: 'local', path: location });
+        }
+      }
+      return result({ factories: entries }, `${entries.length} ${entries.length === 1 ? 'factory' : 'factories'}.`);
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('get_factory', {
+    title: 'Get a factory',
+    description: 'Reads one factory: its summary (inputs, steps in order, agents, tools, checks), its bundle SHA-256, and the full text of every file. Give an id (local or, with source "hub", published) or a path to a folder or bundle .json.',
+    inputSchema: z.object({ id: ID.optional(), path: z.string().max(1000).optional(), source: z.enum(['local', 'hub']).optional() }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async (args) => {
+    try {
+      const found = await resolveFactory(args);
+      const summary = await summarize(found.files, { id: found.id });
+      return result({ summary, files: canonicalFiles(found.files), location: found.location, left_out: found.leftOut }, `${summary.title} v${summary.version}.`);
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('validate_factory', {
+    title: 'Validate a factory',
+    description: 'Checks a factory with the engine\'s parser, without a key or a model: every problem, every tool this runner lacks, and whether it runs here. Give a path to a folder or bundle .json, an id, or the files themselves as a map of path to text.',
+    inputSchema: z.object({ path: z.string().max(1000).optional(), id: ID.optional(), files: z.record(z.string().max(200), z.string().max(400000)).optional() }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async ({ path, id, files }) => {
+    try {
+      const source = files || (await resolveFactory({ id, path })).files;
+      const { ok, errors, warnings, factory } = parseBundle(source);
+      const value = { valid: ok, runnable: ok && factory.runnable, name: factory.name, title: factory.title, version: factory.version, errors, blockers: factory.blockers, warnings: warnings.filter((warning) => !factory.blockers.includes(warning)) };
+      return result(value, !ok ? `Not valid: ${errors.length} problem${errors.length === 1 ? '' : 's'}.` : factory.runnable ? 'Valid, and it runs here.' : 'Valid, but it cannot run here.');
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('export_skill', {
+    title: 'Export as an Agent Skill',
+    description: 'Turns a factory into an Agent Skill folder: <id>/SKILL.md (what it produces, inputs to collect, every step and who does it, where to stop and ask the person to approve) and <id>/factory/ (the files unchanged, plus a foreman written from the flow when the author wrote none). With out_dir, writes the folder there; without, returns SKILL.md and the file list.',
+    inputSchema: z.object({ id: ID.optional(), path: z.string().max(1000).optional(), source: z.enum(['local', 'hub']).optional(), out_dir: z.string().max(1000).optional(), overwrite: z.boolean().optional() }),
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, async ({ out_dir: outDir, overwrite = false, ...args }) => {
+    try {
+      const found = await resolveFactory(args);
+      const skill = await exportSkill(found.files, { id: found.id });
+      const problems = await checkSkill(skill.files, { folder: skill.id });
+      let folder = null;
+      if (outDir) {
+        folder = resolve(outDir, skill.id);
+        if (existsSync(folder)) {
+          if (!overwrite) throw new Error(`${folder} already exists. Pass overwrite: true to replace it.`);
+          if (!existsSync(join(folder, 'SKILL.md'))) throw new Error(`${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: (file) => file === 'SKILL.md' || file.startsWith('factory/') });
+      }
+      return result({ id: skill.id, sha256: skill.sha256, folder, files: Object.keys(skill.files), problems, skill_md: skill.files['SKILL.md'] }, folder ? `Wrote ${folder}.` : 'SKILL.md is below; pass out_dir to write the folder.');
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('run_factory', {
+    title: 'Run a factory',
+    description: 'Runs a factory on this machine with the model key set in this server\'s environment (ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY), or a local OpenAI-compatible server (provider "ollama" or base_url, with model). It can take minutes. It returns when the run is done, fails, or reaches a human decision: then it returns run_id, the text to show, seen_sha256 and approval_id. Show the person the text, get their decision, and call resume_run. Never decide for them.',
+    inputSchema: z.object({
+      id: ID.optional(), path: z.string().max(1000).optional(), source: z.enum(['local', 'hub']).optional(),
+      inputs: z.record(z.string().max(64), z.string().max(40000)).optional(),
+      provider: z.enum(['anthropic', 'openai', 'openrouter', 'ollama', 'openai-compatible']).optional(),
+      model: z.string().max(160).optional(), base_url: z.string().max(2000).optional(),
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, async ({ inputs = {}, provider: kind, model, base_url: baseUrl, ...args }, ctx) => {
+    try {
+      const found = await resolveFactory(args);
+      const provider = chooseProvider({ provider: kind, model, baseUrl, env, fetchImpl });
+      const id = `mcp-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+      const prepared = prepareRun({ files: found.files, inputs, id, runner: { mode: 'mcp', provider: provider.name, model: provider.model } });
+      if (!prepared.ok) throw new Error(prepared.problems.join('\n'));
+      const state = prepared.state;
+      state.mcp = { provider: kind || null, model: provider.model, baseUrl: baseUrl || null };
+      await continueRun(state, nodeHost({ provider, fetchImpl, emit: progress(ctx) }));
+      return await report(state);
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerTool('resume_run', {
+    title: 'Resume a run with the person\'s decision',
+    description: 'Continues a run that is waiting at a human decision. Call it only with the person\'s own answer: approve, reject (ends the run with no result), or revise with a note saying what to change. Pass the seen_sha256 and approval_id from the waiting result, so the decision applies to the exact text the person saw. Returns at the next decision or when the run ends.',
+    inputSchema: z.object({
+      run_id: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
+      decision: z.enum(['approve', 'revise', 'reject']),
+      note: z.string().max(4000).optional(),
+      seen_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+      approval_id: z.string().regex(/^[a-f0-9]{64}$/),
+    }),
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, async ({ run_id: runId, decision, note, seen_sha256: seen, approval_id: approvalId }, ctx) => {
+    try {
+      const state = await loadRun(runId);
+      if (decision === 'revise' && !String(note || '').trim()) throw new Error('A revise decision needs a note saying what to change.');
+      const why = decide(state, { action: decision, note, seen, approvalId });
+      if (why) {
+        const reasons = { not_waiting: 'This run is not waiting for a decision.', bad_action: 'The decision must be approve, revise or reject.', unseen: 'Pass seen_sha256 from the waiting result.', stale: 'seen_sha256 or approval_id does not match the text the run is waiting on. Read the current decision again and show it to the person.', no_revisions: 'This step has been sent back as often as the factory allows: approve or reject it.' };
+        throw new Error(reasons[why] || why);
+      }
+      const settings = state.mcp || {};
+      const provider = chooseProvider({ provider: settings.provider || undefined, model: settings.model, baseUrl: settings.baseUrl || undefined, env, fetchImpl });
+      await continueRun(state, nodeHost({ provider, fetchImpl, emit: progress(ctx) }));
+      return await report(state);
+    } catch (error) { return failure(error); }
+  });
+
+  server.registerResource('factory', new ResourceTemplate('factoryhub://factories/{id}', {
+    list: async () => {
+      const resources = [];
+      for (const [id, location] of await localIds()) {
+        const summary = await summarize((await readFolder(location)).files, { id });
+        resources.push({ uri: `factoryhub://factories/${id}`, name: id, title: summary.title, description: summary.description, mimeType: 'application/json' });
+      }
+      return { resources };
+    },
+  }), { title: 'Factory bundle', description: 'A local factory as a transfer bundle: every file with its SHA-256.', mimeType: 'application/json' }, async (uri, { id }) => {
+    const found = await resolveFactory({ id: String(id) });
+    const files = canonicalFiles(found.files);
+    const envelope = toEnvelope(files, { project: found.id });
+    for (const entry of envelope.files) entry.sha256 = await sha256(entry.content);
+    return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(envelope, null, 2) }] };
+  });
+
+  server.registerResource('factory-format', 'factoryhub://spec/factory-format', { title: 'The factory format', description: 'The specification of the factory format, v1alpha1.', mimeType: 'text/markdown' }, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: 'text/markdown', text: await readFile(SPEC_PATH, 'utf8') }],
+  }));
+
+  server.registerPrompt('factory_format', {
+    title: 'Write a factory',
+    description: 'The factory format specification, to read or to write a new factory from. With a goal, asks for a factory that reaches it.',
+    argsSchema: z.object({ goal: z.string().max(2000).optional() }),
+  }, async ({ goal }) => {
+    const spec = await readFile(SPEC_PATH, 'utf8');
+    const ask = goal
+      ? `Write a factory for this goal, in the format above: ${goal}\n\nOutput every file in full: factory.yaml, flow.yaml and agents/<name>/agent.md for every agent a step names. Then check the files with the validate_factory tool and fix every problem it reports.`
+      : 'Use this specification to read, explain or write factories. Check any factory you write with the validate_factory tool.';
+    return { messages: [{ role: 'user', content: { type: 'text', text: `${spec}\n\n---\n\n${ask}` } }] };
+  });
+
+  return server;
+}

package/spec/README.md

@@ -0,0 +1,36 @@
+# The factory format
+
+| File | What it is |
+|---|---|
+| [`factory-format.md`](factory-format.md) | the specification, v1alpha1 |
+| [`schema/factory.schema.json`](schema/factory.schema.json) | JSON Schema (2020-12) for `factory.yaml` |
+| [`schema/flow.schema.json`](schema/flow.schema.json) | JSON Schema (2020-12) for `flow.yaml` |
+| [`skill-export.md`](skill-export.md) | how a factory becomes an Agent Skill folder |
+| [`skill-export/`](skill-export) | the expected `SKILL.md` of every house factory |
+| [`fixtures/`](fixtures) | good, bad, semantic and lenient factories that test the schemas against the engine |
+| [`test/`](test) | those tests |
+| [`rfcs/`](rfcs) | proposals to change the format |
+
+The reference implementation is the engine in
+[`packages/engine`](../packages/engine). `npm test` checks the schemas, the
+fixtures, the house factories and the skill export against it.
+
+## Using the schemas in an editor
+
+Editors that read the `yaml-language-server` comment validate a file as you
+type:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Mindburn-Labs/factoryhub/main/spec/schema/flow.schema.json
+```
+
+The schemas check one file at a time. Rules that span steps and files, such as
+an agent file existing for every step, are in
+[section 6 of the spec](factory-format.md#6-validity-and-runnability);
+`factoryhub validate` checks those too.
+
+## Changing the format
+
+Read [`rfcs/README.md`](rfcs/README.md). Small fixes to wording go straight to
+a pull request. A change to what a valid factory is, or to how a run behaves,
+starts as an RFC.