gitlab-mcp: Instructions file for Codex

AGENTS.md

Guidance for coding agents and reviewers working on this repository.

GitLab version support

This server supports GitLab 16.0 and later (MIN_SUPPORTED_VERSION in packages/gitlab-mcp/src/services/InstanceCapabilities.ts). It talks to GitLab only through REST API v4 and GraphQL.

Smart MCP, not an API proxy

Tools are an agent-facing layer over GitLab, not a 1:1 proxy: they compose calls, translate parameters, filter and reshape results, and emulate behaviour an older or lower-tier instance lacks. When a capability is missing on some instances, prefer, in order: emulate or degrade (older equivalent, client-side filtering, another endpoint or query, dropping a non-essential field), then report partial effect in the result, and only then hide or refuse, when GitLab itself cannot provide it. Never gate away behaviour a handler already emulates; read the handler before changing its gates.

Rules

1. Everything is available from 16.0 unless declared otherwise. A tool, action or parameter that needs a newer GitLab declares it in its requirements (default, actions.<action> or parameters.<name>, each { tier, minVersion }). The registry hides whatever the connected instance does not meet.
2. Declare minVersion only above the floor. A value at or below 16.0 is ignored by the gate and must not be written; it only misleads readers.
3. Verify every version against GitLab's own sources, never from memory. For each new or changed endpoint, parameter, GraphQL field, argument or fragment type:
   • REST: the {{< history >}} notes in doc/api/*.md, and the Grape optional/requires declaration in lib/api or ee/lib at the release tag (vX.Y.0-ee). Docs often omit the version of a single parameter; the source at the tag is authoritative.
   • GraphQL: doc/api/graphql/reference at the release tag. GitLab rejects the whole query when any selected field, argument or inline-fragment type is unknown, so a single new field gates the entire query and every action using it.
4. Version-dependent behaviour in handlers uses instanceAtLeast / currentInstance from packages/gitlab-mcp/src/entities/instance-version.ts to pick the native path or the emulation. assertInstanceAtLeast (a clear error) is only for capabilities GitLab cannot provide on that instance, never a substitute for an emulation that is possible.
5. A 200 response is not proof a setting was applied. GitLab ignores unknown REST parameters and drops license-, add-on- or feature-flag-gated attributes without an error. Where that matters, compare the returned entity with the request (see packages/gitlab-mcp/src/entities/core/duo-settings.ts).