Conjunto de herramientas dinámico

Documentación para desarrolladores

Esta página es la guía de usuario. Para el contrato autoritativo a nivel de campos y las notas de implementación, consulta docs/dynamic-tools.md en el repositorio.

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 tres herramientas públicas:

Herramienta	Qué hace
gitlab_search_tools	Encuentra la acción correcta de GitLab a partir de lenguaje natural, dominios, verbos, alias y coincidencia tolerante a errores
gitlab_describe_tools	Devuelve los parámetros exactos, ejemplos y metadatos de seguridad de una o varias acciones
gitlab_execute_tool	Ejecuta la acción elegida tras validar el ID de acción y los parámetros

Las meta-herramientas siguen siendo el modo predeterminado hoy porque son la superficie más compatible. El modo dinámico es la alternativa de bajo consumo de tokens.

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 1011 operaciones individuales, e incluso el catálogo predeterminado de meta-herramientas anuncia entre 32 y 48 herramientas de dominio.

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

flowchart LR
    A[tools/list] --> B[3 herramientas dinámicas públicas]
    B --> C[Buscar en catálogo canónico]
    C --> D[Describir acciones elegidas]
    D --> E[Ejecutar una acción canónica]
    E --> F[GitLab REST v4 o GraphQL]

Esto suele añadir una o dos llamadas 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

Nombres actuales

TOOL_SURFACE=dynamic y TOOL_SURFACE=dynamic-3 seleccionan la misma superficie actual de tres herramientas. Usa dynamic para configuración normal y dynamic-3 solo cuando necesites fijar explícitamente la variante de tres herramientas.

TOOL_SURFACE=dynamic-2 es una variante experimental de dos herramientas con gitlab_find_action más gitlab_execute_tool.

Flujo del modelo

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

sequenceDiagram
    participant User as Usuario
    participant AI as Asistente IA
    participant Search as gitlab_search_tools
    participant Describe as gitlab_describe_tools
    participant Execute as gitlab_execute_tool
    participant GitLab

    User->>AI: Lista merge requests abiertas creadas por mí
    AI->>Search: merge request list open authored by me
    Search-->>AI: merge_request.list
    AI->>Describe: merge_request.list
    Describe-->>AI: 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_tool 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_search_tools	Una lista ordenada de IDs de acción canónicos con meta-herramienta base, dominio, acción, URI de schema, indicador destructivo, parámetros requeridos, pistas de uso, acciones relacionadas, explicaciones opcionales y puntuación	Elegir el mejor candidato domain.action y describirlo antes de ejecutar
gitlab_describe_tools	input_schema exacto, parámetros requeridos, metadatos de seguridad, pistas de uso, acciones relacionadas, output_schema opcional, URI de schema y ejemplo ejecutable con gitlab_execute_tool	Construir params desde el schema y evitar nombres de campos inventados
gitlab_execute_tool	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

Buscar y describir son llamadas deliberadamente pequeñas comparadas 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_search_tools 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:

1. Normaliza la consulta en minúsculas y separa espacios, puntos, guiones bajos y guiones.
2. Elimina palabras frecuentes como the, to, with y please.
3. 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.
4. 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.
5. 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.
6. 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.

La búsqueda 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.

Usa IDs canónicos

Los alias ayudan en la búsqueda y pueden resolverse si no son ambiguos, pero los IDs canónicos domain.action son el contrato estable de ejecución. Ante la duda, describe el ID de acción devuelto por la búsqueda y ejecuta exactamente ese ID.

Ejemplo

Primero, busca la acción:

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

Después, describe la acción elegida:

{
  "tool": "gitlab_describe_tools",
  "arguments": {
    "actions": ["merge_request.list"]
  }
}

Por último, ejecútala:

{
  "tool": "gitlab_execute_tool",
  "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 búsqueda o descripción. 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 búsqueda está vacía	Reintentar la búsqueda 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 y describirlo
Los parámetros son rechazados	Describir 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_tool",
  "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_tool:

{
  "tool": "gitlab_execute_tool",
  "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	32 a 48 herramientas de dominio	3 herramientas públicas de descubrimiento y ejecución
Cómo elige el modelo	Escoge una herramienta de dominio y una acción	Busca en el catálogo canónico y después describe la acción
Dónde están los schemas	Schema de herramienta o recursos gitlab://schema/meta/...	gitlab_describe_tools
Mejor uso actual	Compatibilidad predeterminada	Clientes con pocos tokens y preparación para el futuro predeterminado
Vuelta atrás	Ya es el modo predeterminado	Quita TOOL_SURFACE o usa TOOL_SURFACE=meta

Solución de problemas

Síntoma	Qué hacer
Solo ves tres herramientas	Es lo esperado en modo dinámico. Pide al asistente que busque y describa 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	Describe 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

Lectura adicional

• Visión general de herramientas
• Meta-herramientas
• Configuración
• Arquitectura