kepler-mcp-gitlab-server: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Kepler MCP GitLab Server - An MCP server providing GitLab integration tools for AI assistants.

This project was created from the kepler-mcp-server-template and implements GitLab-specific tools.

Build and Development Commands

# Install dependencies
pip install -e ".[dev]"

# Quality checks
make lint              # Ruff linting
make lint-fix          # Ruff with auto-fix
make typecheck         # Mypy strict type checking
make secscan           # Bandit + Safety security scans
make test              # Run all tests
make coverage          # Tests with coverage report
make check-all         # Run all checks in sequence

# Run single test file
pytest tests/test_config.py

# Run single test
pytest tests/test_config.py::TestConfig::test_default_values -v

# Run tests matching pattern
pytest -k "oauth" -v

# Server
make serve-stdio       # Run in stdio mode (Claude Desktop)
make serve-sse         # Run in SSE mode (ChatGPT connectors)

# Docker
make docker-lint       # Build lint stage (CI validation)
make docker-runtime    # Build production image

Architecture Overview

This is an MCP (Model Context Protocol) server template using FastMCP. The architecture supports two transport modes: stdio for local integrations and SSE for HTTP-based integrations.

Core Flow

1. CLI (cli.py) → loads config → creates app via server.create_app() → runs transport
2. server.py creates FastMCP instance, registers core tools + application tools
3. transport.py handles stdio or SSE (Starlette/uvicorn) based on config

Key Extension Point

application.py is the primary extension point. To build a specific MCP server (GitLab, JIRA, etc.):

• Implement tools in register_application_tools(app, config)
• Extend Config model in config.py for application-specific fields
• Use AuthStrategy from security.py for authenticated API calls