Meta-herramientas

Documentación para desarrolladores

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

Las meta-herramientas son el modo de operación predeterminado de GitLab MCP Server. 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.

¿Por qué meta-herramientas?

Los LLMs tienen ventanas de contexto limitadas. Cuando un servidor MCP registra cientos de herramientas individuales (hasta 1011 en GitLab.com Enterprise/Premium), solo las descripciones de las herramientas consumen una gran porción de los tokens disponibles, dejando menos espacio para la conversación real.

Modo	Nº de herramientas	Overhead de tokens	Funcionalidad
Individual	863 / 1006 / 1011	Muy alto	Completa
Meta (base)	32	Bajo	Completa
Meta (enterprise)	47 / 48	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.

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, 47 herramientas enterprise autoalojadas o 48 herramientas GitLab.com Enterprise con Orbit) funciona dentro de estas restricciones. Si desactivas las meta-herramientas (META_TOOLS=false), 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 disponibles. El servidor valida la acción y la despacha a la función handler correspondiente internamente.

flowchart LR
    A[LLM llama a gitlab_issue] --> B{parámetro action}
    B -->|list| C[Handler de listar issues]
    B -->|get| D[Handler de obtener issue]
    B -->|create| E[Handler de crear issue]
    B -->|update| F[Handler de actualizar issue]
    B -->|delete| G[Handler de eliminar issue]
    B -->|close| H[Handler de cerrar issue]

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.

Descubrir parámetros por acción

Las meta-herramientas usan un sobre común:

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

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. Para descubrir la forma exacta de una acción concreta, lee los recursos de schema:

Recurso	Uso
gitlab://schema/meta/	Lista todas las meta-herramientas registradas y las acciones disponibles en la configuración actual del servidor
gitlab://schema/meta/{tool}/{action}	Devuelve el JSON Schema del objeto params de una acción concreta

Ejemplos de lectura de recursos:

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

{
  "method": "resources/read",
  "params": {
    "uri": "gitlab://schema/meta/gitlab_merge_request/create"
  }
}

La respuesta del schema por acción describe solo params. La llamada final a la herramienta sigue usando el sobre de meta-herramienta con action y params. Estos recursos están siempre disponibles, incluso si configuras META_PARAM_SCHEMA=compact o META_PARAM_SCHEMA=full para incluir más detalle de schema en tools/list.

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 cinco acciones de solo lectura del Knowledge Graph: status, schema, tools, 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 15 meta-herramientas adicionales que exponen funciones de GitLab Premium y Ultimate. En modo stdio, configura GITLAB_ENTERPRISE=true; en modo HTTP, usa --enterprise para forzar el catálogo u omítelo para permitir autodetección CE/EE por entrada token+URL. Además, se añaden 6 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
META_TOOLS	true	Selector booleano heredado: true para meta-herramientas o false para herramientas individuales. Prefiere TOOL_SURFACE=meta en configuraciones nuevas.
TOOL_SURFACE	—	Selector explícito para este modo: usa meta para meta-herramientas. Usa individual solo cuando quieras una herramienta MCP por operación de GitLab.
CAPABILITY_SURFACE	full	Selector del catálogo de recursos y prompts: full o minimal. Minimal mantiene solo gitlab://workspace/roots y omite recursos y prompts opcionales.
META_PARAM_SCHEMA	opaque	Controla cuánto schema de params por acción se incluye en tools/list: opaque, compact o full. Los recursos de schema siguen disponibles salvo que se habilite CAPABILITY_SURFACE=minimal.
GITLAB_ENTERPRISE	false	Habilitar meta-herramientas solo enterprise en modo stdio (requiere Premium/Ultimate).
--enterprise	false	En modo HTTP, forzar meta-herramientas enterprise; omítelo para autodetectar CE/EE por entrada token+URL.