@sparkerp/plugin-sdk 0.1.0

package/erp-mcp-server/index.mjs

@@ -0,0 +1,818 @@
+#!/usr/bin/env node
+/**
+ * ERP Plugin Language MCP server — the concrete first slice of the
+ * "AI-Native Developer Platform" architecture in
+ * `low-code-docs/AI Native/AI_NATIVE_Developer platform.md`.
+ *
+ * Gap this closes: that doc's core, highest-leverage ask ("give Claude Code
+ * an ERP MCP server" so the AI discovers the plugin grammar instead of
+ * guessing it) had zero real implementation — `McpToolContribution`
+ * (engine-plugin-api) is a real per-plugin extension POINT, but nothing in
+ * this codebase actually hosts an MCP transport/server that speaks to an
+ * IDE agent. This file is that server: a plain stdio JSON-RPC 2.0 process
+ * (the MCP wire protocol), zero new npm dependencies (same
+ * standalone-outside-the-pnpm-workspace convention as `spark.js` and
+ * `validate-page-properties.mjs`, which it wraps rather than re-implements).
+ *
+ * What is deliberately NOT built here (disclosed, not silently dropped —
+ * see `ai/domains/ai-native-developer-platform-gap-analysis.md`):
+ *   - `erp login`/OAuth device-auth, a plugin registry, `erp plugin pull/push`,
+ *     a hosted `erp dev` environment — all real infra projects (auth server,
+ *     registry service) orthogonal to "expose what already exists to an
+ *     MCP client", not a natural extension of this one file.
+ *   - A Language Server (LSP) — a separate, much larger surface.
+ *   - `erp_create_plugin`/`erp_update_plugin` (AI writes files directly via
+ *     its own Read/Write/Edit tools already — this server's job is
+ *     grounding, not another file-mutation path).
+ *
+ * Tools exposed (Layer 1 structure / Layer 2 semantics / Layer 4 examples
+ * from the doc's own "four layers of grammar" framing):
+ *   - erp_list_schemas / erp_get_schema   — the real JSON Schemas this repo
+ *     already ships (frontend/packages/*\/schema, backend/platform-runtime/schema)
+ *   - erp_validate_page                    — wraps tools/page-validator's real
+ *     validateInstanceConfig-based validator (unknown-property/invalid-binding/
+ *     missing-required/page-structural checks), not a re-derived one
+ *   - erp_validate_plugin_pages            — wraps spark.js's validatePages
+ *   - erp_search_docs                      — greps ai/ (the doc convention)
+ *   - erp_search_examples                  — greps real shipped page/workflow/
+ *     entity/provider JSON across backend/modules for a naming pattern
+ *   - erp_service_plugin_scaffold          — wraps platform-cli's REAL
+ *     `service-plugin:scaffold` command (scaffoldServicePlugin, from
+ *     ../../frontend/packages/platform-cli/dist/index.js) to generate a
+ *     runnable Python/FastAPI or Node.js/Express Service-mode plugin
+ *     starter on disk — the polyglot (non-Java) counterpart to
+ *     erp_plugin_scaffold, which is Java/PF4J-extension-point-only
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline";
+import { pathToFileURL } from "node:url";
+import { EXAMPLE_PATTERNS } from "../erp-cli/example-patterns.mjs";
+import { simpleSchemaCheck, buildEngineCatalog, searchEngineCatalog, describeContract, SCAFFOLD_TEMPLATES } from "../erp-cli/erp.mjs";
+import {
+  SCHEMA_REGISTRY,
+  detectMode,
+  isPackaged,
+  requireMonorepo,
+  bundleDir,
+  schemaPathByName,
+  docsSearchRoots,
+  examplesModulesRoot,
+  exampleFileAbs,
+  blockEngineModuleUrl,
+  blocksCatalogPath,
+} from "../erp-cli/authoring-root.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+
+// ---------------------------------------------------------------------------
+// Schema registry — shared single source of truth (tools/erp-cli/authoring-root.mjs),
+// so the MCP server, the CLI, and the bundle emitter can never drift. In
+// packaged SDK mode these are read from the shipped erp-authoring-bundle/;
+// in monorepo mode, live from backend/platform-runtime + frontend/packages.
+// ---------------------------------------------------------------------------
+const SCHEMAS = SCHEMA_REGISTRY;
+function readSchema(name) {
+  const entry = SCHEMAS[name];
+  if (!entry) {
+    const known = Object.keys(SCHEMAS).join(", ");
+    throw new Error(`unknown schema "${name}". Known schemas: ${known}`);
+  }
+  const abs = schemaPathByName(name);
+  return { path: entry.file, description: entry.description, schema: JSON.parse(readFileSync(abs, "utf8")) };
+}
+
+// ---------------------------------------------------------------------------
+// erp_validate_page — reuse the REAL page validator, don't re-derive it.
+// ---------------------------------------------------------------------------
+async function validatePageTool(pagePath) {
+  // Works in BOTH modes: the page validator resolves @erp/block-engine +
+  // @erp/page-engine through authoring-root.mjs (dist in monorepo mode, the
+  // bundle's self-contained validators/*.mjs in packaged mode).
+  const mod = await import(pathToFileURL(path.join(REPO_ROOT, "tools/page-validator/validate-page-properties.mjs")).href);
+  const registry = await mod.buildRegistry();
+  const abs = path.isAbsolute(pagePath) ? pagePath : path.join(REPO_ROOT, pagePath);
+  const issues = mod.validatePage(abs, registry);
+  return issues.length === 0
+    ? { file: pagePath, valid: true }
+    : { file: pagePath, valid: false, issues };
+}
+
+// ---------------------------------------------------------------------------
+// erp_validate_connector_definition — local schema check for engine-provider-
+// connector authoring files, reusing the SAME simpleSchemaCheck erp.mjs's own
+// `erp connector validate`/`erp schema validate` use (imported, not
+// re-derived) — mirrors this MCP server's "validate tools are local
+// schema/lint checks" convention (erp_validate_page is the one exception,
+// which reuses a real runtime validator instead of a schema).
+// ---------------------------------------------------------------------------
+async function validateConnectorDefinitionTool(filePath) {
+  const abs = path.isAbsolute(filePath) ? filePath : path.join(REPO_ROOT, filePath);
+  const schema = readSchema("connector-definition").schema;
+  const data = JSON.parse(readFileSync(abs, "utf8"));
+  const issues = simpleSchemaCheck(data, schema, "$");
+  if (data.connectorKind === "HTTP" && !data.baseUrl) issues.push('connectorKind="HTTP" requires "baseUrl"');
+  return issues.length === 0 ? { file: filePath, valid: true } : { file: filePath, valid: false, issues };
+}
+
+async function validatePluginPagesTool(pluginDir) {
+  // spark.js's own `validate` command runs this exact check but as a bare
+  // script with no exports (confirmed live — it has zero `export`
+  // statements, unlike validate-page-properties.mjs). Rather than add an
+  // export surface to spark.js for one caller, reuse page-validator's own
+  // exports directly over the same metadata/page directory spark.js walks.
+  const mod = await import(pathToFileURL(path.join(REPO_ROOT, "tools/page-validator/validate-page-properties.mjs")).href);
+  const abs = path.isAbsolute(pluginDir) ? pluginDir : path.join(REPO_ROOT, pluginDir);
+  const pageDir = path.join(abs, "metadata", "page");
+  let files;
+  try {
+    files = readdirSync(pageDir).filter((f) => f.endsWith(".json")).map((f) => path.join(pageDir, f));
+  } catch {
+    return { pluginDir, pagesChecked: 0, valid: true, note: `no page JSON found under ${path.relative(REPO_ROOT, pageDir)}` };
+  }
+  const registry = await mod.buildRegistry();
+  const failures = {};
+  for (const file of files) {
+    const issues = mod.validatePage(file, registry);
+    if (issues.length > 0) failures[path.relative(REPO_ROOT, file)] = issues;
+  }
+  const result = { pluginDir, pagesChecked: files.length, valid: Object.keys(failures).length === 0 };
+  if (Object.keys(failures).length > 0) result.failures = failures;
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// erp_lint_plugin_semantics — [REAL, added 2026-09-03, I18N-001] MCP-native
+// wiring for the SAME semantic lints `erp plugin test` runs
+// (page-semantic-lint/DS-001/I18N-001) — these previously only existed
+// CLI-side inside `tools/erp-cli/erp.mjs`'s own `pluginTestCommand`, so an
+// AI/developer driving this repo purely through MCP tools had no way to run
+// them without shelling out. `erp.mjs` is now import-safe (its `main()` is
+// guarded to only run when it's the actual process entry point) and exports
+// `lintPageSemantics`/`lintDataServiceSemantics`/`lintI18nSemantics`/
+// `loadEntityFieldTypes`/`loadI18nKeys` for exactly this reuse — this
+// function is a thin wrapper, not a re-derivation, so the two surfaces can
+// never silently drift apart.
+// ---------------------------------------------------------------------------
+async function lintPluginSemanticsTool(pluginDir) {
+  // Pure JS — reads the plugin's own JSON + bundled schemas. Works packaged:
+  // the repo-wide helpers (loadAllRepoProviderNames, the java-dir scan) all
+  // degrade to empty when backend/modules isn't present, and every schema
+  // read goes through authoring-root.mjs's resolver.
+  const cli = await import(pathToFileURL(path.join(REPO_ROOT, "tools/erp-cli/erp.mjs")).href);
+  const abs = path.isAbsolute(pluginDir) ? pluginDir : path.join(REPO_ROOT, pluginDir);
+  const pageDir = path.join(abs, "metadata", "page");
+  const dsDir = path.join(abs, "metadata", "data_service");
+  const i18nKeys = cli.loadI18nKeys(abs);
+  const providerNamesSamePlugin = cli.loadProviderNamesFrom(path.join(abs, "metadata", "provider"));
+  const warnings = [];
+
+  let pageFiles = [];
+  try { pageFiles = readdirSync(pageDir).filter((f) => f.endsWith(".json")); } catch { /* no pages */ }
+  for (const f of pageFiles) {
+    try {
+      const pageJson = JSON.parse(readFileSync(path.join(pageDir, f), "utf8"));
+      const entityTypes = cli.loadEntityFieldTypes(abs, pageJson.metadata?.entityDefinition);
+      for (const w of cli.lintPageSemantics(pageJson, entityTypes)) warnings.push({ file: `page/${f}`, rule: w.match(/\[([a-z-]+)\]/)?.[1] ?? "page-semantic-lint", message: w });
+      for (const w of cli.lintI18nSemantics(pageJson, i18nKeys)) warnings.push({ file: `page/${f}`, rule: w.match(/\[([a-z-]+)\]/)?.[1] ?? "I18N-001", message: w });
+      for (const w of cli.lintPageDataSourceSemantics(pageJson, providerNamesSamePlugin, cli.loadAllRepoProviderNames())) warnings.push({ file: `page/${f}`, rule: w.match(/\[([a-z-]+)\]/)?.[1] ?? "PAGE-DS-001", message: w });
+    } catch (e) {
+      warnings.push({ file: `page/${f}`, rule: "lint-error", message: `could not lint: ${e.message}` });
+    }
+  }
+
+  let dsFiles = [];
+  try { dsFiles = readdirSync(dsDir).filter((f) => f.endsWith(".json")); } catch { /* no data services */ }
+  for (const f of dsFiles) {
+    try {
+      const dsJson = JSON.parse(readFileSync(path.join(dsDir, f), "utf8"));
+      const entityName = dsJson.definition?.source?.kind === "entity" ? dsJson.definition.source.entityName : null;
+      const entityTypes = cli.loadEntityFieldTypes(abs, entityName);
+      for (const w of cli.lintDataServiceSemantics(dsJson, entityTypes)) warnings.push({ file: `data_service/${f}`, rule: "DS-001", message: w });
+    } catch (e) {
+      warnings.push({ file: `data_service/${f}`, rule: "lint-error", message: `could not lint: ${e.message}` });
+    }
+  }
+
+  // JOB-001 (2026-09-04, REAL) — same lintJobContributionUsage the CLI's
+  // `erp plugin test` runs, scanning this plugin's own src/main/java for a
+  // new bespoke ErpJobContribution class instead of a JSON job definition
+  // against an already-generic sweep engine.
+  const javaDir = path.join(abs, "..", "src", "main", "java");
+  try {
+    for (const w of cli.lintJobContributionUsage(javaDir)) warnings.push({ file: "src/main/java", rule: "JOB-001", message: w });
+  } catch (e) {
+    warnings.push({ file: "src/main/java", rule: "lint-error", message: `could not lint: ${e.message}` });
+  }
+
+  // SEED-001 (2026-09-10, REAL) — validate metadata/seed-data/*.json against
+  // plugin-seed-data.schema.json + the per-config-entity row schemas, and
+  // sanity-check that a seed row's target entity is shipped by this plugin or
+  // is a known shared platform config entity. See ai/patterns/plugin-install-data-seeding.md.
+  const seedDir = path.join(abs, "metadata", "seed-data");
+  const SHARED_CONFIG_ENTITIES = {
+    entity_status_date_sweep_config: "entity-status-date-sweep-config",
+    entity_aggregation_config: "entity-aggregation-config",
+    entity_cadence_config: "entity-cadence-config",
+    entity_compliance_config: "entity-compliance-config",
+    entity_cross_plugin_action_config: "entity-cross-plugin-action-config",
+    entity_document_generator_config: "entity-document-generator-config",
+    workflow_reminder_config: null,
+    data_service_snapshot_config: null,
+    platform_recommendation_rule: null,
+    platform_rescore_sweep_config: null,
+  };
+  let ownEntities = new Set();
+  try { ownEntities = new Set(readdirSync(path.join(abs, "metadata", "entities")).filter((f) => f.endsWith(".json")).map((f) => f.replace(/\.json$/, ""))); } catch { /* none */ }
+  let seedFiles = [];
+  try { seedFiles = readdirSync(seedDir).filter((f) => f.endsWith(".json")); } catch { /* no seed-data */ }
+  const seedFileSchema = JSON.parse(readFileSync(schemaPathByName("plugin-seed-data"), "utf8"));
+  for (const f of seedFiles) {
+    try {
+      const doc = JSON.parse(readFileSync(path.join(seedDir, f), "utf8"));
+      for (const issue of simpleSchemaCheck(doc, seedFileSchema, "$")) warnings.push({ file: `seed-data/${f}`, rule: "SEED-001", message: issue });
+      if (doc.entity && !(doc.entity in SHARED_CONFIG_ENTITIES) && !ownEntities.has(doc.entity)) {
+        warnings.push({ file: `seed-data/${f}`, rule: "SEED-001", message: `[SEED-001] seed target entity "${doc.entity}" is neither shipped by this plugin (metadata/entities/${doc.entity}.json) nor a known shared platform config entity — it must exist on the tenant before install or the seed is silently skipped` });
+      }
+      const rowSchemaName = SHARED_CONFIG_ENTITIES[doc.entity];
+      if (rowSchemaName && Array.isArray(doc.rows)) {
+        const rowSchema = readSchema(rowSchemaName).schema;
+        doc.rows.forEach((row, i) => {
+          for (const issue of simpleSchemaCheck(row, rowSchema, `$.rows[${i}]`)) warnings.push({ file: `seed-data/${f}`, rule: "SEED-001", message: issue });
+        });
+      }
+    } catch (e) {
+      warnings.push({ file: `seed-data/${f}`, rule: "lint-error", message: `could not lint: ${e.message}` });
+    }
+  }
+
+  return { pluginDir, pagesChecked: pageFiles.length, dataServicesChecked: dsFiles.length, seedFilesChecked: seedFiles.length, warningCount: warnings.length, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// erp_search_docs — grep across the ai/ doc convention (not low-code-docs/).
+// ---------------------------------------------------------------------------
+function walkFiles(dir, exts, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walkFiles(full, exts, out);
+    else if (exts.some((ext) => e.name.endsWith(ext))) out.push(full);
+  }
+  return out;
+}
+
+// [FIXED 2026-09-04, real gap] — this used to search ONLY hand-written
+// ai/domains/*.md narrative docs, with no way to check a doc's claim against
+// the actual platform-runtime source. That let a false "no report-builder
+// infrastructure exists anywhere in this codebase" claim propagate unverified
+// across five module docs even though a real ReportDefinitionService/
+// BiReportDefinitionService engine existed the whole time. Every result is
+// now tagged `source: "ai/domains doc"` (a human-curated claim — may be
+// stale) or `source: "live engine-* source"` (mechanically re-derived by
+// `erp platform catalog`, see erp.mjs's own buildEngineCatalog/
+// searchEngineCatalog — cannot be stale in the same way) so a query can never
+// again come back with ONLY the possibly-stale half.
+function searchDocsTool(query, maxResults = 20) {
+  const q = query.toLowerCase();
+  const docHits = [];
+  for (const root of docsSearchRoots()) {
+    const files = walkFiles(root.dir, [".md"]);
+    for (const file of files) {
+      const lines = readFileSync(file, "utf8").split("\n");
+      lines.forEach((line, i) => {
+        if (line.toLowerCase().includes(q)) {
+          docHits.push({ source: root.source, file: path.relative(root.relBase, file), line: i + 1, text: line.trim() });
+        }
+      });
+      if (docHits.length >= maxResults) break;
+    }
+    if (docHits.length >= maxResults) break;
+  }
+  let engineHits = [];
+  try {
+    engineHits = searchEngineCatalog(query).hits.slice(0, maxResults).map((h) => ({
+      source: h.kind === "java-contract" ? "java contract" : "live engine-* source",
+      engine: h.engine,
+      kind: h.kind,
+      match: h.match,
+      file: h.file ?? null,
+      unit: h.unit ?? undefined,
+    }));
+  } catch (e) {
+    engineHits = [{ source: "live engine-* source", error: `catalog unavailable: ${e.message}` }];
+  }
+  // `matches`/`truncated` keep their EXACT original shape (ai/domains/*.md
+  // doc hits only) — no existing caller of this tool breaks. `engineMatches`
+  // is purely additive: the live engine-* source hits this fix adds.
+  return {
+    query,
+    matches: docHits.slice(0, maxResults),
+    truncated: docHits.length > maxResults,
+    engineMatches: engineHits,
+    note: "`matches` are human-curated narrative claims (ai/domains/*.md) — check `engineMatches` (mechanically scanned from real backend/platform-runtime/engine-* source, via erp.mjs's buildEngineCatalog/searchEngineCatalog) before treating an absence in `matches` as proof a capability doesn't exist.",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// erp_search_examples — real shipped metadata JSON across backend/modules,
+// per the doc's Layer-4 "how do I combine these correctly" ask.
+// ---------------------------------------------------------------------------
+function searchExamplesTool(pattern, kind = "page", maxResults = 10) {
+  const modulesDir = examplesModulesRoot();
+  // 2026-09-03, real gap found and fixed (mirrored in tools/erp-cli/erp.mjs's own
+  // examplesSearchCommand): data-service/data-view/rules/menu were entirely
+  // unsearchable, so a developer/AI looking for a real "searchable related-record
+  // lookup" Data Service precedent (the core.lookup optionsSourceKey recipe) had no
+  // way to find one through this tool at all.
+  const kindDirs = { page: "page", workflow: "workflow", entities: "entities", provider: "provider", "data-service": "data_service", "data-view": "data_view", rules: "rules", menu: "menu" };
+  const sub = kindDirs[kind];
+  if (!sub) throw new Error(`unknown kind "${kind}". Known kinds: ${Object.keys(kindDirs).join(", ")}`);
+  const results = [];
+  let moduleDirs;
+  try {
+    moduleDirs = readdirSync(modulesDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+  } catch {
+    return { pattern, kind, matches: [] };
+  }
+  const p = pattern.toLowerCase();
+  for (const mod of moduleDirs) {
+    const target = path.join(modulesDir, mod.name, "spk-assembly", "metadata", sub);
+    let files;
+    try {
+      files = readdirSync(target).filter((f) => f.endsWith(".json"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.toLowerCase().includes(p) || mod.name.toLowerCase().includes(p)) {
+        results.push(path.join("backend", "modules", path.relative(modulesDir, path.join(target, f))).replace(/\\/g, "/"));
+      }
+      if (results.length >= maxResults) break;
+    }
+    if (results.length >= maxResults) break;
+  }
+  return { pattern, kind, matches: results };
+}
+
+// ---------------------------------------------------------------------------
+// erp_examples_patterns — [REAL, added 2026-09-03] MCP mirror of the CLI's
+// `erp examples patterns` — a curated catalog of named SHAPES (not just
+// filenames), each pointing at a real shipped file confirmed to actually
+// have that shape. Real gap this closes: `erp_search_examples` above only
+// ever returns filenames matching a substring, which still requires an AI
+// driving purely through MCP (no filesystem/source access otherwise) to
+// read N files to find the ONE real precedent for a named shape (e.g.
+// "single-actor self-decide workflow", or — added 2026-09-03 — "mark a
+// foreign-key field for automatic id->display-name resolution"). Shares
+// ONE catalog (tools/erp-cli/example-patterns.mjs) with the CLI command so
+// a developer on either surface sees the identical list, never a drifted
+// copy — see that file's own doc comment.
+// ---------------------------------------------------------------------------
+function examplesPatternsTool(kind) {
+  const kinds = kind ? [kind] : Object.keys(EXAMPLE_PATTERNS);
+  const out = {};
+  for (const k of kinds) {
+    const patterns = EXAMPLE_PATTERNS[k];
+    if (!patterns) { out[k] = { error: `no curated patterns for kind "${k}" — known kinds: ${Object.keys(EXAMPLE_PATTERNS).join(", ")}` }; continue; }
+    out[k] = patterns.map((p) => ({
+      name: p.name,
+      description: p.description,
+      file: p.file,
+      fileExists: existsSync(exampleFileAbs(p.file)),
+    }));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// erp_list_blocks — [REAL, added 2026-09-04] mirrors tools/erp-cli/erp.mjs's
+// `erp blocks list` exactly, same real gap/same fix: no MCP tool enumerated
+// the actual widget/block catalog (~124 real types) with their real
+// properties/events/outputs — `erp_list_schemas`'s `block-definition`/
+// `block-instance` only describe the generic per-INSTANCE contract shape,
+// not what each concrete blockType (core.grid, core.lookup, ...) itself
+// accepts. Derived live from @erp/block-engine's own built dist
+// (`coreBlockTypes()`), never hand-maintained, so it can't drift.
+// ---------------------------------------------------------------------------
+async function loadBlockDefinitionsTool() {
+  // Packaged mode: the frozen blocks.json in the authoring bundle. Monorepo
+  // mode: derived live from @erp/block-engine's own dist registry.
+  const catalogPath = blocksCatalogPath();
+  if (catalogPath) {
+    return JSON.parse(readFileSync(catalogPath, "utf8"));
+  }
+  const mod = await import(blockEngineModuleUrl());
+  return mod.coreBlockTypes().map((bt) => bt.definition);
+}
+
+function summarizeBlockDefinitionTool(def) {
+  return {
+    type: def.type,
+    category: def.designer?.category ?? null,
+    displayNameKey: def.designer?.displayNameKey ?? null,
+    descriptionKey: def.designer?.descriptionKey ?? null,
+    icon: def.designer?.icon ?? null,
+    allowedTargets: def.designer?.allowedTargets ?? [],
+    inputClass: !!def.inputClass,
+    properties: (def.properties ?? []).map((p) => ({ name: p.name, type: p.type, sources: p.sources ?? [], editor: p.designer?.editor ?? null })),
+    outputs: (def.outputs ?? []).map((o) => ({ name: o.name, type: o.type })),
+    events: (def.events ?? []).map((e) => ({ name: e.name, catalogType: e.catalogType ?? null })),
+  };
+}
+
+async function listBlocksTool(type, category) {
+  const defs = await loadBlockDefinitionsTool();
+  let filtered = defs;
+  if (type) {
+    const needle = type.toLowerCase();
+    filtered = filtered.filter((d) => d.type.toLowerCase().includes(needle));
+  }
+  if (category) {
+    const needle = category.toLowerCase();
+    filtered = filtered.filter((d) => (d.designer?.category ?? "").toLowerCase() === needle);
+  }
+  if (type && filtered.length === 1) {
+    return filtered[0]; // exact-ish single match: full raw definition, every designer/labelKey detail
+  }
+  return { totalRegistered: defs.length, matched: filtered.length, blocks: filtered.map(summarizeBlockDefinitionTool) };
+}
+
+// ---------------------------------------------------------------------------
+// erp_tail_logs — [REAL, added 2026-09-04] mirrors tools/erp-cli/erp.mjs's
+// `erp logs tail` exactly, same real gap/same fix: engine-api logged to
+// console ONLY (see application.yml's `logging.file.name`, added alongside
+// this) — an AI driving purely through MCP had no way to see server-side
+// error detail (a real stack trace, not just an HTTP response's own message)
+// for a failed call. Every real API response carries a real
+// `X-Correlation-Id` header matching the log's own `[cid=...]` token on
+// every line for that request — pass it as `grep` to get exactly that
+// request's real trace. No `--follow` here (an MCP tool call is one
+// request/response, not a long-lived stream) — call it again for fresh
+// lines.
+// ---------------------------------------------------------------------------
+function tailLogsTool(lines = 200, grep, file) {
+  requireMonorepo("erp_tail_logs");
+  const logPath = file ? path.resolve(file) : path.join(REPO_ROOT, "backend/platform-runtime/engine-api/logs/engine-api.log");
+  if (!existsSync(logPath)) {
+    throw new Error(`no log file at ${path.relative(REPO_ROOT, logPath)} — engine-api needs to have been (re)started since logging.file.name was set.`);
+  }
+  let allLines = readFileSync(logPath, "utf8").split("\n");
+  if (grep) allLines = allLines.filter((l) => l.includes(grep));
+  if (allLines.length === 0) return { matched: 0, lines: [] };
+  const tail = allLines.slice(-lines);
+  return { matched: allLines.length, lines: tail };
+}
+
+// ---------------------------------------------------------------------------
+// erp_service_plugin_scaffold — [REAL, added 2026-09-14, Polyglot Plugin
+// Runtime initiative] wraps the REAL `platform-cli service-plugin:scaffold`
+// command (frontend/packages/platform-cli/src/servicePluginScaffold.ts's
+// `scaffoldServicePlugin`, already a clean, directly-callable exported
+// function — no adaptation needed, it was already used this way by
+// cli.ts's own `service-plugin:scaffold` case and by
+// servicePluginScaffold.test.ts, so this tool is a thin wrapper, not a
+// re-derivation). Real gap this closes: erp_plugin_scaffold above only
+// emits Java/PF4J extension-point skeletons (rest-contribution/
+// seed-data-config) — makes sense, those ARE Java-only PF4J concepts — but
+// a Service-mode plugin (a standalone Python/FastAPI or Node.js/Express
+// process that self-registers against engine-api, never PF4J-loaded; see
+// servicePluginScaffold.ts's own doc comment) had NO MCP-visible scaffold
+// path at all, even though the real CLI command has existed since this
+// same initiative's earlier batch. Both the disk-writing (`writeScaffoldToDisk`)
+// and in-memory (`scaffoldServicePlugin`) halves are imported from
+// platform-cli's own built dist/index.js — same "wrap real code" convention
+// every other tool in this file follows, no template logic re-implemented
+// here.
+// ---------------------------------------------------------------------------
+async function serviceScaffoldTool(args) {
+  requireMonorepo("erp_service_plugin_scaffold");
+  if (!args.id) throw new Error('"id" is required, e.g. "acme-inventory-sync".');
+  if (args.runtime !== "python" && args.runtime !== "nodejs") {
+    throw new Error(`"runtime" must be "python" or "nodejs" (got ${JSON.stringify(args.runtime)}).`);
+  }
+  if (!args.out) throw new Error('"out" is required — the directory to scaffold the project into (absolute or repo-root-relative).');
+
+  // dist/index.js is the library entry (`main`/`exports["."]`) — cli.js is
+  // the argv-parsing entrypoint (see package.json's own `bin`/`exports`
+  // split); we call the real exported functions directly, exactly as
+  // cli.ts's `service-plugin:scaffold` case and the package's own vitest
+  // suite already do, rather than shelling out to the CLI as a subprocess.
+  const cliMod = await import(pathToFileURL(path.join(REPO_ROOT, "frontend/packages/platform-cli/dist/index.js")).href);
+  const project = cliMod.scaffoldServicePlugin({
+    id: args.id,
+    runtime: args.runtime,
+    ...(args.vendor ? { vendor: args.vendor } : {}),
+    ...(args.port ? { port: Number(args.port) } : {}),
+  });
+  const outDir = path.isAbsolute(args.out) ? args.out : path.join(REPO_ROOT, args.out);
+  const written = await cliMod.writeScaffoldToDisk(outDir, project);
+  return {
+    id: args.id,
+    runtime: args.runtime,
+    outDir,
+    fileCount: written.length,
+    files: written.map((f) => path.relative(outDir, f).replace(/\\/g, "/")),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// erp_list_grammar_rules — named RULE-xxx catalog per the doc's "give the AI
+// grammar rules" ask. Every entry here is a rule a REAL mechanism already
+// enforces today (page-validator or the erp CLI's workflow checks) — this
+// tool documents/names them, it does not add new enforcement.
+// ---------------------------------------------------------------------------
+const GRAMMAR_RULES = [
+  { code: "PAGE-001", rule: "A block instance's blockType must resolve to a registered block type (or be a known composite/custom type).", enforcedBy: "tools/page-validator/validate-page-properties.mjs (validateInstanceConfig, unknown-block-type)" },
+  { code: "PAGE-002", rule: "A block instance's properties must only use property names/value shapes the block type declares (no unknown properties, no invalid bindings, correct enum/min/max/maxLength, no unknown events).", enforcedBy: "tools/page-validator/validate-page-properties.mjs (validateInstanceConfig)" },
+  { code: "PAGE-003", rule: "A required property must actually be present.", enforcedBy: "tools/page-validator/validate-page-properties.mjs (missing-required-property)" },
+  { code: "PAGE-004", rule: "A page's own top-level structure (rows/overlays/variants/designer metadata) must be structurally valid.", enforcedBy: "@erp/page-engine's validatePageDefinition, wired into tools/page-validator/validate-page-properties.mjs" },
+  { code: "PAGE-005", rule: "An instanceId must be a plain kebab-case identifier — no whitespace.", enforcedBy: "tools/page-validator/validate-page-properties.mjs (hasWhitespaceInstanceId)" },
+  { code: "PAGE-006", rule: "An action's order field, if present, must be an integer.", enforcedBy: "tools/page-validator/validate-page-properties.mjs (validateOrderFields)" },
+  { code: "WF-001", rule: "Every transition's fromStage/toStage must be a stage the workflow actually declares.", enforcedBy: "tools/erp-cli/erp.mjs workflow validate" },
+  { code: "WF-002", rule: "Every task's stage must be a declared stage.", enforcedBy: "tools/erp-cli/erp.mjs workflow validate" },
+  { code: "WF-003", rule: "Every approvalPermissions entry's approvalObject must match a task that actually declares it.", enforcedBy: "tools/erp-cli/erp.mjs workflow validate" },
+  { code: "WF-004", rule: "approvalPermissions references a role by its stable role.code, never a mutable display name.", enforcedBy: "PluginWorkflowInstaller.installApprovalPermissions (Phase 0 role-code fix) — convention, not schema-checked" },
+  { code: "ENTITY-001", rule: "A role rule's role must reference a real role — enforced at write time, not by static JSON validation.", enforcedBy: "EntityRoleFieldRuleValidator (engine-entity)" },
+  { code: "DS-001", rule: "An entity-backed Data Service filter's literal value should match its target field's declared dataType (a \"true\"/\"false\" literal against a boolean field, not a mismatched type) — the static, pre-deploy half of the real BadSqlGrammarException/type-coercion bug found live in HCM Talent Batch 1 (see ai/domains/hcm-talent-management.md); the runtime bug itself is fixed in BiReportQueryExecutor, this catches an author's own mismatched literal going forward.", enforcedBy: "tools/erp-cli/erp.mjs plugin test (lintDataServiceSemantics); also erp_lint_plugin_semantics (MCP)" },
+  { code: "I18N-001", rule: "Every i18n key a page references (labelKey/headerKey/textKey/titleKey/displayNameKey/descriptionKey, including select/lookup option labelKeys) must have a real entry in the plugin's own metadata/i18n/*.json — a missing key renders as a raw ⟦key⟧ placeholder at runtime (found live on HCM Compensation Batch 2's own allowances/benefits pages before this rule existed). A companion heuristic flags a value that is exactly the mechanical Title-Case of a camelCase key tail ending in Btn/Heading/Msg/Label/Toast (the \"newBtn\" -> \"New Btn\" regression class from HCM Talent Batch 2) as a likely un-crafted placeholder.", enforcedBy: "tools/erp-cli/erp.mjs plugin test (lintI18nSemantics); also erp_lint_plugin_semantics (MCP)" },
+  { code: "PERM-SEC-001", rule: "A plugin must never hardcode a tenant id, environment URL, or credential — outgoing self-calls resolve via an env-var-with-localhost-fallback pattern instead.", enforcedBy: "convention, verified by direct code review per module (see feedback-plugins-must-be-environment-portable); not yet a static-analysis check any tool here runs automatically." },
+  { code: "PAGE-DS-001", rule: "A page containing a core.grid block (in its own rows, or any responsive variant's rows) must set a top-level metadata.dataSource naming a real metadata/provider/*.json file's own \"name\" field — core.grid's own block properties (columns/pageSize/externalFilter/search/refreshTrigger) carry no dataSource/entity/recordType at all, so this page-level field is the ONLY real wiring TenantPageHost reads. Omitting it, or naming a provider that doesn't resolve (same plugin or any other shipped plugin), silently renders 0 rows with NO error — found live 3+ times on hcm-employee-documents alone before this rule existed (see ai/domains/ai-native-developer-platform-gap-analysis.md's \"core.grid's real data-source wiring\" section and ai/patterns/grid-data-source-wiring.md for the full chain).", enforcedBy: "tools/erp-cli/erp.mjs plugin test (lintPageDataSourceSemantics); also erp_lint_plugin_semantics (MCP)" },
+  { code: "JOB-001", rule: "A plugin's own src/main/java should not add a new bespoke `@Extension implements ErpJobContribution` class without considering the generic, JSON-configured sweep engines first ([[feedback-json-first-scheduled-jobs]] / ai/domains/project-generic-erp-job-engine-target-architecture.md — e.g. EntityStatusDateSweepJob's entity_status_date_sweep_config for an \"entity status/date crosses now -> flip a field\" shape, WorkflowReminderSweepJob's workflow_reminder_config for a \"remind on a stale pending workflow task\" shape). WARN, not FAIL — genuinely complex job logic legitimately still needs custom Java (the *EffectiveDateJob family, the generic sweep engines themselves); this only makes the tradeoff visible pre-deploy instead of silently defaulting to Java.", enforcedBy: "tools/erp-cli/erp.mjs plugin test (lintJobContributionUsage); also erp_lint_plugin_semantics (MCP)" },
+];
+
+// ---------------------------------------------------------------------------
+// Tool catalog (JSON-RPC facing) — name/description/inputSchema/handler.
+// ---------------------------------------------------------------------------
+const TOOLS = [
+  {
+    name: "erp_list_schemas",
+    description: "List every ERP Plugin Language JSON Schema this platform formally defines (page, block, form, action, rule, plugin-manifest, entity-definition, entity-rule-definition, workflow-definition).",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => Object.fromEntries(Object.entries(SCHEMAS).map(([k, v]) => [k, v.description])),
+  },
+  {
+    name: "erp_get_schema",
+    description: "Fetch the full JSON Schema for one ERP Plugin Language artifact type. Call erp_list_schemas first if unsure of the name.",
+    inputSchema: {
+      type: "object",
+      required: ["name"],
+      properties: { name: { type: "string", enum: Object.keys(SCHEMAS) } },
+    },
+    handler: async (args) => readSchema(args.name),
+  },
+  {
+    name: "erp_validate_page",
+    description: "Validate one page JSON file against the real, running block-engine/page-engine validators (unknown properties, invalid bindings, missing required properties, bad enum values, page-structural defects) — the same check the runtime itself performs, run at authoring time.",
+    inputSchema: {
+      type: "object",
+      required: ["pagePath"],
+      properties: { pagePath: { type: "string", description: "Path to a page JSON file, absolute or repo-root-relative." } },
+    },
+    handler: async (args) => validatePageTool(args.pagePath),
+  },
+  {
+    name: "erp_validate_plugin_pages",
+    description: "Validate every page JSON under <pluginDir>/metadata/page/ (same check spark.js's own `validate` command runs before packaging).",
+    inputSchema: {
+      type: "object",
+      required: ["pluginDir"],
+      properties: { pluginDir: { type: "string", description: "A plugin's spk-assembly directory, absolute or repo-root-relative." } },
+    },
+    handler: async (args) => validatePluginPagesTool(args.pluginDir),
+  },
+  {
+    name: "erp_validate_connector_definition",
+    description: "Schema-check a Generic External Provider Connector Engine definition file (engine-provider-connector's connector-definition schema) — e.g. before running `erp connector create` to actually PUT it to the live backend. Flags a connectorKind=\"HTTP\" row missing baseUrl in addition to the plain schema check.",
+    inputSchema: {
+      type: "object",
+      required: ["filePath"],
+      properties: { filePath: { type: "string", description: "Path to a connector-definition JSON file, absolute or repo-root-relative." } },
+    },
+    handler: async (args) => validateConnectorDefinitionTool(args.filePath),
+  },
+  {
+    name: "erp_lint_plugin_semantics",
+    description: "Run the real semantic lints (page-semantic-lint: wrong-block-for-field/decorative-filters; DS-001: Data Service filter type mismatches; I18N-001: missing/placeholder i18n keys; PAGE-DS-001: a page with a core.grid block missing/mis-naming its top-level metadata.dataSource — the silent \"0 rows, no error\" bug class; JOB-001: a new bespoke ErpJobContribution class instead of a JSON job definition against an already-generic sweep engine) across every page/Data Service/Java source file under <pluginDir> — the same checks `erp plugin test` runs CLI-side, now callable directly over MCP. Heuristic WARNs, not hard failures — review each one.",
+    inputSchema: {
+      type: "object",
+      required: ["pluginDir"],
+      properties: { pluginDir: { type: "string", description: "A plugin's spk-assembly directory, absolute or repo-root-relative." } },
+    },
+    handler: async (args) => lintPluginSemanticsTool(args.pluginDir),
+  },
+  {
+    name: "erp_search_docs",
+    description: "Full-text search across ai/ (this repo's real, current architecture/pattern/domain docs — not low-code-docs/, which is raw spec input) PLUS a live, mechanically-derived scan of every backend/platform-runtime/engine-* module's real classes/REST mappings/Flyway tables (`engineMatches`, via `erp platform catalog`). Always check `engineMatches` before writing a 'this capability doesn't exist' disclosure — a hand-written ai/domains/*.md doc can be stale (found live: a false 'no report-builder infrastructure exists anywhere in this codebase' claim propagated across 5 module docs even though ReportDefinitionService/BiReportDefinitionService already existed).",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: { query: { type: "string" }, maxResults: { type: "integer", default: 20 } },
+    },
+    handler: async (args) => searchDocsTool(args.query, args.maxResults ?? 20),
+  },
+  {
+    name: "erp_platform_catalog",
+    description: "The real, mechanically-derived capability inventory of every backend/platform-runtime/engine-* module (public classes/interfaces, REST @*Mapping base paths, Flyway migration table names) — `erp platform catalog`'s MCP twin. Use this (or erp_search_docs, which already includes it) BEFORE writing any 'no X infrastructure exists' disclosure in a new module's docs. Omit both filters to list every engine module with counts; pass `engine` for one module's full class/REST/migration detail; pass `query` to search by substring/keyword across all modules (same matching erp_search_docs uses for its engineMatches).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        engine: { type: "string", description: "Exact engine-* module name, e.g. \"engine-form\" — returns that module's full detail." },
+        query: { type: "string", description: "Search term across module names/classes/REST paths/migration tables, e.g. \"report builder\" or \"pluggable provider\"." },
+        refresh: { type: "boolean", default: false, description: "Regenerate the cache (ai/platform/engine-capability-catalog.json) from a fresh source scan instead of reading the cached one." },
+      },
+    },
+    handler: async (args) => {
+      if (args.query) return searchEngineCatalog(args.query, { refresh: !!args.refresh });
+      const catalog = buildEngineCatalog({ refresh: !!args.refresh });
+      if (args.engine) {
+        const e = catalog.engines[args.engine];
+        if (!e) throw new Error(`unknown engine "${args.engine}". Known: ${Object.keys(catalog.engines).join(", ")}`);
+        return e;
+      }
+      return {
+        generatedAt: catalog.generatedAt,
+        engineCount: catalog.engineCount,
+        engines: Object.fromEntries(Object.entries(catalog.engines).map(([name, e]) => [name, { classCount: e.classCount, restMappingCount: e.controllerBasePaths.length, migrationCount: e.ownedMigrations.length + e.relatedSharedMigrations.length }])),
+      };
+    },
+  },
+  {
+    name: "erp_platform_describe",
+    description: "Real method signatures/field lists for a CURATED set of genuinely-reusable plugin extension-point/gateway-client classes (every *Contribution interface in engine-plugin-api, the canonical WorkflowGatewayClient + its real response records InstanceView/InstanceHumanTask/HistoryEntry/PendingHumanTask/DecidedCount, every per-plugin DmsGatewayClient/WorkflowGatewayClient/CommunicationGatewayClient copy under backend/modules) — the concrete answer to 'what does PendingHumanTask actually contain' or 'what does DmsGatewayClient.uploadFile take' WITHOUT opening the Java source. Matches by partial, case-insensitive name; a name matching multiple per-plugin copies returns all of them (they're hand-copied, not shared, and may have drifted — each result is tagged with its owning file). Not exhaustive over the whole repo — only this curated set; use erp_platform_catalog first to check whether a class exists at all.",
+    inputSchema: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string", description: "Partial or full class/interface/record name, e.g. \"PendingHumanTask\" or \"DmsGatewayClient\"." },
+        refresh: { type: "boolean", default: false, description: "Regenerate the underlying catalog cache from a fresh source scan first." },
+      },
+    },
+    handler: async (args) => {
+      const matches = describeContract(args.name, { refresh: !!args.refresh });
+      if (!matches.length) {
+        return { name: args.name, matches: [], note: "No match in the curated extension-point/gateway-client set. Try erp_platform_catalog with `query` to search the full class inventory instead." };
+      }
+      return { name: args.name, matches };
+    },
+  },
+  {
+    name: "erp_plugin_scaffold",
+    description: "Emits a minimal, correctly-typed Java skeleton for one curated plugin extension point, pulled from a REAL existing shipped implementation in this codebase (not invented syntax) — currently: rest-contribution (modeled on backend/modules/hello-plugin's real HelloRestContribution.java). Use this instead of hand-writing an extension-point class from a guess.",
+    inputSchema: {
+      type: "object",
+      required: ["extensionPoint"],
+      properties: {
+        extensionPoint: { type: "string", enum: Object.keys(SCAFFOLD_TEMPLATES) },
+        packageName: { type: "string", description: "Java package for the scaffolded class, e.g. \"com.example.myplugin\"." },
+        className: { type: "string", description: "Class name for the scaffolded class, e.g. \"MyRestContribution\"." },
+        pluginId: { type: "string", description: "Plugin id used in the REST base path (/api/v1/plugins/<pluginId>)." },
+      },
+    },
+    handler: async (args) => {
+      const tpl = SCAFFOLD_TEMPLATES[args.extensionPoint];
+      if (!tpl) return { error: `unknown extensionPoint "${args.extensionPoint}". Known: ${Object.keys(SCAFFOLD_TEMPLATES).join(", ")}` };
+      const pluginId = args.pluginId || "my-plugin";
+      const packageName = args.packageName || `com.example.${pluginId.replace(/[^a-zA-Z0-9]/g, "")}`;
+      const className = args.className || "MyRestContribution";
+      return { extensionPoint: args.extensionPoint, describe: tpl.describe, packageName, className, pluginId, source: tpl.render({ packageName, className, pluginId }) };
+    },
+  },
+  {
+    name: "erp_service_plugin_scaffold",
+    description: "Generate a REAL, runnable Service-mode plugin starter project (Python/FastAPI or Node.js/Express) on disk — wraps the actual `platform-cli service-plugin:scaffold` command/scaffoldServicePlugin function, not invented syntax. A Service-mode plugin is a standalone process (own Dockerfile, own launcher script) that self-registers/heartbeats against engine-api via POST/DELETE /api/v1/platform/service-registrations — it is NEVER PF4J-loaded/hot-installed the way a `.spk` Java plugin is, so use erp_plugin_scaffold instead for a Java extension-point class. Writes real files to `out` and returns the actual list written (no fabricated success).",
+    inputSchema: {
+      type: "object",
+      required: ["id", "runtime", "out"],
+      properties: {
+        id: { type: "string", description: "Plugin id, e.g. \"acme-inventory-sync\" — used as plugin.json's own id and the self-registration applicationCode." },
+        runtime: { type: "string", enum: ["python", "nodejs"], description: "\"python\" generates a FastAPI project; \"nodejs\" generates an Express/TypeScript project." },
+        out: { type: "string", description: "Directory to scaffold the project into, absolute or repo-root-relative. Created if it doesn't exist." },
+        vendor: { type: "string", description: "Vendor name for plugin.json. Defaults to \"Unknown Vendor\"." },
+        port: { type: "integer", description: "Port the scaffolded process listens on and self-registers with. Defaults to 8100." },
+      },
+    },
+    handler: async (args) => serviceScaffoldTool(args),
+  },
+  {
+    name: "erp_list_grammar_rules",
+    description: "List the named RULE-xxx grammar rules this platform's real validators actually enforce today (page/block/workflow structural rules, plus documented-but-not-yet-automated conventions) — grounds 'is this allowed' in a concrete, cited enforcement point instead of a guess.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => GRAMMAR_RULES,
+  },
+  {
+    name: "erp_search_examples",
+    description: "Find real, already-shipped example metadata JSON files (page/workflow/entities/provider) across every backend/modules/* plugin whose filename or plugin name matches a substring — grounds 'how do I author X' in a genuine precedent instead of an invented shape.",
+    inputSchema: {
+      type: "object",
+      required: ["pattern"],
+      properties: {
+        pattern: { type: "string" },
+        kind: { type: "string", enum: ["page", "workflow", "entities", "provider", "data-service", "data-view", "rules", "menu"], default: "page" },
+        maxResults: { type: "integer", default: 10 },
+      },
+    },
+    handler: async (args) => searchExamplesTool(args.pattern, args.kind, args.maxResults),
+  },
+  {
+    name: "erp_examples_patterns",
+    description: "The curated catalog of named SHAPES (workflow/page/entities), not just filenames — each entry names a recurring authoring problem (e.g. 'mark a foreign-key field for automatic id->display-name resolution', 'related-record-lookup-field', 'multi-stage-conditional-branching') and points at a real shipped file confirmed to have that shape. Use this before erp_search_examples when you know WHAT you're trying to build but not which existing plugin already solved it. Omit kind to list every catalog entry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: Object.keys(EXAMPLE_PATTERNS), description: "Omit to list all kinds." },
+      },
+    },
+    handler: async (args) => examplesPatternsTool(args.kind),
+  },
+  {
+    name: "erp_list_blocks",
+    description: "The real widget/block catalog (~124 registered types — core.grid, core.lookup, core.date-picker, core.file-upload, etc.), derived live from @erp/block-engine's own registry — every property/event/output any block type actually accepts. Closes the real gap where a developer building a page purely through this CLI/MCP had no way to discover 'what widgets exist and what can each one do' without already knowing a widget's name (for erp_search_examples) or reading block-engine source directly. Omit both filters to list every type (summary only); pass type for a single type's FULL definition (every designer group/labelKey too).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Exact or partial blockType to filter/fetch, e.g. \"core.lookup\" or \"lookup\"." },
+        category: { type: "string", description: "Filter by designer category, e.g. \"input\", \"display\", \"layout\", \"data\", \"navigation\"." },
+      },
+    },
+    handler: async (args) => listBlocksTool(args.type, args.category),
+  },
+  {
+    name: "erp_tail_logs",
+    description: "Real engine-api server-side log lines, including full stack traces — closes the real gap where an AI driving purely through MCP had no way to see WHY a call failed beyond its HTTP response body. Every real API response carries a real X-Correlation-Id header matching this log's own [cid=...] token on every line for that request — pass it as `grep` after a failed call to see that exact request's real server-side trace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lines: { type: "integer", default: 200, description: "Max matching lines to return (most recent last)." },
+        grep: { type: "string", description: "Substring filter — typically a request's X-Correlation-Id, or an exception class name." },
+        file: { type: "string", description: "Override log file path; defaults to engine-api's own logs/engine-api.log." },
+      },
+    },
+    handler: async (args) => tailLogsTool(args.lines ?? 200, args.grep, args.file),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// MCP stdio JSON-RPC transport — minimal, spec-shaped, no SDK dependency.
+// ---------------------------------------------------------------------------
+const SERVER_INFO = { name: "erp-plugin-language", version: "0.1.0" };
+const PROTOCOL_VERSION = "2024-11-05";
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function toolResultEnvelope(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+async function handleRequest(req) {
+  const { id, method, params } = req;
+  try {
+    if (method === "initialize") {
+      send({ jsonrpc: "2.0", id, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO } });
+      return;
+    }
+    if (method === "notifications/initialized") {
+      return; // notification, no response
+    }
+    if (method === "tools/list") {
+      send({ jsonrpc: "2.0", id, result: { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) } });
+      return;
+    }
+    if (method === "tools/call") {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) throw new Error(`unknown tool "${params?.name}"`);
+      const result = await tool.handler(params?.arguments ?? {});
+      send({ jsonrpc: "2.0", id, result: toolResultEnvelope(result) });
+      return;
+    }
+    if (id !== undefined) {
+      send({ jsonrpc: "2.0", id, error: { code: -32601, message: `method not found: ${method}` } });
+    }
+  } catch (err) {
+    if (id !== undefined) {
+      send({ jsonrpc: "2.0", id, error: { code: -32000, message: err.message } });
+    }
+  }
+}
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let req;
+  try {
+    req = JSON.parse(trimmed);
+  } catch {
+    return; // ignore non-JSON noise on stdin
+  }
+  handleRequest(req);
+});