Meta-herramientas

Documentación para desarrolladores

Para la referencia técnica completa, consulta docs/meta-tools.md en el repositorio.

Las meta-herramientas son un modo de operación explícito de GitLab MCP Server, habilitado con TOOL_SURFACE=meta. En lugar de exponer cada operación de la API de GitLab como una herramienta MCP separada, las meta-herramientas agrupan operaciones relacionadas bajo una única herramienta con un parámetro action que despacha al handler correcto. El resultado es una lista de herramientas pequeña y explorable —un puñado de herramientas a nivel de dominio como gitlab_issue, gitlab_project y gitlab_pipeline— que aun así alcanza cualquier operación de GitLab.

¿Por qué usar meta-herramientas?

Las meta-herramientas existen para encajar una superficie completa de la API de GitLab en una ventana de contexto LLM limitada. Cuando un servidor MCP registra cientos de herramientas individuales (hasta 1071 en GitLab.com Enterprise/Premium con Orbit), solo las descripciones de las herramientas consumen una gran porción de los tokens disponibles, dejando menos espacio para la conversación real. El modo meta-herramientas colapsa esas operaciones en herramientas a nivel de dominio, así que la lista de herramientas se mantiene pequeña mientras la funcionalidad sigue completa.

Modo	Nº de herramientas	Overhead de tokens	Funcionalidad
Individual	847 / 1065 / 1071	Muy alto	Completa
Meta (base)	32	Bajo	Completa
Meta (enterprise)	49 / 50	Bajo	Completa + Premium/Ultimate

Las meta-herramientas reducen el recuento de herramientas en más del 95% mientras preservan el 100% de la funcionalidad. Cada operación de herramienta individual está disponible como una acción dentro de una de las meta-herramientas de dominio.

El helper de actualización gitlab_server puede aparecer por separado para acciones de mantenimiento del servidor y no está incluido en los conteos 32/49/50 del catálogo de acciones GitLab.

Compatibilidad con clientes

Algunos clientes de IA imponen límites en el número de herramientas (por ejemplo, JetBrains AI Assistant limita los servidores MCP a 100 herramientas). El modo meta-herramientas (32 herramientas base, 49 herramientas enterprise autoalojadas o 50 herramientas GitLab.com Enterprise con Orbit) funciona dentro de estas restricciones. Si seleccionas herramientas individuales con TOOL_SURFACE=individual, los clientes con dichos límites solo verán un subconjunto del conjunto completo de herramientas individuales.

¿Cómo funcionan las meta-herramientas?

Cada meta-herramienta define un enum action que lista todas las operaciones que admite, luego valida la acción elegida y la despacha a la función handler correspondiente internamente. El parámetro action siempre es requerido y debe ser uno de los valores enumerados; los parámetros adicionales dependen de la acción elegida. Por eso una sola herramienta como gitlab_issue puede cubrir un dominio entero sin exponer una herramienta separada por operación.

flowchart LR
	A[LLM llama a gitlab_issue] --> B{parámetro action}
	B --> C[Mapa de acciones del catálogo]
	C -->|list| D[ActionRoute issue.list]
	C -->|get| E[ActionRoute issue.get]
	C -->|create| F[ActionRoute issue.create]
	C -->|update/delete/etc.| G[Otras rutas de issue]
	D --> H[Handlers tipados de issue]
	E --> H
	F --> H
	G --> H

El parámetro action siempre es requerido y debe ser uno de los valores enumerados. Los parámetros adicionales dependen de la acción elegida.

¿Cómo descubro los parámetros por acción?

Las meta-herramientas usan un sobre común, y la forma exacta de params para cualquier acción se descubre a través del manifiesto de herramientas en lugar de incluirse en cada schema de herramienta. Por defecto, META_PARAM_SCHEMA=opaque mantiene pequeño el schema de la herramienta: los clientes ven el enum válido de action, mientras params queda como un objeto específico de la acción.

{
  "action": "create",
  "params": {
    "project_id": "42"
  }
}

Para descubrir la forma exacta de una acción concreta, lee el manifiesto de herramientas:

Recurso	Uso
gitlab://tools	Lista herramientas visibles y entradas ejecutables para la superficie activa
gitlab://tools/{id}	Devuelve la forma de llamada aceptada y el JSON Schema de una acción, como gitlab_project.get

Ejemplos de lectura de recursos:

{
  "method": "resources/read",
  "params": {
    "uri": "gitlab://tools"
  }
}

{
  "method": "resources/read",
  "params": {
    "uri": "gitlab://tools/gitlab_merge_request.create"
  }
}

La respuesta del detalle por acción incluye el schema de params y la forma de llamada final. Estos recursos siguen disponibles para meta-herramientas cuando CAPABILITY_SURFACE=minimal está habilitado, mientras se omiten recursos opcionales de GitLab, prompts y guías de flujo. Los despliegues dinámicos pueden seguir usando gitlab_find_action para schemas inline; los despliegues de meta-herramientas pueden mantener META_PARAM_SCHEMA=opaque y leer gitlab://tools/{id} en vez de incluir schemas en tools/list. Las métricas actuales muestran que compact es 6.5x más grande que opaque, y full es 11.9x más grande.

Ejemplos de uso

Crear un issue

{
  "tool": "gitlab_issue",
  "arguments": {
    "action": "create",
    "params": {
      "project_id": "my-group/my-project",
      "title": "Update API documentation",
      "description": "The REST API docs are missing the new v2 endpoints",
      "labels": "documentation,api",
      "assignee_ids": "42",
      "milestone_id": 7
    }
  }
}

Listar merge requests

{
  "tool": "gitlab_merge_request",
  "arguments": {
    "action": "list",
    "params": {
      "project_id": "my-group/my-project",
      "state": "opened",
      "order_by": "updated_at",
      "per_page": 20
    }
  }
}

Buscar código

{
  "tool": "gitlab_search",
  "arguments": {
    "action": "code",
    "params": {
      "search": "func handleWebhook",
      "project_id": "my-group/my-project"
    }
  }
}

Comprobar disponibilidad de Orbit

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "status",
    "params": {
      "response_format": "llm"
    }
  }
}

gitlab_orbit solo se registra para conexiones GitLab.com Enterprise/Premium y expone seis acciones de solo lectura del Knowledge Graph: status, schema, tools, dsl, query y graph_status.

Referencia de meta-herramientas clave

gitlab_project

Gestiona el ciclo de vida y la configuración de proyectos.

Acciones: list, get, create, update, delete, archive, unarchive, fork, star, unstar, transfer, languages, users, forks, starrers, hooks, create_hook, update_hook, delete_hook

gitlab_issue

Gestión completa del ciclo de vida de issues incluyendo etiquetas, asignados y transiciones de estado.

Acciones: list, get, create, update, delete, close, reopen, subscribe, unsubscribe, move, clone, add_label, remove_label, set_assignees, add_time_spent, reset_time_spent, set_time_estimate, reset_time_estimate

gitlab_merge_request

Flujo de trabajo completo de merge requests desde la creación hasta el merge.

Acciones: list, get, create, update, merge, close, reopen, rebase, approve, unapprove, subscribe, unsubscribe, add_label, remove_label, set_assignees, set_reviewers, add_time_spent, reset_time_spent

gitlab_pipeline

Gestión y monitorización de pipelines.

Acciones: list, get, create, cancel, retry, delete, variables, test_report, bridges, wait

gitlab_job

Gestión de jobs de CI/CD.

Acciones: list, get, play, cancel, retry, erase, trace, artifacts, download_artifact, delete_artifacts, delete_project_artifacts, wait

gitlab_branch

Operaciones con ramas.

Acciones: list, get, create, delete, merged

gitlab_commit

Operaciones con commits e historial.

Acciones: list, get, diff, refs, cherry_pick, revert, comments, create_comment, statuses, merge_requests

gitlab_tag

Gestión de tags.

Acciones: list, get, create, delete

gitlab_release

Gestión del ciclo de vida de releases.

Acciones: list, get, create, update, delete, evidences

gitlab_label

Gestión de etiquetas para proyectos y grupos.

Acciones: list, get, create, update, delete, subscribe, unsubscribe

gitlab_milestone

Seguimiento de milestones.

Acciones: list, get, create, update, delete, issues, merge_requests

gitlab_member

Membresía de proyectos y grupos.

Acciones: list, get, add, update, remove, all

gitlab_group

Gestión de grupos y subgrupos.

Acciones: list, get, create, update, delete, projects, subgroups, members, labels, milestones, hooks

gitlab_search

Búsqueda entre recursos en toda tu instancia de GitLab.

Acciones: code, issues, merge_requests, commits, milestones, notes, projects, snippets, users, wiki

gitlab_user

Información y búsqueda de usuarios.

Acciones: get, current, list, status, activities

gitlab_wiki

Gestión de páginas wiki.

Acciones: list, get, create, update, delete

gitlab_todo

Lista personal de tareas pendientes.

Acciones: list, mark_done, mark_all_done

Modo Enterprise

El catálogo Enterprise/Premium habilita 16 meta-herramientas adicionales que exponen funciones de GitLab Premium y Ultimate. En modo stdio, establece GITLAB_TIER=premium o GITLAB_TIER=ultimate; en modo HTTP, usa --tier=premium (o --tier=ultimate) para forzar el catálogo, u omítelo para permitir autodetección CE/EE por entrada token+URL. Los flags heredados GITLAB_ENTERPRISE=true (stdio) y --enterprise (HTTP) siguen respetándose como alternativa cuando GITLAB_TIER/--tier no está definido, pero están deprecados. El tier también poda entradas de esquema por campo mediante pruneSchemaFieldsByTier (ver internal/tools/action_catalog.go). Además, se añaden rutas de acción solo enterprise a las meta-herramientas base existentes:

• Iterations → enrutadas a través de gitlab_issue
• Project mirrors → enrutadas a través de gitlab_project
• SSH certificates → enrutadas a través de gitlab_group
• Security settings → divididas entre gitlab_project y gitlab_group
• Group credentials → enrutadas a través de gitlab_group
• Group analytics → enrutadas a través de gitlab_group

Consejo

Puedes comprobar qué herramientas tiene registradas tu servidor mirando la salida del log de inicio o llamando al método MCP tools/list.

Configuración

Variable	Predeterminado	Descripción
TOOL_SURFACE	meta	Selector canónico para este modo: usa meta para meta-herramientas. Usa individual solo cuando quieras una herramienta MCP por operación de GitLab.
META_TOOLS	heredado	Selector de compatibilidad deprecado: true mapea a meta, y false mapea a individual cuando TOOL_SURFACE no está definido.
CAPABILITY_SURFACE	full	Selector del catálogo de recursos y prompts: full o minimal. Minimal mantiene el manifiesto gitlab://tools, y omite recursos opcionales, guías y prompts.
META_PARAM_SCHEMA	opaque	Controla cuánto schema de params por acción se incluye en tools/list: opaque, compact o full. Los schemas exactos están disponibles con gitlab://tools/{id}.
GITLAB_TIER	(autodetectado)	Selector de edición: free/ce, premium o ultimate. Cuando se omite, el tier se detecta desde GET /license (por defecto free). Reemplaza al flag deprecado GITLAB_ENTERPRISE.
--tier	(autodetectado)	Flag de edición en modo HTTP: free/ce, premium o ultimate. Reemplaza al flag deprecado --enterprise.

Metadatos de descubrimiento

Cada acción de meta-herramienta lleva metadatos de descubrimiento (alias, uso, guía de parámetros, acciones relacionadas) que ayudan a los modelos a elegir la acción correcta y a dar forma a los parámetros. Ejecuta go run ./cmd/audit_discovery_completeness/ para puntuar el catálogo; el auditor produce un backlog priorizado que usan los agentes de dominio para rellenar carencias siguiendo el estándar de oro link-create-batch.

Preguntas frecuentes

¿Cuánto reducen las meta-herramientas el número de herramientas?

Las meta-herramientas reducen el recuento de herramientas registradas en más del 95% manteniendo el 100% de la funcionalidad. El modo individual puede registrar cientos de herramientas —847 en CE, hasta 1071 en GitLab.com Enterprise/Premium con Orbit—, mientras que el modo meta-herramientas expone 32 herramientas de dominio base (más con el catálogo Enterprise). Cada operación individual sigue siendo accesible como una acción dentro de una meta-herramienta de dominio, así que no se pierde ninguna capacidad; solo cae drásticamente el overhead de tokens de la lista de herramientas.

¿Qué es el parámetro action?

El parámetro action es el campo requerido en cada meta-herramienta. Cada meta-herramienta define un enum action que lista las operaciones que admite, y el servidor valida la acción elegida antes de despachar al handler correspondiente. Por ejemplo, gitlab_issue acepta list, get, create, update, delete y más. El action siempre es requerido y debe ser uno de los valores enumerados; el resto de parámetros van bajo params y dependen de la acción que elijas.

¿Cómo encuentro los parámetros exactos de una acción?

Por defecto, META_PARAM_SCHEMA=opaque mantiene pequeño el schema de cada meta-herramienta, así que la forma exacta de params se descubre a través del manifiesto de herramientas. Lee gitlab://tools para listar las herramientas visibles y entradas ejecutables de la superficie activa, y luego lee gitlab://tools/{id} —por ejemplo gitlab://tools/gitlab_merge_request.create— para obtener la forma de llamada aceptada y el JSON Schema de una acción. Estos recursos de manifiesto siguen disponibles incluso con CAPABILITY_SURFACE=minimal. Los despliegues dinámicos pueden usar en su lugar gitlab_find_action para schemas inline.

¿Cómo habilito las meta-herramientas Enterprise?

El catálogo Enterprise/Premium habilita 16 meta-herramientas adicionales para funciones de GitLab Premium y Ultimate. En modo stdio, establece GITLAB_TIER=premium o GITLAB_TIER=ultimate; en modo HTTP, usa --tier=premium (o --tier=ultimate) para forzar el catálogo, u omítelo para permitir autodetección CE/EE por entrada token+URL. Los flags heredados GITLAB_ENTERPRISE=true y --enterprise siguen respetándose como alternativa cuando el tier no está definido, pero están deprecados. Habilitar el tier también añade rutas solo enterprise (como iterations, project mirrors y SSH certificates) a las meta-herramientas base existentes.

¿Por qué algunos clientes necesitan el modo meta-herramientas?

Algunos clientes de IA imponen límites en el número de herramientas; por ejemplo, JetBrains AI Assistant limita los servidores MCP a 100 herramientas. El modo meta-herramientas mantiene la lista visible de herramientas dentro de esas restricciones porque consolida cientos de operaciones en 32 herramientas de dominio base (o 49/50 con el catálogo Enterprise). Si en su lugar seleccionas herramientas individuales con TOOL_SURFACE=individual, los clientes con dichos límites solo verán un subconjunto del conjunto completo de herramientas individuales, ocultando algunas operaciones.