mcp-efficiency-engine 0.1.0

package/bin/install-host.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const scaffoldEntries = [
+  ".github",
+  ".vscode",
+  "autodocs/README.md",
+  "autodocs/schema",
+  "autolearning",
+  "context/repomix/repomix.config.json",
+  "memory",
+  "observability",
+  "optimization",
+  "orchestrator",
+  "policies",
+  "repo-intake",
+  "repo-registry/repos.schema.json",
+  "repo-registry/repos.template.json",
+  "scripts",
+  "specs",
+  "templates",
+  "tooling",
+  "AGENTS.md",
+  "ARCHITECTURE.md",
+  "FINAL_USAGE_GUIDE.md",
+  "README.md",
+  "README_WIKI.md",
+  "LICENSE",
+  "requirements.txt",
+];
+
+const runtimeDirs = [
+  ".cache/github-repos",
+  "autodocs/generated",
+  "autodocs/site",
+  "context/graphify-out",
+  "context/repomix",
+  "observability/logs/session",
+  "repo-registry",
+  "repo-intake/generated/reports",
+];
+
+function parseArgs(argv) {
+  const options = {
+    postinstall: false,
+    force: false,
+    skipBootstrap: false,
+    nonInteractive: false,
+    targetDir: process.env.MCPEE_TARGET_DIR || process.env.INIT_CWD || process.cwd(),
+    owner: process.env.MCPEE_OWNER || "",
+    repoPrefix: process.env.MCPEE_REPO_PREFIX || "",
+    initialRepoName: process.env.MCPEE_INITIAL_REPO_NAME || "",
+    initialRepoDomain: process.env.MCPEE_INITIAL_REPO_DOMAIN || "",
+    initialRepoLocation: process.env.MCPEE_INITIAL_REPO_LOCATION || "",
+    skipInitialRepo: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "-h":
+      case "--help":
+      case "help":
+        options.help = true;
+        break;
+      case "--postinstall":
+        options.postinstall = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "--skip-bootstrap":
+        options.skipBootstrap = true;
+        break;
+      case "--non-interactive":
+        options.nonInteractive = true;
+        break;
+      case "--skip-initial-repo":
+        options.skipInitialRepo = true;
+        break;
+      case "--target":
+        options.targetDir = argv[index + 1] || options.targetDir;
+        index += 1;
+        break;
+      case "--owner":
+        options.owner = argv[index + 1] || options.owner;
+        index += 1;
+        break;
+      case "--repo-prefix":
+        options.repoPrefix = argv[index + 1] || options.repoPrefix;
+        index += 1;
+        break;
+      case "--initial-repo-name":
+        options.initialRepoName = argv[index + 1] || options.initialRepoName;
+        index += 1;
+        break;
+      case "--initial-repo-domain":
+        options.initialRepoDomain = argv[index + 1] || options.initialRepoDomain;
+        index += 1;
+        break;
+      case "--initial-repo-location":
+        options.initialRepoLocation = argv[index + 1] || options.initialRepoLocation;
+        index += 1;
+        break;
+      default:
+        break;
+    }
+  }
+
+  if (process.env.MCPEE_SKIP_POSTINSTALL === "1") {
+    options.skipBootstrap = true;
+  }
+
+  if (process.env.CI === "true" || !process.stdin.isTTY) {
+    options.nonInteractive = true;
+  }
+
+  return options;
+}
+
+function printInstallHelp() {
+  process.stdout.write(
+    [
+      "mcpee install [opciones]",
+      "",
+      "Opciones:",
+      "  --target <ruta>            Proyecto host donde scaffoldar el engine.",
+      "  --force                    Sobrescribe archivos scaffold cuando ya existan.",
+      "  --skip-bootstrap           Copia artefactos e inicializa registry plantilla sin bootstrap.",
+      "  --non-interactive          Evita prompts; deja registry plantilla listo para editar luego.",
+      "  --owner <valor>            Owner para repo-registry/repos.yml.",
+      "  --repo-prefix <valor>      Prefijo de nombres para repos del intake.",
+      "  --skip-initial-repo        Crea el registry sin alta inicial de repos.",
+    ].join("\n") + "\n",
+  );
+}
+
+function normalizePath(inputPath) {
+  return path.resolve(inputPath);
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function copyFile(sourcePath, targetPath, overwrite) {
+  ensureDir(path.dirname(targetPath));
+  if (!overwrite && fs.existsSync(targetPath)) {
+    const sourceContent = fs.readFileSync(sourcePath);
+    const targetContent = fs.readFileSync(targetPath);
+    if (Buffer.compare(sourceContent, targetContent) === 0) {
+      return { copied: false, skipped: true, reason: "same" };
+    }
+
+    return { copied: false, skipped: true, reason: "exists" };
+  }
+
+  fs.copyFileSync(sourcePath, targetPath);
+  return { copied: true, skipped: false, reason: "copied" };
+}
+
+function copyEntry(sourceRelativePath, targetRoot, overwrite, stats) {
+  const sourcePath = path.join(packageRoot, sourceRelativePath);
+  const targetPath = path.join(targetRoot, sourceRelativePath);
+
+  if (!fs.existsSync(sourcePath)) {
+    return;
+  }
+
+  const entry = fs.statSync(sourcePath);
+  if (entry.isDirectory()) {
+    ensureDir(targetPath);
+    for (const childName of fs.readdirSync(sourcePath)) {
+      copyEntry(path.posix.join(sourceRelativePath.replaceAll(path.sep, "/"), childName), targetRoot, overwrite, stats);
+    }
+    return;
+  }
+
+  const result = copyFile(sourcePath, targetPath, overwrite);
+  if (result.copied) {
+    stats.copied += 1;
+    return;
+  }
+
+  if (result.reason === "exists") {
+    stats.skippedExisting += 1;
+  }
+}
+
+function ensureRuntimeLayout(targetRoot) {
+  for (const dirRelativePath of runtimeDirs) {
+    ensureDir(path.join(targetRoot, dirRelativePath));
+  }
+}
+
+function resolveShellCandidates() {
+  if (process.platform === "win32") {
+    return ["pwsh", "powershell"];
+  }
+
+  return ["pwsh"];
+}
+
+function runPowerShell(scriptPath, args, cwd) {
+  const shellCandidates = resolveShellCandidates();
+  for (const shellCommand of shellCandidates) {
+    const result = spawnSync(shellCommand, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, ...args], {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    if (result.error && result.error.code === "ENOENT") {
+      continue;
+    }
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.status ?? 0;
+  }
+
+  throw new Error("PowerShell no esta disponible. Instala pwsh para completar la instalacion.");
+}
+
+function deriveRepoPrefix(targetRoot, options) {
+  if (options.repoPrefix) {
+    return options.repoPrefix;
+  }
+
+  return `${path.basename(targetRoot).replace(/[^a-zA-Z0-9_-]/g, "-").toLowerCase()}_`;
+}
+
+function initializeTemplateRegistry(targetRoot, options) {
+  const registryPath = path.join(targetRoot, "repo-registry", "repos.yml");
+  if (fs.existsSync(registryPath)) {
+    return 0;
+  }
+
+  const initScript = path.join(targetRoot, "scripts", "intake", "init-template-registry.ps1");
+  const args = [
+    "-Owner",
+    options.owner || "your-team",
+    "-RepoNamePrefix",
+    deriveRepoPrefix(targetRoot, options),
+    "-SkipInitialRepo",
+  ];
+
+  return runPowerShell(initScript, args, targetRoot);
+}
+
+function runBootstrap(targetRoot) {
+  const bootstrapScript = path.join(targetRoot, "scripts", "bootstrap-portable.ps1");
+  return runPowerShell(bootstrapScript, [], targetRoot);
+}
+
+function runHostInstall(rawOptions) {
+  const options = rawOptions;
+  const targetRoot = normalizePath(options.targetDir);
+  const stats = { copied: 0, skippedExisting: 0 };
+
+  if (normalizePath(packageRoot) === targetRoot) {
+    process.stdout.write("[mcpee] Instalacion en el propio repo detectada; se omite scaffold host.\n");
+    return 0;
+  }
+
+  process.stdout.write(`[mcpee] Scaffold del engine en ${targetRoot}\n`);
+  for (const entry of scaffoldEntries) {
+    copyEntry(entry, targetRoot, options.force, stats);
+  }
+
+  ensureRuntimeLayout(targetRoot);
+  process.stdout.write(`[mcpee] Archivos copiados: ${stats.copied}; existentes preservados: ${stats.skippedExisting}\n`);
+
+  if (options.skipBootstrap) {
+    const initStatus = initializeTemplateRegistry(targetRoot, options);
+    if (initStatus !== 0) {
+      return initStatus;
+    }
+
+    process.stdout.write("[mcpee] Bootstrap omitido. Puedes ejecutar .\\scripts\\bootstrap-portable.cmd mas tarde.\n");
+    return 0;
+  }
+
+  if (options.nonInteractive) {
+    const initStatus = initializeTemplateRegistry(targetRoot, options);
+    if (initStatus !== 0) {
+      return initStatus;
+    }
+
+    process.stdout.write("[mcpee] Modo no interactivo detectado. Se inicializo el registry plantilla y se omitio bootstrap interactivo.\n");
+    return 0;
+  }
+
+  return runBootstrap(targetRoot);
+}
+
+function runHostInstallFromCli(argv = process.argv.slice(2)) {
+  try {
+    const options = parseArgs(argv);
+    if (options.help) {
+      printInstallHelp();
+      return 0;
+    }
+    return runHostInstall(options);
+  }
+  catch (error) {
+    process.stderr.write(`[mcpee] ${error.message}\n`);
+    return 1;
+  }
+}
+
+module.exports = {
+  runHostInstall,
+  runHostInstallFromCli,
+};
+
+if (require.main === module) {
+  process.exit(runHostInstallFromCli());
+}

package/bin/mcpee.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const { runHostInstallFromCli } = require("./install-host");
+
+const repoRoot = path.resolve(__dirname, "..");
+const commandMap = {
+  bootstrap: "scripts/bootstrap-portable.ps1",
+  validate: "scripts/setup/validate-context.ps1",
+  hi: "scripts/ops/hi.ps1",
+  bye: "scripts/ops/bye.ps1",
+  intake: "scripts/intake/run-repo-intake.ps1",
+};
+
+function resolveExecutionRoot(scriptRelativePath) {
+  const configuredTarget = process.env.MCPEE_TARGET_DIR ? path.resolve(process.env.MCPEE_TARGET_DIR) : "";
+  const cwdRoot = process.cwd();
+
+  if (configuredTarget && fs.existsSync(path.join(configuredTarget, scriptRelativePath))) {
+    return configuredTarget;
+  }
+
+  if (cwdRoot !== repoRoot && fs.existsSync(path.join(cwdRoot, scriptRelativePath))) {
+    return cwdRoot;
+  }
+
+  return repoRoot;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "mcpee <comando> [args]",
+      "",
+      "Comandos:",
+      "  install    Scaffold del engine en el proyecto actual y ejecuta bootstrap.",
+      "  bootstrap  Ejecuta el bootstrap portable completo.",
+      "  validate   Ejecuta la validacion minima del contexto.",
+      "  hi         Ejecuta el preflight diario.",
+      "  bye        Ejecuta el cierre diario.",
+      "  intake     Ejecuta el repo intake.",
+      "",
+      "Ejemplos:",
+      "  npx mcp-efficiency-engine bootstrap",
+      "  mcpee validate -PortableMode",
+    ].join("\n") + "\n",
+  );
+}
+
+function resolveInvocationCandidates() {
+  if (process.platform === "win32") {
+    return ["pwsh", "powershell"];
+  }
+
+  return ["pwsh"];
+}
+
+function runPowerShellScript(scriptRelativePath, forwardedArgs) {
+  const executionRoot = resolveExecutionRoot(scriptRelativePath);
+  const scriptPath = path.join(executionRoot, scriptRelativePath);
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`Script no encontrado: ${scriptRelativePath}\n`);
+    return 1;
+  }
+
+  const shellCandidates = resolveInvocationCandidates();
+  for (const shellCommand of shellCandidates) {
+    const result = spawnSync(
+      shellCommand,
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, ...forwardedArgs],
+      {
+        cwd: executionRoot,
+        stdio: "inherit",
+      },
+    );
+
+    if (result.error && result.error.code === "ENOENT") {
+      continue;
+    }
+
+    if (result.error) {
+      process.stderr.write(`${result.error.message}\n`);
+      return 1;
+    }
+
+    return result.status ?? 0;
+  }
+
+  process.stderr.write("PowerShell no esta disponible. Instala pwsh para usar este CLI.\n");
+  return 1;
+}
+
+const argv = process.argv.slice(2);
+const firstArg = argv[0] || "bootstrap";
+
+if (["-h", "--help", "help"].includes(firstArg)) {
+  printHelp();
+  process.exit(0);
+}
+
+if (firstArg === "install") {
+  process.exit(runHostInstallFromCli(argv.slice(1)));
+}
+
+const command = commandMap[firstArg] ? firstArg : "bootstrap";
+const forwardedArgs = command === firstArg ? argv.slice(1) : argv;
+
+if (!commandMap[command]) {
+  process.stderr.write(`Comando no soportado: ${firstArg}\n`);
+  printHelp();
+  process.exit(1);
+}
+
+process.exit(runPowerShellScript(commandMap[command], forwardedArgs));

package/context/repomix/repomix.config.json

@@ -0,0 +1,20 @@
+{
+  "output": {
+    "style": "xml",
+    "filePath": "context/repomix/repomix-output.xml",
+    "removeComments": false,
+    "removeEmptyLines": true,
+    "showLineNumbers": true
+  },
+  "ignore": {
+    "customPatterns": [
+      "node_modules/**",
+      "dist/**",
+      "build/**",
+      ".git/**",
+      ".env",
+      ".env.*",
+      "**/*.log"
+    ]
+  }
+}

package/memory/cross-memory-reasoning.md

@@ -0,0 +1,17 @@
+# Cross Memory Reasoning
+
+Used when a query touches multiple domains.
+
+Example:
+
+- code + SLA
+- DBA + architecture
+- docs + business
+
+Process:
+
+1. Query each memory
+2. Extract relevant signals
+3. Merge into unified response
+4. If source is code, resolve symbols via CodeGraph before broad file reads
+5. Register reusable pattern in code-memory feedback loop

package/memory/mempry-registry.yml

@@ -0,0 +1,16 @@
+memories:
+  - name: code-memory
+    engine: codebase-memory
+    retrieval_index: codegraph
+    requires:
+      - codegraph-command
+      - codegraph-index
+
+  - name: knowledge-memory
+    engine: graphify
+
+  - name: enterprise-memory
+    engine: azure-rag
+
+  - name: domain-memory
+    source: repo-registry

package/observability/evals/chat-token-usage-report.json

@@ -0,0 +1,64 @@
+{
+  "timestamp": "2026-07-05T09:54:53.886533+00:00",
+  "source": "observability/logs/iteration-metrics.jsonl",
+  "filters": {
+    "source": "copilot-session",
+    "from": "",
+    "to": ""
+  },
+  "totals": {
+    "events": 36,
+    "input_tokens": 3893402,
+    "output_tokens": 126892,
+    "total_tokens": 4020294,
+    "copilot_credits": 816.9227
+  },
+  "breakdown": {
+    "model": {
+      "copilot/auto": {
+        "count": 36,
+        "input_tokens": 3893402,
+        "output_tokens": 126892,
+        "total_tokens": 4020294,
+        "copilot_credits": 816.9227
+      }
+    },
+    "day": {
+      "2026-07-03": {
+        "count": 19,
+        "input_tokens": 2219137,
+        "output_tokens": 67846,
+        "total_tokens": 2286983,
+        "copilot_credits": 492.07088600000003
+      },
+      "2026-07-04": {
+        "count": 9,
+        "input_tokens": 876490,
+        "output_tokens": 21560,
+        "total_tokens": 898050,
+        "copilot_credits": 160.161499
+      },
+      "2026-07-05": {
+        "count": 8,
+        "input_tokens": 797775,
+        "output_tokens": 37486,
+        "total_tokens": 835261,
+        "copilot_credits": 164.690315
+      }
+    }
+  },
+  "license": {
+    "plan": "business",
+    "seats": 1,
+    "included_credits_per_user_month": 19.0,
+    "included_credits_total_month": 19.0,
+    "official_plans_url": "https://github.com/features/copilot/plans?ref_cta=View+pricing+and+plans&ref_loc=hero&ref_page=%2Ffeatures_copilot_copilot_business&plans=business"
+  },
+  "budget": {
+    "used_copilot_credits": 816.9227,
+    "budget_utilization_rate": 42.995932,
+    "overage_credits": 797.9227,
+    "equivalent_seats_used": 42.995932,
+    "percent_of_one_seat": 4299.59
+  }
+}

package/observability/evals/chat-token-usage-report.md

@@ -0,0 +1,33 @@
+# Chat Token Usage Report
+
+- timestamp: 2026-07-05T09:54:53.886533+00:00
+- source: observability/logs/iteration-metrics.jsonl
+- filter.source: copilot-session
+- filter.from: 
+- filter.to: 
+- plan: business
+- seats: 1
+- official_plans_url: https://github.com/features/copilot/plans?ref_cta=View+pricing+and+plans&ref_loc=hero&ref_page=%2Ffeatures_copilot_copilot_business&plans=business
+
+## Totals
+
+- events: 36
+- input_tokens: 3893402
+- output_tokens: 126892
+- total_tokens: 4020294
+- copilot_credits: 816.9227
+- included_credits_total_month: 19.0
+- budget_utilization_rate: 42.995932
+- overage_credits: 797.9227
+- equivalent_seats_used: 42.995932
+- percent_of_one_seat: 4299.59
+
+## Breakdown by Model
+
+- copilot/auto: count=36, input=3893402, output=126892, total=4020294, credits=816.9227
+
+## Breakdown by Day
+
+- 2026-07-03: count=19, input=2219137, output=67846, total=2286983, credits=492.070886
+- 2026-07-04: count=9, input=876490, output=21560, total=898050, credits=160.161499
+- 2026-07-05: count=8, input=797775, output=37486, total=835261, credits=164.690315

package/observability/evals/iteration-value-report.json

@@ -0,0 +1,76 @@
+{
+  "timestamp": "2026-07-05T09:54:54.568327+00:00",
+  "sources": {
+    "routing": "observability/logs/routing-decisions.jsonl",
+    "feedback": "observability/logs/learning-feedback.jsonl",
+    "metrics": "observability/logs/iteration-metrics.jsonl"
+  },
+  "totals": {
+    "events": 305,
+    "events_with_event_id": 247,
+    "metrics_covered": 7,
+    "feedback_confirmed": 101,
+    "confirmed_success": 101
+  },
+  "kpis": {
+    "metrics_coverage_rate": 0.0283,
+    "confirmed_feedback_rate": 0.4089,
+    "confirmed_success_rate": 1.0,
+    "total_tokens": 6474,
+    "total_cost_usd": 0.0542,
+    "tokens_per_confirmed_success": 64.1,
+    "cost_per_confirmed_success_usd": 0.000537
+  },
+  "breakdown": {
+    "tool_mode": {
+      "hybrid": {
+        "count": 2,
+        "tokens": 2400,
+        "cost_usd": 0.02
+      },
+      "local-only": {
+        "count": 4,
+        "tokens": 4044,
+        "cost_usd": 0.0342
+      },
+      "model-only": {
+        "count": 1,
+        "tokens": 30,
+        "cost_usd": 0.0
+      }
+    },
+    "model": {
+      "GPT-5.3-Codex": {
+        "count": 7,
+        "tokens": 6474,
+        "cost_usd": 0.054200000000000005
+      }
+    },
+    "engine": {
+      "Azure RAG Builder": {
+        "count": 1,
+        "tokens": 1200,
+        "cost_usd": 0.01
+      },
+      "CodeGraph": {
+        "count": 4,
+        "tokens": 2874,
+        "cost_usd": 0.0242
+      },
+      "GitNexus": {
+        "count": 1,
+        "tokens": 1200,
+        "cost_usd": 0.01
+      },
+      "Graphify": {
+        "count": 1,
+        "tokens": 1200,
+        "cost_usd": 0.01
+      }
+    }
+  },
+  "assessment": {
+    "has_value_signal": true,
+    "notes": "Value signal available. Track trend, not one-point absolute values."
+  }
+}