@ema.co/machina 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,824 @@
+#!/usr/bin/env node
+
+// src/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+
+// src/mcp/capabilities.ts
+var CAPABILITIES = [
+  {
+    name: "config",
+    status: "wired",
+    description: "Inspect eMachina's readiness (the needs/state check). Run this FIRST, and whenever a downstream tool reports a gap. Returns which capabilities are wired vs pending, plus required next steps.",
+    methods: [{ name: "status", description: "return the readiness snapshot" }]
+  },
+  {
+    name: "yield",
+    status: "wired",
+    description: "Manage harvest YIELD artifacts \u2014 the deterministic substrate. The agent RUNS the harvest procedure (intake/gather/synthesis = thinking); this tool validates/lists/reads/scaffolds the yields it produces. `validate` is a blocking gate over the canonical contract.",
+    methods: [
+      { name: "validate", description: "run the canonical validator (blocking gate)" },
+      { name: "list", description: "list yield slugs under .harvest/" },
+      { name: "get", description: "read a yield by slug" },
+      { name: "scaffold", description: "create a new yield from the canonical skeleton" }
+    ],
+    extraProperties: {
+      slug: { type: "string", description: "Yield slug (directory under .harvest/) \u2014 for get/scaffold/validate" },
+      path: { type: "string", description: "Explicit path to a yield .md \u2014 overrides slug for validate" }
+    }
+  },
+  {
+    name: "curate",
+    status: "wired",
+    description: "Memorialize / keep-memory-healthy over the corpus (publish, supersede, dedup, advise), powered by the owned atom kernel's submitChanges \u2014 content-addressed dedup + kernel-enforced validation (wire-conformant with canonical KS via golden vectors). Local corpus is the staging tier; org-wide COMPOSES with the ema toolkit's knowledge() by swapping the StorageBackend.",
+    methods: [
+      { name: "publish", description: "memorialize a yield (by slug) or explicit content as an atom" },
+      { name: "supersede", description: "publish an atom that supersedes a prior one (needs `supersedes`)" },
+      { name: "advise", description: "pre-flight the lib's validation on a yield without writing" },
+      { name: "status", description: "report curate readiness" }
+    ],
+    extraProperties: {
+      slug: { type: "string", description: "Yield slug to memorialize (for publish/supersede/advise)" },
+      name: { type: "string", description: "Atom title (if not using slug)" },
+      description: { type: "string", description: "Atom description (if not using slug)" },
+      body: { type: "string", description: "Atom body/content (if not using slug)" },
+      audience: { type: "string", description: "Audience token: public | internal[:slug] | tenant:slug | customer:slug" },
+      supersedes: { type: "string", description: "Atom id this one supersedes (for method=supersede)" }
+    }
+  },
+  {
+    name: "retrieve",
+    status: "wired",
+    description: "Search / rank the LOCAL corpus (curated atoms + .harvest yields) via the owned atom kernel's search \u2014 works offline, with or without DE. Org-wide search COMPOSES with the ema toolkit's knowledge(), not a rebuilt DE client (the scar tissue harvest set out to avoid).",
+    methods: [{ name: "search", description: "query the corpus (relevance-ranked, audience-filtered)" }],
+    extraProperties: {
+      query: { type: "string", description: "Search query (for method=search)" },
+      limit: { type: "number", description: "Max results (default 10)" },
+      audience: { type: "string", description: "Caller audience tokens to filter by (default public+internal)" }
+    }
+  }
+];
+var WIRED = CAPABILITIES.filter((c) => c.status === "wired").map((c) => c.name);
+var PENDING = CAPABILITIES.filter((c) => c.status === "pending").map((c) => c.name);
+
+// src/mcp/tools.ts
+function generateTools() {
+  return CAPABILITIES.map((c) => ({
+    name: c.name,
+    description: c.description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        method: {
+          type: "string",
+          enum: c.methods.map((m) => m.name),
+          description: c.methods.map((m) => `${m.name}: ${m.description}`).join(" | ")
+        },
+        ...c.extraProperties ?? {}
+      },
+      required: ["method"]
+    }
+  }));
+}
+
+// src/mcp/state.ts
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+var VALIDATOR_REL = "skills/harvest/evals/scripts/validate_yield.py";
+function findRepoRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, ".git")) || existsSync(join(dir, ".harvest"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+function checkYieldValidator(repoRoot) {
+  const validatorPath = join(repoRoot, VALIDATOR_REL);
+  if (!existsSync(validatorPath)) {
+    return { ready: false, detail: `validator not found at ${VALIDATOR_REL}` };
+  }
+  try {
+    execFileSync("python3", ["--version"], { stdio: "ignore" });
+    return { ready: true, detail: `${VALIDATOR_REL} reachable via python3` };
+  } catch {
+    return { ready: false, detail: "python3 not on PATH (needed to run the yield validator)" };
+  }
+}
+function checkKnowledgeSubstrate() {
+  return {
+    ready: true,
+    detail: "local atom kernel owned in-process (curate/retrieve wired, offline-capable); org-wide composes with the ema MCP knowledge() at runtime"
+  };
+}
+function getState(repoRoot = findRepoRoot(process.cwd())) {
+  const harvestReady = existsSync(join(repoRoot, ".harvest"));
+  const harvestDir = {
+    ready: harvestReady,
+    detail: harvestReady ? ".harvest/ present" : ".harvest/ not found (run from the eMachina repo)"
+  };
+  const yieldValidator = checkYieldValidator(repoRoot);
+  const knowledgeSubstrate = checkKnowledgeSubstrate();
+  const requiredNextSteps = [];
+  if (!harvestDir.ready) {
+    requiredNextSteps.push("No .harvest/ found \u2014 run the server from the eMachina repo root.");
+  }
+  if (!yieldValidator.ready) {
+    requiredNextSteps.push(`yield(method="validate") needs python3 + ${VALIDATOR_REL}: ${yieldValidator.detail}.`);
+  }
+  return { repoRoot, harvestDir, yieldValidator, knowledgeSubstrate, requiredNextSteps };
+}
+
+// src/mcp/middleware.ts
+function enrichWithState(result, _ctx) {
+  try {
+    const state = getState();
+    if (state.requiredNextSteps.length > 0) {
+      result._required_next_steps ??= state.requiredNextSteps;
+    }
+  } catch {
+  }
+  return result;
+}
+
+// src/mcp/responses.ts
+function success(data = {}, hints = {}) {
+  return { status: "success", ...data, ...hints };
+}
+function error(message, hints = {}) {
+  return { status: "error", error: message, ...hints };
+}
+function clarificationNeeded(message, options, hints = {}) {
+  return { status: "clarification_needed", message, options, ...hints };
+}
+function analysis(summary, issues, next_steps, hints = {}) {
+  return { status: "analysis", summary, issues, next_steps, ...hints };
+}
+function list(key, items, hints = {}) {
+  return { status: "list", count: items.length, [key]: items, ...hints };
+}
+function singleItem(key, item, hints = {}) {
+  return { status: "single_item", [key]: item, ...hints };
+}
+
+// src/mcp/handlers/config/formatters.ts
+function formatStatus(state) {
+  return success(
+    {
+      repoRoot: state.repoRoot,
+      // Per-capability runtime readiness (distinct from the surface definition in the registry).
+      readiness: {
+        config: { ready: true, detail: "always available" },
+        yield: state.yieldValidator,
+        curate: { ready: state.knowledgeSubstrate.ready, detail: state.knowledgeSubstrate.detail },
+        retrieve: { ready: state.knowledgeSubstrate.ready, detail: state.knowledgeSubstrate.detail }
+      },
+      harvest_dir: state.harvestDir,
+      wired: WIRED,
+      pending: PENDING
+    },
+    {
+      _next_step: state.requiredNextSteps.length ? 'Address _required_next_steps, or call a wired tool \u2014 e.g. yield(method="list").' : 'All checked capabilities ready \u2014 yield(method="list") to see the corpus.',
+      ...state.requiredNextSteps.length ? { _required_next_steps: state.requiredNextSteps } : {}
+    }
+  );
+}
+
+// src/mcp/handlers/config/index.ts
+async function dispatchConfig(args, ctx) {
+  const method = args.method;
+  switch (method) {
+    case "status":
+      return formatStatus(getState(ctx.repoRoot));
+    case void 0:
+      return clarificationNeeded("Which operation?", ["status"], {
+        _tip: 'config(method="status") returns the readiness snapshot.'
+      });
+    default:
+      return error(`Unknown method: ${method}`, { _tip: "config supports: status." });
+  }
+}
+
+// src/mcp/handlers/config/adapter.ts
+async function handleConfig(args) {
+  const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+  return dispatchConfig(args, ctx);
+}
+
+// src/mcp/handlers/yield/index.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/mcp/handlers/yield/formatters.ts
+function formatValidate(ok, path, detail) {
+  if (ok) {
+    return success({ valid: true, path, validator_output: detail }, { _tip: "Yield conforms to the contract." });
+  }
+  return analysis(
+    `Yield failed validation: ${path}`,
+    [{ severity: "critical", message: detail }],
+    ["Fix the reported issues", 'Re-run yield(method="validate", slug="\u2026")'],
+    {
+      _warning: "The yield does NOT conform to the contract \u2014 treat it as not accepted.",
+      _fix: detail
+    }
+  );
+}
+
+// src/mcp/handlers/yield/index.ts
+var HARVEST = ".harvest";
+var ASSET_REL = "skills/harvest/assets/harvest-yield.example.md";
+function yieldPath(repoRoot, slug) {
+  return join2(repoRoot, HARVEST, slug, "harvest-yield.md");
+}
+async function dispatchYield(args, ctx) {
+  const method = args.method;
+  const { repoRoot } = ctx;
+  const slug = args.slug;
+  switch (method) {
+    case "validate": {
+      const path = args.path ?? (slug ? yieldPath(repoRoot, slug) : void 0);
+      if (!path) return error("validate needs a slug or path", { _tip: 'yield(method="validate", slug="my-slug").' });
+      if (!existsSync2(path)) return error(`Yield not found: ${path}`, { _tip: 'Check the slug, or yield(method="list").' });
+      try {
+        const out = execFileSync2("python3", [join2(repoRoot, VALIDATOR_REL), path], { encoding: "utf8" });
+        return formatValidate(true, path, out.trim());
+      } catch (e) {
+        const err = e;
+        const detail = ((err.stdout ?? "") + (err.stderr ?? "")).trim() || err.message || String(e);
+        return formatValidate(false, path, detail);
+      }
+    }
+    case "list": {
+      const root = join2(repoRoot, HARVEST);
+      if (!existsSync2(root)) return error(`.harvest/ not found under ${repoRoot}`, { _tip: "Run from the eMachina repo root." });
+      const slugs = readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync2(yieldPath(repoRoot, d.name))).map((d) => d.name);
+      return list("slugs", slugs, { _next_step: 'yield(method="get", slug="\u2026") to read one.' });
+    }
+    case "get": {
+      if (!slug) return error("get needs a slug", { _tip: 'yield(method="get", slug="my-slug").' });
+      const path = yieldPath(repoRoot, slug);
+      if (!existsSync2(path)) return error(`Yield not found for slug: ${slug}`, { _tip: 'yield(method="list") to see available slugs.' });
+      return singleItem("yield", { slug, path, content: readFileSync(path, "utf8") });
+    }
+    case "scaffold": {
+      if (!slug) return error("scaffold needs a slug", { _tip: 'yield(method="scaffold", slug="my-new-slug").' });
+      const path = yieldPath(repoRoot, slug);
+      if (existsSync2(path)) return error(`Yield already exists for slug: ${slug}`, { _tip: "Pick a new slug, or get the existing one." });
+      let content;
+      try {
+        content = scaffoldFromAsset(repoRoot, slug);
+      } catch (e) {
+        return error(e instanceof Error ? e.message : String(e), {
+          _tip: "Run from the eMachina repo root so the canonical skeleton is reachable."
+        });
+      }
+      mkdirSync(join2(repoRoot, HARVEST, slug), { recursive: true });
+      writeFileSync(path, content);
+      return success(
+        { slug, path },
+        {
+          _next_step: `Fill the placeholders (Ask/Why/Goals/Findings/Sources), then yield(method="validate", slug="${slug}").`,
+          _warning: "Scaffold copies the canonical skeleton \u2014 the agent authors the content (the MCP never invents findings)."
+        }
+      );
+    }
+    case void 0:
+      return clarificationNeeded("Which operation?", ["validate", "list", "get", "scaffold"], {
+        _tip: 'e.g. yield(method="list").'
+      });
+    default:
+      return error(`Unknown method: ${method}`, { _tip: "yield supports: validate, list, get, scaffold." });
+  }
+}
+function scaffoldFromAsset(repoRoot, slug) {
+  const assetPath = join2(repoRoot, ASSET_REL);
+  if (!existsSync2(assetPath)) {
+    throw new Error(`Canonical yield skeleton not found at ${ASSET_REL} \u2014 cannot scaffold without it (no hardcoded fallback, to avoid contract drift).`);
+  }
+  return readFileSync(assetPath, "utf8").replace(/^name:.*$/m, `name: ${slug}`).replace(/^[ \t]*updated:.*\r?\n/m, "");
+}
+
+// src/mcp/handlers/yield/adapter.ts
+async function handleYield(args) {
+  const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+  return dispatchYield(args, ctx);
+}
+
+// src/mcp/atom/hash.ts
+import { createHash } from "node:crypto";
+function sha256Hex(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+  if (value !== null && typeof value === "object" && typeof value.toJSON === "function") {
+    return canonicalize(value.toJSON());
+  }
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).sort()) {
+      const v = source[key];
+      if (v !== void 0) out[key] = canonicalize(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/mcp/atom/id.ts
+var AUDIENCE_RE = /^(public|internal(:[a-z0-9-]+)?|tenant:[a-z0-9-]+|customer:[a-z0-9-]+)$/;
+function isValidAudience(token) {
+  return typeof token === "string" && AUDIENCE_RE.test(token);
+}
+function contentAddressId(c) {
+  const hash = sha256Hex(canonicalJson({ name: c.name, description: c.description, body: c.body }));
+  return `atom:${hash.slice(0, 32)}`;
+}
+
+// src/mcp/atom/validate.ts
+var LIMITS = {
+  MAX_NAME: 512,
+  MAX_DESCRIPTION: 4096,
+  MAX_BODY: 1e6
+  // 1M chars — generous for free-form knowledge, catches runaway/garbage
+};
+var ATOM_ID_RE = /^atom:[a-f0-9]{16,64}$/;
+function isValidAtomId(v) {
+  return typeof v === "string" && ATOM_ID_RE.test(v);
+}
+var ValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(`validation failed: ${errors.join("; ")}`);
+    this.name = "ValidationError";
+    this.errors = errors;
+  }
+};
+function reqString(v, field, max, errors) {
+  if (typeof v !== "string" || v.trim() === "") {
+    errors.push(`${field} is required and must be a non-empty string`);
+  } else if (v.length > max) {
+    errors.push(`${field} exceeds max length ${max} (got ${v.length})`);
+  }
+}
+function validateAtomInput(input) {
+  const errors = [];
+  if (input === null || typeof input !== "object") return ["atom input must be an object"];
+  reqString(input.name, "name", LIMITS.MAX_NAME, errors);
+  reqString(input.description, "description", LIMITS.MAX_DESCRIPTION, errors);
+  reqString(input.body, "body", LIMITS.MAX_BODY, errors);
+  if (input.audience !== void 0 && !isValidAudience(input.audience)) {
+    errors.push(`invalid audience token "${input.audience}" (expect public|internal[:slug]|tenant:slug|customer:slug)`);
+  }
+  if (input.supersedes !== void 0 && !isValidAtomId(input.supersedes)) {
+    errors.push(`supersedes must be a valid atom id (atom:<hex>), got "${String(input.supersedes)}"`);
+  }
+  if (input.produced_by !== void 0 && typeof input.produced_by !== "string") {
+    errors.push("produced_by must be a string");
+  }
+  return errors;
+}
+function validateChange(change) {
+  if (change === null || typeof change !== "object") return ["change must be an object"];
+  switch (change.op) {
+    case "publish":
+      if (change.atom === void 0) return ["publish requires `atom`"];
+      return validateAtomInput(change.atom);
+    case "retract":
+      return isValidAtomId(change.id) ? [] : [`retract requires a valid atom id, got "${String(change.id)}"`];
+    case "set_audience": {
+      const errors = [];
+      if (!isValidAtomId(change.id)) errors.push(`set_audience requires a valid atom id, got "${String(change.id)}"`);
+      if (change.audience === void 0 || !isValidAudience(change.audience)) {
+        errors.push(`set_audience requires a valid audience token, got "${change.audience}"`);
+      }
+      return errors;
+    }
+    default:
+      return [`unknown op "${String(change.op)}" (expect publish|retract|set_audience)`];
+  }
+}
+function validate(change) {
+  const errors = validateChange(change);
+  return { valid: errors.length === 0, errors };
+}
+function assertValidChange(change) {
+  const errors = validateChange(change);
+  if (errors.length > 0) throw new ValidationError(errors);
+}
+
+// src/mcp/atom/core.ts
+function buildAtom(input) {
+  const errors = validateAtomInput(input);
+  if (errors.length > 0) throw new ValidationError(errors);
+  const audience = input.audience ?? "internal";
+  const id = contentAddressId({ name: input.name, description: input.description, body: input.body });
+  return {
+    id,
+    audience,
+    name: input.name,
+    description: input.description,
+    body: input.body,
+    status: "active",
+    produced_by: input.produced_by ?? "unknown",
+    produced_at: (/* @__PURE__ */ new Date()).toISOString(),
+    ...input.supersedes !== void 0 ? { supersedes: input.supersedes } : {},
+    ...input.derived_from !== void 0 ? { derived_from: input.derived_from } : {}
+  };
+}
+async function project(retrieval, fn) {
+  if (!retrieval) return void 0;
+  try {
+    await fn(retrieval);
+    return void 0;
+  } catch (err) {
+    return `retrieval projection (${retrieval.name}) failed: ${err.message}`;
+  }
+}
+async function submitChanges(change, backends) {
+  assertValidChange(change);
+  const { storage, retrieval } = backends;
+  switch (change.op) {
+    case "publish": {
+      if (!change.atom) throw new Error("submitChanges(publish): `atom` is required");
+      const atom = buildAtom(change.atom);
+      if (await storage.has(atom.id)) {
+        return { status: "deduplicated", id: atom.id, atom: await storage.get(atom.id) ?? atom };
+      }
+      await storage.put(atom);
+      const warning = await project(retrieval, (r) => r.index(atom));
+      return { status: "published", id: atom.id, atom, ...warning ? { warning } : {} };
+    }
+    case "retract": {
+      if (!change.id) throw new Error("submitChanges(retract): `id` is required");
+      const existing = await storage.get(change.id);
+      if (!existing) throw new Error(`submitChanges(retract): atom "${change.id}" not found`);
+      const tombstoned = { ...existing, status: "retracted" };
+      await storage.put(tombstoned);
+      await project(retrieval, (r) => r.remove(change.id));
+      return { status: "retracted", id: change.id, atom: tombstoned };
+    }
+    case "set_audience": {
+      const id = change.id;
+      const audience = change.audience;
+      const existing = await storage.get(id);
+      if (!existing) throw new Error(`submitChanges(set_audience): atom "${id}" not found`);
+      const updated = { ...existing, audience };
+      await storage.put(updated);
+      await project(retrieval, (r) => r.index(updated));
+      return { status: "audience_set", id, atom: updated };
+    }
+    default: {
+      throw new Error(`submitChanges: unknown op "${change.op}"`);
+    }
+  }
+}
+async function search(query, opts, backends) {
+  if (!backends.retrieval) throw new Error("search: no retrieval backend configured");
+  return backends.retrieval.search(query, opts);
+}
+
+// src/mcp/atom/backends.ts
+import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2, existsSync as existsSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+function idToFile(id) {
+  return `${id.replace(/[^a-zA-Z0-9._-]/g, "_")}.json`;
+}
+var LocalStorageBackend = class {
+  constructor(dir) {
+    this.dir = dir;
+    mkdirSync2(dir, { recursive: true });
+  }
+  name = "local-fs";
+  async put(atom) {
+    writeFileSync2(join3(this.dir, idToFile(atom.id)), JSON.stringify(atom, null, 2));
+  }
+  async get(id) {
+    const path = join3(this.dir, idToFile(id));
+    if (!existsSync3(path)) return null;
+    return JSON.parse(readFileSync2(path, "utf8"));
+  }
+  async has(id) {
+    return existsSync3(join3(this.dir, idToFile(id)));
+  }
+  async list() {
+    if (!existsSync3(this.dir)) return [];
+    return readdirSync2(this.dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync2(join3(this.dir, f), "utf8")));
+  }
+  async delete(id) {
+    const path = join3(this.dir, idToFile(id));
+    if (existsSync3(path)) rmSync(path);
+  }
+};
+function audienceVisible(atomAudience, caller) {
+  return atomAudience === "public" || Array.isArray(caller) && caller.includes(atomAudience);
+}
+function tokenize(s) {
+  return s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+var StoreScanRetrieval = class {
+  name = "store-scan";
+  atoms = /* @__PURE__ */ new Map();
+  /** Optionally hydrate the projection from the primary store. */
+  async rebuildFrom(storage) {
+    this.atoms.clear();
+    for (const a of await storage.list()) this.atoms.set(a.id, a);
+  }
+  async index(atom) {
+    this.atoms.set(atom.id, atom);
+  }
+  async remove(id) {
+    this.atoms.delete(id);
+  }
+  async search(query, opts) {
+    const caller = opts.audience ?? ["public"];
+    const qTokens = tokenize(query);
+    const hits = [];
+    for (const atom of this.atoms.values()) {
+      if (atom.status === "retracted") continue;
+      if (!audienceVisible(atom.audience, caller)) continue;
+      const hay = tokenize(`${atom.name} ${atom.description} ${atom.body}`);
+      const haySet = new Set(hay);
+      const matched = qTokens.filter((t) => haySet.has(t)).length;
+      if (matched === 0) continue;
+      hits.push({
+        id: atom.id,
+        name: atom.name,
+        description: atom.description,
+        audience: atom.audience,
+        score: qTokens.length ? matched / qTokens.length : 0
+      });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, opts.limit ?? 10);
+  }
+};
+
+// src/mcp/handlers/corpus.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+var HARVEST2 = ".harvest";
+var CORPUS_REL = ".knowledge/atoms";
+function corpusStore(repoRoot) {
+  return new LocalStorageBackend(join4(repoRoot, CORPUS_REL));
+}
+function readYield(repoRoot, slug) {
+  const path = join4(repoRoot, HARVEST2, slug, "harvest-yield.md");
+  return existsSync4(path) ? readFileSync3(path, "utf8") : null;
+}
+function deriveDescription(content, slug) {
+  const body = content.replace(/^---[\s\S]*?---/m, "");
+  for (const line of body.split("\n")) {
+    const t = line.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">") && !t.startsWith("`")) return t.slice(0, 200);
+  }
+  return slug;
+}
+
+// src/mcp/handlers/curate/index.ts
+function atomInputFromArgs(repoRoot, args) {
+  const audience = typeof args.audience === "string" ? args.audience : void 0;
+  const supersedes = typeof args.supersedes === "string" ? args.supersedes : void 0;
+  const slug = typeof args.slug === "string" ? args.slug : void 0;
+  if (slug) {
+    const content = readYield(repoRoot, slug);
+    if (content === null) return { err: `Yield not found for slug: ${slug}` };
+    return {
+      input: {
+        name: slug,
+        description: deriveDescription(content, slug),
+        body: content,
+        produced_by: "curate",
+        ...audience ? { audience } : {},
+        ...supersedes ? { supersedes } : {}
+      }
+    };
+  }
+  const name = args.name;
+  const description = args.description;
+  const body = args.body;
+  if (!name || !description || !body) {
+    return { err: "Provide either a `slug` (of a .harvest yield) or explicit name + description + body." };
+  }
+  return {
+    input: {
+      name,
+      description,
+      body,
+      produced_by: "curate",
+      ...audience ? { audience } : {},
+      ...supersedes ? { supersedes } : {}
+    }
+  };
+}
+async function dispatchCurate(args, ctx) {
+  const method = args.method;
+  const storage = corpusStore(ctx.repoRoot);
+  switch (method) {
+    case "advise": {
+      const { input, err } = atomInputFromArgs(ctx.repoRoot, args);
+      if (err || !input) return error(err ?? "invalid input", { _tip: 'curate(method="advise", slug="\u2026").' });
+      const v = validate({ op: "publish", atom: input });
+      if (v.valid) {
+        return success({ advice: "valid", name: input.name }, {
+          _next_step: `curate(method="publish", slug="${args.slug ?? input.name}") to memorialize it.`
+        });
+      }
+      return {
+        status: "analysis",
+        summary: "Yield fails atom-kernel validation \u2014 fix before publishing.",
+        issues: v.errors,
+        next_steps: ["Fix the listed issues, then re-run curate(advise)."],
+        _warning: "Validation is enforced by the atom kernel; publish would be rejected."
+      };
+    }
+    case "publish":
+    case "supersede": {
+      const { input, err } = atomInputFromArgs(ctx.repoRoot, args);
+      if (err || !input) {
+        return error(err ?? "invalid input", {
+          _tip: 'curate(method="publish", slug="\u2026"), or pass name/description/body. supersede also needs `supersedes`.'
+        });
+      }
+      if (method === "supersede" && !input.supersedes) {
+        return error("supersede requires `supersedes` (the atom id being superseded).", {
+          _tip: 'curate(method="supersede", slug="\u2026", supersedes="atom:\u2026").'
+        });
+      }
+      try {
+        const res = await submitChanges({ op: "publish", atom: input }, { storage });
+        return success(
+          { id: res.id, curate_status: res.status, name: input.name, audience: res.atom?.audience },
+          {
+            _next_step: 'retrieve(method="search", query="\u2026") \u2014 the atom is now in the local corpus.',
+            _tip: res.status === "deduplicated" ? "Identical content already memorialized \u2014 content-addressed dedup (no-op)." : "Memorialized to the local corpus (swap StorageBackend for GCS org-wide)."
+          }
+        );
+      } catch (e) {
+        if (e instanceof ValidationError) {
+          return {
+            status: "analysis",
+            summary: "Validation failed (enforced by the atom kernel).",
+            issues: e.errors,
+            next_steps: ["Fix the issues, then re-run curate."]
+          };
+        }
+        return error(e instanceof Error ? e.message : String(e));
+      }
+    }
+    case "status":
+      return success({ wired: true }, { _tip: "curate \u2192 atom-kernel submitChanges (local corpus StorageBackend)." });
+    case void 0:
+      return clarificationNeeded("Which operation?", ["publish", "supersede", "advise", "status"], {
+        _tip: 'e.g. curate(method="publish", slug="my-slug").'
+      });
+    default:
+      return error(`Unknown method: ${method}`, { _tip: "curate supports: publish, supersede, advise, status." });
+  }
+}
+
+// src/mcp/handlers/curate/adapter.ts
+async function handleCurate(args) {
+  const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+  return dispatchCurate(args, ctx);
+}
+
+// src/mcp/handlers/retrieve/index.ts
+import { existsSync as existsSync5, readdirSync as readdirSync3 } from "node:fs";
+import { join as join5 } from "node:path";
+async function loadCorpus(repoRoot) {
+  const retrieval = new StoreScanRetrieval();
+  const ids = /* @__PURE__ */ new Set();
+  for (const atom of await corpusStore(repoRoot).list()) {
+    await retrieval.index(atom);
+    ids.add(atom.id);
+  }
+  const root = join5(repoRoot, HARVEST2);
+  if (existsSync5(root)) {
+    for (const d of readdirSync3(root, { withFileTypes: true })) {
+      if (!d.isDirectory() || d.name.startsWith(".")) continue;
+      const content = readYield(repoRoot, d.name);
+      if (content === null) continue;
+      const atom = buildAtom({
+        name: d.name,
+        description: deriveDescription(content, d.name),
+        body: content,
+        audience: "internal",
+        produced_by: "harvest"
+      });
+      await retrieval.index(atom);
+      ids.add(atom.id);
+    }
+  }
+  return { retrieval, count: ids.size };
+}
+async function dispatchRetrieve(args, ctx) {
+  const method = args.method ?? "search";
+  if (method !== "search") {
+    return error(`Unknown method: ${method}`, { _tip: "retrieve supports: search." });
+  }
+  const query = args.query;
+  if (!query || query.trim() === "") {
+    return clarificationNeeded("What should I search the corpus for?", [], {
+      _tip: 'retrieve(method="search", query="\u2026").'
+    });
+  }
+  const limit = typeof args.limit === "number" ? args.limit : 10;
+  const audience = Array.isArray(args.audience) ? args.audience : ["public", "internal"];
+  const { retrieval, count } = await loadCorpus(ctx.repoRoot);
+  const hits = await search(query, { audience, limit }, { retrieval });
+  const results = hits.map((h) => ({ slug: h.name, score: Number(h.score.toFixed(3)), description: h.description }));
+  const top = results[0];
+  return {
+    ...list("results", results, {
+      _next_step: top ? `yield(method="get", slug="${top.slug}") to read the top hit.` : "No local hits \u2014 broaden the query, or compose with the ema toolkit's knowledge() for org-wide search.",
+      _tip: `Searched ${count} local atoms (curated + .harvest yields; audience: ${audience.join(", ")}). Org-wide composes with ema-toolkit knowledge() (DE).`
+    }),
+    composes_with: ["ema-toolkit:knowledge()"]
+  };
+}
+
+// src/mcp/handlers/retrieve/adapter.ts
+async function handleRetrieve(args) {
+  const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+  return dispatchRetrieve(args, ctx);
+}
+
+// src/mcp/server.ts
+var toolHandlers = {
+  config: (args) => handleConfig(args),
+  yield: (args) => handleYield(args),
+  curate: (args) => handleCurate(args),
+  retrieve: (args) => handleRetrieve(args)
+};
+function assertSurfaceParity() {
+  for (const c of CAPABILITIES) {
+    if (!toolHandlers[c.name]) throw new Error(`Capability "${c.name}" has no handler in the dispatch map`);
+  }
+  for (const name of Object.keys(toolHandlers)) {
+    if (!CAPABILITIES.some((c) => c.name === name)) throw new Error(`Handler "${name}" has no capability spec`);
+  }
+}
+assertSurfaceParity();
+function wrap(result) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    isError: result.status === "error"
+  };
+}
+async function startMcpServer() {
+  const server = new Server(
+    { name: "emachina", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+    // add `{ listChanged: true }` only if adopting the dynamic surface
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: generateTools() }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    const handler = toolHandlers[name];
+    if (!handler) {
+      return wrap(
+        error(`Unknown tool: ${name}`, { _tip: `Available tools: ${Object.keys(toolHandlers).join(", ")}.` })
+      );
+    }
+    try {
+      let result = await handler(args ?? {});
+      try {
+        result = enrichWithState(result, { tool: name });
+      } catch {
+      }
+      return wrap(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return wrap(error(message, { _tip: "Unexpected handler error \u2014 likely a bug; check server logs." }));
+    }
+  });
+  await server.connect(new StdioServerTransport());
+}
+var argv1 = process.argv[1];
+var isMain = !!argv1 && import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+if (isMain) {
+  startMcpServer().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+export {
+  assertSurfaceParity,
+  startMcpServer
+};