Orbit

Orbit expone la API experimental Knowledge Graph de GitLab.com mediante seis herramientas MCP de solo lectura —status, schema, tools, dsl, query y graph_status—. Solo está disponible cuando el servidor se conecta a https://gitlab.com y el catálogo Enterprise/Premium está habilitado con Ultimate (GITLAB_TIER=ultimate, o --tier=ultimate en modo HTTP). Los flags heredados GITLAB_ENTERPRISE=true/--enterprise siguen funcionando pero están deprecados. Orbit nunca escribe: cada herramienta inspecciona salud, esquema o datos indexados, o ejecuta una consulta de solo lectura sobre el grafo.

Referencia técnica

Para la referencia generada completa, consulta docs/tools/orbit.md en el repositorio.

¿Cuándo está disponible Orbit?

Orbit solo se registra en conexiones a GitLab.com Ultimate. Requiere el host https://gitlab.com y el catálogo Enterprise/Premium habilitado con Ultimate. En modo meta-herramientas aparece como la única herramienta gitlab_orbit con seis acciones; en modo individual aparece como seis herramientas gitlab_orbit_*. Todas las herramientas Orbit son de solo lectura.

Requisito	Valor
Host de GitLab	https://gitlab.com
Catálogo	Enterprise/Premium
Modo meta-herramientas	gitlab_orbit con seis acciones
Modo individual	Seis herramientas gitlab_orbit_*
Comportamiento de escritura	Solo lectura

Las instancias GitLab autoalojadas no registran herramientas Orbit, incluso cuando el catálogo Enterprise/Premium está habilitado.

Acciones

Acción	Herramienta individual	Propósito
status	gitlab_orbit_status	Comprobar la salud del servicio Orbit y el estado de sus componentes
schema	gitlab_orbit_schema	Inspeccionar la ontología del grafo y ampliar definiciones de nodos
tools	gitlab_orbit_tools	Descubrir el manifiesto vivo de consultas Orbit
dsl	gitlab_orbit_dsl	Obtener el esquema DSL o gramática LLM de Orbit
query	gitlab_orbit_query	Ejecutar un objeto de consulta de solo lectura sobre el Knowledge Graph
graph_status	gitlab_orbit_graph_status	Inspeccionar el estado de indexación de un namespace, proyecto o ruta completa

¿Cuál es el flujo típico?

El flujo típico de Orbit descubre primero el esquema vivo y luego ejecuta una consulta tipada —nunca al revés—, porque la ontología y el DSL que sirve GitLab.com pueden cambiar. Confirma que el servicio está activo con status, inspecciona el grafo con schema, obtén el manifiesto vivo de consultas con tools, opcionalmente recupera la gramática DSL con dsl, y luego envía un objeto de consulta a query.

1. Llama a gitlab_orbit con action: "status" para confirmar que el servicio está disponible.
2. Llama a action: "schema" para inspeccionar dominios, nodos y relaciones del grafo.
3. Llama a action: "tools" antes de action: "query" para obtener el schema vivo de consultas servido por GitLab.com.
4. (Opcional) Llama a action: "dsl" para obtener el esquema DSL o gramática LLM de Orbit.
5. Pasa un objeto JSON de consulta a action: "query" con response_format en raw o llm.

Variantes del DSL de consulta

El parámetro query de la acción query es un objeto JSON cuyo query_type selecciona una de cuatro variantes. El siguiente diagrama resume la forma mínima aceptada para cada variante. Un graph TD de Mermaid es la herramienta adecuada porque las cuatro variantes comparten un único discriminador query_type y solo divergen en las claves hermanas; un árbol hace que los discriminantes y campos requeridos sean legibles de un vistazo.

graph TD
    Q["QueryInput<br/>(gitlab_orbit_query)"] --> QT{"query_type"}
    QT -->|"traversal"| TR["node OR nodes<br/>+ entity, node_ids/filters/id_range<br/>+ relationships?, columns?, order_by?, limit?, cursor?"]
    QT -->|"aggregation"| AG["nodes[]<br/>+ aggregations[] (function, target, alias)<br/>+ group_by?, aggregation_sort?"]
    QT -->|"neighbors"| NB["node (bounded)<br/>+ neighbors.node<br/>+ direction?, rel_types?"]
    QT -->|"path_finding"| PF["nodes[] (>=2, bounded)<br/>+ path {type, from, to, max_depth: 1..3, rel_types?}"]

Flujo descubrir → consultar

El patrón recomendado es descubrir primero el esquema vivo (schema, y opcionalmente dsl) y luego ejecutar una consulta tipada mediante query. Un sequenceDiagram es la herramienta adecuada porque los pasos involucran a cuatro actores distintos (cliente de IA, servidor MCP, GitLab.com e indexer de Orbit) y los límites de respuesta importan: el LLM no debe asumir que el esquema devuelto por dsl es estable.

sequenceDiagram
    participant LLM as Cliente IA
    participant MCP as Servidor MCP
    participant GL as API GitLab.com
    participant IDX as Indexer Orbit

    LLM->>MCP: gitlab_orbit_schema (response_format=llm)
    MCP->>GL: GET /api/v4/orbit/schema
    GL-->>MCP: ontología (nodos, aristas, versiones)
    MCP-->>LLM: texto del esquema

    LLM->>MCP: gitlab_orbit_dsl (response_format=llm)
    MCP->>GL: GET /api/v4/orbit/schema/dsl
    GL-->>MCP: DSL de consulta / gramática LLM
    MCP-->>LLM: texto del DSL

    LLM->>MCP: gitlab_orbit_query (query={query_type, ...})
    MCP->>GL: POST /api/v4/orbit/query
    GL->>IDX: resolver node_ids / filters
    IDX-->>GL: filas indexadas
    GL-->>MCP: filas / agregaciones / caminos
    MCP-->>LLM: resultado + markdown

Ejemplo: Comprobar estado de Orbit

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "status"
  }
}

Ejemplo: Obtener el esquema del grafo

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "schema",
    "params": {
      "expand": ["Project", "User"],
      "response_format": "llm"
    }
  }
}

Ejemplo: Obtener el manifiesto de herramientas Orbit

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "tools"
  }
}

Ejemplo: Obtener el DSL de consultas Orbit

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

Ejemplo: Ejecutar una consulta Knowledge Graph

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "query",
    "params": {
      "query": {
        "query_type": "traversal",
        "node": {
          "id": "p",
          "entity": "Project",
          "filters": {
            "full_path": { "op": "starts_with", "value": "gitlab-org/" }
          },
          "columns": ["id", "full_path"]
        }
      },
      "response_format": "llm"
    }
  }
}

Ejemplo: Comprobar estado de indexación

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "graph_status",
    "params": {
      "project_id": 278964,
      "response_format": "llm"
    }
  }
}

Detalle de acciones

status — Comprobar salud del servicio Orbit

Devuelve la salud del clúster y el estado de los componentes backend. Útil para verificar si Orbit está disponible para tu token y proyecto.

Ejemplo: Ver arriba.

schema — Inspeccionar la ontología del grafo

Devuelve la ontología del grafo Orbit, incluyendo versión, dominios, nodos y aristas. Usa expand para obtener definiciones detalladas de nodos. Soporta response_format (raw o llm).

Ejemplo: Ver arriba.

tools — Descubrir el manifiesto de herramientas Orbit

Devuelve el manifiesto MCP Orbit vivo. Úsalo antes de query para descubrir los esquemas de consulta y parámetros soportados.

Ejemplo: Ver arriba.

dsl — Obtener el esquema DSL o gramática LLM de Orbit

Devuelve el DSL de consultas Orbit como JSON Schema (raw) o gramática LLM (llm). Útil para construcción avanzada de consultas e integración con LLMs.

Ejemplo: Ver arriba.

query — Ejecutar una consulta Knowledge Graph

Ejecuta una consulta de solo lectura sobre el Knowledge Graph. El parámetro query debe ajustarse al esquema de tools. Soporta response_format (raw o llm).

Ejemplo: Ver arriba.

graph_status — Inspeccionar estado de indexación

Devuelve el estado de indexación del grafo para un namespace, proyecto o ruta. Útil para saber si un proyecto está indexado y listo para consultas.

Ejemplo: Ver arriba.

¿Cómo descubro los schemas de consulta?

En modo meta-herramientas, los schemas de parámetros por acción están disponibles como recursos MCP: léelos para conocer la forma exacta de params de cada acción Orbit sin expandir todos los schemas en tools/list. Estos recursos siguen disponibles con CAPABILITY_SURFACE=full o minimal en cualquier modo de META_PARAM_SCHEMA.

Recurso	Propósito
gitlab://tools/gitlab_orbit.status	Parámetros para comprobar salud del servicio
gitlab://tools/gitlab_orbit.schema	Parámetros para inspeccionar la ontología
gitlab://tools/gitlab_orbit.tools	Parámetros para descubrir el manifiesto de consultas
gitlab://tools/gitlab_orbit.dsl	Parámetros para el esquema DSL/gramática
gitlab://tools/gitlab_orbit.query	Parámetros para consultas Knowledge Graph
gitlab://tools/gitlab_orbit.graph_status	Parámetros para comprobar estado de indexación

¿Cómo ejecuto las pruebas en vivo?

Orbit incluye una suite de pruebas en vivo protegida por build tag en test/e2e/orbit/live_test.go que ejercita cada handler contra los endpoints reales https://gitlab.com/api/v4/orbit/*. La suite tiene cuatro puntos de entrada y 41 subtests que cubren los seis handlers, las formas canónicas del DSL de consulta, pruebas de humo basadas en fixtures, y toda la superficie de características del DSL. El orquestador make test-e2e-gitlab-com aprovisiona los proyectos kg-fixtures y security-fixtures en tu namespace (idempotente), espera a que el indexer de Orbit se ponga al día, y luego ejecuta las pruebas:

# Añade un Personal Access Token (alcance api) a .env primero
echo 'GITLAB_COM_TOKEN=glpat-...' >> .env

# El namespace por defecto es plens1; anúlalo con ORBIT_FIXTURES_NAMESPACE
make test-e2e-gitlab-com ORBIT_FIXTURES_NAMESPACE=acme-research

# Cuando los fixtures ya están aprovisionados, ejecuta solo las pruebas
GITLAB_COM_TOKEN=glpat-... \
  go test -tags orbitlive -count=1 -v -timeout 300s ./test/e2e/orbit/

Consulta Orbit live test fixtures para ver la disposición de los fixtures, el reproductor scripts/setup-orbit-fixtures.sh, y la advertencia sobre el indexer (el estado error transitorio es normal y las pruebas son informativas, no de igualdad estricta).

Preguntas frecuentes

¿Orbit está disponible en GitLab autoalojado?

No. Orbit solo está disponible cuando GitLab MCP Server se conecta a https://gitlab.com. Las instancias GitLab autoalojadas no registran herramientas Orbit, incluso cuando el catálogo Enterprise/Premium está habilitado, porque la API experimental Knowledge Graph subyacente está alojada en GitLab.com. No existe ningún flag que añada Orbit a una conexión autoalojada.

¿Qué licencia y configuración requiere Orbit?

Orbit requiere GitLab Ultimate en una conexión a GitLab.com. Actívalo con GITLAB_TIER=ultimate en modo stdio o --tier=ultimate en modo HTTP. Los flags heredados GITLAB_ENTERPRISE=true y --enterprise siguen funcionando como alternativa pero están deprecados. Cuando se cumplen estas condiciones, Orbit aparece como la meta-herramienta gitlab_orbit (seis acciones) o seis herramientas individuales gitlab_orbit_*.

¿Orbit es de solo lectura?

Sí. Las seis herramientas Orbit son de solo lectura. status, schema, tools, dsl y graph_status solo inspeccionan salud, ontología, manifiesto, DSL y estado de indexación, y query ejecuta objetos de consulta de solo lectura sobre el Knowledge Graph contra el índice. Ninguna acción de Orbit modifica datos de GitLab, así que Orbit es seguro de exponer incluso en despliegues cautelosos.

¿Cuáles son las cuatro variantes de query_type de Orbit?

La acción query acepta un objeto JSON de consulta cuyo query_type selecciona una de cuatro variantes: traversal (recorrer nodos por entity, node_ids, filters o id_range), aggregation (agrupar y agregar sobre nodos), neighbors (expandir los vecinos de un nodo acotado) y path_finding (encontrar caminos entre dos o más nodos acotados, con max_depth de 1 a 3). Las cuatro comparten el único discriminador query_type y solo divergen en sus claves hermanas.

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

En modo meta-herramientas, lee el recurso MCP por acción: por ejemplo, gitlab://tools/gitlab_orbit.query devuelve el schema de parámetros de la acción query. Estos recursos siguen disponibles con CAPABILITY_SURFACE=full o minimal y en cualquier modo de META_PARAM_SCHEMA. También puedes llamar a action: "tools" para obtener el manifiesto vivo de consultas servido por GitLab.com antes de construir una consulta.