atxtechbro / atxtechbro/dotfiles
Refactor GitLab MCP server into modular structure
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Overview
Refactor the GitLab MCP server from a monolithic ~2000-line server.py file into a modular structure organized by functionality.
**Parent Issue**: #753
## Current State
The GitLab MCP server currently has:
- 53 tools across 5 functional areas in a single server.py file
- Clear logical groupings already exist in comments:
- Pipeline Operations (7 tools)
- Core Repository Management (10 tools)
- User & Group Management (7 tools)
- Advanced Repository Operations (8 tools)
- Comprehensive Issue Management (10 tools)
- Advanced Merge Request Operations (11 tools)
## Proposed Structure
```
src/gitlab_mcp_server/
├── server.py # Main server setup and tool registration
├── utils.py # Shared utilities (run_glab_command, etc.)
└── handlers/
├── __init__.py
├── pipelines.py # Pipeline operations (7 tools)
├── projects.py # Project/branch/tag management (10 tools)
├── users.py # User & group management (7 tools)
├── repository.py # Advanced repo operations (8 tools)
├── issues.py # Issue management (10 tools)
└── merge_requests.py # MR operations (11 tools)
```
## Implementation Tasks
- [ ] Extract shared utilities to `utils.py`
- [ ] Create handler modules for each functional area
- [ ] Move tool definitions to appropriate handler modules
- [ ] Move handler functions to appropriate modules
- [ ] Update main server.py to import and register tools from modules
- [ ] Ensure all imports work correctly (no circular dependencies)
- [ ] Update any existing tests to work with new structure
- [ ] Update documentation to reflect new architecture
## Acceptance Criteria
- [ ] All 53 tools continue to work exactly as before
- [ ] Code is organized into logical modules by functionality
- [ ] Shared utilities are extracted and reused across modules
- [ ] Import structure is clean and maintainable
- [ ] Module boundaries are clear and well-documented
- [ ] No functional regressions introduced
- [ ] README documents the new modular structure
## Benefits
- **Maintainability**: Easier to find and modify specific functionality
- **Organization**: Clear separation of concerns by feature area
- **Collaboration**: Multiple developers can work on different modules
- **Testing**: Individual modules can be tested in isolation
- **Code Reuse**: Common patterns extracted to shared utilities
## Implementation Notes
- Maintain backward compatibility for all existing tools
- Use consistent import patterns across modules
- Follow established naming conventions
- Extract common handler patterns into utilities
- Ensure protocol-level testing continues to work
This refactoring will make the GitLab MCP server much more maintainable and easier to extend with new functionality.
---
🤖 Generated with [Claude Code](https://claude.ai/code)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by inspecting the monolithic server.py and the existing tests, then map its 53 tools to the proposed handlers under src/gitlab_mcp_server/handlers/ and shared code to utils.py. Check the import and registration structure as modules are separated. Done means all tools retain their behavior, protocol-level and existing tests pass, and the README documents the modular architecture.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100