Nexus - AI Task Orchestrator

61-mcp-context-optimization
Procedimiento: MCP Context Optimization Analysis

Mantenimiento
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
10336 caracteres
# Procedimiento: MCP Context Optimization Analysis

## Metadata
- **ID**: PROC-61
- **Frecuencia**: Trimestral o tras agregar nuevas tools
- **Duraci├│n estimada**: 3-5 d├¡as
- **Requiere**: Acceso a c├│digo fuente, logs MCP
- **Dependencias**: PROC-03, PROC-06, PROC-08, PROC-09

## Objetivo

Reducir el n├║mero de tokens que Claude necesita procesar al usar las MCP tools, mejorando:
- Velocidad de respuesta
- Coste por interacci├│n
- Espacio disponible para razonamiento
- Capacidad de manejar m├ís datos en una conversaci├│n

---

## Flujo de Ejecuci├│n

```
ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
Ôöé                    PROC-61 Workflow                              Ôöé
Ôö£ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöñ
Ôöé                                                                  Ôöé
Ôöé  FASE 1: Medici├│n (performance-engineer)                        Ôöé
Ôöé  Ôö£ÔöÇ Baseline tokens por tool                                    Ôöé
Ôöé  Ôö£ÔöÇ Identificar top consumers                                   Ôöé
Ôöé  ÔööÔöÇ Establecer SLIs objetivo                                    Ôöé
Ôöé           Ôöé                                                      Ôöé
Ôöé           Ôû╝                                                      Ôöé
Ôöé  FASE 2: Dise├▒o (backend-architect + api-design-principles)     Ôöé
Ôöé  Ôö£ÔöÇ Redise├▒ar JSON schemas                                      Ôöé
Ôöé  Ôö£ÔöÇ Optimizar response formats                                  Ôöé
Ôöé  ÔööÔöÇ Definir response modes (minimal/standard/full)              Ôöé
Ôöé           Ôöé                                                      Ôöé
Ôöé           Ôû╝                                                      Ôöé
Ôöé  FASE 3: Implementaci├│n (dotnet-architect)                      Ôöé
Ôöé  Ôö£ÔöÇ Refactorizar Tools                                          Ôöé
Ôöé  Ôö£ÔöÇ Implementar serializaci├│n optimizada                        Ôöé
Ôöé  ÔööÔöÇ Tests de regresi├│n                                          Ôöé
Ôöé           Ôöé                                                      Ôöé
Ôöé           Ôû╝                                                      Ôöé
Ôöé  FASE 4: Validaci├│n (performance-engineer)                      Ôöé
Ôöé  Ôö£ÔöÇ Medir reducci├│n tokens                                      Ôöé
Ôöé  Ôö£ÔöÇ Validar SLOs                                                Ôöé
Ôöé  ÔööÔöÇ Documentar impacto                                          Ôöé
Ôöé                                                                  Ôöé
ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ
```

---

## SLIs Objetivo

| M├®trica | Objetivo | Cr├¡tico |
|---------|----------|---------|
| Schema por tool | Ôëñ 200 tokens | Ôëñ 300 tokens |
| Response t├¡pica | Ôëñ 500 tokens | Ôëñ 1000 tokens |
| Response m├íxima | Ôëñ 2000 tokens | Ôëñ 5000 tokens |

**Regla general**: 1 token Ôëê 4 caracteres en ingl├®s, ~3 en espa├▒ol

---

## FASE 1: Medici├│n Baseline

### 1.1 Listar todas las tools

```bash
# Contar tools MCP
grep -r "public string Name =>" src/src/BigCommerceApi/Mcp/Tools/ | wc -l
```

### 1.2 Extraer schemas

Para cada tool, medir:
- Tokens en descripci├│n
- Tokens en par├ímetros (nombre + descripci├│n)
- Tokens en InputSchema
- Tokens en OutputSchema

### 1.3 Medir responses t├¡picas

```sql
-- Si hay logging de MCP
SELECT
    ToolName,
    COUNT(*) as Calls,
    AVG(LEN(ResponseJson)) / 4 as EstTokens
FROM McpToolLogs
WHERE CreatedAt > DATEADD(day, -7, GETDATE())
GROUP BY ToolName
ORDER BY EstTokens DESC
```

### 1.4 Generar tabla de priorizaci├│n

| Tool | Schema Tokens | Response Tokens | Total | Prioridad |
|------|---------------|-----------------|-------|-----------|
| products_search | ? | ? | ? | ? |
| catalog_preview | ? | ? | ? | ? |
| ... | ... | ... | ... | ... |

- [ ] Top 10 tools identificadas
- [ ] SLIs baseline documentados

---

## FASE 2: Dise├▒o de Optimizaciones

### 2.1 ├üreas de Optimizaci├│n

#### JSON Schemas (Tool Definitions)

| Problema | Impacto | Soluci├│n |
|----------|---------|----------|
| Descripciones largas | +50-200 tokens | Max 10 palabras |
| Ejemplos inline | +100-500 tokens | Mover a docs |
| Enums extensos | +20-100 tokens | Agrupar |
| Par├ímetros raramente usados | +10-30 tokens | Tool separada |

**Ejemplo:**
```json
// ANTES: ~80 tokens
{
  "name": "searchText",
  "description": "Texto de b├║squeda para filtrar subcategor├¡as. Este par├ímetro permite buscar tanto en el nombre de la subcategor├¡a como en el breadcrumb completo incluyendo todas las categor├¡as padre.",
  "type": "string"
}

// DESPU├ëS: ~25 tokens
{
  "name": "q",
  "description": "Filtro texto (nombre o breadcrumb)",
  "type": "string"
}
```

#### Tool Responses

| Problema | Impacto | Soluci├│n |
|----------|---------|----------|
| Campos null/vac├¡os | +5-20 tokens | Omitir |
| Timestamps ISO | +15 tokens | Formato corto |
| URLs completas | +20-50 tokens | Path relativo |
| Paginaci├│n verbose | +30-50 tokens | Formato compacto |
| Pretty-print JSON | +20% tokens | Minificar |

**Ejemplo:**
```json
// ANTES: ~120 tokens
{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "currentPage": 1,
      "pageSize": 50,
      "totalItems": 1523,
      "totalPages": 31,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  },
  "timestamp": "2024-12-28T10:30:45.123Z"
}

// DESPU├ëS: ~50 tokens
{
  "items": [...],
  "page": [1, 50, 1523],
  "more": true
}
```

### 2.2 Response Modes

| Modo | Uso | Campos |
|------|-----|--------|
| `minimal` | Listados, conteos | Solo IDs y 1-2 campos |
| `standard` | Uso normal | Campos m├ís usados |
| `full` | Detalle completo | Todos los campos |

### 2.3 Checklist por Tool

- [ ] Nombre: ┬┐Es el m├ís corto posible?
- [ ] Descripci├│n: ┬┐< 100 caracteres?
- [ ] Par├ímetros obligatorios: ┬┐Necesarios todos?
- [ ] Par├ímetros opcionales: ┬┐Cu├íles se usan <10%?
- [ ] Descripciones params: ┬┐< 50 chars?
- [ ] Campos null: ┬┐Se omiten?
- [ ] JSON: ┬┐Minificado?

---

## FASE 3: Implementaci├│n

### 3.1 JsonSerializerOptions optimizadas

```csharp
public static readonly JsonSerializerOptions CompactOptions = new()
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = false
};
```

### 3.2 Response DTOs compactos

```csharp
// Usar [JsonPropertyName] para nombres cortos
public record CompactProduct(
    [property: JsonPropertyName("id")] string ProductId,
    [property: JsonPropertyName("n")] string Name,
    [property: JsonPropertyName("p")] decimal? Price
);
```

### 3.3 Response modes

```csharp
public enum ResponseMode { Minimal, Standard, Full }

public object FormatResponse<T>(T data, ResponseMode mode) => mode switch
{
    ResponseMode.Minimal => ToMinimal(data),
    ResponseMode.Full => data,
    _ => ToStandard(data)
};
```

---

## FASE 4: Validaci├│n

### 4.1 Comparar antes/despu├®s

| Tool | Antes | Despu├®s | Reducci├│n |
|------|-------|---------|-----------|
| products_search | X tokens | Y tokens | -Z% |
| catalog_preview | X tokens | Y tokens | -Z% |

### 4.2 Validar SLOs

- [ ] Schema < 200 tokens (todas las tools)
- [ ] Response t├¡pica < 500 tokens (80% tools)
- [ ] Response m├íxima < 2000 tokens (todas las tools)

### 4.3 Test funcional

- [ ] Claude interpreta correctamente nuevas responses
- [ ] No hay regresiones en funcionalidad
- [ ] Tests unitarios pasan

---

## Resultado

| Estado | Criterio |
|--------|----------|
| **├ëxito** | ÔëÑ30% reducci├│n en top 5 tools, SLOs cumplidos |
| **Parcial** | 15-30% reducci├│n, algunos SLOs pendientes |
| **Fallo** | <15% reducci├│n o regresiones funcionales |

---

## Mensaje de Finalizaci├│n

**IMPORTANTE - ACCI├ôN REQUERIDA AL FINALIZAR:**

Cuando hayas completado todos los pasos de este procedimiento, DEBES ejecutar el siguiente comando usando la herramienta Bash:

Ejecuta: `echo "====== PROCESO TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: Optimizacion MCP -X% tokens, SLOs cumplidos"`

Sustituye X por el porcentaje real de reducci├│n.

---

## Referencias

- **PROC-03**: Database Performance Review
- **PROC-06**: Add MCP Tool (est├índares optimizados)
- **PROC-08**: Tech Debt Analysis
- **Anthropic Tokenizer**: https://console.anthropic.com/tokenizer

---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-61 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "reduction_percent": 25,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-61"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- context_before_tokens, context_after_tokens, reduction_percent

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar