gitlab-mcp-server: Instructions file for GitHub Copilot

Go MCP Server Development Guidelines

When building MCP servers in Go, follow these best practices and patterns using the official Go SDK (v1.8.0+).

Server Setup

Create an MCP server using mcp.NewServer:

import "github.com/modelcontextprotocol/go-sdk/mcp"

server := mcp.NewServer(
    &mcp.Implementation{
        Name:    "my-server",
        Version: "v1.8.0",
    },
    nil, // or provide *mcp.ServerOptions
)

Tool Naming Conventions

Use snake_case with a service prefix to avoid conflicts when multiple MCP servers run together:

• Format for this project: catalog action IDs are {domain}.{action} (issue.create, project.list); on the individual surface the declared name is domain-first, gitlab_{domain}_{action} (gitlab_issue_create, gitlab_project_list), with a legacy verb-first set (gitlab_list_issue_discussions) that stays as declared. New actions take the domain-first form; the name is IndividualTool.Name in the ActionSpec, never derived by formula. Meta-tools are the bare domain (gitlab_issue) with the operation in the action argument
• The action segment is a verb: get, list, search, create, update, delete
• Be specific: Avoid generic names that could conflict with other servers
• Descriptions: Must narrowly and unambiguously describe functionality, matching actual behavior

Adding Tools

For ordinary GitLab API actions in this repository, add or update domain-local ActionSpecs and handlers. Do not add package-local RegisterTools functions or ad hoc mcp.AddTool calls; shared projection layers consume the canonical action catalog for meta-tools, dynamic find/execute, gitlab://tools, audits, docs, and individual tool registration.

Each ActionSpec declares a minimum edition (free, premium, or ultimate). Edition gating flows through GITLAB_MCP_TIER / --tier and pruneSchemaFieldsByTier in internal/tools/action_catalog.go, which removes premium/ultimate-only actions and prunes per-field schema entries once the active tier resolves. Set the lowest edition that exposes the endpoint correctly and add tier hints in ParameterGuidance when a field is edition-gated. Run go run ./cmd/audit_discovery_completeness/ to confirm each new action has aliases, usage, parameter guidance, and related actions.