mcp-efficiency-engine 0.1.0

package/.github/workflows/techriders-coverage-effective.yml

@@ -0,0 +1,91 @@
+name: TechRiders Effective Coverage Gate
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'projects/techriders/**'
+      - '.github/workflows/techriders-coverage-effective.yml'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'projects/techriders/**'
+      - '.github/workflows/techriders-coverage-effective.yml'
+
+permissions:
+  contents: read
+
+env:
+  TECHRIDERS_EFFECTIVE_COVERAGE_MIN: '80'
+
+jobs:
+  techriders-coverage-effective:
+    name: TechRiders Effective Coverage Gate (Windows)
+    runs-on: windows-latest
+    env:
+      TECHRIDERS_BACKEND_PATH: projects/techriders/backend
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up .NET 10 SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Detect TechRiders backend path
+        id: detect_backend
+        shell: pwsh
+        run: |
+          if (Test-Path "$env:TECHRIDERS_BACKEND_PATH") {
+            "available=true" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+            "TechRiders backend detected at $env:TECHRIDERS_BACKEND_PATH" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+          }
+          else {
+            "available=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+            "TechRiders backend not found in this checkout. Coverage gate skipped." | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+          }
+
+      - name: Run TechRiders tests with effective coverage
+        if: steps.detect_backend.outputs.available == 'true'
+        run: |
+          dotnet test "$env:TECHRIDERS_BACKEND_PATH\tests\TechRiders.Api.Tests\TechRiders.Api.Tests.csproj" --collect:"XPlat Code Coverage" --settings "$env:TECHRIDERS_BACKEND_PATH\tests\coverage.effective.runsettings"
+        shell: pwsh
+
+      - name: Evaluate effective coverage threshold
+        id: coverage_gate
+        if: steps.detect_backend.outputs.available == 'true'
+        run: |
+          $coverageFile = Get-ChildItem -Path "$env:TECHRIDERS_BACKEND_PATH\tests\TechRiders.Api.Tests\TestResults" -Recurse -Filter coverage.cobertura.xml |
+            Sort-Object LastWriteTime -Descending |
+            Select-Object -First 1
+
+          if (-not $coverageFile) {
+            throw "coverage.cobertura.xml was not generated."
+          }
+
+          [xml]$coverageXml = Get-Content $coverageFile.FullName
+          $overall = [math]::Round(([double]$coverageXml.coverage.'line-rate') * 100, 2)
+          $minimum = [double]$env:TECHRIDERS_EFFECTIVE_COVERAGE_MIN
+
+          "coverage_file=$($coverageFile.FullName)" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+          "coverage_overall=$overall" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+          "## TechRiders Effective Coverage" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+          "- Coverage file: $($coverageFile.FullName)" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+          "- Overall line coverage: $overall%" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+          "- Minimum required: $minimum%" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+
+          if ($overall -lt $minimum) {
+            throw "Effective coverage gate failed: $overall% < $minimum%"
+          }
+        shell: pwsh
+
+      - name: Upload effective coverage report
+        if: always() && steps.detect_backend.outputs.available == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: techriders-effective-coverage
+          path: projects/techriders/backend/tests/TechRiders.Api.Tests/TestResults/**/coverage.cobertura.xml
+          retention-days: 30

package/.vscode/mcp.json

@@ -0,0 +1,44 @@
+{
+  "servers": {
+    "token-saver-mcp": {
+      "command": "token-saver-mcp"
+    },
+    "codebase-memory-mcp": {
+      "command": "codebase-memory-mcp"
+    },
+    "codegraph": {
+      "command": "codegraph",
+      "args": [
+        "serve",
+        "--mcp"
+      ]
+    },
+    "gitnexus": {
+      "command": "gitnexus",
+      "args": [
+        "mcp"
+      ],
+      "env": {
+        "GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT": "50000",
+        "GITNEXUS_EMBEDDING_THREADS": "4"
+      }
+    },
+    "repomix": {
+      "command": "repomix",
+      "args": [
+        "--mcp"
+      ]
+    },
+    "graphify": {
+      "command": "py",
+      "args": [
+        "-3.14",
+        "-m",
+        "graphify.serve",
+        "--transport",
+        "stdio",
+        "context/graphify-out/graph.json"
+      ]
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,160 @@
+<!-- markdownlint-disable MD013 -->
+
+# AGENTS.md — Enterprise Global Contract
+
+## Routing base
+
+| Intención | Fuente | Agente | Motor |
+|---|---|---|---|
+| Bug/fix/refactor/test | Código repo único | backend | CodeGraph |
+| Frontend/UI implementación | Código frontend repo único | frontend-agent | CodeGraph |
+| Legacy/migración/multi-repo | Código legacy | legacy | GitNexus |
+| SQL/schema/procedure | SQL/docs técnicas | dba | Graphify |
+| UX/UI/design system | Guías de diseño y patrones UI | ux-ui | Graphify |
+| Knowledge local/docs técnicas | Docs locales | rag-local | Graphify |
+| Contratos/SLA/SharePoint/políticas | Docs corporativos | rag-azure | Azure RAG Builder |
+| IoT/edge/telemetría | Código + docs | iot | GitNexus/CodeGraph + Graphify |
+| Formación/posts/storytelling | Knowledge generado | community-manager | Graphify |
+| Documentación técnica incremental / proyección wiki | Artefactos `repo-intake/generated` | wiki-agent | CodeGraph (fallback Graphify) |
+| Exportar contexto | Repo/docs | snapshot | Repomix |
+
+## Optimización obligatoria
+
+- Aplicar Token Saver antes de cualquier retrieval amplio.
+- Aplicar Caveman Mode en loops de debug/coding, salvo que el usuario pida detalle.
+- No sacrificar citas/fuentes por ahorrar tokens cuando la tarea requiere grounding.
+
+## Reglas
+
+- No usar todos los motores a la vez.
+- No usar Azure RAG Builder para modificar código.
+- No usar CodeGraph para buscar contratos.
+- No usar Repomix como contexto vivo.
+- Si no hay grounding suficiente, declarar gap.
+
+## Boost-First Always-On
+
+Regla obligatoria para todos los agentes:
+
+1. Antes de cualquier edicion o ejecucion de cambios, aplicar seleccion explicita de boost/agente/skill.
+2. En cada tarea, exponer evidencia minima de ejecucion: boost/agente/skill, motor, fallback (si aplica), validacion.
+3. Cuando la tarea afecte a un proyecto concreto, persistir trazabilidad en `projects/<nombre-proyecto>/analysis_mcpee/`.
+4. Si no se puede aplicar el motor esperado (index stale, tool no disponible, etc.), declarar gap y fallback en la salida.
+
+## Primera Pasada Por Boost
+
+Regla obligatoria para todos los agentes:
+
+1. La primera pasada sobre un boost, capability o proyecto nuevo debe ser de
+  onboarding profundo y con grounding máximo relevante, aunque tarde más.
+2. En esa primera pasada se debe recuperar la mayor cantidad de contexto útil
+  y verificable posible desde las fuentes canónicas del boost: repo-intake,
+  onboarding, instrucciones, prompts, skills, agentes locales y documentación
+  del propio proyecto.
+3. Si el boost o proyecto define agentes o subagentes especializados, el
+  agente principal debe usarlos cuando estén disponibles o, como mínimo,
+  leerlos y aplicar sus reglas como contrato operativo explícito.
+4. Token Saver sigue activo: no implica lectura masiva ciega, sino pocas
+  recuperaciones grandes, estructuradas y con alta densidad de evidencia.
+5. Tras esa primera pasada profunda, las siguientes iteraciones vuelven al
+  modo optimizado normal.
+
+## Always-On Optimization
+
+Caveman Mode y Token Saver están siempre activos para todos los agentes.
+
+### Token Saver
+
+Aplicar antes de cualquier consulta a CodeGraph, GitNexus, Graphify, Azure RAG Builder o Repomix.
+
+### Caveman
+
+Aplicar a toda respuesta. Por defecto usar Caveman Lite/Full según tarea.
+
+### Excepción
+
+No eliminar explicación necesaria, fuentes, validación ni contexto crítico. Si hace falta más detalle, cambiar intensidad, no desactivar la optimización.
+
+## Memory-first + Learning
+
+All agents MUST:
+
+1. Select memory BEFORE using any tool
+2. Use cross-memory when multiple domains are involved
+3. Prefer memories over raw retrieval
+4. Use previous successful patterns if available (learning)
+5. Register execution feedback
+
+Execution order:
+
+Memory → Reasoning → Tool (if needed) → Learning
+
+## Diagrama Visual De Routing
+
+```mermaid
+flowchart LR
+  I[Intencion] --> RT[Router]
+  RT --> DEV[backend]
+  RT --> FE[frontend-agent]
+  RT --> LEG[legacy]
+  RT --> DBA[dba]
+  RT --> RLOCAL[rag-local]
+  RT --> RAZ[rag-azure]
+  RT --> IOT[iot]
+  RT --> COM[community-manager]
+  RT --> WIKI[wiki-agent]
+  RT --> SNAP[snapshot]
+  DEV --> CG[CodeGraph]
+  FE --> CG
+  LEG --> GN[GitNexus]
+  DBA --> GF[Graphify]
+  RLOCAL --> GF
+  RAZ --> AZRAG[Azure RAG Builder]
+  WIKI --> CG
+  SNAP --> RPX[Repomix]
+```
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **mcp-efficiency-engine**. Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "main"})`.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `query({search_query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.
+- For security review, `explain({target: "fileOrSymbol"})` lists taint findings (source→sink flows; needs `analyze --pdg`).
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
+- NEVER commit changes without running `detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/mcp-efficiency-engine/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/mcp-efficiency-engine/clusters` | All functional areas |
+| `gitnexus://repo/mcp-efficiency-engine/processes` | All execution flows |
+| `gitnexus://repo/mcp-efficiency-engine/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

package/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Arquitectura de MCP Efficiency Engine
+
+```mermaid
+flowchart TD
+    U[Usuario] --> CM[Caveman Mode / Interaction Policy]
+    CM --> O[Orchestrator / Corporate Router]
+    O --> A[Agents Layer]
+
+    A --> DEV[backend]
+    A --> LEG[legacy]
+    A --> DBA[dba]
+    A --> RAG[rag-local]
+    A --> AZ[rag-azure]
+    A --> IOT[iot]
+    A --> COM[community-manager]
+    A --> SNAP[snapshot]
+
+    DEV --> TS[Token Saver Policy]
+    LEG --> TS
+    DBA --> TS
+    RAG --> TS
+    AZ --> TS
+    IOT --> TS
+    COM --> TS
+    SNAP --> TS
+
+    TS --> CG[CodeGraph]
+    TS --> GN[GitNexus]
+    TS --> GF[Graphify]
+    TS --> AZRAG[RAG-Azure-Builder]
+    TS --> RPM[Repomix]
+
+    CG --> CODE[Repos de código]
+    GN --> CODE
+    GF --> KG[graphify-out / knowledge graph local]
+    AZRAG --> AIS[Azure AI Search / embeddings / docs corporativos]
+    RPM --> SNAPOUT[Snapshot portable]
+
+    CODE --> RESP[Respuesta / Acción]
+    KG --> RESP
+    AIS --> RESP
+    SNAPOUT --> RESP
+
+    RESP --> OBS[Observability]
+    OBS --> MET[Metrics]
+    OBS --> LOGS[Logs]
+    OBS --> EVAL[Evaluation]
+```
+
+## Lectura rápida
+
+```txt
+Caveman optimiza cómo se habla.
+Token Saver optimiza qué contexto se usa.
+Routing decide qué motor se usa.
+Observability mide si todo funciona.
+```

package/FINAL_USAGE_GUIDE.md

@@ -0,0 +1,106 @@
+# Guía de uso — MCP Efficiency Engine
+
+## 1. Cómo queda finalmente todo
+
+La arquitectura final tiene seis bloques:
+
+```txt
+1. MCP para código vivo.
+2. RAG local para conocimiento técnico.
+3. Azure RAG Builder para documentos corporativos reales.
+4. Repo Intake para usar todos tus repos sin copiarlos.
+5. Token Saver para reducir contexto/coste.
+6. Caveman Mode para reducir ruido de interacción.
+```
+
+## 2. Capas
+
+```txt
+Usuario
+  ↓
+Caveman Mode             -> controla cuánto y cómo responde el agente
+  ↓
+Orchestrator / Router    -> decide agente y motor
+  ↓
+Agente especializado     -> aplica rol
+  ↓
+Skill + Spec             -> aplica capacidad y reglas
+  ↓
+Token Saver              -> limita contexto, chunks, ficheros, tool calls
+  ↓
+Motor                    -> CodeGraph / GitNexus / Graphify / Azure RAG / Repomix
+  ↓
+Observability            -> mide routing, coste, grounding, eficiencia
+```
+
+## 3. Decisión de motor
+
+```txt
+Código repo único        -> CodeGraph
+Código legacy/multi-repo -> GitNexus
+Docs técnicas/locales    -> Graphify
+Docs corporativos reales -> Azure RAG Builder
+Export portable          -> Repomix
+Repos externos           -> Repo Intake
+```
+
+## 4. Decisión de optimización
+
+```txt
+Problema de coste/contexto -> Token Saver
+Problema de verbosidad     -> Caveman Mode
+Problema de ambos          -> Token Saver + Caveman
+```
+
+## 5. Reglas prácticas
+
+- Si el agente va a consultar datos: aplicar Token Saver.
+- Si el usuario está en loop de debug/coding: aplicar Caveman Mode.
+- Si la respuesta es para formación/documentación: Caveman puede relajarse.
+- Si la respuesta necesita trazabilidad: no eliminar fuentes por Caveman.
+- Si Azure RAG recupera demasiados chunks: limitar top-k y pedir solo fuentes necesarias.
+- Si CodeGraph/GitNexus puede devolver símbolo/call path: no leer ficheros completos.
+
+## 6. Regla final
+
+```txt
+No modelas repos.
+Modelas capacidades.
+No optimizas solo tokens.
+Optimizas el pipeline completo.
+```
+
+## Always-On: decisión final
+
+Token Saver y Caveman ya no son modos que se activan manualmente. Son parte del runtime del sistema.
+
+```txt
+Toda petición -> Caveman + Routing + Token Saver + Motor correcto
+```
+
+Esto significa:
+
+- todas las respuestas serán más directas por defecto,
+- todo retrieval se hará con contexto mínimo suficiente,
+- las fuentes se conservan cuando sean obligatorias,
+- el sistema solo aumenta detalle si el usuario o el caso lo requiere.
+
+## Diagrama Visual De Uso Diario
+
+```mermaid
+sequenceDiagram
+  participant U as Usuario
+  participant HI as hi.ps1
+  participant CTX as validate-context
+  participant IN as repo-intake
+  participant EV as routing-evals
+  participant BY as bye.ps1
+  U->>HI: Inicio de jornada
+  HI->>CTX: Validar contratos y estructura
+  HI->>IN: Actualizar contexto multi-repo
+  HI->>EV: Verificar routing
+  U->>U: Trabajo diario
+  U->>BY: Cierre de jornada
+  BY->>IN: Refresh intake/discovery
+  BY->>EV: Comprobacion final
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Efficiency Engine Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.