gitlab-mcp-server: Instructions file for GitHub Copilot

gitlab-mcp-server — GitLab MCP Server in Go

Project Overview

This project implements a Model Context Protocol (MCP) server that exposes GitLab operations as MCP tools. It is written in Go using the official github.com/modelcontextprotocol/go-sdk package and communicates with the GitLab REST API v4 (primary) and GraphQL API (for domains without REST coverage — see ADR-0006).

Architecture

• Language: Go 1.27.3
• MCP SDK: github.com/modelcontextprotocol/go-sdk/mcp v1.8.0
• GitLab Client: gitlab.com/gitlab-org/api/client-go/v3 v3.30.0 (official client, migrated from deprecated xanzy/go-gitlab)
• Transport: stdio (primary), HTTP (optional)
• Cross-platform: Windows, Linux & macOS, amd64 & arm64

Project Structure

gitlab-mcp-server/
├── cmd/                    # server + 44 dev utility binaries; see docs/development/cmd-utilities.md for the full reference
│   ├── server/             # MCP server entry point (+ --shutdown, --probe flags)
│   ├── audit_1to1/         # 1:1 SDK↔API parity audit (-scope structs|actions|metadata|enums|sdk|paths|grants; -validate-docs); grants is R-GRANT, the fine-grained table held to the live GitLab record
│   ├── audit_catalog_first/        # Catalog-first registration invariants (ADR-0004)
│   ├── audit_discovery_completeness/ # Discovery-metadata quality audit (META-001)
│   ├── audit_doc_tool_names/ # Every `gitlab_*` name the docs mention exists on the surface it claims (make check-doc-tool-names)
│   ├── audit_dynamic_aliases/ # Dynamic-toolset alias governance
│   ├── audit_e2e_coverage/ # What the e2e suite dispatched, and the catalog actions it never reached (make audit-e2e-coverage, make check-e2e-static)
│   ├── audit_edition_tier/ # Doc-grounded licensing tier vs binary gating
│   ├── audit_gateway_chars/ # Served descriptions/titles vs strict gateway validators (make check-gateway-chars)
│   ├── audit_install_buttons/ # One-click install payloads decode to one configuration per command
│   ├── audit_binary_vulns/ # Every release binary against the vulnerability database at module grain (make check-binary-vulns)
│   ├── audit_surface_quality/ # MCP surface metadata + output quality (-view; was audit_tools + audit_output)
│   ├── audit_supply_chain/ # Release-configuration invariants (SHA-pinned uses:, Dependabot cooldowns, SECURITY.md, installers)
│   ├── audit_tokens/       # Token overhead; -footprint, --compare-schemas (was audit_meta_schema); cl100k_base tokenizer (tokens.go)
│   ├── audit_metrics/      # MCP tool/resource/prompt metrics
│   ├── audit_readonly_graphql/ # No ReadOnly action may reach a GraphQL mutation (make check-readonly-graphql)
│   ├── audit_sdk_context/  # Every client-go call in internal/ and cmd/ passes gl.WithContext(ctx); test files are its blind spot (make check-sdk-context)
│   ├── audit_tenancy/      # Holds the tenant policy register (internal/tenancy) to the code: sites, values, refusals, charges, reasons, and nothing shaped like a limit, in a shape its tripwire reads, outside a row or an exemption (docs/development/cmd-utilities.md lists what it cannot see); -compare-binaries proves a move changed no code (make check-tenancy)
│   ├── audit_graphql_documents/ # Every raw GraphQL document under ./internal/... is one the pinned GitLab schema accepts (make check-graphql-documents); the documents client-go builds are judged by the test transport alone
│   ├── gen_graphql_schema/ # Pins the GitLab GraphQL schema from a live introspection (make gen-graphql-schema; --check gates it)
│   ├── gen_action_grants/  # Derives each action's requests from its handlers and joins them to what GitLab declares a fine-grained token needs: action-requests.json, the compiled table and the site's reference/fine-grained-permissions.mdx with its Spanish twin (make gen-action-grants; check-action-grants and check-action-grants-derivation gate it)
│   ├── audit_test_goroutines/ # Off-goroutine testing.T abort audit (--check gate)
│   ├── audit_test_names/   # Test naming convention (+ -apply/-dry-run; -check-files gates test-file naming)
│   ├── audit_test_subtests/ # Case loops that assert without a t.Run subtest (-fix rewrites the unambiguous ones)
│   ├── audit_test_closed_servers/ # httptest servers closed while their address is still used later in the function (make check-closed-servers)
│   ├── bench_resources/    # What the server costs to run, and the charts the docs publish
│   ├── godoc_tool/         # Godoc auditor + fixer (audit/fix; was audit_godocs + add_docs; make check-godocs)
│   ├── format_md_tables/   # Markdown pipe-table normalizer
│   ├── measure_conditions/ # Plan and job summary of the on-demand condition coverage workflow (conditions.yml, dispatched by hand)
│   ├── gen_action_catalog_manifest/ # ActionSpec group-builder manifest
│   ├── gen_brand/          # Every vector brand asset from one parametric geometry
│   ├── gen_icon_webp/      # Light/dark WebP icon fallbacks from icons.go
│   ├── gen_lhm_manifest/   # Capability arrays in lhm.plugin.json (LobeHub)
│   ├── gen_llms/           # llms.txt / llms-full.txt
│   ├── gen_testing_docs/   # docs/development/testing/testing.md test-metrics block
│   ├── gen_tool_reference/ # The site's per-domain tool reference, one page per catalog group in English and Spanish, from the catalog and domains.json (make gen-tool-reference; check-tool-reference gates it)
│   ├── gen_third_party_notices/ # THIRD_PARTY_NOTICES from the release binaries' build information, the packages they link and the module cache (GoReleaser's sboms, the Dockerfile, make mcpb)
│   ├── gen_model_corpus/   # Model evaluation corpus breadth ledger
│   ├── gen_model_results/  # Folds a model evaluation run's shards into the published record
│   └── internal/           # Helpers shared by the commands (actionrequests, apidocs, auditshared, docgen, mcpsurface, sdkroutes)
├── internal/
│   ├── config/             # Configuration loading (dotenv files, flags, env vars, HTTP env overlay)
│   ├── edition/            # Licensing tier model (Free/Premium/Ultimate)
│   ├── finegrained/        # What a fine-grained token needs per action: the table types, the phase A and B authority, the withheld words (issue 952, ADR-0024)
│   ├── gitlab/             # GitLab API client wrapper
│   ├── oauth/              # OAuth HTTP mode: token cache, GitLab verifier, RFC 9728 metadata
│   ├── serverpool/         # HTTP mode: per-token+URL server pool & LRU cache
│   ├── subscriptions/      # resources/subscribe: polled watchers, leases (ADR-0015)
│   ├── tenancy/            # Tenant policy register (ADR-0023): keys and mint costs, one row per decision, values, Validate; decides, never enforces
│   ├── telemetry/, mcpotel/ # OpenTelemetry export and MCP instrumentation
│   ├── clientcompat/, gatewaycompat/, cachehints/, capguard/ # Per-client and gateway compatibility, cache hints, capability guard
│   ├── toolutil/           # Shared tool utilities (errors, pagination, markdown, logging)
│   ├── graphqlschema/      # Pinned GitLab GraphQL schema (SDL embedded as text + provenance) and Validate()
│   ├── testutil/           # Shared test helpers (NewTestClient, RespondJSON); NewTestClient validates every GraphQL document against the pinned schema; netfixture/ is the dead endpoint and the stoppable server a test uses instead of a closed httptest server
│   ├── tools/              # Tool orchestration layer + 180 sub-packages
│   │   ├── action_catalog.go # Canonical action catalog built from domain ActionSpecs
│   │   ├── actiongrants/   # The generated fine-grained table (table_gen.go, never edited) the catalog reads each action's requirement from
│   │   ├── register.go     # RegisterAll() — projects individual tools from the canonical action catalog
│   │   ├── register_meta.go # RegisterMetaStandaloneTools(): the standalone utilities (gitlab_discover_project, the gitlab_interactive_* flows) on the meta and individual surfaces; the catalog groups are registered by RegisterMetaCatalog (meta_catalog.go)
│   │   ├── dynamic/        # Low-token dynamic find/execute surface
│   │   ├── dynamiccatalog/ # Build(): the dynamic catalog assembled the way the server assembles it
│   │   ├── toolvisibility/ # Apply(): the post-registration pass over the tools outside the catalog, shared by cmd/server and the evaluator
│   │   ├── branches/       # Branch & protected branch tools
│   │   ├── commits/        # Commit tools
│   │   ├── issues/         # Issue CRUD tools
│   │   ├── mergerequests/  # Merge request CRUD tools
│   │   ├── projects/       # Project CRUD tools
│   │   └── ...             # 180 sub-packages (181 packages with the root)
│   ├── resources/          # MCP resource implementations
│   ├── prompts/            # MCP prompt implementations
│   ├── completions/        # Argument completion handler
│   ├── progress/           # MCP progress notifications
│   └── elicitation/        # MCP elicitation capability
├── docs/                   # Contributor documentation only: development/ and a README pointing users at the site (ADR-0025)
│   └── development/        # adr/ (Architectural Decision Records), testing/ (generated), static analysis, cmd utilities, tool surfaces, and the internal architecture, error handling, GraphQL integration, capability APIs and distribution pages (architecture.md, error-handling.md, graphql.md, capabilities.md, distribution.md)
├── site/                   # The user documentation: an Astro Starlight site, published at https://docs.jmrp.io/gitlab-mcp-server/
│   ├── src/content/docs/   # One .mdx page per slug, its Spanish twin under es/; reference/tools/ (make gen-tool-reference) and reference/fine-grained-permissions.mdx (make gen-action-grants) are generated
│   ├── src/data/           # Generated figures the pages read: stats.json (audit_metrics), token-footprint.json (audit_tokens), resource-benchmark.json (bench_resources); home.ts, the landing data, is hand-written
│   └── scripts/            # The site's own checks (i18n:check, facts:check, chips:check, llms:check and version:check among them) and its llms.txt generator
├── plan/                   # Untracked working area: ignored by git, never committed
├── .github/                # Copilot agents, skills, instructions
├── .gitignore
├── go.mod
├── go.sum
├── Makefile
└── README.md