mcp-server-gitlab copilot-instructions.md

mcp-server-gitlab

mcp-server-gitlab is a GitLab MCP (Model Context Protocol) server built with TypeScript, Bun, and the fastmcp framework. It provides GitLab REST API integration tools for managing projects, merge requests, and user tasks through various MCP-compatible clients like Claude Desktop and Smithery.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Bootstrap, Build, and Test the Repository:

1. Install Bun runtime (required):

   curl -fsSL https://bun.sh/install | bash
   source ~/.bashrc
   

2. Install dependencies:

   bun install
   

   • Fresh install: ~20 seconds, subsequent installs: ~0.02 seconds (cached)
   • Installs 608+ packages including TypeScript, Jest, fastmcp, and axios

3. Build the project:

   bun run build
   

   • Takes approximately 2-3 seconds
   • NEVER CANCEL - Always wait for completion
   • Runs: clean → TypeScript compilation → post-build script (fixes ES module imports)
   • Output: Compiled JavaScript in dist/ directory with executable permissions

4. Run tests:

   bun test
   

   • Takes approximately 0.14 seconds - very fast
   • NEVER CANCEL - Always wait for completion
   • Requires environment variables to be set (see Environment Setup section)
   • 84 tests across 18 files, all unit tests with mocked API calls

Environment Setup (CRITICAL):

Create .env file before running tests or application:

cp .env.example .env

Edit .env with actual values:

GITLAB_TOKEN=glpat-your-actual-token-here
GITLAB_API_URL=https://your-gitlab-instance.com

Optional environment variables:

# User ID mapping to reduce API calls
GITLAB_USER_MAPPING={"username1": 123, "username2": 456}

# Project ID mapping to reduce API calls  
GITLAB_PROJECT_MAPPING={"project-name": 1001, "group/project": "group/project"}