mcp-efficiency-engine 0.1.7 → 0.1.8

package/README.md

@@ -233,19 +233,30 @@ Resumen rapido:
 - La conexion real de boosts/repos ocurre al ejecutar intake.
 - Si no configuras repos adicionales, se usa el repo inicial por defecto.
 
+Flujo recomendado para nuevos usuarios:
+
+- `repo-registry/repos.template.json`: plantilla guiada con dominios y ejemplos.
+- `repo-registry/repos.yml`: registry operativo que consume el intake.
+- `scripts/intake/init-template-registry.cmd`: inicializa `repos.yml` desde la plantilla y pregunta owner/prefix/repo inicial.
+
 Pasos recomendados despues de instalar:
 
 ```powershell
-# 1) (Opcional) editar repos auxiliares/boosts
+# 1) Inicializar registry operativo desde la plantilla (modo asistido)
+.\scripts\intake\init-template-registry.cmd
+
+# 2) (Opcional) ajustar repos auxiliares/boosts
 notepad .\repo-registry\repos.yml
 
-# 2) materializar capacidades de todos los repos del registry
+# 3) materializar capacidades de todos los repos del registry
 .\scripts\intake\run-repo-intake.cmd
 
-# 3) validar que el router ya los ve
+# 4) validar que el router ya los ve
 .\scripts\ops\hi.ps1
 ```
 
+Si quieres preparar entradas manuales, usa los ejemplos de `repo-registry/repos.template.json` (`local`, `github`, `rag_local_github`, `azure_rag_github`) y copialos a `repos.yml`.
+
 Si quieres que te pregunte por owner/prefix/repo inicial en modo asistido, ejecuta:
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-efficiency-engine",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Motor de orquestacion para agentes MCP con routing por dominio y bootstrap portable.",
   "license": "MIT",
   "type": "commonjs",

package/repo-registry/repos.template.json

@@ -1,6 +1,33 @@
 {
   "registry_mode": "template",
   "schema_version": "2.0",
+  "onboarding_help": {
+    "what_is_this": "Define aqui los repos/boosts que quieres conectar al motor de routing.",
+    "quick_start": [
+      "1) Duplica un ejemplo de repo_examples dentro de repos[]",
+      "2) Ajusta domain, type y location/repo_url",
+      "3) Ejecuta scripts/intake/run-repo-intake.cmd",
+      "4) Ejecuta scripts/ops/hi.ps1 para validar"
+    ],
+    "required_fields": [
+      "name",
+      "domain",
+      "type",
+      "location (si type=local)",
+      "repo_url (si type=github)"
+    ],
+    "domain_reference": {
+      "backend": "Codigo backend en repo unico (CodeGraph)",
+      "frontend": "Codigo frontend en repo unico (CodeGraph)",
+      "community-content": "Contenido/comunidad/documentacion de apoyo",
+      "legacy": "Migracion/impacto multi-repo (GitNexus)",
+      "dba": "SQL, esquema y conocimiento de base de datos",
+      "iot": "IoT/edge/telemetria",
+      "ux-ui": "Patrones de diseno, UX y design system",
+      "azure-rag": "Contratos/politicas enterprise con Azure RAG",
+      "rag": "RAG local con docs tecnicas"
+    }
+  },
   "governance": {
     "owner": "your-team",
     "approval_required": false,
@@ -12,7 +39,14 @@
       "name": "your-prefix_backend_local",
       "domain": "backend",
       "type": "local",
-      "location": "../your-backend-repo"
+      "location": "../your-backend-repo",
+      "optional": false,
+      "dependencies": [],
+      "engines": {
+        "knowledge": "codegraph",
+        "execution": "none",
+        "snapshot": "repomix"
+      }
     },
     "github": {
       "name": "your-prefix_backend_remote",
@@ -20,7 +54,44 @@
       "type": "github",
       "repo_url": "https://github.com/your-org/your-repo.git",
       "branch": "main",
-      "cache_location": ".cache/github-repos/your-prefix_backend_remote"
+      "cache_location": ".cache/github-repos/your-prefix_backend_remote",
+      "optional": false,
+      "dependencies": [],
+      "engines": {
+        "knowledge": "codegraph",
+        "execution": "none",
+        "snapshot": "repomix"
+      }
+    },
+    "rag_local_github": {
+      "name": "your-prefix_rag_local",
+      "domain": "rag",
+      "type": "github",
+      "repo_url": "https://github.com/your-org/your-rag-docs.git",
+      "branch": "main",
+      "cache_location": ".cache/github-repos/your-prefix_rag_local",
+      "optional": true,
+      "dependencies": [],
+      "engines": {
+        "knowledge": "graphify",
+        "execution": "none",
+        "snapshot": "repomix"
+      }
+    },
+    "azure_rag_github": {
+      "name": "your-prefix_azure_rag",
+      "domain": "azure-rag",
+      "type": "github",
+      "repo_url": "https://github.com/your-org/your-enterprise-docs.git",
+      "branch": "main",
+      "cache_location": ".cache/github-repos/your-prefix_azure_rag",
+      "optional": true,
+      "dependencies": [],
+      "engines": {
+        "knowledge": "azure-rag-builder",
+        "execution": "none",
+        "snapshot": "repomix"
+      }
     }
   }
 }

package/scripts/intake/init-template-registry.ps1

@@ -125,16 +125,30 @@ function Get-DefaultEnginesForDomain {
   param([Parameter(Mandatory = $true)][string]$Domain)
 
   switch ($Domain) {
-    'dev' {
+    'backend' {
       return [pscustomobject]@{
         knowledge = 'codegraph'
         execution = 'none'
         snapshot = 'repomix'
       }
     }
-    'legacy' {
+    'frontend' {
+      return [pscustomobject]@{
+        knowledge = 'codegraph'
+        execution = 'none'
+        snapshot = 'repomix'
+      }
+    }
+    'community-content' {
       return [pscustomobject]@{
         knowledge = 'graphify'
+        execution = 'none'
+        snapshot = 'repomix'
+      }
+    }
+    'legacy' {
+      return [pscustomobject]@{
+        knowledge = 'gitnexus'
         execution = 'gitnexus'
         snapshot = 'repomix'
       }
@@ -160,6 +174,20 @@ function Get-DefaultEnginesForDomain {
         snapshot = 'repomix'
       }
     }
+    'rag' {
+      return [pscustomobject]@{
+        knowledge = 'graphify'
+        execution = 'none'
+        snapshot = 'repomix'
+      }
+    }
+    'ux-ui' {
+      return [pscustomobject]@{
+        knowledge = 'graphify'
+        execution = 'none'
+        snapshot = 'repomix'
+      }
+    }
     default {
       return [pscustomobject]@{
         knowledge = 'codegraph'
@@ -218,11 +246,11 @@ else {
 $templateRegistry.repos = @()
 if ($addInitialRepo) {
   $defaultRepoName = if ([string]::IsNullOrWhiteSpace($InitialRepoName)) { "$resolvedPrefix$((Split-Path $repoRoot -Leaf).ToLowerInvariant())" } else { $InitialRepoName }
-  $defaultRepoDomain = if ([string]::IsNullOrWhiteSpace($InitialRepoDomain)) { 'dev' } else { $InitialRepoDomain }
+  $defaultRepoDomain = if ([string]::IsNullOrWhiteSpace($InitialRepoDomain)) { 'backend' } else { $InitialRepoDomain }
   $defaultRepoLocation = if ([string]::IsNullOrWhiteSpace($InitialRepoLocation)) { '.' } else { $InitialRepoLocation }
 
   $resolvedRepoName = Read-RequiredValue -Prompt 'Initial repo name' -DefaultValue $defaultRepoName -ProvidedValue $InitialRepoName
-  $resolvedRepoDomain = Read-ChoiceValue -Prompt 'Initial repo domain' -AllowedValues @('dev', 'legacy', 'dba', 'iot', 'azure-rag') -DefaultValue $defaultRepoDomain -ProvidedValue $InitialRepoDomain
+  $resolvedRepoDomain = Read-ChoiceValue -Prompt 'Initial repo domain' -AllowedValues @('backend', 'frontend', 'community-content', 'legacy', 'dba', 'iot', 'ux-ui', 'azure-rag', 'rag') -DefaultValue $defaultRepoDomain -ProvidedValue $InitialRepoDomain
   $resolvedRepoLocation = Read-RequiredValue -Prompt 'Initial repo location' -DefaultValue $defaultRepoLocation -ProvidedValue $InitialRepoLocation
   $resolvedEngines = Get-DefaultEnginesForDomain -Domain $resolvedRepoDomain
 

package/scripts/ops/hi.ps1

@@ -569,6 +569,10 @@ function Ensure-CodegraphInitialized {
 }
 
 function Ensure-SetupPrerequisites {
+    param(
+        [string]$Reason = 'missing prerequisite'
+    )
+
     if ($script:SetupAttempted) {
         if (-not $script:SetupSucceeded) {
             throw 'setup-prerequisites was already attempted and failed earlier in this run'
@@ -577,11 +581,15 @@ function Ensure-SetupPrerequisites {
     }
 
     $script:SetupAttempted = $true
-    Write-Host '[info] Missing prerequisite detected. Running setup-prerequisites automatically...' -ForegroundColor DarkYellow
-    & pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup\setup-prerequisites.ps1
-    if ($LASTEXITCODE -ne 0) {
+    Write-Host ("[info] Missing prerequisite detected ({0}). Running setup-prerequisites automatically..." -f $Reason) -ForegroundColor DarkYellow
+    try {
+        $script:StepLogs['setup-prerequisites-auto'] = Invoke-LoggedAction -StepName 'setup-prerequisites-auto' -InfoLines @("Auto-recovery reason: $Reason") -Action {
+            & pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup\setup-prerequisites.ps1 -VerboseTrace
+        }
+    }
+    catch {
         $script:SetupSucceeded = $false
-        throw "setup-prerequisites failed with exit code $LASTEXITCODE"
+        throw $_.Exception.Message
     }
 
     $script:SetupSucceeded = $true
@@ -656,7 +664,7 @@ Invoke-Step -Name 'Validate context' -Action $validateContextAction -Required $t
 if ($script:HasFailures) {
     $script:HasFailures = $false
     Invoke-Step -Name 'Setup prerequisites' -Action {
-        [void](Ensure-SetupPrerequisites)
+        [void](Ensure-SetupPrerequisites -Reason 'validate-context failed')
     } -Required $true
 
     Invoke-Step -Name 'Validate context (retry)' -Action $validateContextAction -Required $true
@@ -691,7 +699,7 @@ Invoke-Step -Name 'Validate memory/cache artifacts' -Action {
     }
 
     if (-not (Get-Command codebase-memory-mcp -ErrorAction SilentlyContinue)) {
-        [void](Ensure-SetupPrerequisites)
+        [void](Ensure-SetupPrerequisites -Reason 'codebase-memory-mcp command not found')
     }
 
     if (-not (Get-Command codebase-memory-mcp -ErrorAction SilentlyContinue)) {
@@ -701,7 +709,7 @@ Invoke-Step -Name 'Validate memory/cache artifacts' -Action {
 
 Invoke-Step -Name 'Activate token-saver mode' -Action {
     if (-not (Test-CommandAvailable -Name 'token-saver-mcp')) {
-        [void](Ensure-SetupPrerequisites)
+        [void](Ensure-SetupPrerequisites -Reason 'token-saver-mcp command not found')
     }
 
     if (-not (Test-CommandAvailable -Name 'token-saver-mcp')) {

package/scripts/setup/setup-prerequisites.ps1

@@ -5,7 +5,8 @@ param(
     [switch]$SkipGitnexus,
     [switch]$SkipGraphify,
     [switch]$SkipRepomix,
-    [switch]$PortableMode
+    [switch]$PortableMode,
+    [switch]$VerboseTrace
 )
 
 $ErrorActionPreference = 'Stop'
@@ -20,6 +21,17 @@ function Test-Command {
     return [bool](Get-Command -Name $Name -ErrorAction SilentlyContinue)
 }
 
+function Write-TraceStep {
+    param(
+        [Parameter(Mandatory = $true)][string]$Message
+    )
+
+    if ($VerboseTrace) {
+        $stamp = (Get-Date).ToString('HH:mm:ss')
+        Write-Host ("[trace {0}] {1}" -f $stamp, $Message) -ForegroundColor DarkGray
+    }
+}
+
 function Install-NpmGlobalPackage {
     param(
         [Parameter(Mandatory = $true)][string]$Package,
@@ -165,6 +177,7 @@ function Sync-GraphifyArtifactsFromScripts {
 }
 
 Write-Host '== MCP platform prerequisites setup =='
+Write-TraceStep -Message ("repoRoot={0}" -f $repoRoot)
 
 $toolingManifest = Get-ToolingManifest -Path $toolingManifestPath
 $externalCliEntries = @($toolingManifest.external_clis)
@@ -174,14 +187,17 @@ foreach ($tool in $externalCliEntries) {
 }
 
 if (-not $SkipCodebaseMemory) {
+    Write-TraceStep -Message 'Installing codebase-memory-mcp from tooling manifest'
     Install-ToolFromManifest -Tool $toolByCommand['codebase-memory-mcp']
 }
 
 if (-not $SkipTokenSaver) {
+    Write-TraceStep -Message 'Installing token-saver-mcp from tooling manifest'
     Install-ToolFromManifest -Tool $toolByCommand['token-saver-mcp']
 }
 
 if (-not $SkipCodegraph) {
+    Write-TraceStep -Message 'Installing/verifying codegraph'
     Install-ToolFromManifest -Tool $toolByCommand['codegraph']
     Write-Host '[setup] codegraph install'
     codegraph install
@@ -195,12 +211,14 @@ if (-not $SkipCodegraph) {
 }
 
 if (-not $SkipGitnexus) {
+    Write-TraceStep -Message 'Installing/verifying gitnexus'
     Install-ToolFromManifest -Tool $toolByCommand['gitnexus']
     Write-Host '[setup] gitnexus setup'
     gitnexus setup
 }
 
 if (-not $SkipRepomix) {
+    Write-TraceStep -Message 'Installing/verifying repomix'
     Install-ToolFromManifest -Tool $toolByCommand['repomix']
 }
 
@@ -219,9 +237,11 @@ else {
 }
 
 # Core observability dependency used by KPI publishing and telemetry export.
+Write-TraceStep -Message 'Ensuring Python module langsmith'
 Ensure-PythonModuleInstalled -PythonCommand $pyCmd -PythonArgs $pyArgs -Module 'langsmith' -Package 'langsmith'
 
 if (-not $SkipGraphify) {
+    Write-TraceStep -Message 'Installing Python requirements for graphify runtime'
     Install-PythonRequirements -PythonCommand $pyCmd -PythonArgs $pyArgs -RequirementsPath 'requirements.txt'
 
     if (-not (Test-PythonImport -PythonCommand $pyCmd -PythonArgs $pyArgs -Module 'graphify.serve')) {
@@ -234,6 +254,7 @@ if (-not $SkipGraphify) {
 
     if (-not (Test-Path 'context/graphify-out/graph.json')) {
         Write-Host '[setup] graphify update scripts --no-cluster'
+        Write-TraceStep -Message ("Running: {0} {1} -m graphify update scripts --no-cluster" -f $pyCmd, ($pyArgs -join ' '))
         & $pyCmd @pyArgs -m graphify update scripts --no-cluster
         if ($LASTEXITCODE -ne 0) {
             throw "graphify update failed with exit code $LASTEXITCODE"
@@ -245,6 +266,7 @@ if (-not $SkipGraphify) {
     }
     else {
         Write-Host '[ok] context/graphify-out/graph.json already exists'
+        Write-TraceStep -Message 'Skipping graphify update because context graph already exists'
     }
 }
 

package/scripts/setup/validate-context.ps1

@@ -87,6 +87,26 @@ function Sync-GraphifyArtifactsIfNeeded {
   }
 }
 
+function Resolve-PythonLauncher {
+  if (Get-Command py -ErrorAction SilentlyContinue) {
+    return [pscustomobject]@{
+      command = 'py'
+      args = @('-3')
+      printable = 'py -3'
+    }
+  }
+
+  if (Get-Command python -ErrorAction SilentlyContinue) {
+    return [pscustomobject]@{
+      command = 'python'
+      args = @()
+      printable = 'python'
+    }
+  }
+
+  return $null
+}
+
 # Ensure report directory exists
 $reportDir = Split-Path -Parent $setupValidationReportPath
 if (-not (Test-Path $reportDir)) {
@@ -333,29 +353,32 @@ if (-not (Get-Command py -ErrorAction SilentlyContinue) -and -not (Get-Command p
   }
 }
 else {
-  $pythonCmd = "python"
-  $pythonArgs = @("-c", "import graphify.serve, mcp; print('ok')")
-  if (Get-Command py -ErrorAction SilentlyContinue) {
-    $pythonCmd = "py"
-    $pythonArgs = @("-3.14", "-c", "import graphify.serve, mcp; print('ok')")
-  }
+  $pythonLauncher = Resolve-PythonLauncher
+  $pythonCmd = [string]$pythonLauncher.command
+  $pythonArgs = @($pythonLauncher.args + @("-c", "import graphify.serve, mcp; print('ok')"))
 
   & $pythonCmd @pythonArgs *> $null
   $setupValidationReport.python_modules += @{
-    launcher = $pythonCmd
+    launcher = [string]$pythonLauncher.printable
     args = $pythonArgs
     import_ok = ($LASTEXITCODE -eq 0)
   }
   if ($LASTEXITCODE -ne 0) {
     if (-not ($CIMode)) {
-      $errors += 'Graphify MCP runtime missing. Run: py -3.14 -m pip install -r requirements.txt'
+      $errors += "Graphify MCP runtime missing. Run: $($pythonLauncher.printable) -m pip install -r requirements.txt"
     }
   }
 }
 
 if ((-not (Test-Path "context/graphify-out/graph.json")) -and (-not (Test-Path "scripts/graphify-out/graph.json"))) {
   if (-not ($CIMode)) {
-    $errors += "Missing graphify graph output. Run: py -3.14 -m graphify update scripts --no-cluster"
+    $pythonLauncher = Resolve-PythonLauncher
+    if ($null -ne $pythonLauncher) {
+      $errors += "Missing graphify graph output. Run: $($pythonLauncher.printable) -m graphify update scripts --no-cluster"
+    }
+    else {
+      $errors += 'Missing graphify graph output. Run: python -m graphify update scripts --no-cluster'
+    }
   }
 }