gitlab-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

• npm run build — TypeScript compile to dist/ (tsc, ESM).
• npm run dev — Run the server directly from src/ via tsx (stdio transport by default).
• npm start — Run the compiled server from dist/index.js.
• npm test — Jest. Run a single test with npx jest <path> or npx jest -t "<name>".
• Local smoke test over HTTP: MCP_TRANSPORT=http GITLAB_MCP_PORT=8008 GITLAB_TOKEN=glpat-... npm run dev, then point an MCP client at http://localhost:8008/ (health check: curl http://localhost:8008/health).
• Interactive tool testing: npx @modelcontextprotocol/inspector npx @ttpears/gitlab-mcp-server.
• Debug logging: set NODE_ENV=development — startup prints the resolved config to stderr; production suppresses it.

Architecture

Four source files, ~4.7k lines total — keep the layering in mind before adding code:

• src/config.ts — loadConfig() reads env (GITLAB_URL, GITLAB_TOKEN, GITLAB_READ_TOKEN, GITLAB_MAX_PAGE_SIZE, GITLAB_TIMEOUT) into a zod-validated Config. validateUserConfig() parses per-request userCredentials. GITLAB_TOKEN and GITLAB_READ_TOKEN are mutually exclusive; setting both is a startup error. Old GITLAB_AUTH_MODE and GITLAB_SHARED_ACCESS_TOKEN env vars trigger a deprecation warning and are ignored.
• src/gitlab-client.ts — GitLabGraphQLClient wraps graphql-request and is the only place that talks to GitLab. Every method accepts optional userCredentials; getClient() picks a token per the four-step rule (see Project Conventions below). Also hosts fetchAllPages() — the cursor-loop helper every fetchAll tool uses — and schema-introspection helpers.
• src/tools.ts — Declarative tool registry: each entry is { name, description, inputSchema: zod, handler(args, client) }. Handlers are thin — they validate input, call the client, and shape the response. This is where pagination defaults and sort enums live for each tool.
• src/index.ts — GitLabMCPServer owns both transports. Stdio mode uses a single Server instance. HTTP mode (MCP_TRANSPORT=http) runs Express and maintains a httpSessions map keyed by session id, each with its own Server + StreamableHTTPServerTransport + per-session userConfig. The HTTP entry point accepts both / and /mcp (the latter exists for container setups). LibreChat sends credentials via Authorization: Bearer <PAT> and optional X-GitLab-Url headers — these are lifted into the session's userConfig. Idle sessions are reaped by sessionCleanupInterval.