gitlab-mcp-server go-mcp-server.instructions.md

Go MCP Server Development Guidelines

When building MCP servers in Go, follow these best practices and patterns using the official Go SDK (v1.7.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.7.0",
    },
    nil, // or provide mcp.Options
)

Tool Naming Conventions

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

• Format for this project: individual tools use gitlab_{action}_{resource} (e.g., gitlab_create_issue, gitlab_list_projects), while catalog action IDs use {domain}.{action}
• Be action-oriented: Start with verbs (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_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.

For shared projection code or standalone surfaces that intentionally register SDK tools directly, use mcp.AddTool with struct-based input and output for type safety: