diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..36b5243 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## Descripción + + +## Tipo de cambio +- [ ] Feature (nueva funcionalidad) +- [ ] Bugfix (corrección de error) +- [ ] Hotfix (corrección urgente) +- [ ] Docs (documentación) +- [ ] Refactor (sin cambio funcional) + +## Checklist +- [ ] Tests añadidos/actualizados +- [ ] Documentación actualizada +- [ ] `black` y `flake8` pasan +- [ ] Funciona con la API del BOE + +## Testing + + +## Notas adicionales + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..2f3189b --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,19 @@ +version: 2 +updates: + - package-ecosystem: pip + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + labels: + - dependencies + - python + + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + labels: + - dependencies + - github-actions diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..bc0ce1d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,56 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install dependencies + run: pip install -e ".[dev]" + - name: Check formatting with Black + run: python -m black --check src/ + - name: Lint with flake8 + run: python -m flake8 src/ + - name: Type check with mypy + run: python -m mypy src/ + + test: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.8', '3.10', '3.11', '3.12'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: pip install -e ".[test]" + - name: Run tests with coverage + run: python -m pytest tests/ -v --cov=src/mcp_boe --cov-report=xml + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + if: matrix.python-version == '3.11' + with: + fail_ci_if_error: false + + connectivity: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install dependencies + run: pip install -e . + - name: Test BOE API connectivity + run: python examples/basic_usage.py connectivity diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..92a3e33 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,26 @@ +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install build tools + run: pip install build twine + - name: Build package + run: python -m build + - name: Publish to PyPI + run: twine upload dist/* + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }} diff --git a/.gitignore b/.gitignore index 09bf5d6..fe0c798 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,59 @@ +# Python *.pyc -__pycache__/ \ No newline at end of file +__pycache__/ +*.pyo +*.pyd +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +venv/ +env/ +.venv/ +.env/ + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Testing +.pytest_cache/ +.coverage +htmlcov/ +.tox/ +.nox/ +coverage.xml +*.cover +*.py,cover + +# Mypy +.mypy_cache/ + +# Local scripts (not part of the project) +crear_estructura_testing.sh \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9f63467 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,107 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +MCP-BOE is a Model Context Protocol (MCP) server that provides access to the Spanish Official State Gazette (BOE - Boletín Oficial del Estado) API. It allows LLMs like Claude to search consolidated legislation, daily BOE/BORME summaries, and auxiliary reference tables. + +## Build & Development Commands + +```bash +# Install for development +pip install -e ".[dev]" + +# Install with REST API support +pip install -e ".[api]" + +# Run the MCP server +python -m mcp_boe.server + +# Server modes +python -m mcp_boe.server --mode server # Run MCP server (default) +python -m mcp_boe.server --mode test # Run test function +python -m mcp_boe.server --mode diagnose # Diagnose API connectivity + +# Test connectivity +python examples/basic_usage.py connectivity + +# Run all tests +python examples/basic_usage.py all + +# Run specific tests +python examples/basic_usage.py search # Legislation search +python examples/basic_usage.py summary # BOE summaries +python examples/basic_usage.py departments # Auxiliary tables + +# Start REST API wrapper +python rest_api_wrapper.py + +# Linting and formatting +python -m black src/ +python -m flake8 src/ +python -m mypy src/ + +# Run pytest +python -m pytest tests/ +``` + +## Architecture + +### Core Components + +- **`src/mcp_boe/server.py`**: Main MCP server (`BOEMCPServer`) that registers tool handlers and coordinates communication with MCP clients. Entry point is `main()`. + +- **`src/mcp_boe/utils/http_client.py`**: `BOEHTTPClient` - async HTTP client for BOE API with retry logic, timeout handling, and XML/JSON parsing. Base URL: `https://www.boe.es/datosabiertos/api` + +- **`src/mcp_boe/tools/`**: MCP tool implementations, each class provides `get_tools()` returning tool definitions and async methods for tool execution: + - `legislation.py` - `LegislationTools`: Search and retrieve consolidated legislation + - `summaries.py` - `SummaryTools`: BOE/BORME daily summaries + - `auxiliary.py` - `AuxiliaryTools`: Reference tables (departments, legal ranges, matters) + +- **`src/mcp_boe/models/boe_models.py`**: Pydantic models and validation helpers (`validate_boe_identifier`, `validate_date_format`) + +### Tool Registration Pattern + +Tools are registered in `BOEMCPServer._setup_handlers()` via `@self.server.list_tools()` and `@self.server.call_tool()` decorators. Each tool class implements: +1. `get_tools()` - Returns list of `mcp.types.Tool` with JSON Schema input definitions +2. Async handler methods that return `List[TextContent]` + +### API Endpoints Used + +``` +/legislacion-consolidada - Legislation search and retrieval +/boe/sumario/{date} - BOE daily summaries +/borme/sumario/{date} - BORME daily summaries +/tablas-auxiliares/{table} - Auxiliary tables (departamentos, rangos, materias, etc.) +``` + +### Key Identifiers + +- BOE document IDs: `BOE-A-YYYY-NNNNN` (e.g., `BOE-A-2015-10566`) +- Date format: `YYYYMMDD` (e.g., `20240529`) +- Department codes: 4-digit strings (e.g., `7723` for Jefatura del Estado) +- Legal range codes: 4-digit strings (e.g., `1300` for Ley, `1200` for Real Decreto) + +## Configuration + +Environment variables for advanced configuration (see `BOEMCPConfig`): +- `BOE_HTTP_TIMEOUT`: Request timeout (default: 30s) +- `BOE_MAX_RETRIES`: Max retry attempts (default: 3) +- `BOE_RETRY_DELAY`: Delay between retries (default: 1s) +- `LOG_LEVEL`: Logging level (default: INFO) + +## MCP Client Configuration + +For Claude Code with uvx: +```json +{ + "mcpServers": { + "mcp-boe": { + "command": "uvx", + "args": ["--from", "git+https://github.com/ComputingVictor/MCP-BOE.git", "mcp-boe"], + "transport": "stdio" + } + } +} +``` diff --git a/PLAN_CI_CD.md b/PLAN_CI_CD.md new file mode 100644 index 0000000..2e74f5c --- /dev/null +++ b/PLAN_CI_CD.md @@ -0,0 +1,185 @@ +# Plan CI/CD y Estrategia de Branching + +## Estrategia de Ramas (GitFlow simplificado) + +``` +main ← Producción, siempre estable + ↑ +develop ← Integración, próxima release + ↑ +feature/* ← Nuevas funcionalidades (feature/add-search-filter) +bugfix/* ← Correcciones (bugfix/fix-date-validation) +hotfix/* ← Fixes urgentes en producción (desde main) +release/* ← Preparación de releases (desde develop) +``` + +### Reglas de Ramas +- `main`: Protegida, solo merge via PR desde `develop` o `hotfix/*` +- `develop`: Protegida, solo merge via PR desde `feature/*`, `bugfix/*`, `release/*` +- `feature/*`: Crear desde `develop`, merge a `develop` +- `hotfix/*`: Crear desde `main`, merge a `main` Y `develop` + +## Archivos a Crear + +### 1. `.github/workflows/ci.yml` - CI en PRs y pushes + +```yaml +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - run: pip install -e ".[dev]" + - run: python -m black --check src/ + - run: python -m flake8 src/ + - run: python -m mypy src/ + + test: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.8', '3.10', '3.11', '3.12'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - run: pip install -e ".[test]" + - run: python -m pytest tests/ -v --cov=src/mcp_boe --cov-report=xml + - uses: codecov/codecov-action@v4 + if: matrix.python-version == '3.11' + + connectivity: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - run: pip install -e . + - run: python examples/basic_usage.py connectivity +``` + +### 2. `.github/workflows/release.yml` - Publicación a PyPI + +```yaml +name: Release + +on: + push: + tags: ['v*'] + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - run: pip install build twine + - run: python -m build + - run: twine upload dist/* + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }} +``` + +### 3. `.github/PULL_REQUEST_TEMPLATE.md` + +```markdown +## Descripción + + +## Tipo de cambio +- [ ] Feature (nueva funcionalidad) +- [ ] Bugfix (corrección de error) +- [ ] Hotfix (corrección urgente) +- [ ] Docs (documentación) +- [ ] Refactor (sin cambio funcional) + +## Checklist +- [ ] Tests añadidos/actualizados +- [ ] Documentación actualizada +- [ ] `black` y `flake8` pasan +- [ ] Funciona con la API del BOE +``` + +### 4. `.github/dependabot.yml` + +```yaml +version: 2 +updates: + - package-ecosystem: pip + directory: "/" + schedule: + interval: weekly + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly +``` + +### 5. Protección de ramas (configurar en GitHub Settings) + +**main:** +- Require PR before merging +- Require status checks: `lint`, `test` +- Require branches up to date +- No force pushes + +**develop:** +- Require PR before merging +- Require status checks: `lint`, `test` + +## Pasos de Implementación + +1. **Crear rama develop** + ```bash + git checkout -b develop + git push -u origin develop + ``` + +2. **Crear archivos de workflow** + - `.github/workflows/ci.yml` + - `.github/workflows/release.yml` + - `.github/PULL_REQUEST_TEMPLATE.md` + - `.github/dependabot.yml` + +3. **Configurar protección en GitHub** + - Settings → Branches → Add rule + +4. **Añadir secrets en GitHub** + - `PYPI_TOKEN` para releases + - `CODECOV_TOKEN` para coverage (opcional) + +## Flujo de Trabajo Diario + +```bash +# Nueva feature +git checkout develop +git pull +git checkout -b feature/mi-feature +# ... trabajo ... +git push -u origin feature/mi-feature +# Crear PR a develop en GitHub + +# Hotfix urgente +git checkout main +git pull +git checkout -b hotfix/fix-critico +# ... fix ... +git push -u origin hotfix/fix-critico +# Crear PR a main Y otro a develop +``` diff --git a/src/mcp_boe/models/boe_models.py b/src/mcp_boe/models/boe_models.py index 56a2b52..272a6cd 100644 --- a/src/mcp_boe/models/boe_models.py +++ b/src/mcp_boe/models/boe_models.py @@ -465,23 +465,48 @@ class Config: # MODELOS PARA RESPUESTAS DE ERROR # ============================================================================ -class APIError(BaseModel): - """Error de la API del BOE.""" - codigo: int = Field(..., description="Código de error HTTP") - mensaje: str = Field(..., description="Mensaje de error") - detalles: Optional[str] = Field(None, description="Detalles adicionales del error") - timestamp: datetime = Field(default_factory=datetime.now, description="Momento del error") - - class Config: - json_schema_extra = { - "example": { - "codigo": 404, - "mensaje": "La información solicitada no existe", - "detalles": "El identificador BOE-A-2025-99999 no se encontró", - "timestamp": "2025-01-23T10:30:00Z" - } +class APIError(Exception): + """ + Error de la API del BOE. + + Hereda de Exception para poder ser usado en bloques try/except. + """ + + def __init__( + self, + codigo: int, + mensaje: str, + detalles: Optional[str] = None, + timestamp: Optional[datetime] = None + ): + self.codigo = codigo + self.mensaje = mensaje + self.detalles = detalles + self.timestamp = timestamp or datetime.now() + super().__init__(f"[{codigo}] {mensaje}") + + def __str__(self) -> str: + base = f"[{self.codigo}] {self.mensaje}" + if self.detalles: + base += f" - {self.detalles}" + return base + + def __repr__(self) -> str: + return f"APIError(codigo={self.codigo}, mensaje='{self.mensaje}', detalles={self.detalles!r})" + + def to_dict(self) -> dict: + """Serializar error para logging/respuesta.""" + return { + "codigo": self.codigo, + "mensaje": self.mensaje, + "detalles": self.detalles, + "timestamp": self.timestamp.isoformat() } + # Ejemplo de uso documentado en docstring + # APIError(codigo=404, mensaje="La información solicitada no existe", + # detalles="El identificador BOE-A-2025-99999 no se encontró") + # ============================================================================ # FUNCIONES AUXILIARES diff --git a/testing_mcp_boe_consolidada/00_estructura/METODOLOGIA_DOCUMENTACION.md b/testing_mcp_boe_consolidada/00_estructura/METODOLOGIA_DOCUMENTACION.md new file mode 100644 index 0000000..eac2022 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/METODOLOGIA_DOCUMENTACION.md @@ -0,0 +1,450 @@ +# METODOLOGÍA DE DOCUMENTACIÓN +## Banco de Pruebas MCP-BOE-CONSOLIDADA + +**Versión:** 1.0 +**Fecha:** 2025-11-23 +**Autor:** pepo +**Device:** MacBook-Air-de-Pepo.local + +--- + +## 🎯 OBJETIVOS DEL SISTEMA DE DOCUMENTACIÓN + +1. **Trazabilidad Completa** + - Cada test documentado desde entrada hasta resultado + - Cadena de evidencia verificable + - Reproducibilidad garantizada + +2. **Análisis Comparativo** + - Comparación con boe-mcp + - Identificación de gaps + - Scoring objetivo + +3. **Aprendizaje Continuo** + - Captura de insights + - Identificación de patrones + - Base de conocimiento + +4. **Auditoría Técnica** + - Evidencia de cada llamada + - Métricas verificables + - Conclusiones fundamentadas + +--- + +## 📂 ESTRUCTURA DE ARCHIVOS POR TEST + +### Archivos Obligatorios: + +#### 1. `input.json` +**Propósito:** Registrar parámetros exactos enviados al MCP + +**Formato:** +```json +{ + "test_id": "1.1", + "test_name": "busqueda_simple", + "timestamp": "2025-11-23T17:41:11Z", + "tool": "search_consolidated_legislation", + "parameters": { + "query": "Ley 40/2015", + "limit": 5, + "offset": 0 + }, + "expected_behavior": "Debe devolver la Ley 40/2015 en primeros resultados" +} +``` + +#### 2. `raw_response.json` +**Propósito:** Capturar respuesta completa sin procesar + +**Formato:** +```json +{ + "timestamp_received": "2025-11-23T17:41:12.345Z", + "latency_ms": 1345, + "status": "success", + "raw_data": "...[respuesta completa del MCP]..." +} +``` + +#### 3. `parsed_output.json` +**Propósito:** Datos procesados y estructurados para análisis + +**Formato:** +```json +{ + "test_id": "1.1", + "parsed_at": "2025-11-23T17:41:13Z", + "results": { + "count": 5, + "items": [...], + "metadata": {...} + }, + "quality_metrics": { + "relevance": 0.95, + "completeness": 1.0, + "accuracy": 1.0 + } +} +``` + +#### 4. `ANALISIS_test_X.X.md` +**Propósito:** Análisis humano completo del test + +**Secciones obligatorias:** +- Objetivo +- Input +- Métricas +- Output +- Resultado (PASS/PARTIAL/FAIL) +- Análisis detallado +- Insights +- Errores +- Comparación +- Recomendaciones + +### Archivos Opcionales: + +#### 5. `screenshots/` +**Cuándo crear:** Si hay visualización de datos o interfaz + +**Naming convention:** +- `01_input_params.png` +- `02_response_data.png` +- `03_error_message.png` +- `04_comparison.png` + +#### 6. `logs.txt` +**Cuándo crear:** Si hay debugging complejo o errores + +**Contenido:** +- Console logs +- Error traces +- Debug output + +--- + +## 📝 PROCESO DE DOCUMENTACIÓN PASO A PASO + +### ANTES DE EJECUTAR EL TEST: + +#### Paso 1: Crear estructura de directorios +```bash +mkdir -p 01_nivel_basico/test_1.X_nombre/screenshots +``` + +#### Paso 2: Preparar input.json +- Definir parámetros del test +- Documentar expectativas +- Timestamp de preparación + +#### Paso 3: Revisar contexto +- ¿Qué valida este test? +- ¿Qué necesito observar? +- ¿Qué comparar con boe-mcp? + +### DURANTE LA EJECUCIÓN: + +#### Paso 4: Capturar timestamp inicio +```bash +date -u +'%Y-%m-%dT%H:%M:%SZ' +``` + +#### Paso 5: Ejecutar herramienta MCP +- Usar parámetros de input.json +- Observar comportamiento +- Notar peculiaridades + +#### Paso 6: Capturar timestamp fin +```bash +date -u +'%Y-%m-%dT%H:%M:%SZ' +``` + +#### Paso 7: Guardar respuesta raw +- Copiar respuesta completa +- Guardar en raw_response.json +- Incluir metadatos de captura + +### DESPUÉS DE LA EJECUCIÓN: + +#### Paso 8: Procesar datos +- Parsear respuesta +- Extraer campos relevantes +- Calcular métricas +- Guardar en parsed_output.json + +#### Paso 9: Capturar screenshots (si aplica) +- Input visible +- Response visible +- Errores visibles +- Comparaciones + +#### Paso 10: Analizar resultado +- ¿Funcionó correctamente? +- ¿PASS / PARTIAL / FAIL? +- ¿Qué aprendí? +- ¿Qué mejorar? + +#### Paso 11: Documentar análisis +- Usar template_test.md +- Completar todas las secciones +- Ser específico y objetivo +- Incluir evidencias + +#### Paso 12: Actualizar checklist +- Marcar test como completado +- Actualizar progreso del nivel +- Verificar prerequisites para siguiente test + +--- + +## 📊 CRITERIOS DE EVALUACIÓN + +### Test Individual: + +#### ✅ PASS (Aprobado) +**Criterios:** +- Respuesta recibida sin errores +- Estructura de datos correcta +- Contenido relevante y preciso +- Performance aceptable (<2s) +- Cobertura funcional completa + +**Puntuación:** 100/100 + +#### ⚠️ PARTIAL (Parcial) +**Criterios:** +- Respuesta recibida con warnings +- Estructura correcta pero incompleta +- Contenido mayormente relevante +- Performance degradada (2-5s) +- Cobertura funcional limitada + +**Puntuación:** 50-99/100 + +#### ❌ FAIL (Fallido) +**Criterios:** +- Error crítico en respuesta +- Estructura incorrecta +- Contenido irrelevante +- Timeout (>5s) +- Funcionalidad no disponible + +**Puntuación:** 0-49/100 + +### Nivel Completo: + +#### 🏆 EXCELENTE +- ≥90% tests PASS +- Sin bugs críticos +- Performance consistente +- Documentación completa + +#### 👍 BUENO +- 70-89% tests PASS +- Bugs menores manejables +- Performance aceptable +- Documentación adecuada + +#### 🤝 ACEPTABLE +- 50-69% tests PASS +- Algunos bugs críticos +- Performance irregular +- Documentación básica + +#### 👎 DEFICIENTE +- <50% tests PASS +- Múltiples bugs críticos +- Performance inaceptable +- Documentación incompleta + +--- + +## 📈 MÉTRICAS OBLIGATORIAS + +### Por Test Individual: + +#### Temporales: +- `timestamp_start`: ISO 8601 +- `timestamp_end`: ISO 8601 +- `latency_ms`: Entero +- `execution_time`: Segundos + +#### Volumen: +- `response_size_bytes`: Entero +- `response_size_kb`: Float (2 decimales) +- `num_results`: Entero +- `depth_levels`: Entero (anidamiento) + +#### Calidad: +- `relevance_score`: 0.0-1.0 +- `completeness_score`: 0.0-1.0 +- `accuracy_score`: 0.0-1.0 +- `overall_score`: 0-100 + +#### Errores: +- `error_count`: Entero +- `warning_count`: Entero +- `error_severity`: [none, low, medium, high, critical] +- `error_messages`: Array de strings + +### Por Nivel: + +#### Agregadas: +- `total_tests`: Entero +- `pass_count`: Entero +- `partial_count`: Entero +- `fail_count`: Entero +- `pass_rate`: Porcentaje + +#### Performance: +- `avg_latency_ms`: Float +- `median_latency_ms`: Float +- `p95_latency_ms`: Float +- `p99_latency_ms`: Float + +#### Volumen: +- `total_data_processed_mb`: Float +- `avg_response_size_kb`: Float + +--- + +## 🔄 WORKFLOW DE REVISIÓN + +### Auto-revisión: +1. Completar checklist de secciones +2. Verificar evidencias incluidas +3. Confirmar métricas calculadas +4. Revisar ortografía y formato + +### Validación cruzada: +1. Comparar con template +2. Verificar consistencia de datos +3. Confirmar reproducibilidad +4. Validar conclusiones + +### Aprobación de nivel: +1. Revisar informe de nivel +2. Verificar todos los tests documentados +3. Confirmar criterios de éxito +4. Aprobar paso a siguiente nivel + +--- + +## 📎 NOMENCLATURA Y CONVENCIONES + +### Nombres de archivos: +- **Tests:** `test_X.Y_nombre_descriptivo/` +- **Inputs:** `input.json` +- **Outputs raw:** `raw_response.json` +- **Outputs parsed:** `parsed_output.json` +- **Análisis:** `ANALISIS_test_X.Y.md` +- **Screenshots:** `NN_descripcion.png` + +### IDs de tests: +- **Formato:** `[nivel].[número]` +- **Ejemplo:** `1.1`, `1.2`, `2.1` + +### Timestamps: +- **Formato:** ISO 8601 UTC +- **Ejemplo:** `2025-11-23T17:41:11Z` + +### Paths: +- **Root:** `/Users/pepo/Documents/Proyectos/BOE/testing_mcp_boe_consolidada/` +- **Niveles:** `0X_nivel_nombre/` +- **Tests:** `test_X.Y_nombre/` + +--- + +## ✅ CHECKLIST DE CALIDAD + +### Antes de marcar test como completo: + +- [ ] `input.json` creado con parámetros correctos +- [ ] `raw_response.json` guardado con respuesta completa +- [ ] `parsed_output.json` procesado con métricas +- [ ] `ANALISIS_test_X.X.md` completado con todas las secciones +- [ ] Screenshots capturados (si aplica) +- [ ] Métricas calculadas correctamente +- [ ] Resultado determinado (PASS/PARTIAL/FAIL) +- [ ] Comparación con boe-mcp documentada +- [ ] Insights y aprendizajes registrados +- [ ] Recomendaciones incluidas +- [ ] Formato markdown correcto +- [ ] Links funcionando +- [ ] Timestamp actualizado + +### Antes de marcar nivel como completo: + +- [ ] Todos los tests del nivel ejecutados +- [ ] Informe de nivel completo +- [ ] Métricas agregadas calculadas +- [ ] Comparativa consolidada +- [ ] Score del nivel determinado +- [ ] Decisión sobre siguiente nivel tomada +- [ ] Checklist de progreso actualizado + +--- + +## 🚨 CASOS ESPECIALES + +### Si un test falla críticamente: +1. Documentar el fallo detalladamente +2. Intentar identificar causa raíz +3. Buscar workaround si existe +4. Reportar al desarrollador si es bug +5. Marcar como bloqueante si impide progreso +6. Documentar impacto en nivel + +### Si hay timeout: +1. Registrar tiempo transcurrido +2. Intentar con parámetros reducidos +3. Documentar comportamiento +4. Marcar como limitación de performance + +### Si respuesta es inesperada: +1. Comparar con especificación API +2. Verificar si es bug o feature no documentado +3. Contrastar con boe-mcp +4. Documentar discrepancia + +### Si test requiere prerequisitos: +1. Documentar dependencias +2. Verificar estado antes de ejecutar +3. Ejecutar setup necesario +4. Documentar en análisis + +--- + +## 📌 MEJORES PRÁCTICAS + +### Documentación: +- ✅ Ser específico y objetivo +- ✅ Incluir evidencias concretas +- ✅ Usar formato markdown consistente +- ✅ Agregar contexto suficiente +- ❌ No asumir conocimiento previo +- ❌ No usar lenguaje ambiguo + +### Testing: +- ✅ Un test, un objetivo +- ✅ Parámetros bien documentados +- ✅ Resultados reproducibles +- ❌ No tests dependientes entre sí +- ❌ No asumir estado previo + +### Análisis: +- ✅ Fundamentar conclusiones +- ✅ Comparar con alternativas +- ✅ Proponer mejoras concretas +- ❌ No hacer juicios sin evidencia +- ❌ No omitir limitaciones + +--- + +**FIN DEL DOCUMENTO DE METODOLOGÍA** + +--- + +*Metodología v1.0 - Banco Pruebas MCP-BOE-CONSOLIDADA* diff --git a/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_informe_final.md b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_informe_final.md new file mode 100644 index 0000000..9036123 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_informe_final.md @@ -0,0 +1,399 @@ +# INFORME FINAL COMPLETO +## Banco de Pruebas MCP-BOE-CONSOLIDADA + +**Servidor MCP:** mcp-boe-consolidada (ComputingVictor) +**Proyecto:** Evaluación Exhaustiva y Comparativa +**Fecha Inicio:** [YYYY-MM-DD] +**Fecha Finalización:** [YYYY-MM-DD] +**Duración Total:** [X semanas/meses] +**Device:** MacBook-Air-de-Pepo.local +**Ejecutor:** pepo +**Versión Informe:** 1.0 + +--- + +## 📊 RESUMEN EJECUTIVO + +### Estado Final del Proyecto: +**[EXITOSO / PARCIALMENTE EXITOSO / INCOMPLETO]** + +### Métricas Globales: +- **Tests totales ejecutados:** [N] +- **Tasa de éxito global:** [XX%] +- **Niveles completados:** [X/8] +- **Tiempo total invertido:** [XXX horas] +- **Documentos generados:** [N] +- **Bugs críticos encontrados:** [N] + +### Score Final: +**[XX.X/100]** + +--- + +## 🎯 OBJETIVOS Y ALCANCE + +### Objetivo Principal: +[Descripción del propósito del banco de pruebas] + +### Alcance Definido: +- Validación funcional completa +- Comparación con boe-mcp +- Identificación de gaps +- Propuesta de mejoras +- Documentación exhaustiva + +### Alcance Logrado: +[X%] del alcance definido + +--- + +## 📋 RESULTADOS POR NIVEL + +### NIVEL 1: Funcionalidad Básica +- **Estado:** [✅ Completado / ⚠️ Parcial / ❌ Incompleto] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 2: Recuperación de Documentos +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 3: Navegación Granular +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 4: Análisis de Relaciones +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 5: Sumarios y Publicaciones +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 6: Tablas Auxiliares +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 7: Casos de Uso Reales +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +### NIVEL 8: Estrés y Límites +- **Estado:** [✅/⚠️/❌] +- **Tests:** [N/N] +- **Score:** [XX/100] +- **Hallazgos clave:** [Resumen] +- **Link:** [ruta al informe] + +--- + +## 📊 ANÁLISIS GLOBAL + +### Cobertura Funcional Alcanzada: + +#### API Oficial BOE Consolidada: +- **Búsqueda:** [XX%] +- **Recuperación:** [XX%] +- **Navegación:** [XX%] +- **Análisis:** [XX%] +- **Sumarios:** [XX%] +- **Vocabulario:** [XX%] + +#### Features del MCP: +- **Documentación:** [XX%] +- **Usabilidad:** [XX%] +- **Performance:** [XX%] +- **Estabilidad:** [XX%] +- **Manejo errores:** [XX%] + +--- + +## 🔍 ANÁLISIS COMPARATIVO + +### MCP-BOE-CONSOLIDADA vs BOE-MCP + +#### Tabla Comparativa: + +| Característica | mcp-boe-consolidada | boe-mcp | Ganador | +|----------------|---------------------|---------|---------| +| Arquitectura | REST API directo | Python nativo | [¿?] | +| Documentación | [Score] | [Score] | [¿?] | +| Features | [Score] | [Score] | [¿?] | +| Performance | [Score] | [Score] | [¿?] | +| Estabilidad | [Score] | [Score] | [¿?] | +| Navegación | [Score] | [Score] | [¿?] | +| ELI Support | [Score] | [Score] | [¿?] | +| Vocabulario | [Score] | [Score] | [¿?] | + +#### Ventajas de mcp-boe-consolidada: +1. [Ventaja 1 con evidencia] +2. [Ventaja 2 con evidencia] +3. [Ventaja 3 con evidencia] + +#### Ventajas de boe-mcp: +1. [Ventaja 1 con evidencia] +2. [Ventaja 2 con evidencia] + +#### Features únicas de cada uno: +- **mcp-boe-consolidada exclusivas:** [Lista] +- **boe-mcp exclusivas:** [Lista] + +--- + +## 🐛 BUGS Y LIMITACIONES + +### Bugs Críticos Encontrados: + +#### Bug #1: [Nombre] +- **Severidad:** [Alta/Media/Baja] +- **Frecuencia:** [Siempre/A veces/Rara] +- **Reproducción:** [Pasos] +- **Workaround:** [Si existe] +- **Reportado:** [Sí/No] + +[Repetir para cada bug] + +### Limitaciones de Diseño: + +1. **[Limitación 1]** + - Impacto: [Descripción] + - Mitigación: [Si existe] + +[Repetir para cada limitación] + +--- + +## 💡 INSIGHTS Y DESCUBRIMIENTOS + +### Hallazgos Técnicos: +[Descubrimientos técnicos relevantes] + +### Mejores Prácticas: +[Patrones de uso óptimos identificados] + +### Anti-patterns: +[Qué evitar al usar el MCP] + +### Casos de Uso Validados: +1. [Caso 1]: [Descripción y resultado] +2. [Caso 2]: [Descripción y resultado] + +--- + +## 📈 MÉTRICAS CONSOLIDADAS + +### Performance Global: +- **Latencia media:** [XXX ms] +- **Latencia P50:** [XXX ms] +- **Latencia P95:** [XXX ms] +- **Latencia P99:** [XXX ms] +- **Tests <1s:** [XX%] +- **Tests <2s:** [XX%] + +### Estabilidad: +- **Tasa de error:** [X%] +- **Errores críticos:** [N] +- **Timeout rate:** [X%] +- **Uptime durante tests:** [XX%] + +### Volumen de Datos: +- **Total procesado:** [XXX MB] +- **Respuesta media:** [XXX KB] +- **Mayor respuesta:** [XXX KB] +- **Menor respuesta:** [XXX bytes] + +--- + +## ✏️ RECOMENDACIONES + +### Para Desarrolladores del MCP: + +#### Prioridad Alta: +1. [Mejora crítica 1] +2. [Mejora crítica 2] + +#### Prioridad Media: +1. [Mejora importante 1] +2. [Mejora importante 2] + +#### Prioridad Baja: +1. [Nice to have 1] +2. [Nice to have 2] + +### Para Usuarios del MCP: + +#### Mejores Prácticas: +1. [Práctica 1] +2. [Práctica 2] + +#### Qué Evitar: +1. [Anti-pattern 1] +2. [Anti-pattern 2] + +#### Casos de Uso Recomendados: +1. [Uso ideal 1] +2. [Uso ideal 2] + +--- + +## 🚀 PROPUESTA: MCP-BOE-ULTIMATE + +### Concepto: +[Descripción del MCP híbrido ideal] + +### Features a Integrar: + +#### De mcp-boe-consolidada: +- [Feature 1] +- [Feature 2] + +#### De boe-mcp: +- [Feature 1] +- [Feature 2] + +#### Nuevas Features Propuestas: +- [Feature 1] +- [Feature 2] + +### Score Estimado: +**[XX.X/100]** (vs 78.5 actual) + +### Roadmap de Desarrollo: + +#### Fase 1: Base (Semanas 1-4) +- [Milestone 1] +- [Milestone 2] + +#### Fase 2: Features Avanzados (Semanas 5-8) +- [Milestone 3] +- [Milestone 4] + +#### Fase 3: Optimización (Semanas 9-12) +- [Milestone 5] +- [Milestone 6] + +--- + +## 📊 SCORING FINAL DETALLADO + +### Categorías y Puntuación: + +#### 1. Arquitectura y Diseño (15 pts) +- Calidad del código: [X/5] +- Arquitectura REST: [X/5] +- Manejo de errores: [X/5] +- **Subtotal:** [X/15] + +#### 2. Funcionalidad (25 pts) +- Cobertura API: [X/10] +- Features completas: [X/8] +- Casos de uso: [X/7] +- **Subtotal:** [X/25] + +#### 3. Performance (15 pts) +- Latencia: [X/7] +- Throughput: [X/5] +- Escalabilidad: [X/3] +- **Subtotal:** [X/15] + +#### 4. Documentación (15 pts) +- README: [X/5] +- API docs: [X/5] +- Ejemplos: [X/5] +- **Subtotal:** [X/15] + +#### 5. Estabilidad (10 pts) +- Error rate: [X/5] +- Manejo excepciones: [X/5] +- **Subtotal:** [X/10] + +#### 6. Usabilidad (10 pts) +- Facilidad de uso: [X/5] +- Naming: [X/3] +- Defaults: [X/2] +- **Subtotal:** [X/10] + +#### 7. Testing (5 pts) +- Cobertura tests: [X/3] +- CI/CD: [X/2] +- **Subtotal:** [X/5] + +#### 8. Innovación (5 pts) +- Features únicos: [X/3] +- Enfoque novedoso: [X/2] +- **Subtotal:** [X/5] + +### **SCORE FINAL: [XX.X/100]** + +--- + +## ✅ CONCLUSIONES + +### Logros del Proyecto: +[Qué se logró exitosamente] + +### Limitaciones Encontradas: +[Qué no se pudo completar o validar] + +### Impacto del Trabajo: +[Valor generado por este banco de pruebas] + +### Siguientes Pasos Recomendados: +1. [Acción 1] +2. [Acción 2] +3. [Acción 3] + +--- + +## 📎 REPOSITORIO DE DOCUMENTACIÓN + +### Estructura de Archivos: +- **Total de archivos:** [N] +- **Documentos markdown:** [N] +- **JSON files:** [N] +- **Screenshots:** [N] +- **Tamaño total:** [XXX MB] + +### Acceso: +- **Directorio principal:** `/Users/pepo/Documents/Proyectos/BOE/testing_mcp_boe_consolidada/` +- **Informes por nivel:** `[rutas]` +- **Comparativas:** `99_comparativas/` + +--- + +## 🙏 AGRADECIMIENTOS + +- ComputingVictor (desarrollador mcp-boe-consolidada) +- Comunidad BOE API +- Claude Desktop / Anthropic + +--- + +**Fecha de cierre:** [YYYY-MM-DD] +**Versión final:** 1.0 +**Autor:** pepo +**Estado:** [COMPLETO / EN PROGRESO] + +--- + +*Informe Final - Banco Pruebas MCP-BOE-CONSOLIDADA* diff --git a/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_nivel.md b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_nivel.md new file mode 100644 index 0000000..50c7d5b --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_nivel.md @@ -0,0 +1,216 @@ +# INFORME NIVEL [X]: [NOMBRE_NIVEL] + +**Servidor MCP:** mcp-boe-consolidada +**Nivel:** [X] +**Categoría:** [Funcionalidad Básica/Navegación/etc] +**Fecha Inicio:** [YYYY-MM-DD] +**Fecha Fin:** [YYYY-MM-DD] +**Duración Total:** [X horas/días] +**Device:** MacBook-Air-de-Pepo.local +**Ejecutor:** pepo + +--- + +## 📊 RESUMEN EJECUTIVO + +### Estado General: +**[EXCELENTE / BUENO / ACEPTABLE / DEFICIENTE]** + +### Tests Ejecutados: +- **Total:** [N tests] +- **✅ PASS:** [N] ([XX%]) +- **⚠️ PARTIAL:** [N] ([XX%]) +- **❌ FAIL:** [N] ([XX%]) + +### Tiempo Total Invertido: +- **Ejecución:** [XX horas] +- **Documentación:** [XX horas] +- **Análisis:** [XX horas] + +--- + +## 🎯 OBJETIVOS DEL NIVEL + +### Objetivo principal: +[Qué se buscaba validar en este nivel] + +### Funcionalidades evaluadas: +1. [Feature 1] +2. [Feature 2] +3. [Feature 3] + +### Cobertura esperada: +[Qué porcentaje de la API/funcionalidad debería validarse] + +--- + +## 📋 DETALLE DE TESTS + +### Test [X.1]: [Nombre] +- **Resultado:** [✅/⚠️/❌] +- **Latencia:** [XXX ms] +- **Observación:** [Breve comentario] +- **Link:** [ruta al análisis completo] + +### Test [X.2]: [Nombre] +- **Resultado:** [✅/⚠️/❌] +- **Latencia:** [XXX ms] +- **Observación:** [Breve comentario] +- **Link:** [ruta al análisis completo] + +[Repetir para cada test del nivel] + +--- + +## ✅ FUNCIONALIDADES VALIDADAS + +### Completamente operativas: +- ✅ [Feature 1]: Funciona según especificación +- ✅ [Feature 2]: Sin limitaciones detectadas + +### Parcialmente operativas: +- ⚠️ [Feature 3]: Funciona con restricciones [detallar] + +### No operativas: +- ❌ [Feature 4]: [Explicar problema] + +--- + +## 📊 MÉTRICAS GLOBALES DEL NIVEL + +### Performance: +- **Latencia media:** [XXX ms] +- **Latencia mínima:** [XXX ms] +- **Latencia máxima:** [XXX ms] +- **Tests bajo 1s:** [N/total] +- **Tests bajo 2s:** [N/total] + +### Volumen de datos: +- **Respuesta media:** [XXX KB] +- **Respuesta mínima:** [XXX KB] +- **Respuesta máxima:** [XXX KB] +- **Total procesado:** [XXX MB] + +### Errores: +- **Rate de error:** [X%] +- **Errores críticos:** [N] +- **Warnings:** [N] +- **Workarounds necesarios:** [N] + +--- + +## 🔍 ANÁLISIS CUALITATIVO + +### Fortalezas detectadas: +1. [Fortaleza 1 con evidencia] +2. [Fortaleza 2 con evidencia] + +### Debilidades detectadas: +1. [Debilidad 1 con evidencia] +2. [Debilidad 2 con evidencia] + +### Comportamientos inesperados: +- [Si los hubo] + +--- + +## 🐛 BUGS Y LIMITACIONES + +### Bugs críticos: +1. **[Nombre bug]** + - Severidad: [Alta/Media/Baja] + - Reproducción: [Pasos] + - Workaround: [Si existe] + +### Limitaciones de diseño: +1. **[Limitación]** + - Impacto: [Descripción] + - Alternativa: [Si existe] + +--- + +## 💡 INSIGHTS Y APRENDIZAJES + +### Descubrimientos técnicos: +[Hallazgos técnicos relevantes] + +### Mejores prácticas identificadas: +[Patrones de uso óptimos] + +### Casos de uso validados: +[Aplicaciones reales confirmadas] + +--- + +## 📊 COMPARACIÓN vs boe-mcp + +### Features exclusivas de mcp-boe-consolidada: +- [Feature 1] +- [Feature 2] + +### Features que boe-mcp hace mejor: +- [Si aplica] + +### Features equivalentes: +- [Lista] + +--- + +## ✏️ RECOMENDACIONES + +### Para desarrolladores del MCP: +1. [Mejora sugerida 1] +2. [Mejora sugerida 2] + +### Para usuarios del MCP: +1. [Buena práctica 1] +2. [Buena práctica 2] + +### Para siguiente nivel: +1. [Foco de atención] +2. [Tests adicionales necesarios] + +--- + +## 📈 PROGRESO DEL PROYECTO + +### Niveles completados: [X/8] +### Cobertura funcional acumulada: [XX%] +### Tests totales ejecutados: [N] +### Tiempo total invertido: [XX horas] + +--- + +## ✅ CONCLUSIÓN DEL NIVEL + +### Veredicto: +[Resumen ejecutivo en 2-3 párrafos sobre el nivel] + +### Score del nivel: [XX/100] + +### Criterios de evaluación: +- Funcionalidad: [XX/30] +- Performance: [XX/20] +- Estabilidad: [XX/20] +- Documentación: [XX/15] +- Usabilidad: [XX/15] + +### ¿Continuar al siguiente nivel? +**[SÍ / NO]** - [Justificación] + +--- + +## 📎 ANEXOS + +- Directorio de tests: `[ruta]` +- Logs completos: `[ruta]` +- Screenshots: `[ruta]` +- Datos raw: `[ruta]` + +--- + +**Fecha de cierre del informe:** [YYYY-MM-DD] + +--- + +*Plantilla v1.0 - Banco Pruebas MCP-BOE-CONSOLIDADA* diff --git a/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_session.md b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_session.md new file mode 100644 index 0000000..7099320 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_session.md @@ -0,0 +1,110 @@ +# SESSION XXX - [Título Descriptivo] + +**Fecha:** YYYY-MM-DD +**Duración:** XX min +**RPVEA Phase Principal:** [R/P/V/E/A] + +--- + +## 🎯 Objetivo de la Sesión + +[Descripción clara del objetivo principal de esta sesión] + +--- + +## 📋 Tests Planificados + +| Test ID | Nombre | Herramienta | Estado Inicial | +|---------|--------|-------------|----------------| +| X.X | nombre_test | tool_name | pending | + +--- + +## 🔬 Triple Validación + +### V1 - Schema (Pydantic) +- **Modelo:** `[modelo verificado]` +- **Estado:** ✅/❌ [descripción] + +### V2 - API (Endpoint) +- **Endpoint:** `[URL probada]` +- **Estado:** ✅/❌ [descripción] + +### V3 - Real Query +- **Parámetros:** `[parámetros usados]` +- **Estado:** ✅/❌ [descripción] + +--- + +## 📊 Tests Ejecutados + +| Test ID | Nombre | Resultado | Latencia | Notas | +|---------|--------|-----------|----------|-------| +| X.X | nombre | PASS/PARTIAL/FAIL | XXX ms | [notas] | + +--- + +## 🐛 Bugs Encontrados + +### BUG-XXX: [Título del bug] +- **Severidad:** [baja/media/alta/crítica] +- **Archivo:** `path/to/file.py` +- **Línea:** XXX +- **Descripción:** [descripción detallada] +- **Impacto:** [qué tests bloquea] +- **Fix propuesto:** [solución] + +--- + +## 💡 Lecciones Aprendidas + +### 1. [Categoría]: [Título] +**Contexto:** [qué estabas haciendo] +**Problema:** [qué salió mal o qué descubriste] +**Lección:** [qué aprendiste] +**Aplicación futura:** [cómo aplicar esto adelante] + +### 2. [Categoría]: [Título] +... + +--- + +## 📈 Métricas de la Sesión + +- **Tests completados:** X/Y +- **Tasa de éxito:** XX% +- **Tiempo total:** XX min +- **Bugs críticos:** X +- **Bugs menores:** X + +--- + +## ✅ Checklist de Cierre + +- [ ] Todos los tests documentados +- [ ] raw_response.json guardado para cada test +- [ ] parsed_output.json procesado +- [ ] ANALISIS_test_X.X.md completado +- [ ] test_registry.json actualizado +- [ ] Bugs registrados con ID +- [ ] Lecciones documentadas + +--- + +## 🔜 Próximos Pasos + +1. [ ] [Tarea pendiente 1] +2. [ ] [Tarea pendiente 2] +3. [ ] [Tarea pendiente 3] + +--- + +## 📝 Notas Adicionales + +[Cualquier nota adicional relevante para esta sesión] + +--- + +**Sesión completada:** ✅/❌ +**Reviewer:** [nombre] +**Fecha revisión:** YYYY-MM-DD diff --git a/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_test.md b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_test.md new file mode 100644 index 0000000..6e17814 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/PLANTILLAS/template_test.md @@ -0,0 +1,151 @@ +# Test [NÚMERO]: [NOMBRE_DESCRIPTIVO] + +**Nivel:** [X] +**Categoría:** [Búsqueda/Navegación/Análisis/etc] +**Herramienta MCP:** [nombre_herramienta] +**Fecha Ejecución:** [YYYY-MM-DDTHH:MM:SSZ] +**Device:** MacBook-Air-de-Pepo.local +**Ejecutor:** pepo + +--- + +## 🎯 OBJETIVO DEL TEST + +[Descripción clara de qué se está probando y por qué] + +--- + +## 📥 INPUT + +### Parámetros enviados: +```json +{ + "parametro1": "valor1", + "parametro2": "valor2" +} +``` + +### Justificación de parámetros: +- **parametro1**: [Por qué este valor] +- **parametro2**: [Por qué este valor] + +--- + +## ⏱️ MÉTRICAS DE EJECUCIÓN + +- **Timestamp Inicio:** [HH:MM:SS.mmm] +- **Timestamp Fin:** [HH:MM:SS.mmm] +- **Latencia Total:** [XXX ms] +- **Tamaño Respuesta:** [XXX bytes / KB] +- **Registros Devueltos:** [N] + +--- + +## 📤 OUTPUT + +### Respuesta raw (primeros 500 caracteres): +``` +[Muestra de respuesta sin procesar] +``` + +### Estructura de datos recibida: +- **Tipo:** [JSON/XML/String] +- **Campos principales:** [lista] +- **Profundidad:** [niveles de anidamiento] + +--- + +## ✅ RESULTADO + +**Estado:** [✅ PASS / ⚠️ PARTIAL / ❌ FAIL] + +### Criterios de validación: +- [ ] Respuesta recibida sin errores +- [ ] Estructura de datos correcta +- [ ] Contenido relevante y preciso +- [ ] Performance aceptable (<2s) +- [ ] Cobertura funcional completa + +--- + +## 🔍 ANÁLISIS DETALLADO + +### Funcionalidad validada: +[Qué features se confirmaron funcionando] + +### Observaciones técnicas: +[Detalles técnicos relevantes encontrados] + +### Calidad de datos: +[Precisión, completitud, formato] + +--- + +## 💡 INSIGHTS Y APRENDIZAJES + +### Hallazgos positivos: +- [Feature destacada] +- [Comportamiento útil] + +### Limitaciones detectadas: +- [Gap o restricción encontrada] + +### Casos edge detectados: +- [Situaciones límite probadas] + +--- + +## 🐛 ERRORES Y WARNINGS + +### Errores críticos: +[Si los hubo] + +### Warnings o advertencias: +[Si los hubo] + +### Workarounds aplicados: +[Si fueron necesarios] + +--- + +## 📊 COMPARACIÓN vs boe-mcp + +### Diferencias observadas: +- [Punto de comparación 1] +- [Punto de comparación 2] + +### Ventajas de mcp-boe-consolidada: +- [Si aplica] + +### Desventajas de mcp-boe-consolidada: +- [Si aplica] + +--- + +## ✏️ RECOMENDACIONES + +### Para uso del MCP: +[Mejores prácticas descubiertas] + +### Para mejora del MCP: +[Sugerencias al desarrollador] + +### Para siguiente test: +[Qué probar en test siguiente] + +--- + +## 📎 ARCHIVOS GENERADOS + +- `input.json` - Parámetros del test +- `raw_response.json` - Respuesta completa +- `parsed_output.json` - Datos estructurados +- `screenshots/` - Capturas visuales (si aplica) + +--- + +**Conclusión:** [Resumen en 1-2 líneas del test] + +--- + +*Plantilla v1.0 - Banco Pruebas MCP-BOE-CONSOLIDADA* \ No newline at end of file diff --git a/testing_mcp_boe_consolidada/00_estructura/PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md b/testing_mcp_boe_consolidada/00_estructura/PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md new file mode 100644 index 0000000..8de17a6 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md @@ -0,0 +1,311 @@ +# 📋 BANCO DE PRUEBAS EXHAUSTIVO - MCP-BOE-CONSOLIDADA +## Sistema de Evaluación Completa y Documentación + +**Servidor MCP:** mcp-boe-consolidada (ComputingVictor) +**Score Previo:** 78.5/100 +**Fecha Inicio:** 2025-11-23T17:41:11Z +**Device:** MacBook-Air-de-Pepo.local +**Usuario:** pepo +**Objetivo:** Validación práctica exhaustiva con documentación completa + +--- + +## 🎯 ESTRUCTURA DEL BANCO DE PRUEBAS + +### **NIVELES DE EVALUACIÓN:** + +``` +NIVEL 0: INSTALACIÓN Y CONFIGURACIÓN ✓ +├── Verificación de instalación +├── Configuración claude_desktop_config.json +└── Primera conexión exitosa + +NIVEL 1: FUNCIONALIDAD BÁSICA DE API +├── Test 1.1: Búsqueda simple por texto +├── Test 1.2: Búsqueda con filtros temporales +├── Test 1.3: Búsqueda por departamento +├── Test 1.4: Búsqueda por rango normativo +└── Test 1.5: Búsqueda por materia + +NIVEL 2: RECUPERACIÓN DE DOCUMENTOS COMPLETOS +├── Test 2.1: Obtener metadatos básicos +├── Test 2.2: Obtener análisis jurídico +├── Test 2.3: Obtener texto consolidado completo +├── Test 2.4: Obtener metadatos ELI +└── Test 2.5: Obtener estructura (índice) + +NIVEL 3: NAVEGACIÓN GRANULAR +├── Test 3.1: Obtener bloque específico (artículo) +├── Test 3.2: Navegar disposiciones +├── Test 3.3: Extraer anexos +└── Test 3.4: Reconstruir documento parcial + +NIVEL 4: ANÁLISIS DE RELACIONES +├── Test 4.1: Encontrar leyes que modifican +├── Test 4.2: Encontrar leyes modificadas por +├── Test 4.3: Cadena de modificaciones +└── Test 4.4: Análisis de derogaciones + +NIVEL 5: SUMARIOS Y PUBLICACIONES +├── Test 5.1: Sumario BOE fecha específica +├── Test 5.2: Sumario BORME +├── Test 5.3: Búsqueda BOE reciente +└── Test 5.4: Resumen semanal + +NIVEL 6: TABLAS AUXILIARES Y VOCABULARIO +├── Test 6.1: Tabla de departamentos +├── Test 6.2: Tabla de rangos normativos +├── Test 6.3: Tabla de materias +├── Test 6.4: Búsqueda en datos auxiliares +└── Test 6.5: Descripción de códigos + +NIVEL 7: CASOS DE USO REALES +├── Test 7.1: Seguimiento reforma legislativa +├── Test 7.2: Análisis impacto normativo +├── Test 7.3: Investigación jurídica específica +└── Test 7.4: Construcción base conocimiento + +NIVEL 8: ESTRÉS Y LÍMITES +├── Test 8.1: Búsquedas masivas +├── Test 8.2: Documentos extensos +├── Test 8.3: Consultas complejas anidadas +└── Test 8.4: Rendimiento temporal +``` + +--- + +## 📂 ESTRUCTURA DE DIRECTORIOS + +``` +testing_mcp_boe_consolidada/ +├── 00_estructura/ +│ ├── PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md (este archivo) +│ ├── METODOLOGIA_DOCUMENTACION.md +│ └── PLANTILLAS/ +│ ├── template_test.md +│ ├── template_nivel.md +│ └── template_informe_final.md +│ +├── 01_nivel_basico/ +│ ├── test_1.1_busqueda_simple/ +│ │ ├── input.json +│ │ ├── raw_response.json +│ │ ├── parsed_output.json +│ │ ├── screenshots/ +│ │ └── ANALISIS_test_1.1.md +│ ├── test_1.2_filtro_temporal/ +│ ├── test_1.3_filtro_departamento/ +│ ├── test_1.4_filtro_rango/ +│ ├── test_1.5_filtro_materia/ +│ └── INFORME_NIVEL_1.md +│ +├── 02_nivel_documentos/ +│ ├── test_2.1_metadatos/ +│ ├── test_2.2_analisis/ +│ ├── test_2.3_texto_completo/ +│ ├── test_2.4_eli_metadata/ +│ ├── test_2.5_estructura/ +│ └── INFORME_NIVEL_2.md +│ +├── 03_nivel_navegacion/ +│ ├── test_3.1_bloque_articulo/ +│ ├── test_3.2_disposiciones/ +│ ├── test_3.3_anexos/ +│ ├── test_3.4_reconstruccion_parcial/ +│ └── INFORME_NIVEL_3.md +│ +├── 04_nivel_relaciones/ +│ ├── test_4.1_leyes_modifican/ +│ ├── test_4.2_modificadas_por/ +│ ├── test_4.3_cadena_modificaciones/ +│ ├── test_4.4_derogaciones/ +│ └── INFORME_NIVEL_4.md +│ +├── 05_nivel_sumarios/ +│ ├── test_5.1_sumario_boe/ +│ ├── test_5.2_sumario_borme/ +│ ├── test_5.3_busqueda_reciente/ +│ ├── test_5.4_resumen_semanal/ +│ └── INFORME_NIVEL_5.md +│ +├── 06_nivel_tablas/ +│ ├── test_6.1_departamentos/ +│ ├── test_6.2_rangos/ +│ ├── test_6.3_materias/ +│ ├── test_6.4_busqueda_auxiliares/ +│ ├── test_6.5_descripcion_codigos/ +│ └── INFORME_NIVEL_6.md +│ +├── 07_casos_uso_reales/ +│ ├── caso_7.1_seguimiento_reforma/ +│ ├── caso_7.2_impacto_normativo/ +│ ├── caso_7.3_investigacion_juridica/ +│ ├── caso_7.4_base_conocimiento/ +│ └── INFORME_NIVEL_7.md +│ +├── 08_estres_limites/ +│ ├── test_8.1_busquedas_masivas/ +│ ├── test_8.2_documentos_extensos/ +│ ├── test_8.3_consultas_complejas/ +│ ├── test_8.4_rendimiento/ +│ └── INFORME_NIVEL_8.md +│ +├── 99_comparativas/ +│ ├── vs_boe_mcp/ +│ │ ├── gaps_mcp_boe_consolidada.md +│ │ ├── ventajas_mcp_boe_consolidada.md +│ │ └── matriz_comparativa.md +│ └── recomendaciones_finales.md +│ +└── INFORME_FINAL_COMPLETO.md +``` + +--- + +## 📝 METODOLOGÍA DE DOCUMENTACIÓN + +### **Para cada test individual:** + +1. **input.json** - Parámetros exactos enviados +2. **raw_response.json** - Respuesta completa del servidor +3. **parsed_output.json** - Datos procesados y estructurados +4. **screenshots/** - Capturas si hay visualización +5. **ANALISIS_test_X.X.md** - Documento de análisis con: + - ✅ Resultado: PASS/FAIL/PARTIAL + - 📊 Métricas: tiempo, tamaño, complejidad + - 🔍 Observaciones técnicas + - 💡 Insights y aprendizajes + - 🐛 Errores o limitaciones detectadas + +### **Para cada nivel:** + +**INFORME_NIVEL_X.md** contendrá: +- Resumen ejecutivo del nivel +- Tests ejecutados (x/y exitosos) +- Tiempo total invertido +- Funcionalidades validadas +- Gaps detectados +- Recomendaciones para siguiente nivel + +--- + +## 🎯 CRITERIOS DE ÉXITO + +### **Test Individual:** +- ✅ PASS: Funciona correctamente según especificación +- ⚠️ PARTIAL: Funciona con limitaciones o workarounds +- ❌ FAIL: No funciona o error crítico + +### **Nivel Completo:** +- **EXCELENTE:** ≥90% tests PASS +- **BUENO:** 70-89% tests PASS +- **ACEPTABLE:** 50-69% tests PASS +- **DEFICIENTE:** <50% tests PASS + +--- + +## 📊 MÉTRICAS A CAPTURAR + +### **Por cada test:** +- Timestamp inicio y fin +- Latencia de respuesta (ms) +- Tamaño de respuesta (bytes/KB) +- Número de resultados devueltos +- Estructura de datos recibida +- Errores o warnings + +### **Por nivel:** +- Tasa de éxito (%) +- Tiempo total de ejecución +- Cobertura funcional validada +- Bugs críticos encontrados +- Features destacadas + +--- + +## 🚀 PROCESO DE EJECUCIÓN + +### **Fase 1: Preparación** +1. Verificar instalación mcp-boe-consolidada +2. Configurar claude_desktop_config.json +3. Crear estructura de directorios +4. Preparar plantillas de documentación + +### **Fase 2: Ejecución por Niveles** +Para cada nivel (1-8): +1. Ejecutar todos los tests del nivel +2. Capturar inputs, outputs y screenshots +3. Documentar cada test individualmente +4. Generar informe del nivel +5. Validar con usuario antes de continuar + +### **Fase 3: Análisis Comparativo** +1. Comparar con resultados de boe-mcp +2. Identificar gaps en ambos MCPs +3. Proponer mejoras para MCP-BOE-Ultimate + +### **Fase 4: Informe Final** +1. Consolidar todos los informes de nivel +2. Generar scoring actualizado +3. Recomendaciones finales +4. Roadmap de mejoras + +--- + +## 🔄 CONTROL DE VERSIONES + +- **v1.0** - 2025-11-23: Estructura inicial del banco de pruebas +- Cada test modificado → actualizar timestamp en ANALISIS_test_X.X.md +- Cada nivel completado → marcar en checklist progreso + +--- + +## 📌 NOTAS IMPORTANTES + +### **Diferencias clave respecto a boe-mcp:** +- mcp-boe-consolidada usa REST API oficial directamente +- Tiene soporte completo para metadatos ELI +- Incluye tablas auxiliares y vocabulario controlado +- Mejor documentación y ejemplos + +### **Ventajas esperadas:** +- Mayor estabilidad (API oficial) +- Documentación más completa +- Cobertura funcional más amplia +- Testing más exhaustivo en el repo + +### **Posibles gaps a validar:** +- Navegación granular (bloques específicos) +- Validación de consolidación +- Performance en documentos muy grandes +- Manejo de errores y edge cases + +--- + +## ✅ CHECKLIST DE PROGRESO + +### Preparación: +- [ ] Verificar instalación +- [ ] Crear estructura de directorios +- [ ] Preparar plantillas +- [ ] Validar configuración + +### Niveles de Prueba: +- [ ] Nivel 1: Funcionalidad Básica +- [ ] Nivel 2: Recuperación Documentos +- [ ] Nivel 3: Navegación Granular +- [ ] Nivel 4: Análisis Relaciones +- [ ] Nivel 5: Sumarios +- [ ] Nivel 6: Tablas Auxiliares +- [ ] Nivel 7: Casos de Uso Reales +- [ ] Nivel 8: Estrés y Límites + +### Análisis Final: +- [ ] Comparativa vs boe-mcp +- [ ] Identificación de gaps +- [ ] Scoring actualizado +- [ ] Informe final completo + +--- + +**FIN DEL DOCUMENTO DE PLANIFICACIÓN** diff --git a/testing_mcp_boe_consolidada/00_estructura/RESUMEN_VALIDACION.md b/testing_mcp_boe_consolidada/00_estructura/RESUMEN_VALIDACION.md new file mode 100644 index 0000000..81cc089 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/RESUMEN_VALIDACION.md @@ -0,0 +1,404 @@ +# 📋 RESUMEN PARA VALIDACIÓN +## Sistema de Banco de Pruebas MCP-BOE-CONSOLIDADA + +**Fecha:** 2025-11-23T17:41:11Z +**Estado:** Estructura creada - Pendiente validación +**Device:** MacBook-Air-de-Pepo.local + +--- + +## ✅ LO QUE HE CREADO + +### 📂 Estructura de Directorios: + +``` +testing_mcp_boe_consolidada/ +└── 00_estructura/ + ├── PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md ✅ + ├── METODOLOGIA_DOCUMENTACION.md ✅ + ├── RESUMEN_VALIDACION.md (este archivo) ✅ + └── PLANTILLAS/ + ├── template_test.md ✅ + ├── template_nivel.md ✅ + └── template_informe_final.md ✅ +``` + +**Total archivos creados:** 6 + +--- + +## 📄 DOCUMENTOS PRINCIPALES + +### 1️⃣ PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md + +**Contenido:** +- 📊 8 niveles de evaluación definidos (0-8) +- 🎯 Objetivos claros por nivel +- 📂 Estructura completa de directorios +- ✅ Checklist de progreso +- 📊 Criterios de evaluación +- 🔄 Control de versiones + +**Características clave:** +- Adaptado de banco de pruebas de boe-mcp +- Enfoque en mcp-boe-consolidada (REST API) +- Comparación vs boe-mcp integrada +- Score inicial: 78.5/100 (referencia) + +### 2️⃣ METODOLOGIA_DOCUMENTACION.md + +**Contenido:** +- 🎯 Objetivos del sistema de documentación +- 📂 Estructura de archivos por test +- 📝 Proceso paso a paso (12 pasos) +- 📊 Criterios de evaluación (PASS/PARTIAL/FAIL) +- 📈 Métricas obligatorias +- 🔄 Workflow de revisión +- 📎 Nomenclatura y convenciones +- ✅ Checklists de calidad +- 🚨 Manejo de casos especiales +- 📌 Mejores prácticas + +**Características clave:** +- Proceso estandarizado +- Trazabilidad completa +- Reproducibilidad garantizada +- 4 archivos por test (input, raw, parsed, análisis) + +### 3️⃣ template_test.md (Plantilla) + +**Secciones:** +- 🎯 Objetivo del test +- 📥 Input (parámetros) +- ⏱️ Métricas de ejecución +- 📤 Output (respuesta) +- ✅ Resultado (PASS/PARTIAL/FAIL) +- 🔍 Análisis detallado +- 💡 Insights y aprendizajes +- 🐛 Errores y warnings +- 📊 Comparación vs boe-mcp +- ✏️ Recomendaciones + +**Uso:** Documentar cada test individual + +### 4️⃣ template_nivel.md (Plantilla) + +**Secciones:** +- 📊 Resumen ejecutivo +- 🎯 Objetivos del nivel +- 📋 Detalle de tests +- ✅ Funcionalidades validadas +- 📊 Métricas globales +- 🔍 Análisis cualitativo +- 🐛 Bugs y limitaciones +- 💡 Insights y aprendizajes +- 📊 Comparación vs boe-mcp +- ✏️ Recomendaciones +- ✅ Conclusión y score + +**Uso:** Informe consolidado por nivel (1-8) + +### 5️⃣ template_informe_final.md (Plantilla) + +**Secciones:** +- 📊 Resumen ejecutivo global +- 🎯 Objetivos y alcance +- 📋 Resultados por nivel (8 niveles) +- 📊 Análisis global +- 🔍 Análisis comparativo completo +- 🐛 Bugs y limitaciones consolidados +- 💡 Insights generales +- 📈 Métricas consolidadas +- ✏️ Recomendaciones finales +- 🚀 Propuesta MCP-BOE-Ultimate +- 📊 Scoring final detallado +- ✅ Conclusiones + +**Uso:** Informe final del proyecto completo + +--- + +## 🎯 NIVELES DE PRUEBA DEFINIDOS + +### NIVEL 0: Instalación ✓ +- Verificación instalación +- Configuración +- Primera conexión + +### NIVEL 1: Funcionalidad Básica +- 5 tests de búsqueda +- Filtros: texto, temporal, departamento, rango, materia + +### NIVEL 2: Documentos Completos +- 5 tests de recuperación +- Metadatos, análisis, texto, ELI, estructura + +### NIVEL 3: Navegación Granular +- 4 tests de navegación +- Bloques, disposiciones, anexos, reconstrucción + +### NIVEL 4: Análisis de Relaciones +- 4 tests de relaciones +- Modifican, modificadas, cadenas, derogaciones + +### NIVEL 5: Sumarios +- 4 tests de publicaciones +- BOE, BORME, búsqueda reciente, resumen semanal + +### NIVEL 6: Tablas Auxiliares +- 5 tests de vocabulario +- Departamentos, rangos, materias, búsqueda, códigos + +### NIVEL 7: Casos de Uso Reales +- 4 casos prácticos +- Reforma, impacto, investigación, base conocimiento + +### NIVEL 8: Estrés y Límites +- 4 tests de stress +- Masivas, extensos, complejas, rendimiento + +**Total tests planificados:** ~35 tests + +--- + +## 📊 SISTEMA DE DOCUMENTACIÓN + +### Por cada test: + +``` +test_X.Y_nombre/ +├── input.json ← Parámetros del test +├── raw_response.json ← Respuesta completa del MCP +├── parsed_output.json ← Datos procesados +├── ANALISIS_test_X.Y.md ← Análisis humano completo +└── screenshots/ ← Capturas (opcional) + ├── 01_input.png + ├── 02_response.png + └── 03_comparison.png +``` + +### Por cada nivel: + +``` +0X_nivel_nombre/ +├── test_X.1_nombre/ +├── test_X.2_nombre/ +├── test_X.3_nombre/ +└── INFORME_NIVEL_X.md ← Consolidación del nivel +``` + +### Final: + +``` +├── 99_comparativas/ +│ └── vs_boe_mcp/ +│ ├── gaps_mcp_boe_consolidada.md +│ ├── ventajas_mcp_boe_consolidada.md +│ └── matriz_comparativa.md +└── INFORME_FINAL_COMPLETO.md +``` + +--- + +## 📏 CRITERIOS DE EVALUACIÓN + +### Test Individual: +- ✅ **PASS:** Funciona perfectamente (100/100) +- ⚠️ **PARTIAL:** Funciona con limitaciones (50-99/100) +- ❌ **FAIL:** No funciona o error crítico (0-49/100) + +### Nivel Completo: +- 🏆 **EXCELENTE:** ≥90% tests PASS +- 👍 **BUENO:** 70-89% tests PASS +- 🤝 **ACEPTABLE:** 50-69% tests PASS +- 👎 **DEFICIENTE:** <50% tests PASS + +### Score Final (100 puntos): +- Arquitectura y Diseño: 15 pts +- Funcionalidad: 25 pts +- Performance: 15 pts +- Documentación: 15 pts +- Estabilidad: 10 pts +- Usabilidad: 10 pts +- Testing: 5 pts +- Innovación: 5 pts + +--- + +## 🔄 PROCESO DE EJECUCIÓN + +### Fase 1: Preparación +1. Verificar instalación mcp-boe-consolidada +2. Configurar claude_desktop_config.json +3. Crear estructura de directorios ✅ +4. Preparar plantillas de documentación ✅ + +### Fase 2: Ejecución por Niveles +**Para cada nivel (1-8):** +1. Ejecutar todos los tests del nivel +2. Capturar inputs, outputs y screenshots +3. Documentar cada test individualmente +4. Generar informe del nivel +5. **Validar con usuario antes de continuar** ⚠️ + +### Fase 3: Análisis Comparativo +1. Comparar con resultados de boe-mcp +2. Identificar gaps en ambos MCPs +3. Proponer mejoras para MCP-BOE-Ultimate + +### Fase 4: Informe Final +1. Consolidar todos los informes de nivel +2. Generar scoring actualizado +3. Recomendaciones finales +4. Roadmap de mejoras + +--- + +## 🆚 DIFERENCIAS CLAVE vs boe-mcp + +### Arquitectura: +- **mcp-boe-consolidada:** REST API oficial directa +- **boe-mcp:** Python nativo con parsing + +### Ventajas esperadas de mcp-boe-consolidada: +- ✅ Mayor estabilidad (API oficial) +- ✅ Documentación más completa +- ✅ Soporte ELI completo +- ✅ Tablas auxiliares incluidas +- ✅ Testing exhaustivo en repo + +### Gaps posibles a validar: +- ❓ Navegación granular (bloques) +- ❓ Validación de consolidación +- ❓ Performance en docs grandes +- ❓ Manejo de edge cases + +--- + +## ⚠️ ADAPTACIONES vs Banco Original (boe-mcp) + +### Mantenido igual: +- ✅ Estructura de 8 niveles +- ✅ Sistema de scoring +- ✅ Metodología de documentación +- ✅ Criterios PASS/PARTIAL/FAIL +- ✅ Proceso de validación por niveles + +### Adaptado para mcp-boe-consolidada: +- 🔄 Tests específicos para REST API +- 🔄 Validación de metadatos ELI +- 🔄 Tests de tablas auxiliares (nuevo) +- 🔄 Comparación directa con boe-mcp +- 🔄 Foco en estabilidad API oficial + +### Añadido: +- ➕ Nivel 6 específico para tablas auxiliares +- ➕ Validación de vocabulario controlado +- ➕ Tests de códigos y descripciones +- ➕ Análisis de dependencia API oficial + +--- + +## 📋 CHECKLIST PARA VALIDACIÓN + +Por favor, revisa y confirma: + +### Estructura General: +- [ ] ¿La organización en 8 niveles tiene sentido? +- [ ] ¿Los ~35 tests son suficientes? +- [ ] ¿La estructura de directorios es clara? + +### Documentación: +- [ ] ¿Las plantillas cubren toda la información necesaria? +- [ ] ¿La metodología es clara y reproducible? +- [ ] ¿Los criterios de evaluación son objetivos? + +### Proceso: +- [ ] ¿El workflow de 4 fases es adecuado? +- [ ] ¿Los pasos de documentación son completos? +- [ ] ¿Las métricas a capturar son relevantes? + +### Comparación: +- [ ] ¿La comparación con boe-mcp está bien integrada? +- [ ] ¿Los gaps identificados son pertinentes? +- [ ] ¿La propuesta de MCP-Ultimate tiene sentido? + +### Casos Especiales: +- [ ] ¿El manejo de errores está contemplado? +- [ ] ¿Los timeouts tienen protocolo claro? +- [ ] ¿Los resultados inesperados tienen guía? + +--- + +## 🚀 SIGUIENTES PASOS (SI APRUEBAS) + +1. **Crear estructura de directorios completa** + - 8 directorios de nivel + - Subdirectorios para cada test + - Directorio comparativas + +2. **Verificar instalación mcp-boe-consolidada** + - Confirmar en claude_desktop_config.json + - Probar primera conexión + - Listar herramientas disponibles + +3. **Ejecutar NIVEL 1 completo** + - 5 tests de funcionalidad básica + - Documentar cada uno + - Generar informe del nivel + - Validar contigo antes de continuar + +--- + +## ❓ PREGUNTAS PARA TI + +### Sobre alcance: +1. ¿Los 8 niveles y ~35 tests son suficientes o quieres más granularidad? +2. ¿Algún caso de uso específico que añadir? +3. ¿Algún nivel que priorizar sobre otros? + +### Sobre documentación: +4. ¿Las plantillas son suficientemente detalladas? +5. ¿Falta alguna métrica crítica que capturar? +6. ¿El formato markdown es adecuado o prefieres otro? + +### Sobre proceso: +7. ¿Validación nivel por nivel es OK o prefieres otro checkpoints? +8. ¿Cuánto detalle quieres en las comparaciones con boe-mcp? +9. ¿Quieres que guarde logs de debugging también? + +### Sobre timing: +10. ¿Ejecutar los 8 niveles de una vez o en sesiones separadas? +11. ¿Algún deadline o prioridad temporal? + +--- + +## ✅ PARA APROBAR Y CONTINUAR + +**Si todo está correcto, confirma con:** +- "✅ Aprobado, continúa con NIVEL 1" +- O indica ajustes específicos que hacer + +**Si necesitas cambios:** +- Dime qué modificar específicamente +- Haré los ajustes antes de ejecutar tests + +--- + +## 📊 ESTADO ACTUAL + +``` +✅ Estructura de documentación: COMPLETA +✅ Plantillas: LISTAS +✅ Metodología: DEFINIDA +⏸️ Esperando tu VALIDACIÓN +🔜 Siguiente: Crear directorios y ejecutar NIVEL 1 +``` + +--- + +**Esperando tu feedback para continuar** 🚀 + +--- + +*Resumen de Validación v1.0 - 2025-11-23T17:41:11Z* diff --git a/testing_mcp_boe_consolidada/00_estructura/RPVEA_BOE_FRAMEWORK.md b/testing_mcp_boe_consolidada/00_estructura/RPVEA_BOE_FRAMEWORK.md new file mode 100644 index 0000000..dce2bb3 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/RPVEA_BOE_FRAMEWORK.md @@ -0,0 +1,599 @@ +# RPVEA Framework para MCP-BOE-Consolidada +## Research → Prepare → Validate → Execute → Assess + +**Versión:** 1.1 +**Fecha:** 2025-11-23 +**Adaptado de:** GVA RPVEA Framework 2.0 +**Proyecto:** MCP-BOE-Consolidada + +--- + +## 🎯 PROPÓSITO + +Este framework adapta la metodología RPVEA del proyecto GVA ArcGIS MCP para el testing y desarrollo del servidor MCP-BOE-Consolidada. La regla fundamental: + +> **"5 minutos en R (Research) ahorran 30 minutos en E/V (Execute/Validate)"** + +--- + +## 🔀 TIPOS DE TESTS: CONFORMIDAD vs CALIDAD + +### Distinción Fundamental + +El MCP-BOE puede verse desde dos perspectivas: +- **Como pass-through**: Expone la API del BOE tal cual +- **Como capa de valor añadido**: Mejora la experiencia sobre la API + +Esta distinción es crítica para definir qué es un "bug" vs qué es una "mejora potencial". + +### Tests de Conformidad (Tipo C) + +**Pregunta:** ¿El MCP expone correctamente la API del BOE? + +| Aspecto | Criterio de éxito | +|---------|-------------------| +| Parámetros | Se pasan correctamente a la API | +| Respuesta | Se parsea sin pérdida de datos | +| Errores | Se propagan adecuadamente | +| Tipos | Coinciden con schema Pydantic | + +**Resultado esperado:** La respuesta del MCP es equivalente a llamar la API directamente. + +**Si falla:** Es un **BUG** del MCP que debe corregirse. + +### Tests de Calidad (Tipo Q) + +**Pregunta:** ¿Los resultados son útiles para el usuario final? + +| Aspecto | Criterio de evaluación | +|---------|------------------------| +| Relevancia | ¿Los primeros resultados son los más relevantes? | +| Completitud | ¿Se obtiene toda la información necesaria? | +| Usabilidad | ¿Es fácil encontrar lo que se busca? | +| Performance | ¿Los tiempos son aceptables? | + +**Resultado esperado:** Documentar comportamiento actual y gaps de usabilidad. + +**Si hay gap:** Es una **MEJORA POTENCIAL** a evaluar para implementación. + +### Matriz de Clasificación + +``` +┌─────────────────────────────────────────────────────────────┐ +│ RESULTADO DEL TEST │ +├─────────────────────┬───────────────────────────────────────┤ +│ │ Conformidad (C) │ Calidad (Q) │ +├─────────────────────┼───────────────────┼───────────────────┤ +│ PASS │ ✅ Funciona bien │ ✅ Útil tal cual │ +├─────────────────────┼───────────────────┼───────────────────┤ +│ FAIL │ 🐛 BUG → Fix │ 📋 Gap → Evaluar │ +├─────────────────────┼───────────────────┼───────────────────┤ +│ Acción si falla │ Corregir código │ Documentar + │ +│ │ obligatoriamente │ decidir si mejora │ +└─────────────────────┴───────────────────┴───────────────────┘ +``` + +### Ejemplos Prácticos + +#### Test de Conformidad: +``` +Test C-1.1: Búsqueda simple +- Input: query="Ley 40/2015" +- Verificar: ¿MCP devuelve mismos resultados que API directa? +- Si difiere: BUG en parsing o paso de parámetros +``` + +#### Test de Calidad: +``` +Test Q-1.1: Relevancia de búsqueda genérica +- Input: query="protección de datos" +- Verificar: ¿LOPD aparece en top 3 resultados? +- Si no: Documentar como gap de relevancia +- Decisión: ¿Implementar ranking propio? (feature nueva) +``` + +### Flujo de Decisión Post-Test + +``` + ┌──────────────┐ + │ Ejecutar Test│ + └──────┬───────┘ + │ + ┌──────▼───────┐ + │ ¿Tipo C o Q? │ + └──────┬───────┘ + │ + ┌────────────────┴────────────────┐ + │ │ + ┌──────▼──────┐ ┌───────▼──────┐ + │ Conformidad │ │ Calidad │ + └──────┬──────┘ └───────┬──────┘ + │ │ + ┌──────▼──────┐ ┌───────▼──────┐ + │ ¿Pasó? │ │ ¿Pasó? │ + └──────┬──────┘ └───────┬──────┘ + │ │ + ┌─────┴─────┐ ┌─────┴─────┐ + │ │ │ │ +┌───▼───┐ ┌────▼────┐ ┌─────▼───┐ ┌────▼────┐ +│ ✅ │ │ 🐛 │ │ ✅ │ │ 📋 │ +│ PASS │ │ BUG │ │ PASS │ │ GAP │ +│ │ │ Fix │ │ │ │Documentar│ +│ │ │Requerido│ │ │ │ Evaluar │ +└───────┘ └─────────┘ └─────────┘ └─────────┘ +``` + +### Registro en test_registry.json + +```json +{ + "test_id": "1.1", + "type": "C", // "C" = Conformidad, "Q" = Calidad + "name": "busqueda_simple_conformidad", + "question": "¿El MCP pasa correctamente los parámetros a la API?", + "success_criteria": "Respuesta MCP == Respuesta API directa", + "if_fails": "BUG - requiere fix" +} +``` + +```json +{ + "test_id": "1.1Q", + "type": "Q", + "name": "busqueda_simple_calidad", + "question": "¿La búsqueda genérica devuelve resultados útiles?", + "success_criteria": "Ley buscada en top 3 resultados", + "if_fails": "GAP - evaluar mejora de ranking" +} +``` + +### Documentación de Gaps de Calidad + +Para cada gap identificado, crear entrada en `quality_gaps.json`: + +```json +{ + "gap_id": "GAP-001", + "discovered_in_test": "Q-1.1", + "title": "Búsquedas genéricas no priorizan por relevancia", + "description": "Buscar 'protección de datos' no devuelve LOPD en primeros resultados", + "current_behavior": "Ordenamiento por fecha de publicación", + "desired_behavior": "Ordenamiento por relevancia textual", + "impact": "medio", + "effort_estimate": "alto", + "implementation_options": [ + { + "option": "A", + "description": "Documentar como limitación de API BOE", + "effort": "bajo", + "pros": ["Sin cambios de código", "Sin mantenimiento"], + "cons": ["UX subóptima"] + }, + { + "option": "B", + "description": "Implementar re-ranking en MCP", + "effort": "alto", + "pros": ["Mejor UX"], + "cons": ["Mantenimiento", "Posible divergencia con API"] + } + ], + "decision": null, + "decision_date": null, + "decision_rationale": null +} + +--- + +## 📋 FASES RPVEA ADAPTADAS PARA BOE + +### FASE R: RESEARCH (Investigación) - 10-15 min + +**Objetivo:** Entender completamente antes de actuar. + +#### Checklist R-BOE: +- [ ] Revisar documentación API BOE para el endpoint a probar +- [ ] Verificar estructura de datos esperada +- [ ] Identificar parámetros y sus tipos +- [ ] Buscar ejemplos de respuestas en documentación +- [ ] Consultar código existente en `src/mcp_boe/` +- [ ] Revisar tests similares ya ejecutados + +#### Reglas críticas: +1. **NUNCA asumir, SIEMPRE verificar** +2. Si la API devuelve XML, entender la estructura XML antes de parsear +3. Si un campo es opcional, verificar comportamiento con/sin él + +#### Deliverables R: +- Documentación del endpoint objetivo +- Estructura de request/response esperada +- Lista de edge cases identificados + +--- + +### FASE P: PREPARE (Preparación) - 5-10 min + +**Objetivo:** Preparar todo antes de ejecutar. + +#### Checklist P-BOE: +- [ ] Crear directorio del test: `test_X.Y_nombre/` +- [ ] Preparar `input.json` con parámetros exactos +- [ ] Definir expectativas en `expected_behavior` +- [ ] Identificar normativa de referencia (BOE-A-XXXX-XXXXX) +- [ ] Verificar que el MCP server está activo + +#### Estructura input.json: +```json +{ + "test_id": "1.1", + "test_name": "busqueda_simple", + "rpvea_session": "S001", + "timestamp_prepared": "2025-11-23T17:41:11Z", + "tool": "search_consolidated_legislation", + "parameters": { + "query": "Ley 40/2015", + "limit": 5 + }, + "expected_behavior": "Debe devolver la Ley 40/2015 en los primeros resultados", + "reference_law_id": "BOE-A-2015-10566", + "triple_validation": { + "v1_schema": "pending", + "v2_api": "pending", + "v3_real": "pending" + } +} +``` + +#### Deliverables P: +- Directorio test creado +- `input.json` preparado +- Expectativas documentadas + +--- + +### FASE V: VALIDATE (Validación) - 5-15 min + +**Objetivo:** Triple Validación antes de código en producción. + +#### TRIPLE VALIDACIÓN BOE: + +##### V1: Validación de Schema (Pydantic) +**¿Qué valida?** Estructura de datos del modelo +**Cómo validar:** +```python +# Verificar modelos en src/mcp_boe/models/boe_models.py +# Comprobar campos requeridos y opcionales +# Validar tipos de datos +``` +**Resultado:** ✅ Schema válido / ❌ Schema con errores + +##### V2: Validación de API (Endpoint) +**¿Qué valida?** Respuesta real de la API del BOE +**Cómo validar:** +```bash +# Probar endpoint directamente +curl "https://www.boe.es/datosabiertos/api/legislacion-consolidada?query=Ley%2040/2015" +``` +**Resultado:** ✅ API responde correctamente / ❌ Error de API + +##### V3: Validación Real (Query Test) +**¿Qué valida?** Comportamiento real con datos reales +**Cómo validar:** +- Ejecutar herramienta MCP con parámetros reales +- Verificar que los datos devueltos son correctos y relevantes +- Comparar con expectativas definidas en P + +**Resultado:** ✅ Test PASS / ⚠️ PARTIAL / ❌ FAIL + +#### Matriz de decisión: +| V1 | V2 | V3 | Acción | +|----|----|----|--------| +| ✅ | ✅ | ✅ | Proceder con confianza | +| ✅ | ✅ | ❌ | Investigar discrepancia en datos | +| ✅ | ❌ | - | Bug en integración API | +| ❌ | - | - | Fix modelo Pydantic primero | + +#### Deliverables V: +- Resultado V1, V2, V3 documentado +- Decisión de proceder o no + +--- + +### FASE E: EXECUTE (Ejecución) - 15-30 min + +**Objetivo:** Ejecutar tests de forma sistemática. + +#### Checklist E-BOE: +- [ ] Capturar timestamp inicio +- [ ] Ejecutar herramienta MCP +- [ ] Capturar respuesta completa en `raw_response.json` +- [ ] Calcular latencia +- [ ] Procesar datos en `parsed_output.json` +- [ ] Capturar timestamp fin + +#### Proceso de ejecución: +1. **Pre-flight check:** + - ¿V1, V2, V3 pasaron? Si no, no ejecutar. + - ¿Parámetros correctos en input.json? + +2. **Ejecución:** + - Usar la herramienta MCP apropiada + - Observar comportamiento + - Capturar TODA la respuesta + +3. **Post-ejecución:** + - Guardar raw_response.json + - Procesar en parsed_output.json + - Calcular métricas + +#### Deliverables E: +- `raw_response.json` completo +- `parsed_output.json` procesado +- Métricas básicas calculadas + +--- + +### FASE A: ASSESS (Evaluación) - 10-15 min + +**Objetivo:** Evaluar resultados y documentar aprendizajes. + +#### Checklist A-BOE: +- [ ] Determinar resultado: PASS / PARTIAL / FAIL +- [ ] Calcular métricas de calidad +- [ ] Identificar errores o bugs +- [ ] Documentar insights y lecciones +- [ ] Comparar con expectativas +- [ ] Proponer mejoras si aplica +- [ ] Actualizar TEST_REGISTRY.json + +#### Documento ANALISIS_test_X.X.md: +```markdown +# ANÁLISIS TEST X.X - [Nombre] + +## RPVEA Session: SXXX +## Fecha: YYYY-MM-DD + +### Triple Validación +- V1 (Schema): ✅/❌ +- V2 (API): ✅/❌ +- V3 (Real): ✅/❌ + +### Resultado: PASS/PARTIAL/FAIL + +### Métricas +- Latencia: XXX ms +- Tamaño respuesta: XX KB +- Relevancia: X.XX + +### Lecciones Aprendidas +- [Lección 1] +- [Lección 2] + +### Errores Detectados +- [Error 1] - Severidad: [baja/media/alta/crítica] + +### Recomendaciones +- [Recomendación 1] +``` + +#### Deliverables A: +- `ANALISIS_test_X.X.md` completo +- TEST_REGISTRY.json actualizado +- Lecciones documentadas + +--- + +## 📊 TEST REGISTRY SYSTEM + +### Estructura test_registry.json: + +```json +{ + "version": "1.0", + "project": "mcp-boe-consolidada", + "last_updated": "2025-11-23T17:41:11Z", + "tests": { + "1.1": { + "name": "busqueda_simple", + "level": 1, + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1": null, + "v2": null, + "v3": null + }, + "baseline": { + "latency_ms": null, + "relevance": null + } + } + }, + "statistics": { + "total": 0, + "pass": 0, + "partial": 0, + "fail": 0, + "pending": 0 + } +} +``` + +### Workflow de registro: + +1. **Pre-cambio:** Registrar baseline actual +2. **Post-cambio:** Ejecutar regression tests +3. **Comparar:** Detectar regresiones +4. **Documentar:** Actualizar registry + +--- + +## 🔄 SESSION DOCUMENTATION + +### Formato SESSION_XX.md: + +```markdown +# SESSION XX - [Título descriptivo] +## Fecha: YYYY-MM-DD +## RPVEA Phase: [R/P/V/E/A] + +### Objetivo de la sesión +[Descripción breve] + +### Tests ejecutados +| Test ID | Nombre | Resultado | Duración | +|---------|--------|-----------|----------| +| 1.1 | busqueda_simple | PASS | 5 min | + +### Bugs encontrados +- [BUG-001] APIError hereda de BaseModel en lugar de Exception + +### Lecciones aprendidas +1. **[Categoría]:** [Lección] + +### Próximos pasos +- [ ] Tarea 1 +- [ ] Tarea 2 +``` + +--- + +## ⚠️ REGLAS CRÍTICAS RPVEA-BOE + +### NUNCA: +1. ❌ Ejecutar tests sin completar R y P +2. ❌ Modificar código sin Triple Validación +3. ❌ Asumir que la API devuelve lo esperado +4. ❌ Ignorar errores "menores" - documentar TODO +5. ❌ Saltarse la fase A (assessment) + +### SIEMPRE: +1. ✅ Investigar antes de ejecutar +2. ✅ Validar schema, API, y real query +3. ✅ Documentar cada test completamente +4. ✅ Actualizar test registry después de cada test +5. ✅ Capturar lecciones aprendidas + +### SI ENCUENTRAS UN BUG: +1. **STOP** - No continuar con más tests +2. **DOCUMENT** - Registrar el bug detalladamente +3. **ASSESS** - ¿Es bloqueante para otros tests? +4. **DECIDE** - ¿Fix inmediato o continuar documentando? +5. **TRACK** - Agregar a lista de bugs pendientes + +--- + +## 📈 INTEGRACIÓN CON CI/CD + +### Pre-commit hooks: +- Validar que test_registry.json está actualizado +- Verificar formato de documentación + +### GitHub Actions: +- Ejecutar regression tests en PR +- Comparar con baseline +- Alertar si hay regresiones + +### Scripts de soporte: +```bash +# Registrar nuevo test +python scripts/register_test.py --id 1.1 --name busqueda_simple + +# Ejecutar regression tests +python scripts/run_regression.py --level 1 + +# Generar informe de nivel +python scripts/generate_report.py --level 1 +``` + +--- + +## 📂 ESTRUCTURA DE DIRECTORIOS ACTUALIZADA + +``` +testing_mcp_boe_consolidada/ +├── 00_estructura/ +│ ├── PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md +│ ├── METODOLOGIA_DOCUMENTACION.md +│ ├── RPVEA_BOE_FRAMEWORK.md (este archivo) +│ ├── test_registry.json +│ ├── test_history.json +│ └── PLANTILLAS/ +│ ├── template_test.md +│ ├── template_nivel.md +│ ├── template_session.md +│ └── template_informe_final.md +│ +├── sessions/ +│ ├── SESSION_001.md +│ ├── SESSION_002.md +│ └── ... +│ +├── 01_nivel_basico/ +│ ├── test_1.1_busqueda_simple/ +│ │ ├── input.json +│ │ ├── raw_response.json +│ │ ├── parsed_output.json +│ │ └── ANALISIS_test_1.1.md +│ └── INFORME_NIVEL_1.md +│ +├── ... (niveles 02-08) +│ +└── bugs/ + ├── BUG-001_apierror_inheritance.md + └── ... +``` + +--- + +## 🚀 QUICK START + +### Para iniciar una sesión de testing: + +1. **Research (5 min):** + ```bash + # Leer documentación del endpoint + # Revisar código existente + ``` + +2. **Prepare (3 min):** + ```bash + mkdir -p 01_nivel_basico/test_1.1_busqueda_simple + # Crear input.json + ``` + +3. **Validate (5 min):** + ```bash + # V1: Revisar modelo Pydantic + # V2: Probar API directamente + # V3: Preparar query real + ``` + +4. **Execute (5 min):** + ```bash + # Ejecutar herramienta MCP + # Capturar respuesta + ``` + +5. **Assess (5 min):** + ```bash + # Documentar resultado + # Actualizar registry + ``` + +--- + +## 📝 CHANGELOG + +| Versión | Fecha | Cambios | +|---------|-------|---------| +| 1.0 | 2025-11-23 | Versión inicial adaptada de GVA RPVEA | +| 1.1 | 2025-11-23 | Añadida distinción Tests Conformidad (C) vs Calidad (Q) | + +--- + +**FIN DEL FRAMEWORK RPVEA-BOE** + +*"Prototype First, Code Second"* +*"Bug ≠ Gap: Conformidad es obligatorio, Calidad es decisión"* diff --git a/testing_mcp_boe_consolidada/00_estructura/quality_gaps.json b/testing_mcp_boe_consolidada/00_estructura/quality_gaps.json new file mode 100644 index 0000000..b7e4130 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/quality_gaps.json @@ -0,0 +1,24 @@ +{ + "version": "1.0", + "project": "mcp-boe-consolidada", + "description": "Registro de gaps de calidad identificados durante testing exploratorio", + "created": "2025-11-23", + "last_updated": "2025-11-23", + "gaps": {}, + "statistics": { + "total": 0, + "by_impact": { + "alto": 0, + "medio": 0, + "bajo": 0 + }, + "by_status": { + "open": 0, + "evaluating": 0, + "accepted": 0, + "rejected": 0, + "implemented": 0 + } + }, + "decision_log": [] +} diff --git a/testing_mcp_boe_consolidada/00_estructura/test_registry.json b/testing_mcp_boe_consolidada/00_estructura/test_registry.json new file mode 100644 index 0000000..5a9ddb2 --- /dev/null +++ b/testing_mcp_boe_consolidada/00_estructura/test_registry.json @@ -0,0 +1,344 @@ +{ + "version": "1.1", + "project": "mcp-boe-consolidada", + "framework": "RPVEA-BOE", + "created": "2025-11-23T17:41:11Z", + "last_updated": "2025-11-23T19:00:00Z", + "test_types": { + "C": "Conformidad - ¿El MCP expone correctamente la API?", + "Q": "Calidad - ¿Los resultados son útiles para el usuario?" + }, + "tests": { + "C-1.1": { + "type": "C", + "name": "busqueda_simple_conformidad", + "description": "Verificar que búsqueda simple pasa parámetros correctamente a API", + "question": "¿El MCP devuelve los mismos resultados que la API directa?", + "success_criteria": "Respuesta MCP equivalente a respuesta API BOE directa", + "if_fails": "BUG - requiere fix en paso de parámetros o parsing", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "result_count": null + } + }, + "Q-1.1": { + "type": "Q", + "name": "busqueda_simple_calidad", + "description": "Evaluar relevancia de resultados en búsqueda genérica", + "question": "¿Búsqueda genérica devuelve resultados útiles/relevantes?", + "success_criteria": "Ley más relevante aparece en top 3 resultados", + "if_fails": "GAP - evaluar mejora de ranking (feature nueva)", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "quality_metrics": { + "relevance_score": null, + "position_expected_result": null, + "user_effort_to_find": null + } + }, + "C-1.2": { + "type": "C", + "name": "filtro_temporal_conformidad", + "description": "Verificar que filtros de fecha se aplican correctamente", + "question": "¿Los parámetros from_date/to_date filtran correctamente?", + "success_criteria": "Solo resultados dentro del rango de fechas", + "if_fails": "BUG - filtro de fechas no funciona", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "result_count": null + } + }, + "C-1.3": { + "type": "C", + "name": "filtro_departamento_conformidad", + "description": "Verificar que filtro de departamento funciona", + "question": "¿El parámetro department_code filtra correctamente?", + "success_criteria": "Solo resultados del departamento especificado", + "if_fails": "BUG - filtro de departamento no funciona", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "result_count": null + } + }, + "C-1.4": { + "type": "C", + "name": "filtro_rango_conformidad", + "description": "Verificar que filtro de rango normativo funciona", + "question": "¿El parámetro legal_range_code filtra correctamente?", + "success_criteria": "Solo resultados del rango especificado (Ley, RD, etc.)", + "if_fails": "BUG - filtro de rango no funciona", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "result_count": null + } + }, + "C-1.5": { + "type": "C", + "name": "filtro_materia_conformidad", + "description": "Verificar que filtro de materia funciona", + "question": "¿El parámetro matter_code filtra correctamente?", + "success_criteria": "Solo resultados de la materia especificada", + "if_fails": "BUG - filtro de materia no funciona", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "result_count": null + } + }, + "Q-1.2": { + "type": "Q", + "name": "busqueda_especifica_calidad", + "description": "Evaluar si búsqueda específica encuentra la ley exacta", + "question": "¿Buscar 'Ley 40/2015' devuelve BOE-A-2015-10566 primero?", + "success_criteria": "Ley específica en posición 1", + "if_fails": "GAP - evaluar si necesita mejora en matching exacto", + "level": 1, + "tool": "search_consolidated_legislation", + "status": "pending", + "rpvea_session": null, + "last_run": null, + "result": null, + "quality_metrics": { + "exact_match_found": null, + "position_of_match": null + } + }, + "C-2.1": { + "type": "C", + "name": "metadatos_basicos_conformidad", + "description": "Verificar obtención de metadatos básicos", + "question": "¿get_consolidated_law devuelve metadatos correctamente?", + "success_criteria": "Metadatos completos y parseados sin errores", + "if_fails": "BUG - error en obtención/parsing de metadatos", + "level": 2, + "tool": "get_consolidated_law", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "fields_returned": null + } + }, + "Q-2.1": { + "type": "Q", + "name": "metadatos_completitud_calidad", + "description": "Evaluar completitud de metadatos devueltos", + "question": "¿Los metadatos incluyen toda la info útil para el usuario?", + "success_criteria": "Campos clave presentes: título, fecha, estado, departamento", + "if_fails": "GAP - evaluar añadir campos adicionales", + "level": 2, + "tool": "get_consolidated_law", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "quality_metrics": { + "fields_present": null, + "fields_missing": null, + "completeness_score": null + } + }, + "C-2.2": { + "type": "C", + "name": "analisis_juridico_conformidad", + "description": "Verificar obtención de análisis jurídico", + "question": "¿include_analysis=true devuelve análisis correctamente?", + "success_criteria": "Análisis jurídico presente y parseado", + "if_fails": "BUG - error en obtención de análisis", + "level": 2, + "tool": "get_consolidated_law", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null + } + }, + "C-2.3": { + "type": "C", + "name": "texto_completo_conformidad", + "description": "Verificar obtención de texto consolidado", + "question": "¿include_full_text=true devuelve texto completo?", + "success_criteria": "Texto consolidado presente y legible", + "if_fails": "BUG - error en obtención de texto", + "level": 2, + "tool": "get_consolidated_law", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "size_kb": null + } + }, + "C-2.4": { + "type": "C", + "name": "eli_metadata_conformidad", + "description": "Verificar obtención de metadatos ELI", + "question": "¿include_eli_metadata=true devuelve datos ELI?", + "success_criteria": "Metadatos ELI presentes según estándar europeo", + "if_fails": "BUG - error en obtención de ELI", + "level": 2, + "tool": "get_consolidated_law", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null + } + }, + "C-2.5": { + "type": "C", + "name": "estructura_indice_conformidad", + "description": "Verificar obtención de estructura/índice", + "question": "¿get_law_structure devuelve índice de bloques?", + "success_criteria": "Estructura jerárquica de la norma devuelta", + "if_fails": "BUG - error en obtención de estructura", + "level": 2, + "tool": "get_law_structure", + "status": "blocked", + "blocked_by": "BUG-001", + "rpvea_session": null, + "last_run": null, + "result": null, + "triple_validation": { + "v1_schema": null, + "v2_api": null, + "v3_real": null + }, + "baseline": { + "latency_ms": null, + "block_count": null + } + } + }, + "bugs": { + "BUG-001": { + "title": "APIError hereda de BaseModel en lugar de Exception", + "severity": "critical", + "status": "open", + "file": "src/mcp_boe/models/boe_models.py", + "line": 463, + "discovered_in_session": "S001", + "discovered_date": "2025-11-23", + "blocks_tests": ["C-2.1", "Q-2.1", "C-2.2", "C-2.3", "C-2.4", "C-2.5"] + } + }, + "statistics": { + "total_tests": 14, + "by_type": { + "conformidad": 10, + "calidad": 4 + }, + "by_status": { + "pass": 0, + "partial": 0, + "fail": 0, + "pending": 8, + "blocked": 6 + }, + "by_level": { + "1": {"total": 7, "conformidad": 5, "calidad": 2, "completed": 0}, + "2": {"total": 7, "conformidad": 5, "calidad": 2, "completed": 0} + }, + "bugs": { + "total": 1, + "open": 1, + "fixed": 0, + "critical": 1 + }, + "quality_gaps": { + "total": 0, + "open": 0, + "evaluating": 0 + } + } +} diff --git a/testing_mcp_boe_consolidada/01_nivel_basico/.gitkeep b/testing_mcp_boe_consolidada/01_nivel_basico/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/02_nivel_documentos/.gitkeep b/testing_mcp_boe_consolidada/02_nivel_documentos/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/03_nivel_navegacion/.gitkeep b/testing_mcp_boe_consolidada/03_nivel_navegacion/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/04_nivel_relaciones/.gitkeep b/testing_mcp_boe_consolidada/04_nivel_relaciones/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/05_nivel_sumarios/.gitkeep b/testing_mcp_boe_consolidada/05_nivel_sumarios/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/06_nivel_tablas/.gitkeep b/testing_mcp_boe_consolidada/06_nivel_tablas/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/07_casos_uso_reales/.gitkeep b/testing_mcp_boe_consolidada/07_casos_uso_reales/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/08_estres_limites/.gitkeep b/testing_mcp_boe_consolidada/08_estres_limites/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/testing_mcp_boe_consolidada/README.md b/testing_mcp_boe_consolidada/README.md new file mode 100644 index 0000000..b0d60ce --- /dev/null +++ b/testing_mcp_boe_consolidada/README.md @@ -0,0 +1,355 @@ +# 🧪 BANCO DE PRUEBAS MCP-BOE-CONSOLIDADA + +**Proyecto:** Evaluación Exhaustiva del MCP mcp-boe-consolidada +**Fecha Inicio:** 2025-11-23 +**Ubicación:** `/Users/pepo/Dev/MCP-BOE-consolidada/testing_mcp_boe_consolidada/` +**Device:** MacBook-Air-de-Pepo.local +**Usuario:** pepo + +--- + +## 📂 ESTRUCTURA DEL PROYECTO + +``` +testing_mcp_boe_consolidada/ +│ +├── README.md (este archivo) +│ +├── 00_estructura/ # Documentación y plantillas +│ ├── PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md +│ ├── METODOLOGIA_DOCUMENTACION.md +│ ├── RESUMEN_VALIDACION.md +│ └── PLANTILLAS/ +│ ├── template_test.md +│ ├── template_nivel.md +│ └── template_informe_final.md +│ +├── 01_nivel_basico/ # Funcionalidad básica de búsqueda +│ └── [5 tests de búsqueda y filtrado] +│ +├── 02_nivel_documentos/ # Recuperación de documentos +│ └── [5 tests de metadatos, análisis, texto completo, ELI] +│ +├── 03_nivel_navegacion/ # Navegación granular +│ └── [4 tests de bloques, disposiciones, anexos] +│ +├── 04_nivel_relaciones/ # Análisis de relaciones +│ └── [4 tests de modificaciones, derogaciones, cadenas] +│ +├── 05_nivel_sumarios/ # Sumarios y publicaciones +│ └── [4 tests de BOE, BORME, búsquedas recientes] +│ +├── 06_nivel_tablas/ # Tablas auxiliares y vocabulario +│ └── [5 tests de departamentos, rangos, materias, códigos] +│ +├── 07_casos_uso_reales/ # Casos de uso prácticos +│ └── [4 casos: reforma, impacto, investigación, base conocimiento] +│ +├── 08_estres_limites/ # Pruebas de rendimiento +│ └── [4 tests de stress: masivas, extensos, complejos] +│ +├── 99_comparativas/ # Análisis comparativo +│ └── vs_boe_mcp/ +│ ├── gaps_mcp_boe_consolidada.md +│ ├── ventajas_mcp_boe_consolidada.md +│ └── matriz_comparativa.md +│ +└── INFORME_FINAL_COMPLETO.md # Informe final consolidado +``` + +--- + +## 🎯 NIVELES DE EVALUACIÓN + +### ✅ NIVEL 0: Instalación y Configuración +- Estado: **COMPLETADO** +- Configuración verificada +- Primera conexión exitosa + +### 🔜 NIVEL 1: Funcionalidad Básica (5 tests) +- Test 1.1: Búsqueda simple por texto +- Test 1.2: Búsqueda con filtros temporales +- Test 1.3: Búsqueda por departamento +- Test 1.4: Búsqueda por rango normativo +- Test 1.5: Búsqueda por materia + +### ⏸️ NIVEL 2: Recuperación de Documentos (5 tests) +- Test 2.1: Obtener metadatos básicos +- Test 2.2: Obtener análisis jurídico +- Test 2.3: Obtener texto consolidado completo +- Test 2.4: Obtener metadatos ELI +- Test 2.5: Obtener estructura (índice) + +### ⏸️ NIVEL 3: Navegación Granular (4 tests) +- Test 3.1: Obtener bloque específico (artículo) +- Test 3.2: Navegar disposiciones +- Test 3.3: Extraer anexos +- Test 3.4: Reconstruir documento parcial + +### ⏸️ NIVEL 4: Análisis de Relaciones (4 tests) +- Test 4.1: Encontrar leyes que modifican +- Test 4.2: Encontrar leyes modificadas por +- Test 4.3: Cadena de modificaciones +- Test 4.4: Análisis de derogaciones + +### ⏸️ NIVEL 5: Sumarios y Publicaciones (4 tests) +- Test 5.1: Sumario BOE fecha específica +- Test 5.2: Sumario BORME +- Test 5.3: Búsqueda BOE reciente +- Test 5.4: Resumen semanal + +### ⏸️ NIVEL 6: Tablas Auxiliares (5 tests) +- Test 6.1: Tabla de departamentos +- Test 6.2: Tabla de rangos normativos +- Test 6.3: Tabla de materias +- Test 6.4: Búsqueda en datos auxiliares +- Test 6.5: Descripción de códigos + +### ⏸️ NIVEL 7: Casos de Uso Reales (4 casos) +- Caso 7.1: Seguimiento reforma legislativa +- Caso 7.2: Análisis impacto normativo +- Caso 7.3: Investigación jurídica específica +- Caso 7.4: Construcción base conocimiento + +### ⏸️ NIVEL 8: Estrés y Límites (4 tests) +- Test 8.1: Búsquedas masivas +- Test 8.2: Documentos extensos +- Test 8.3: Consultas complejas anidadas +- Test 8.4: Rendimiento temporal + +--- + +## 📊 PROGRESO DEL PROYECTO + +### Estado General: +- **Niveles Completados:** 0/8 +- **Tests Ejecutados:** 0/35 +- **Tasa de Éxito:** N/A +- **Tiempo Invertido:** 0h + +### Score Actual: +- **mcp-boe-consolidada:** Por determinar +- **Referencia boe-mcp:** 67.5/100 +- **Referencia inicial mcp-boe-consolidada (análisis previo):** 78.5/100 + +--- + +## 🚀 INICIO RÁPIDO + +### 1. Consultar la documentación: +```bash +cd 00_estructura +cat PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md +cat METODOLOGIA_DOCUMENTACION.md +``` + +### 2. Revisar plantillas: +```bash +cd 00_estructura/PLANTILLAS +ls -la +``` + +### 3. Iniciar NIVEL 1: +```bash +cd ../01_nivel_basico +# Esperar a que se ejecuten los tests +``` + +--- + +## 📖 DOCUMENTACIÓN CLAVE + +### 📋 Plan General: +**`00_estructura/PLAN_BANCO_PRUEBAS_MCP_BOE_CONSOLIDADA.md`** +- Descripción completa del banco de pruebas +- 8 niveles definidos +- Criterios de éxito +- Checklist de progreso + +### 📝 Metodología: +**`00_estructura/METODOLOGIA_DOCUMENTACION.md`** +- Proceso paso a paso (12 pasos) +- Sistema de archivos por test +- Métricas obligatorias +- Criterios de evaluación +- Checklists de calidad + +### ✅ Validación: +**`00_estructura/RESUMEN_VALIDACION.md`** +- Resumen ejecutivo +- Preguntas clave +- Checklist de validación +- Próximos pasos + +### 🎨 Plantillas: +**`00_estructura/PLANTILLAS/`** +- `template_test.md` - Para cada test individual +- `template_nivel.md` - Para informe de nivel +- `template_informe_final.md` - Para informe final + +--- + +## 📊 SISTEMA DE DOCUMENTACIÓN + +### Por cada test se generan 4 archivos: + +``` +test_X.Y_nombre/ +├── input.json # Parámetros exactos del test +├── raw_response.json # Respuesta completa del MCP +├── parsed_output.json # Datos procesados y métricas +├── ANALISIS_test_X.Y.md # Análisis humano completo +└── screenshots/ # Capturas visuales (opcional) +``` + +### Métricas capturadas automáticamente: +- ⏱️ Timestamps (inicio/fin) +- 📊 Latencia (ms) +- 💾 Tamaño de respuesta (bytes/KB) +- 🎯 Número de resultados +- ✅ Resultado: PASS/PARTIAL/FAIL +- 📈 Scores de calidad (relevancia, completitud, precisión) + +--- + +## 🆚 COMPARACIÓN vs boe-mcp + +### Objetivo: +Identificar fortalezas y debilidades de ambos MCPs para proponer un **MCP-BOE-Ultimate** híbrido. + +### Dimensiones de comparación: +- Arquitectura y diseño +- Funcionalidad y cobertura API +- Performance y latencia +- Documentación +- Estabilidad y manejo de errores +- Usabilidad +- Features únicos + +### Archivos de comparativa: +- `99_comparativas/vs_boe_mcp/gaps_mcp_boe_consolidada.md` +- `99_comparativas/vs_boe_mcp/ventajas_mcp_boe_consolidada.md` +- `99_comparativas/vs_boe_mcp/matriz_comparativa.md` + +--- + +## 🎯 CRITERIOS DE ÉXITO + +### Test Individual: +- ✅ **PASS (100 pts):** Funciona perfectamente según especificación +- ⚠️ **PARTIAL (50-99 pts):** Funciona con limitaciones o workarounds +- ❌ **FAIL (0-49 pts):** No funciona o error crítico + +### Nivel Completo: +- 🏆 **EXCELENTE:** ≥90% tests PASS +- 👍 **BUENO:** 70-89% tests PASS +- 🤝 **ACEPTABLE:** 50-69% tests PASS +- 👎 **DEFICIENTE:** <50% tests PASS + +### Score Final (sobre 100): +- Arquitectura y Diseño: 15 pts +- Funcionalidad: 25 pts +- Performance: 15 pts +- Documentación: 15 pts +- Estabilidad: 10 pts +- Usabilidad: 10 pts +- Testing: 5 pts +- Innovación: 5 pts + +--- + +## 🔄 PROCESO DE EJECUCIÓN + +### Fase 1: Preparación ✅ +- ✅ Estructura de directorios creada +- ✅ Plantillas preparadas +- ✅ Metodología definida +- ✅ Documentación completa + +### Fase 2: Ejecución por Niveles 🔜 +**Para cada nivel (1-8):** +1. Ejecutar todos los tests del nivel +2. Capturar inputs, outputs y métricas +3. Documentar cada test individualmente +4. Generar informe del nivel +5. Validar con usuario antes de continuar + +### Fase 3: Análisis Comparativo ⏸️ +1. Comparar con resultados de boe-mcp +2. Identificar gaps en ambos MCPs +3. Identificar ventajas de cada uno +4. Crear matriz comparativa + +### Fase 4: Informe Final ⏸️ +1. Consolidar todos los informes de nivel +2. Generar scoring actualizado +3. Recomendaciones finales +4. Propuesta MCP-BOE-Ultimate +5. Roadmap de mejoras + +--- + +## 📌 NOTAS IMPORTANTES + +### Diferencias clave vs boe-mcp: +- **Arquitectura:** REST API oficial vs Python nativo +- **ELI Support:** Completo vs Limitado +- **Tablas auxiliares:** Incluidas vs No disponibles +- **Documentación:** Exhaustiva vs Básica +- **Testing:** Completo en repo vs Minimal + +### Ventajas esperadas de mcp-boe-consolidada: +- Mayor estabilidad (API oficial) +- Soporte ELI completo +- Vocabulario controlado incluido +- Mejor documentación +- Testing más exhaustivo + +### Gaps posibles a validar: +- Navegación granular (bloques específicos) +- Validación de consolidación +- Performance en documentos grandes +- Manejo de edge cases +- Features de parsing avanzado + +--- + +## 🤝 CONTRIBUCIONES + +### Desarrollador: +- **ComputingVictor** - mcp-boe-consolidada +- Repositorio: https://github.com/ComputingVictor/mcp-boe-consolidada + +### Evaluador: +- **pepo** - Banco de pruebas exhaustivo +- Device: MacBook-Air-de-Pepo.local +- Fecha: 2025-11-23 + +--- + +## 📞 CONTACTO Y FEEDBACK + +Para reportar bugs, sugerir mejoras o contribuir: +1. Documentar en el test correspondiente +2. Incluir en informe de nivel +3. Consolidar en informe final +4. Reportar al desarrollador si es crítico + +--- + +## 📜 LICENCIA Y CRÉDITOS + +Este banco de pruebas es una herramienta de evaluación independiente basada en: +- Metodología adaptada del banco de pruebas de boe-mcp +- Análisis previo comparativo de ambos MCPs +- Documentación oficial de la API del BOE + +--- + +**Estado:** Preparado para comenzar NIVEL 1 +**Última actualización:** 2025-11-23T17:53:11Z +**Versión:** 1.0 + +--- + +**🚀 ¡Listo para comenzar la evaluación exhaustiva!** diff --git a/testing_mcp_boe_consolidada/TRACKING_PROGRESO.md b/testing_mcp_boe_consolidada/TRACKING_PROGRESO.md new file mode 100644 index 0000000..d0b508b --- /dev/null +++ b/testing_mcp_boe_consolidada/TRACKING_PROGRESO.md @@ -0,0 +1,224 @@ +# 📊 TRACKING DE PROGRESO +## Banco de Pruebas MCP-BOE-CONSOLIDADA + +**Última actualización:** 2025-11-23T17:53:11Z +**Device:** MacBook-Air-de-Pepo.local + +--- + +## ✅ FASE 1: PREPARACIÓN - COMPLETADA + +### Checklist: +- [x] Estructura de directorios creada +- [x] Documentación preparada +- [x] Plantillas listas +- [x] Metodología definida +- [x] README creado +- [x] Ubicación establecida: `/Users/pepo/Dev/MCP-BOE-consolidada/testing_mcp_boe_consolidada/` + +**Fecha completada:** 2025-11-23 +**Tiempo invertido:** ~1 hora + +--- + +## 🔜 FASE 2: EJECUCIÓN POR NIVELES + +### NIVEL 1: Funcionalidad Básica +**Estado:** ⏸️ Pendiente +**Tests planificados:** 5 +**Tests completados:** 0/5 + +- [ ] Test 1.1: Búsqueda simple por texto +- [ ] Test 1.2: Búsqueda con filtros temporales +- [ ] Test 1.3: Búsqueda por departamento +- [ ] Test 1.4: Búsqueda por rango normativo +- [ ] Test 1.5: Búsqueda por materia + +**Informe generado:** ❌ + +--- + +### NIVEL 2: Recuperación de Documentos +**Estado:** ⏸️ Pendiente +**Tests planificados:** 5 +**Tests completados:** 0/5 + +- [ ] Test 2.1: Obtener metadatos básicos +- [ ] Test 2.2: Obtener análisis jurídico +- [ ] Test 2.3: Obtener texto consolidado completo +- [ ] Test 2.4: Obtener metadatos ELI +- [ ] Test 2.5: Obtener estructura (índice) + +**Informe generado:** ❌ + +--- + +### NIVEL 3: Navegación Granular +**Estado:** ⏸️ Pendiente +**Tests planificados:** 4 +**Tests completados:** 0/4 + +- [ ] Test 3.1: Obtener bloque específico (artículo) +- [ ] Test 3.2: Navegar disposiciones +- [ ] Test 3.3: Extraer anexos +- [ ] Test 3.4: Reconstruir documento parcial + +**Informe generado:** ❌ + +--- + +### NIVEL 4: Análisis de Relaciones +**Estado:** ⏸️ Pendiente +**Tests planificados:** 4 +**Tests completados:** 0/4 + +- [ ] Test 4.1: Encontrar leyes que modifican +- [ ] Test 4.2: Encontrar leyes modificadas por +- [ ] Test 4.3: Cadena de modificaciones +- [ ] Test 4.4: Análisis de derogaciones + +**Informe generado:** ❌ + +--- + +### NIVEL 5: Sumarios y Publicaciones +**Estado:** ⏸️ Pendiente +**Tests planificados:** 4 +**Tests completados:** 0/4 + +- [ ] Test 5.1: Sumario BOE fecha específica +- [ ] Test 5.2: Sumario BORME +- [ ] Test 5.3: Búsqueda BOE reciente +- [ ] Test 5.4: Resumen semanal + +**Informe generado:** ❌ + +--- + +### NIVEL 6: Tablas Auxiliares +**Estado:** ⏸️ Pendiente +**Tests planificados:** 5 +**Tests completados:** 0/5 + +- [ ] Test 6.1: Tabla de departamentos +- [ ] Test 6.2: Tabla de rangos normativos +- [ ] Test 6.3: Tabla de materias +- [ ] Test 6.4: Búsqueda en datos auxiliares +- [ ] Test 6.5: Descripción de códigos + +**Informe generado:** ❌ + +--- + +### NIVEL 7: Casos de Uso Reales +**Estado:** ⏸️ Pendiente +**Tests planificados:** 4 +**Tests completados:** 0/4 + +- [ ] Caso 7.1: Seguimiento reforma legislativa +- [ ] Caso 7.2: Análisis impacto normativo +- [ ] Caso 7.3: Investigación jurídica específica +- [ ] Caso 7.4: Construcción base conocimiento + +**Informe generado:** ❌ + +--- + +### NIVEL 8: Estrés y Límites +**Estado:** ⏸️ Pendiente +**Tests planificados:** 4 +**Tests completados:** 0/4 + +- [ ] Test 8.1: Búsquedas masivas +- [ ] Test 8.2: Documentos extensos +- [ ] Test 8.3: Consultas complejas anidadas +- [ ] Test 8.4: Rendimiento temporal + +**Informe generado:** ❌ + +--- + +## ⏸️ FASE 3: ANÁLISIS COMPARATIVO + +### Tareas: +- [ ] Comparar con resultados de boe-mcp +- [ ] Identificar gaps en mcp-boe-consolidada +- [ ] Identificar ventajas de mcp-boe-consolidada +- [ ] Crear matriz comparativa detallada +- [ ] Documentar features únicos de cada MCP + +**Estado:** Pendiente +**Archivos a generar:** +- `99_comparativas/vs_boe_mcp/gaps_mcp_boe_consolidada.md` +- `99_comparativas/vs_boe_mcp/ventajas_mcp_boe_consolidada.md` +- `99_comparativas/vs_boe_mcp/matriz_comparativa.md` + +--- + +## ⏸️ FASE 4: INFORME FINAL + +### Tareas: +- [ ] Consolidar informes de todos los niveles +- [ ] Calcular scoring final +- [ ] Generar métricas globales +- [ ] Crear propuesta MCP-BOE-Ultimate +- [ ] Definir roadmap de mejoras +- [ ] Documentar recomendaciones + +**Estado:** Pendiente +**Archivo a generar:** +- `INFORME_FINAL_COMPLETO.md` + +--- + +## 📊 RESUMEN GLOBAL + +### Tests: +- **Total planificados:** 35 tests +- **Total ejecutados:** 0 +- **Tasa de éxito:** N/A +- **PASS:** 0 +- **PARTIAL:** 0 +- **FAIL:** 0 + +### Niveles: +- **Total niveles:** 8 +- **Completados:** 0/8 (0%) +- **En progreso:** 0 +- **Pendientes:** 8 + +### Tiempo: +- **Preparación:** ~1 hora +- **Ejecución:** 0 horas +- **Documentación:** 0 horas +- **Total:** ~1 hora + +### Score: +- **mcp-boe-consolidada:** Por determinar +- **Objetivo:** Superar 78.5/100 + +--- + +## 📅 HISTORIAL DE ACTUALIZACIONES + +### 2025-11-23T17:53:11Z +- ✅ Estructura de proyecto creada +- ✅ Directorios para 8 niveles creados +- ✅ Documentación preparada +- ✅ Plantillas listas +- ✅ README generado +- 🎯 **LISTO PARA COMENZAR NIVEL 1** + +--- + +## 🎯 PRÓXIMO PASO + +**Ejecutar NIVEL 1: Funcionalidad Básica** +- 5 tests de búsqueda +- Documentar cada test +- Generar informe del nivel +- Validar antes de continuar + +--- + +**FIN DEL TRACKING** diff --git a/testing_mcp_boe_consolidada/bugs/BUG-001_apierror_inheritance.md b/testing_mcp_boe_consolidada/bugs/BUG-001_apierror_inheritance.md new file mode 100644 index 0000000..303fb2d --- /dev/null +++ b/testing_mcp_boe_consolidada/bugs/BUG-001_apierror_inheritance.md @@ -0,0 +1,244 @@ +# BUG-001: APIError hereda de BaseModel en lugar de Exception + +**ID:** BUG-001 +**Severidad:** CRÍTICA +**Estado:** FIXED +**Descubierto en:** SESSION_001 +**Fecha:** 2025-11-23 + +--- + +## 📍 Ubicación + +- **Archivo:** `src/mcp_boe/models/boe_models.py` +- **Líneas:** 463-483 +- **Clase:** `APIError` + +--- + +## 🔍 Descripción + +La clase `APIError` está definida heredando de `BaseModel` (Pydantic) en lugar de `Exception`. Esto viola el contrato de Python para excepciones y causa errores en tiempo de ejecución. + +### Código actual (incorrecto): +```python +class APIError(BaseModel): + """Error de la API del BOE.""" + codigo: int = Field(..., description="Código de error HTTP") + mensaje: str = Field(..., description="Mensaje de error") + detalles: Optional[str] = Field(None, description="Detalles adicionales del error") + timestamp: datetime = Field(default_factory=datetime.now, description="Momento del error") +``` + +--- + +## 💥 Error Producido + +``` +catching classes that do not inherit from BaseException is not allowed +``` + +Este error ocurre cuando el código intenta usar `APIError` en un bloque `except`: +```python +try: + # llamada a API +except APIError as e: # ← ERROR AQUÍ + # manejo del error +``` + +--- + +## 🎯 Impacto + +### Tests bloqueados: +- Test 2.1: metadatos_basicos +- Test 2.2: analisis_juridico +- Test 2.3: texto_completo +- Test 2.4: eli_metadata +- Test 2.5: estructura_indice +- Potencialmente todos los tests de nivel 3+ + +### Funcionalidad afectada: +- Cualquier operación que pueda generar errores de API +- Manejo de errores HTTP +- Recuperación de fallos de red + +--- + +## ✅ Fix Propuesto + +### Opción A: Convertir a Exception simple +```python +class APIError(Exception): + """Error de la API del BOE.""" + + def __init__( + self, + codigo: int, + mensaje: str, + detalles: Optional[str] = None + ): + self.codigo = codigo + self.mensaje = mensaje + self.detalles = detalles + self.timestamp = datetime.now() + super().__init__(f"[{codigo}] {mensaje}") + + def __str__(self) -> str: + base = f"[{self.codigo}] {self.mensaje}" + if self.detalles: + base += f" - {self.detalles}" + return base + + def to_dict(self) -> dict: + """Serializar error para logging/respuesta.""" + return { + "codigo": self.codigo, + "mensaje": self.mensaje, + "detalles": self.detalles, + "timestamp": self.timestamp.isoformat() + } +``` + +### Opción B: Mantener modelo Pydantic separado + Exception +```python +class APIErrorData(BaseModel): + """Modelo de datos para error de API (para serialización).""" + codigo: int = Field(..., description="Código de error HTTP") + mensaje: str = Field(..., description="Mensaje de error") + detalles: Optional[str] = Field(None, description="Detalles adicionales") + timestamp: datetime = Field(default_factory=datetime.now) + + +class APIError(Exception): + """Excepción para errores de la API del BOE.""" + + def __init__(self, codigo: int, mensaje: str, detalles: Optional[str] = None): + self.data = APIErrorData(codigo=codigo, mensaje=mensaje, detalles=detalles) + super().__init__(str(self.data)) +``` + +### Recomendación: +**Opción A** es más simple y suficiente para el caso de uso actual. + +--- + +## 🔧 Archivos a Modificar + +1. `src/mcp_boe/models/boe_models.py` - Cambiar definición de APIError +2. Buscar todos los usos de `APIError` para verificar compatibilidad: + - `src/mcp_boe/utils/http_client.py` + - `src/mcp_boe/tools/*.py` + +--- + +## 📋 Checklist de Fix + +- [x] Modificar clase APIError en boe_models.py +- [x] Actualizar imports si es necesario +- [x] Verificar usos en http_client.py +- [x] Verificar usos en tools/ +- [ ] Ejecutar tests unitarios existentes +- [x] Ejecutar test 2.1 para validar fix +- [x] Actualizar estado del bug a FIXED + +--- + +## 📝 Historial + +| Fecha | Acción | Autor | +|-------|--------|-------| +| 2025-11-23 | Bug descubierto durante test 2.1 | pepo | +| 2025-11-23 | Documentación creada | claude | +| 2025-11-23 | Session 2: Fix parcial (herencia Exception) | claude | +| 2025-11-24 | Session 3: Fix completo (timestamp opcional) | claude | +| 2025-11-24 | Bug cerrado - triple validación PASS | claude | + +--- + +**Prioridad de fix:** ALTA - Bloquea múltiples tests + +--- + +## 🔄 PROGRESO DEL FIX (Session 2 - 2025-11-23) + +### Triple Validación RPVEA: + +#### V1: Schema ✅ PASS +- APIError cambiado a heredar de Exception +- Sintaxis correcta, se puede instanciar y hacer raise/except + +#### V2: API ❌ FAIL - Problema encontrado +- `http_client.py` líneas 172-177 y 180-185 pasan `timestamp=datetime.now()` +- El nuevo constructor no acepta `timestamp` como argumento +- Error: `TypeError: APIError.__init__() got an unexpected keyword argument 'timestamp'` + +#### V3: Real Query - PENDIENTE (bloqueado por V2) + +### Fix adicional requerido: +Modificar `APIError.__init__` para aceptar `timestamp` opcional: +```python +def __init__( + self, + codigo: int, + mensaje: str, + detalles: Optional[str] = None, + timestamp: Optional[datetime] = None # AÑADIR +): + ... + self.timestamp = timestamp or datetime.now() # CAMBIAR +``` + +### Estado actual: +- Archivo modificado: `src/mcp_boe/models/boe_models.py` +- ✅ Fix completo aplicado + +--- + +## ✅ FIX COMPLETADO (Session 3 - 2025-11-24) + +### Triple Validación RPVEA - TODAS PASADAS: + +#### V1: Schema ✅ PASS +- APIError hereda de Exception +- Sintaxis correcta + +#### V2: API ✅ PASS +- Constructor acepta `timestamp` opcional +- Compatible con `http_client.py` (líneas 172-177, 180-185, 253-256) +- Tests verificados: + - Sin timestamp → genera automáticamente + - Con timestamp → usa el proporcionado + - raise/except → funciona correctamente + +#### V3: Real Query ✅ PASS +- Búsqueda "Ley 40/2015" ejecutada via MCP +- Respuesta: BOE-A-2015-10566 encontrado +- API funcionando correctamente + +### Código final aplicado: +```python +class APIError(Exception): + """ + Error de la API del BOE. + Hereda de Exception para poder ser usado en bloques try/except. + """ + + def __init__( + self, + codigo: int, + mensaje: str, + detalles: Optional[str] = None, + timestamp: Optional[datetime] = None # Parámetro opcional añadido + ): + self.codigo = codigo + self.mensaje = mensaje + self.detalles = detalles + self.timestamp = timestamp or datetime.now() # Usa el proporcionado o genera + super().__init__(f"[{codigo}] {mensaje}") +``` + +### Nota sobre `timestamp`: +- Este `timestamp` es para **logging/debugging de errores** (momento en que ocurrió el error) +- NO tiene relación con los filtros `from_date`/`to_date` de búsquedas +- Los filtros de búsqueda filtran por `fecha_actualizacion` de las normas (ver documentación API) diff --git a/testing_mcp_boe_consolidada/sessions/SESSION_001.md b/testing_mcp_boe_consolidada/sessions/SESSION_001.md new file mode 100644 index 0000000..d0cd167 --- /dev/null +++ b/testing_mcp_boe_consolidada/sessions/SESSION_001.md @@ -0,0 +1,149 @@ +# SESSION 001 - Configuración Inicial y Descubrimiento de Bug Crítico + +**Fecha:** 2025-11-23 +**Duración:** ~45 min +**RPVEA Phase Principal:** R (Research) + V (Validate) + +--- + +## 🎯 Objetivo de la Sesión + +1. Configurar CI/CD y sincronizar con repositorio +2. Iniciar ejecución de tests nivel 1 +3. Validar funcionamiento básico del MCP + +--- + +## 📋 Tests Planificados + +| Test ID | Nombre | Herramienta | Estado Inicial | +|---------|--------|-------------|----------------| +| 1.1 | busqueda_simple | search_consolidated_legislation | pending | + +--- + +## 🔬 Triple Validación + +### V1 - Schema (Pydantic) +- **Modelo:** `LegislationSearchResult` en `boe_models.py` +- **Estado:** ⚠️ Parcial - Se descubrió bug en `APIError` + +### V2 - API (Endpoint) +- **Endpoint:** `search_consolidated_legislation` +- **Estado:** ✅ API responde correctamente + +### V3 - Real Query +- **Parámetros:** `query="protección de datos", limit=5` +- **Estado:** ⚠️ Funciona pero resultados no óptimos en relevancia + +--- + +## 📊 Tests Ejecutados + +| Test ID | Nombre | Resultado | Latencia | Notas | +|---------|--------|-----------|----------|-------| +| 1.1 | busqueda_simple | PARTIAL | ~2s | Búsqueda funciona pero relevancia mejorable | +| 2.1 | metadatos_basicos | BLOCKED | - | Error por bug BUG-001 | + +--- + +## 🐛 Bugs Encontrados + +### BUG-001: APIError hereda de BaseModel en lugar de Exception +- **Severidad:** CRÍTICA +- **Archivo:** `src/mcp_boe/models/boe_models.py` +- **Línea:** 463-483 +- **Descripción:** La clase `APIError` hereda de `BaseModel` (Pydantic) en lugar de `Exception`. Esto provoca el error "catching classes that do not inherit from BaseException is not allowed" cuando se intenta usar en bloques `except`. +- **Impacto:** Bloquea tests que pueden generar errores de API (nivel 2+) +- **Fix propuesto:** +```python +# ANTES (incorrecto): +class APIError(BaseModel): + """Error de la API del BOE.""" + codigo: int = Field(...) + ... + +# DESPUÉS (correcto): +class APIError(Exception): + """Error de la API del BOE.""" + def __init__(self, codigo: int, mensaje: str, detalles: Optional[str] = None): + self.codigo = codigo + self.mensaje = mensaje + self.detalles = detalles + self.timestamp = datetime.now() + super().__init__(f"[{codigo}] {mensaje}") +``` + +--- + +## 💡 Lecciones Aprendidas + +### 1. Testing: Validar schema antes de ejecutar +**Contexto:** Intenté ejecutar tests de nivel 2 directamente +**Problema:** El test falló por un bug en el modelo, no en la funcionalidad +**Lección:** La Triple Validación (V1→V2→V3) habría detectado esto antes +**Aplicación futura:** Siempre ejecutar V1 (schema) antes de V3 (real query) + +### 2. Búsqueda: Relevancia no es óptima +**Contexto:** Buscar "protección de datos" no devuelve LOPD directamente +**Problema:** La API del BOE prioriza por otros criterios, no solo relevancia textual +**Lección:** Usar términos más específicos (IDs de ley, títulos exactos) para mejores resultados +**Aplicación futura:** Documentar patrones de búsqueda efectivos + +### 3. Metodología: RPVEA previene errores +**Contexto:** Saltarse la fase R y P llevó directamente al bug +**Problema:** Tiempo perdido investigando un error que no era del test +**Lección:** "5 minutos en R ahorran 30 minutos en E/V" +**Aplicación futura:** Adoptar RPVEA formalmente para este proyecto + +--- + +## 📈 Métricas de la Sesión + +- **Tests completados:** 0/5 (nivel 1) +- **Tasa de éxito:** 0% (bloqueado por bug) +- **Tiempo total:** ~45 min +- **Bugs críticos:** 1 +- **Bugs menores:** 0 + +--- + +## ✅ Checklist de Cierre + +- [x] Bug crítico identificado y documentado +- [x] Metodología RPVEA adoptada +- [x] test_registry.json creado +- [x] Estructura de sesiones creada +- [ ] Bug BUG-001 corregido +- [ ] Tests nivel 1 completados + +--- + +## 🔜 Próximos Pasos + +1. [x] Crear framework RPVEA-BOE adaptado +2. [ ] Corregir BUG-001 (APIError inheritance) +3. [ ] Ejecutar tests nivel 1 con metodología RPVEA +4. [ ] Documentar resultados en test_registry.json + +--- + +## 📝 Notas Adicionales + +### Decisión de metodología: +Se decidió pausar los tests para adoptar la metodología RPVEA del proyecto GVA antes de continuar. Esto permite: +1. Testing más sistemático +2. Mejor documentación +3. Detección temprana de bugs +4. Base para regresión + +### CI/CD completado: +- Commit 11599ee pushed a develop +- Estructura de testing sincronizada con repo +- .gitignore actualizado + +--- + +**Sesión completada:** ⚠️ Parcial (pendiente fix de bug) +**Reviewer:** - +**Fecha revisión:** -