atxtechbro / atxtechbro/dotfiles

Refactor MCP servers for better modularity and maintainability

Open
#753 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Problem

Both our GitLab and GitHub MCP servers have grown into large monolithic files that are becoming difficult to maintain:

- **GitLab MCP Server**: ~2000 lines with 53 tools in a single server.py file
- **GitHub MCP Server**: Also growing large with multiple functional areas

This creates several issues:
- Hard to navigate and find specific functionality
- Difficult for multiple developers to work on simultaneously
- Reduced code discoverability and reusability
- Harder to test individual components in isolation
- Cognitive overhead when working on specific features

## Solution

Refactor both servers into modular structures with clear separation of concerns:

### Proposed Structure
```
src/{server}_mcp_server/
├── server.py # Main server setup and tool registration
├── utils.py # Shared utilities (API calls, formatting, etc.)
└── handlers/
├── __init__.py
├── {feature1}.py # Feature-specific handlers
├── {feature2}.py # Feature-specific handlers
└── ...
```

### Benefits
- **Maintainability**: Easier to find and modify specific functionality
- **Organization**: Logical grouping by functionality
- **Collaboration**: Multiple developers can work on different modules
- **Testing**: Individual modules can be tested in isolation
- **Code Reuse**: Shared utilities extracted to common modules

## Tasks

This master issue tracks the overall refactoring effort with two subtasks:

- [ ] #754 Refactor GitLab MCP server into modular structure
- [ ] #755 Refactor GitHub MCP server into modular structure

## Acceptance Criteria

- [ ] Both servers are broken into logical modules by functionality
- [ ] Shared utilities are extracted to common modules
- [ ] All existing functionality continues to work unchanged
- [ ] Module boundaries are clear and well-documented
- [ ] Import structure is clean with no circular dependencies
- [ ] Tests validate that refactoring doesn't break existing behavior

## Implementation Notes

- Use clear functional boundaries (e.g., issues, merge requests, pipelines)
- Extract common patterns into shared utilities
- Maintain backward compatibility for all existing tools
- Follow consistent module naming and structure patterns
- Document the new architecture for future contributors

This refactoring will make both servers 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 with subtasks #754 and #755, then inspect each server.py and the proposed utils.py and handlers/ layout. Compare the existing tool registrations and functional areas before deciding module boundaries. Done means both servers are modular, existing behavior and tests remain intact, imports are clean, and the new architecture is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, gitlab
Domain
backend, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.