create-mcp-tool

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}/
├── {domain}.go         # Input/Output structs + handler logic
├── action_specs.go     # Canonical ActionSpec route metadata
├── markdown.go         # Markdown formatters + init() registry
└── {domain}_test.go    # Table-driven tests with httptest

Step 1: Define Input/Output Structs

In {domain}.go:

package {domain}

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

type ListInput struct {
    toolutil.PaginationInput
    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"`
}

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
• Use toolutil.StringOrInt for project/group IDs
• Use jsonschema:"description,required" for required fields
• Use json:",omitempty" for optional fields
• No domain prefix on type names — the package provides namespace

Step 2: Implement Handler Functions

In {domain}.go:

func List(ctx context.Context, client *gitlabclient.Client, input ListInput) (ListOutput, error) {
    opts := &gl.ListXxxOptions{
        ListOptions: gl.ListOptions{
            Page:    input.Page(),
            PerPage: input.PerPage(),
        },
    }

    items, resp, err := client.GL().Xxx.ListXxx(input.ProjectID.String(), opts, gl.WithContext(ctx))
    if err != nil {
        return ListOutput{}, toolutil.WrapErrWithMessage("xxxList", err)
    }

    out := ListOutput{
        Items:      convertItems(items),
        Pagination: toolutil.BuildPagination(resp),
    }
    return out, nil
}

func Create(ctx context.Context, client *gitlabclient.Client, input CreateInput) (Output, error) {
    opts := &gl.CreateXxxOptions{
        Name: gl.Ptr(input.Name),
    }

    item, _, err := client.GL().Xxx.CreateXxx(input.ProjectID.String(), opts, gl.WithContext(ctx))
    if err != nil {
        switch {
        case toolutil.ContainsAny(err, "already exists"):
            return Output{}, toolutil.WrapErrWithHint("xxxCreate", err,
                "a resource with this name already exists")
        default:
            return Output{}, toolutil.WrapErrWithMessage("xxxCreate", err)
        }
    }

    return convertItem(item), nil
}