Conjunto de herramientas dinámico

El conjunto de herramientas dinámico es el modo de bajo consumo de tokens de GitLab MCP Server. Mantiene disponible todo el catálogo de acciones de GitLab, pero muestra a tu cliente de IA solo dos herramientas públicas:

| Herramienta | Qué hace | | --------------------- | ------------------------------------------------------------------------------------------------------- | | gitlab_find_action | Encuentra la acción correcta de GitLab y devuelve parámetros exactos, ejemplos y metadatos de seguridad | | gitlab_execute_action | Ejecuta la acción elegida tras validar el ID de acción y los parámetros |

El modo dinámico de find/execute es la superficie predeterminada. Las meta-herramientas siguen disponibles con TOOL_SURFACE=meta para clientes que prefieren despachadores consolidados por dominio.

Por qué existe el modo dinámico

Los servidores MCP grandes pueden gastar mucho contexto solo en descubrimiento de herramientas antes de que el usuario pida nada. GitLab MCP Server puede exponer hasta 1033 operaciones individuales, y el catálogo opcional de meta-herramientas anuncia entre 33 y 50 herramientas de dominio.

El modo dinámico expone ese catálogo canónico mediante dos herramientas visibles. El modelo descubre solo lo que necesita para la tarea actual.

flowchart LR
	A[tools/list] --> B[2 herramientas dinámicas públicas]
	B --> C[Encontrar acción y schema]
	C --> E[Ejecutar una acción canónica]
    E --> F[GitLab REST v4 o GraphQL]

Esto suele añadir una llamada de descubrimiento por tarea, pero mantiene muy pequeño el contexto inicial de herramientas MCP. El catálogo se comparte con las meta-herramientas, así que el modo dinámico reutiliza los mismos schemas, protecciones de acciones destructivas, filtrado de solo lectura, previsualizaciones de safe mode, filtrado por scopes del token y formato de resultados.

Activar el modo dinámico

Clientes stdio

Añade TOOL_SURFACE=dynamic al entorno del servidor:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "TOOL_SURFACE": "dynamic"
      }
    }
  }
}

Despliegues HTTP

gitlab-mcp-server --http \
  --gitlab-url=https://gitlab.com \
  --tool-surface=dynamic

Para el contexto inicial más pequeño, usa también la superficie mínima de capacidades:

gitlab-mcp-server --http \
  --gitlab-url=https://gitlab.com \
  --tool-surface=dynamic \
  --capability-surface=minimal

CAPABILITY_SURFACE=minimal mantiene gitlab://workspace/roots y los recursos de manifiesto de herramientas (gitlab://tools y gitlab://tools/{id}), y omite recursos opcionales, prompts y guías de flujo. Dynamic conserva el descubrimiento de schemas porque gitlab_find_action devuelve los schemas exactos inline. META_PARAM_SCHEMA solo afecta los schemas de las meta-herramientas, así que deja el valor predeterminado opaque en despliegues dinámicos.

Flujo del modelo

El modo dinámico funciona mejor cuando el asistente sigue un ritmo simple: encontrar, ejecutar.

sequenceDiagram
    participant User as Usuario
    participant AI as Asistente IA
	participant Find as gitlab_find_action
    participant Execute as gitlab_execute_action
    participant GitLab

    User->>AI: Lista merge requests abiertas creadas por mí
	AI->>Find: merge request list open authored by me
	Find-->>AI: merge_request.list con schema de parámetros y ejemplos
    AI->>Execute: merge_request.list con parámetros validados
    Execute->>GitLab: Petición API
    GitLab-->>Execute: Datos de GitLab
    Execute-->>AI: Markdown y JSON estructurado
    AI-->>User: Respuesta formateada

Cada herramienta dinámica devuelve un resultado MCP normal: Markdown en content, datos JSON en structuredContent e isError en el envoltorio del resultado cuando el servidor devuelve una guía de reparación. gitlab_execute_action no usa un camino especial hacia GitLab. Despacha al mismo handler de acción que usan las meta-herramientas, así que los schemas, las comprobaciones de política, las previsualizaciones de safe mode, las confirmaciones destructivas y el formato de resultados siguen siendo coherentes.

Qué devuelve cada llamada

| Llamada | Qué recibe el asistente | Cómo debe usarlo el asistente | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | gitlab_find_action | IDs de acción canónicos ordenados con input_schema exacto, meta-herramienta base, dominio, acción, URI de schema, indicador destructivo, parámetros requeridos, pistas de uso, ejemplos, explicaciones opcionales y puntuación | Elegir el mejor candidato domain.action y construir params desde el schema | | gitlab_execute_action | La respuesta existente de la acción desde el handler base, normalmente Markdown y JSON estructurado | Usar los datos devueltos para responder al usuario, o reparar a partir de errores isError: true |

Encontrar acciones es deliberadamente barato comparado con anunciar todas las operaciones de GitLab en tools/list. El modelo solo paga por schemas detallados cuando necesita una acción concreta.

Cómo encuentra acciones la búsqueda

gitlab_find_action es más que una búsqueda de subcadenas. Indexa IDs canónicos, palabras del ID separadas, nombres de meta-herramientas base, dominios, nombres de acción, alias, etiquetas, parámetros requeridos, parámetros opcionales, nombres de propiedades del schema, valores enum, descripciones compactas del schema y metadatos internos de backend.

El pipeline de ranking:

Normaliza la consulta en minúsculas y separa espacios, puntos, guiones bajos y guiones.
Elimina palabras frecuentes como the, to, with y please.
Expande sinónimos como mr → merge request, secret → variable/token de CI, show → get y remove → delete. Palabras de backend como github pr o jira ticket se normalizan a conceptos GitLab de merge request o issue sin exponer IDs de acción no GitLab.
Puntúa primero IDs canónicos exactos, después alias, etiquetas, nombres de dominio/acción, parámetros requeridos, valores enum del schema, campos del schema y metadatos más amplios.
Ejecuta recuperación fuzzy de errores tipográficos solo cuando la búsqueda léxica no devuelve resultados o solo devuelve resultados de baja confianza.
Busca prompts largos en ventanas de tres a seis términos para que prompts de varios pasos puedan sacar varias acciones relevantes.

La recuperación fuzzy está limitada a propósito: permite hasta dos errores de edición en tokens de al menos tres caracteres y suprime coincidencias tipográficas débiles para acciones destructivas. Eso ayuda con prompts como merje requesy list, mientras que términos cortos como mr siguen apoyándose en alias y sinónimos en lugar de coincidencias tipográficas demasiado permisivas.

Find acepta explain: true cuando el asistente necesita razones deterministas de puntuación. La respuesta por defecto sigue siendo compacta. Activar explain no cambia el ranking; solo añade metadatos de razonamiento. Las búsquedas sin coincidencias devuelven una lista pequeña de sugerencias, y los flujos curados pueden devolver related_actions, como repository.compare antes de analyze.release_notes.

Algunos límites útiles están fijados dentro del servidor en vez de configurarse por entorno:

| Comportamiento | Valor actual | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Resultados devueltos por find | Por defecto 20 y máximo 50 | | Resultado de alta confianza | Puntuación mínima 80 y al menos 15 puntos de margen sobre el siguiente resultado | | Manejo de prompts largos | Busca ventanas solapadas de tres a seis términos para que un prompt pueda sacar varias acciones | | Recuperación fuzzy de typos | Máximo dos ediciones y solo para términos de al menos tres caracteres | | Sugerencias sin coincidencias | Hasta seis tokens cercanos del catálogo, luego áreas comunes como project, issue, merge request, pipeline, branch y user |

Estos números son constantes internas de ajuste. No son variables de entorno. Existen para mantener el descubrimiento predecible sin perder recuperación ante redacciones y errores tipográficos comunes de los modelos.

Ejemplo

Primero, encuentra la acción:

{
  "tool": "gitlab_find_action",
  "arguments": {
    "query": "merge request list open authored by me project",
    "limit": 5
  }
}

Después, ejecútala:

{
  "tool": "gitlab_execute_action",
  "arguments": {
    "action": "merge_request.list",
    "params": {
      "project_id": "my-group/my-project",
      "state": "opened",
      "scope": "created_by_me",
      "per_page": 20
    }
  }
}

El asistente debe ejecutar el ID de acción canónico devuelto por find. Los alias ayudan al descubrimiento, pero los IDs canónicos son el contrato estable de ejecución.

Comportamiento de reparación

El modo dinámico está diseñado para poder repararse. Si una llamada devuelve isError: true, el asistente debe usar el mensaje como feedback y repetir el paso correcto.

| Fallo | Recuperación | | -------------------------------------- | ---------------------------------------------------------------------------------------------- | | La consulta de find está vacía | Reintentar find con dominio, recurso, verbo y filtros útiles | | El ID de acción es desconocido | Buscar de nuevo o usar los IDs canónicos sugeridos por el mensaje de error | | Alias ambiguo | Elegir uno de los IDs domain.action listados por find | | Los parámetros son rechazados | Encontrar la acción y reconstruir params desde input_schema | | Una acción destructiva queda bloqueada | Pedir aprobación explícita al usuario antes de reintentar con confirm: true a nivel superior |

Las acciones destructivas siguen protegidas

El modo dinámico reutiliza el mismo modelo de seguridad que las meta-herramientas. Las acciones destructivas siguen requiriendo confirmación explícita salvo que el despliegue haya desactivado intencionadamente las confirmaciones con YOLO_MODE o AUTOPILOT.

{
  "tool": "gitlab_execute_action",
  "arguments": {
    "action": "project.delete",
    "params": {
      "project_id": "my-group/my-project"
    }
  }
}

Sin confirmación, el servidor devuelve un resultado de error en lugar de eliminar el proyecto. Para ejecutar la acción intencionadamente, pasa confirm: true a nivel superior en los argumentos de gitlab_execute_action:

{
  "tool": "gitlab_execute_action",
  "arguments": {
    "action": "project.delete",
    "confirm": true,
    "params": {
      "project_id": "my-group/my-project"
    }
  }
}

La ejecución dinámica valida los parámetros antes de despachar. Los campos desconocidos, incluidos campos sensibles no soportados como masked o protected en variables de pipeline schedules, se rechazan con guía de reparación en lugar de eliminarse silenciosamente.

Para despliegues más seguros, usa GITLAB_READ_ONLY=true para eliminar acciones mutantes o GITLAB_SAFE_MODE=true para previsualizar mutaciones sin aplicarlas.

Dinámico vs meta-herramientas

| Pregunta | Meta-herramientas | Conjunto dinámico | | --------------------------- | ---------------------------------------------- | --------------------------------------------------------- | | Qué aparece en tools/list | 33 a 50 herramientas de dominio | 2 herramientas públicas de descubrimiento y ejecución | | Cómo elige el modelo | Escoge una herramienta de dominio y una acción | Encuentra una acción con schema y luego la ejecuta | | Dónde están los schemas | Schema de herramienta o gitlab://tools/{id} | gitlab_find_action o gitlab://tools/{id} | | Mejor uso actual | Modo explícito de compatibilidad | Descubrimiento de acciones predeterminado de bajo consumo | | Vuelta atrás | Usa TOOL_SURFACE=meta | Ruta predeterminada |

Solución de problemas

| Síntoma | Qué hacer | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Solo ves dos herramientas | Es lo esperado en modo dinámico. Pide al asistente que encuentre acciones antes de ejecutar | | La búsqueda devuelve resultados demasiado amplios | Incluye dominio, recurso, acción y filtros, por ejemplo merge request list open authored by me | | Execute rechaza una acción | Busca de nuevo y usa el ID canónico domain.action del resultado | | Execute rechaza parámetros | Encuentra la acción y reintenta con los nombres y tipos exactos | | Recursos y prompts siguen consumiendo contexto | Añade CAPABILITY_SURFACE=minimal o --capability-surface=minimal |