mcp-efficiency-engine 0.1.0

package/scripts/discovery/discover-boost-repos.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def load_registry(path: Path) -> dict[str, Any]:
+    content = path.read_text(encoding="utf-8")
+    if content.lstrip().startswith("{"):
+        return json.loads(content)
+    raise ValueError("Registry must be JSON-first in current setup.")
+
+
+def slug_name(folder_name: str) -> str:
+    name = folder_name.lower().replace("-", "_")
+    name = re.sub(r"[^a-z0-9_]+", "_", name)
+    name = re.sub(r"_+", "_", name).strip("_")
+    if not name.startswith("boost_"):
+        name = f"boost_{name}"
+    return name
+
+
+def infer_domain(folder_name: str) -> str:
+    token = folder_name.lower()
+    if "dba" in token or "sql" in token or "db" in token:
+        return "dba"
+    if "iot" in token or "edge" in token:
+        return "iot"
+    if "rag" in token or "azure" in token:
+        return "azure-rag"
+    if "legacy" in token or "migration" in token:
+        return "legacy"
+    return "dev"
+
+
+def default_engines(domain: str) -> dict[str, str]:
+    if domain == "dba":
+        return {"knowledge": "graphify", "execution": "none", "snapshot": "repomix"}
+    if domain == "iot":
+        return {"knowledge": "graphify", "execution": "gitnexus", "snapshot": "repomix"}
+    if domain == "azure-rag":
+        return {"knowledge": "azure-rag-builder", "execution": "none", "snapshot": "repomix"}
+    if domain == "legacy":
+        return {"knowledge": "gitnexus", "execution": "none", "snapshot": "repomix"}
+    return {"knowledge": "codegraph", "execution": "none", "snapshot": "repomix"}
+
+
+def build_candidate(folder: Path, review_ticket_prefix: str, idx: int) -> dict[str, Any]:
+    folder_name = folder.name
+    repo_name = slug_name(folder_name)
+    domain = infer_domain(folder_name)
+    return {
+        "name": repo_name,
+        "domain": domain,
+        "version": "1.0.0",
+        "location": f"../{folder_name}",
+        "type": "local",
+        "dependencies": [],
+        "approval": {
+            "status": "approved",
+            "approved_by": "platform-team",
+            "approved_date": datetime.now().date().isoformat(),
+            "review_ticket": f"{review_ticket_prefix}-{1000 + idx}",
+        },
+        "engines": default_engines(domain),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Discover sibling boost_* repos and generate onboarding proposal.")
+    parser.add_argument("--root", default="C:/repo", help="Parent folder containing sibling repos")
+    parser.add_argument("--registry", default="repo-registry/repos.yml", help="Registry file path")
+    parser.add_argument("--output", default="repo-intake/generated/reports/boost-discovery-proposal.json")
+    parser.add_argument("--apply", action="store_true", help="Apply candidates directly to registry")
+    parser.add_argument("--review-ticket-prefix", default="PLATFORM", help="Prefix used for generated review tickets")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[2]
+    registry_path = (repo_root / args.registry).resolve()
+    registry = load_registry(registry_path)
+
+    prefix = str(registry.get("governance", {}).get("repo_name_prefix", "boost_"))
+    root = Path(args.root)
+    if not root.exists():
+        print(f"Root path not found: {root}")
+        return 1
+
+    existing_names = {
+        str(r.get("name", ""))
+        for r in registry.get("repos", [])
+        if isinstance(r, dict)
+    }
+    existing_locations = {
+        str(r.get("location", ""))
+        for r in registry.get("repos", [])
+        if isinstance(r, dict)
+    }
+
+    siblings = [
+        p for p in root.iterdir()
+        if p.is_dir() and p.name.startswith(prefix) and p.name != repo_root.name
+    ]
+
+    candidates: list[dict[str, Any]] = []
+    skipped: list[dict[str, str]] = []
+    idx = 1
+    for folder in sorted(siblings, key=lambda x: x.name.lower()):
+        candidate = build_candidate(folder=folder, review_ticket_prefix=args.review_ticket_prefix, idx=idx)
+        idx += 1
+
+        if candidate["name"] in existing_names:
+            skipped.append({"folder": folder.name, "reason": "already_registered_name"})
+            continue
+        if candidate["location"] in existing_locations:
+            skipped.append({"folder": folder.name, "reason": "already_registered_location"})
+            continue
+        candidates.append(candidate)
+
+    proposal = {
+        "timestamp": utc_now(),
+        "root": str(root).replace("\\", "/"),
+        "prefix": prefix,
+        "registry": str(registry_path).replace("\\", "/"),
+        "existing_count": len(existing_names),
+        "candidates_count": len(candidates),
+        "skipped_count": len(skipped),
+        "candidates": candidates,
+        "skipped": skipped,
+        "apply_mode": bool(args.apply),
+    }
+
+    out_path = (repo_root / args.output).resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(proposal, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    md_path = out_path.with_suffix(".md")
+    lines = [
+        "# Boost Discovery Proposal",
+        "",
+        f"- timestamp: {proposal['timestamp']}",
+        f"- candidates: {proposal['candidates_count']}",
+        f"- skipped: {proposal['skipped_count']}",
+        "",
+        "## Candidates",
+        "",
+    ]
+    if candidates:
+        for c in candidates:
+            lines.append(f"- {c['name']} ({c['domain']}) -> {c['location']}")
+    else:
+        lines.append("- none")
+    lines.extend(["", "## Skipped", ""])
+    if skipped:
+        for s in skipped:
+            lines.append(f"- {s['folder']}: {s['reason']}")
+    else:
+        lines.append("- none")
+    md_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    if args.apply and candidates:
+        registry_repos = registry.get("repos", [])
+        if not isinstance(registry_repos, list):
+            print("Registry repos field is invalid.")
+            return 1
+        registry_repos.extend(candidates)
+        registry["repos"] = registry_repos
+        registry_path.write_text(json.dumps(registry, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        print(f"Applied {len(candidates)} candidates to registry.")
+    else:
+        print("Dry-run mode. No registry changes applied.")
+
+    print(f"Proposal JSON: {out_path}")
+    print(f"Proposal MD: {md_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/discovery/refresh-project-notes.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+AUTO_START = "<!-- AUTO-GENERATED:START -->"
+AUTO_END = "<!-- AUTO-GENERATED:END -->"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def get_number(value: Any, default: float = 0.0) -> float:
+    if isinstance(value, (int, float)):
+        return float(value)
+    return default
+
+
+def upsert_auto_section(path: Path, title: str, body_lines: list[str]) -> None:
+    header = f"# {title}\n\n"
+    auto_block = [AUTO_START, *body_lines, AUTO_END, ""]
+    auto_text = "\n".join(auto_block)
+
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(header + auto_text, encoding="utf-8")
+        return
+
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        text = header
+
+    if AUTO_START in text and AUTO_END in text:
+        start = text.index(AUTO_START)
+        end = text.index(AUTO_END) + len(AUTO_END)
+        new_text = text[:start].rstrip() + "\n\n" + auto_text
+    else:
+        new_text = text.rstrip() + "\n\n" + auto_text
+
+    path.write_text(new_text, encoding="utf-8")
+
+
+def build_decisions_lines(routing: dict[str, Any], learning: dict[str, Any], value: dict[str, Any]) -> list[str]:
+    cases_total = int(routing.get("cases_total", 0) or 0)
+    cases_passed = int(routing.get("cases_passed", 0) or 0)
+
+    health = learning.get("health", {}) if isinstance(learning.get("health", {}), dict) else {}
+    fallback_ok = bool(health.get("fallback_ok", False))
+    grounded_ok = bool(health.get("grounded_ok", False))
+    confidence_ok = bool(health.get("confidence_ok", False))
+
+    assessment = value.get("assessment", {}) if isinstance(value.get("assessment", {}), dict) else {}
+    has_value_signal = bool(assessment.get("has_value_signal", False))
+
+    lines = [
+        f"- updated_at: {utc_now()}",
+        f"- decision: mantener routing gate activo (routing-evals {cases_passed}/{cases_total} passed).",
+        f"- decision: priorizar reduccion de fallback si health.fallback_ok={fallback_ok}.",
+        f"- decision: mantener evidencia obligatoria mientras health.grounded_ok={grounded_ok}.",
+        f"- decision: mantener confidence floor mientras health.confidence_ok={confidence_ok}.",
+        f"- decision: usar value-per-iteration para priorizacion (has_value_signal={has_value_signal}).",
+    ]
+    return lines
+
+
+def build_glossary_lines(learning: dict[str, Any], value: dict[str, Any]) -> list[str]:
+    kpis = learning.get("kpis", {}) if isinstance(learning.get("kpis", {}), dict) else {}
+    vkpis = value.get("kpis", {}) if isinstance(value.get("kpis", {}), dict) else {}
+
+    fallback_rate = round(get_number(kpis.get("fallback_rate")) * 100.0, 2)
+    grounded_rate = round(get_number(kpis.get("grounded_rate")) * 100.0, 2)
+    success_rate = round(get_number(kpis.get("success_rate")) * 100.0, 2)
+    coverage_rate = round(get_number(vkpis.get("metrics_coverage_rate")) * 100.0, 2)
+    tokens_per_success = get_number(vkpis.get("tokens_per_confirmed_success"))
+
+    lines = [
+        f"- updated_at: {utc_now()}",
+        f"- fallback_rate: porcentaje de rutas en fallback. valor_actual={fallback_rate}%.",
+        f"- grounded_rate: porcentaje de rutas con fuentes validas. valor_actual={grounded_rate}%.",
+        f"- confirmed_success_rate: tasa de exito con feedback confirmado. valor_actual={success_rate}%.",
+        f"- metrics_coverage_rate: porcentaje de eventos con metricas. valor_actual={coverage_rate}%.",
+        f"- tokens_per_confirmed_success: tokens medios por exito confirmado. valor_actual={tokens_per_success}.",
+        "- value_signal: indicador de que hay datos suficientes para optimizacion por iteracion.",
+    ]
+    return lines
+
+
+def build_risks_lines(learning: dict[str, Any], value: dict[str, Any]) -> list[str]:
+    total_events = int(learning.get("total_events", 0) or 0)
+    pending_events = int(learning.get("pending_events", 0) or 0)
+
+    kpis = learning.get("kpis", {}) if isinstance(learning.get("kpis", {}), dict) else {}
+    thresholds = learning.get("thresholds", {}) if isinstance(learning.get("thresholds", {}), dict) else {}
+
+    fallback_rate = get_number(kpis.get("fallback_rate"))
+    grounded_rate = get_number(kpis.get("grounded_rate"))
+    confidence_avg = get_number(kpis.get("confidence_avg"))
+
+    fallback_max = get_number(thresholds.get("fallback_rate_max"), 0.2)
+    grounded_min = get_number(thresholds.get("grounded_rate_min"), 0.8)
+    confidence_min = get_number(thresholds.get("confidence_avg_min"), 0.8)
+
+    vkpis = value.get("kpis", {}) if isinstance(value.get("kpis", {}), dict) else {}
+    metrics_coverage_rate = get_number(vkpis.get("metrics_coverage_rate"))
+    confirmed_feedback_rate = get_number(vkpis.get("confirmed_feedback_rate"))
+
+    risks: list[str] = [f"- updated_at: {utc_now()}"]
+
+    if fallback_rate > fallback_max:
+        risks.append(
+            f"- high_fallback: fallback_rate={round(fallback_rate * 100.0, 2)}% supera max={round(fallback_max * 100.0, 2)}%."
+        )
+
+    if grounded_rate < grounded_min:
+        risks.append(
+            f"- low_grounding: grounded_rate={round(grounded_rate * 100.0, 2)}% por debajo de min={round(grounded_min * 100.0, 2)}%."
+        )
+
+    if confidence_avg < confidence_min:
+        risks.append(f"- low_confidence: confidence_avg={round(confidence_avg, 3)} por debajo de min={confidence_min}.")
+
+    if pending_events > 0:
+        pending_pct = round((pending_events / total_events) * 100.0, 2) if total_events > 0 else 0.0
+        risks.append(f"- pending_feedback: pending_events={pending_events}/{total_events} ({pending_pct}%).")
+
+    if metrics_coverage_rate < 1.0:
+        risks.append(f"- incomplete_metrics: metrics_coverage_rate={round(metrics_coverage_rate * 100.0, 2)}%.")
+
+    if confirmed_feedback_rate < 1.0:
+        risks.append(f"- incomplete_feedback: confirmed_feedback_rate={round(confirmed_feedback_rate * 100.0, 2)}%.")
+
+    if len(risks) == 1:
+        risks.append("- no_critical_risks_detected: umbrales clave en rango.")
+
+    return risks
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Refresh context/project-notes from observability reports.")
+    parser.add_argument("--routing", default="observability/evals/routing-eval-report.json")
+    parser.add_argument("--learning", default="observability/evals/learning-loop-report.json")
+    parser.add_argument("--value", default="observability/evals/iteration-value-report.json")
+    parser.add_argument("--notes-dir", default="context/project-notes")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[2]
+    routing = load_json((repo_root / args.routing).resolve())
+    learning = load_json((repo_root / args.learning).resolve())
+    value = load_json((repo_root / args.value).resolve())
+
+    notes_dir = (repo_root / args.notes_dir).resolve()
+    decisions = notes_dir / "decisions.md"
+    glossary = notes_dir / "glossary.md"
+    known_risks = notes_dir / "known-risks.md"
+
+    upsert_auto_section(decisions, "Decisions", build_decisions_lines(routing, learning, value))
+    upsert_auto_section(glossary, "Glossary", build_glossary_lines(learning, value))
+    upsert_auto_section(known_risks, "Known Risks", build_risks_lines(learning, value))
+
+    print(f"Project notes refreshed in: {notes_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/github/INSTALL.md

@@ -0,0 +1,295 @@
+# Guía de Instalación y Uso — GitHub MCP Scripts
+
+## ✅ Lo que NECESITAS
+
+Solo necesitas estas dos cosas:
+
+1. **GitHub CLI (`gh`)** — Disponible en todas las plataformas
+2. **PowerShell 7+** — Para ejecutar scripts
+
+## ❌ Lo que NO NECESITAS
+
+- ~~`npm install -g @github/mcp-github-server`~~ (no existe en npm registry)
+- ~~MCP Server local~~ (no es necesario para estos scripts)
+
+Los scripts usan `gh` CLI que ya está optimizado para GitHub.
+
+---
+
+## Instalación Rápida
+
+### Opción 1: Windows (Recomendado)
+
+```powershell
+# 1. Instalar GitHub CLI
+winget install GitHub.cli
+
+# 2. Instalar PowerShell 7 (si no tienes)
+winget install Microsoft.PowerShell
+
+# 3. Reinicia terminal
+
+# 4. Login
+gh auth login
+
+# 5. Configura token (permanente)
+$env:GITHUB_TOKEN = "ghp_xxxxxxxxxxxxxxxxxxxx"
+Add-Content $PROFILE "`n`$env:GITHUB_TOKEN = 'ghp_xxxxxxxxxxxxxxxxxxxx'"
+
+# 6. Verifica
+gh auth status
+```
+
+### Opción 2: macOS
+
+```bash
+# 1. Instalar GitHub CLI
+brew install gh
+
+# 2. PowerShell (opcional, ya tienes bash)
+brew install powershell
+
+# 3. Login
+gh auth login
+
+# 4. Configura token
+echo 'export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
+source ~/.zshrc
+
+# 5. Verifica
+gh auth status
+```
+
+### Opción 3: Linux (Ubuntu/Debian)
+
+```bash
+# 1. Instalar GitHub CLI
+sudo apt install gh
+
+# 2. Instalar PowerShell
+sudo apt install powershell
+
+# 3. Login
+gh auth login
+
+# 4. Configura token
+echo 'export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
+source ~/.bashrc
+
+# 5. Verifica
+gh auth status
+```
+
+---
+
+## Crear GitHub Personal Access Token (PAT)
+
+1. **GitHub Settings:**
+   - https://github.com/settings/tokens
+
+2. **Generate new token (classic):**
+   - Name: `MCP Efficiency Engine`
+   - Scopes: `repo`, `workflow`
+   - Expiration: 30 days (renovar después)
+
+3. **Copiar token:**
+   ```
+   ghp_xxxxxxxxxxxxxxxxxxxx
+   ```
+
+4. **Guardar en tu sistema:**
+   - Windows: `cmdkey /add:github.com /user:username /pass:ghp_xxxx`
+   - macOS/Linux: `echo 'export GITHUB_TOKEN="ghp_xxxx"' >> ~/.bashrc`
+
+---
+
+## Usar los Scripts Localmente
+
+### Paso 1: Clonar Repo
+
+```bash
+git clone https://github.com/Sertxito/mcp-efficiency-engine.git
+cd mcp-efficiency-engine
+```
+
+### Paso 2: Ejecutar Scripts
+
+#### Sincronizar Repos (Preview)
+
+```powershell
+# Ver qué haría sin hacer cambios
+pwsh scripts/github/sync-repo.ps1 -FilesPattern "projects/**" -DryRun
+```
+
+#### Generar DevLog
+
+```powershell
+# Generar devlog con últimos 20 commits
+pwsh scripts/github/create-devlog.ps1 -CommitsToAnalyze 20
+
+# Ver preview sin crear archivo
+pwsh scripts/github/create-devlog.ps1 -DryRun
+```
+
+#### Gestionar Issues
+
+```powershell
+# Asignar Copilot a issues sin asignar
+pwsh scripts/github/manage-issues.ps1 -Action assign
+
+# Solicitar reviews de Copilot en PRs
+pwsh scripts/github/manage-issues.ps1 -Action review
+
+# Auto-cerrar issues resueltas
+pwsh scripts/github/manage-issues.ps1 -Action close
+```
+
+---
+
+## Uso en GitHub Actions (CI/CD)
+
+Los workflows ya están configurados. Se ejecutan automáticamente:
+
+| Workflow | Trigger | Qué Hace |
+|----------|---------|---------|
+| **auto-sync.yml** | Push a main (projects/) | Sincroniza cambios a boost_sertxIA |
+| **auto-devlog.yml** | Push a main | Genera devlog de commits |
+| **auto-manage-issues.yml** | Lunes 9 AM | Gestiona issues automáticamente |
+
+### Trigger Manual
+
+```bash
+# Desde tu terminal local
+gh workflow run auto-sync.yml -r main
+gh workflow run auto-devlog.yml -r main
+gh workflow run auto-manage-issues.yml -r main
+```
+
+### Ver Resultados
+
+```bash
+# Ver workflows en ejecución
+gh workflow list
+
+# Ver runs de un workflow
+gh run list
+
+# Ver logs de un run
+gh run view <run-id> --log
+```
+
+---
+
+## Troubleshooting
+
+### Error: "GitHub CLI not found"
+
+```bash
+# Instalar
+# Windows
+winget install GitHub.cli
+
+# macOS
+brew install gh
+
+# Linux
+sudo apt install gh
+```
+
+### Error: "Not authenticated"
+
+```bash
+# Login
+gh auth login
+
+# Verificar
+gh auth status
+```
+
+### Error: "Token expired or invalid"
+
+```bash
+# Renovar token en: https://github.com/settings/tokens
+# Guardar nueva vez:
+$env:GITHUB_TOKEN = "ghp_nuevo_token"
+```
+
+### Error: "Rate limit exceeded"
+
+GitHub API tiene límites:
+- **Unauthenticated:** 60 requests/hora
+- **Authenticated:** 5,000 requests/hora
+
+Si ves este error, espera 1 hora o reduce cantidad de operaciones.
+
+### Error: "Permission denied"
+
+```bash
+# Verificar permisos del token
+gh auth status
+
+# El token debe tener:
+# - repo (acceso a repositorios)
+# - workflow (permisos para workflows)
+```
+
+---
+
+## Cambios Clave Desde v1.0
+
+### Setup Simplificado
+
+- ✅ Eliminado requisito de `npm install -g @github/mcp-github-server`
+- ✅ Solo necesitas `gh` CLI (disponible everywhere)
+- ✅ Funciona en CI/CD sin configuración extra
+
+### Workflows Añadidos
+
+- ✅ `auto-sync.yml` — Sincronización automática
+- ✅ `auto-devlog.yml` — DevLog automático
+- ✅ `auto-manage-issues.yml` — Gestión de issues
+
+### Documentación
+
+- ✅ Guía de instalación simplificada
+- ✅ Troubleshooting actualizado
+- ✅ Ejemplos de uso locales + CI/CD
+
+---
+
+## Próximos Pasos
+
+1. **Instalar localmente:**
+   ```powershell
+   winget install GitHub.cli
+   gh auth login
+   ```
+
+2. **Test un script:**
+   ```powershell
+   pwsh scripts/github/manage-issues.ps1 -Action assign -DryRun
+   ```
+
+3. **Verificar workflows activos:**
+   ```bash
+   gh workflow list
+   ```
+
+4. **Personalizar según necesidad:**
+   - Editar `.github/workflows/*.yml`
+   - Ajustar triggers (schedules, paths)
+   - Agregar más acciones
+
+---
+
+## Referencias
+
+- [GitHub CLI Documentation](https://cli.github.com/)
+- [GitHub REST API](https://docs.github.com/en/rest)
+- [Scripts README](./README.md)
+- [GitHub MCP Integration Guide](../.github/GITHUB_MCP_INTEGRATION.md)
+
+---
+
+**Última actualización:** 2026-07-04  
+**Estado:** ✅ Guía completa + Workflows listos para usar