gitlab-mcp-server: Skill for Claude Code

Create MCP Tool — GitLab

Step-by-step workflow for creating a new MCP tool that wraps a GitLab REST/GraphQL API endpoint.

Prerequisites

• Identify the GitLab API endpoint(s) (REST v4 or GraphQL)
• Confirm the client-go library supports the endpoint — if not, consider the upstream-contribution skill
• Decide the domain name (e.g., tags, branches, pipelines)

File Structure

Create a new sub-package under internal/tools/{domain}/:

{domain}/
├── doc.go              # Package comment (the one `// Package {domain} ...` comment)
├── {domain}.go         # Input/Output structs + handler logic
├── action_specs.go     # Canonical ActionSpec route metadata
├── markdown.go         # Markdown formatters + init() registry
├── shapes.go           # Optional: nested output shapes mirrored from client-go sub-objects
└── {domain}_test.go    # Tests with httptest (plus action_specs_test.go, markdown_test.go as needed)

A multi-word domain separates the words with underscores in its file names only: merge_requests.go and merge_requests_test.go in package mergerequests. Go's convention and the stylecheck/revive naming rules refuse underscores in a package identifier, and the directory follows the package.

Step 1: Define Input/Output Structs

In {domain}.go:

package {domain}

import "github.com/jmrplens/gitlab-mcp-server/v3/internal/toolutil"

type ListInput struct {
    toolutil.PaginationInput
    toolutil.KeysetPaginationInput // only when the endpoint supports keyset pagination
    ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
}

type Output struct {
    toolutil.HintableOutput
    ID     int    `json:"id"`
    Name   string `json:"name"`
    WebURL string `json:"web_url"`
}

type ListOutput struct {
    toolutil.HintableOutput
    Items      []Output                 `json:"items"`
    Pagination toolutil.PaginationOutput `json:"pagination"`
}

Rules:

• Embed toolutil.HintableOutput as first field (enables next_steps in JSON)
• Embed toolutil.PaginationInput for list operations, and toolutil.KeysetPaginationInput beside it when the GitLab endpoint supports keyset pagination; such a list also passes toolutil.KeysetContinuation(input.KeysetPaginationInput) on its SDK call, last, after gl.WithContext(ctx) (it makes the token the whole query, so an option after it would add to GitLab's link), or the next_page_token its keyset pages publish cannot be followed (testutil.KeysetListing and testutil.FollowKeyset test it)
• Use toolutil.StringOrInt for project/group IDs
• Tag fields that only exist at a higher GitLab tier with tier:"premium" or tier:"ultimate"; the catalog prunes them from the schema below that tier
• Use jsonschema:"description,required" for a field GitLab requires on the route the action sends, and only for that: the marker is the one required list all three surfaces serve (omitempty no longer decides it), and make audit-1to1-required fails on a marker the live record disagrees with unless cmd/audit_1to1/internal/required/declarations.go says why. A choice between fields GitLab states as at_least_one_of or exactly_one_of is an anyOf through toolutil.SchemaAnyOfRequired in the spec's InputSchemaOverrides, with neither field marked
• Use json:",omitempty" for optional fields
• No domain prefix on type names — the package provides namespace