Skip to content

Commit f41a505

Browse files
polazpolaz
authored
Merge pull request #23 from structured-world/refactor/#15-mrs-cqrs-consolidation
feat(mrs): consolidate 20 MR tools into 5 CQRS tools (#15)
2 parents 946a3b2 + 0be7b43 commit f41a505

File tree

9 files changed

+1575
-1869
lines changed

9 files changed

+1575
-1869
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ coverage/
2020
# ai
2121
.opencode*
2222
.aider*
23+
CLAUDE.md
2324

2425
# Scripts directory (local tools and utilities)
2526
scripts/

‎.releaserc.json‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,46 @@
11
{
22
"branches": ["main"],
33
"plugins": [
4-
"@semantic-release/commit-analyzer",
5-
"@semantic-release/release-notes-generator",
4+
[
5+
"@semantic-release/commit-analyzer",
6+
{
7+
"preset": "conventionalcommits",
8+
"releaseRules": [
9+
{ "type": "feat", "release": "minor" },
10+
{ "type": "fix", "release": "patch" },
11+
{ "type": "perf", "release": "patch" },
12+
{ "type": "refactor", "release": "patch" },
13+
{ "type": "revert", "release": "patch" },
14+
{ "type": "ci", "release": false },
15+
{ "type": "docs", "release": false },
16+
{ "type": "style", "release": false },
17+
{ "type": "test", "release": false },
18+
{ "type": "build", "release": false },
19+
{ "type": "chore", "release": false }
20+
]
21+
}
22+
],
23+
[
24+
"@semantic-release/release-notes-generator",
25+
{
26+
"preset": "conventionalcommits",
27+
"presetConfig": {
28+
"types": [
29+
{ "type": "feat", "section": "Features", "hidden": false },
30+
{ "type": "fix", "section": "Bug Fixes", "hidden": false },
31+
{ "type": "perf", "section": "Performance", "hidden": false },
32+
{ "type": "refactor", "section": "Refactoring", "hidden": false },
33+
{ "type": "revert", "section": "Reverts", "hidden": false },
34+
{ "type": "ci", "hidden": true },
35+
{ "type": "docs", "hidden": true },
36+
{ "type": "style", "hidden": true },
37+
{ "type": "test", "hidden": true },
38+
{ "type": "build", "hidden": true },
39+
{ "type": "chore", "hidden": true }
40+
]
41+
}
42+
}
43+
],
644
[
745
"@semantic-release/changelog",
846
{

‎README.md‎

Lines changed: 42 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -461,8 +461,8 @@ When OAuth is enabled, the following endpoints are available:
461461
- `USE_MILESTONE`: When set to 'true', enables the milestone-related tools (list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone, get_milestone_issue, get_milestone_merge_requests, promote_milestone, get_milestone_burndown_events). By default, milestone features are disabled.
462462
- `USE_PIPELINE`: When set to 'true', enables the pipeline-related tools (list_pipelines, get_pipeline, list_pipeline_jobs, list_pipeline_trigger_jobs, get_pipeline_job, get_pipeline_job_output, create_pipeline, retry_pipeline, cancel_pipeline, play_pipeline_job, retry_pipeline_job, cancel_pipeline_job). By default, pipeline features are disabled.
463463
- `USE_LABELS`: When set to 'true', enables the label-related tools (list_labels, get_label, create_label, update_label, delete_label). By default, label features are enabled.
464-
- `USE_MRS`: When set to 'true', enables the merge request-related tools (list_merge_requests, get_merge_request, create_merge_request, update_merge_request, merge_merge_request, get_merge_request_diffs, list_merge_request_diffs, mr_discussions, create_merge_request_thread, create_merge_request_note, update_merge_request_note, create_draft_note, update_draft_note, delete_draft_note, publish_draft_note, bulk_publish_draft_notes, get_draft_note, list_draft_notes). By default, merge request features are enabled.
465-
- `USE_FILES`: When set to 'true', enables the file-related tools (get_file_contents, get_repository_tree, create_or_update_file, push_files, upload_markdown). By default, file operation features are enabled.
464+
- `USE_MRS`: When set to 'true', enables the merge request-related tools (browse_merge_requests, browse_mr_discussions, manage_merge_request, manage_mr_discussion, manage_draft_notes). These 5 CQRS tools consolidate all MR operations. By default, merge request features are enabled.
465+
- `USE_FILES`: When set to 'true', enables the file-related tools (browse_files, manage_files). These 2 CQRS tools consolidate all file operations. By default, file operation features are enabled.
466466
- `USE_VARIABLES`: When set to 'true', enables the CI/CD variables-related tools (list_variables, get_variable, create_variable, update_variable, delete_variable). Supports both project-level and group-level variables. By default, variables features are enabled.
467467
- `GITLAB_AUTH_COOKIE_PATH`: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.
468468
- `SKIP_TLS_VERIFY`: When set to 'true', skips TLS certificate verification for all GitLab API requests (both REST and GraphQL). **WARNING**: This bypasses SSL certificate validation and should only be used for testing with self-signed certificates or trusted internal GitLab instances. Never use this in production environments.
@@ -532,84 +532,54 @@ export GITLAB_TOOL_CREATE_WORK_ITEM="Create tickets for our sprint planning"
532532
- **Case Sensitivity**: Tool names in environment variables must be UPPERCASE (e.g., `LIST_PROJECTS` not `list_projects`)
533533
- **Invalid Names**: Invalid tool names in environment variables are ignored with a warning in debug logs
534534
- **Content Guidelines**: Descriptions can be any valid string but should be kept concise for better UX
535-
- **Scope**: Works with all 86 available tools across all entities (Core, Work Items, Merge Requests, Files, etc.)
535+
- **Scope**: Works with all 61 available tools across all entities (Core, Work Items, Merge Requests, Files, etc.)
536536

537537
## Tools 🛠️
538538

539-
**85 Tools Available** - Organized by entity and functionality below.
539+
**61 Tools Available** - Organized by entity and functionality below.
540540

541541
### Key Features:
542+
- **CQRS Pattern** - Consolidated action-based tools: `browse_*` for reads, `manage_*` for writes
542543
- **Modular Entity Architecture** - Separate entities for Labels, Merge Requests, Files, Pipelines, etc.
543544
- **Environment-Gated Features** - Enable/disable tool groups with USE_* environment variables
544545
- **Work Items Management** - Modern GraphQL API for Issues, Epics, Tasks, and more
545546
- **Complete GitLab API Coverage** - Repository, Merge Requests, Pipelines, Wiki, and more
546547
- **Tier-based Feature Detection** - Automatically enables features based on your GitLab tier
547548
- **Read-only Mode Support** - Safe operation mode for production environments
548549

549-
### Migration from v2.0:
550-
All issue management has been migrated to the Work Items GraphQL API. The legacy REST API issue tools (`create_issue`, `update_issue`, etc.) have been removed. Use the Work Items tools (`create_work_item`, `update_work_item`, etc.) instead for better performance and more features.
551-
552-
<details>
553-
<summary>Removed/Migrated Tools from v2.0</summary>
554-
555-
The following issue-related tools have been removed and replaced by Work Items GraphQL API:
556-
557-
- `create_issue` → Use `create_work_item` instead
558-
- `update_issue` → Use `update_work_item` instead
559-
- `delete_issue` → Use `delete_work_item` instead
560-
- `list_issues` → Use `list_work_items` instead
561-
- `my_issues` → Use `list_work_items` with assignee filter
562-
- `get_issue` → Use `get_work_item` instead
563-
- `create_issue_link` → Use `update_work_item` with LINKED_ITEMS widget
564-
- `delete_issue_link` → Use `update_work_item` with LINKED_ITEMS widget
565-
- `update_issue_note` → Use `update_work_item` with NOTES widget
566-
- `create_issue_note` → Use `update_work_item` with NOTES widget
567-
- `list_issue_links` → Use Work Items GraphQL API
568-
- `list_issue_discussions` → Use Work Items GraphQL API
569-
- `get_issue_link` → Use Work Items GraphQL API
570-
571-
</details>
572-
573550
## Complete Tool Reference
574551

575552
### Legend
576553
- 📖 = Read-only tool (available in GITLAB_READ_ONLY_MODE)
577554
- ✏️ = Read/Write tool (disabled in GITLAB_READ_ONLY_MODE)
578555

579-
### Core Tools (21 tools)
580-
Core GitLab functionality always available.
556+
### Core Tools (13 tools)
557+
Core GitLab functionality always available. Uses CQRS pattern with consolidated action-based tools.
581558

582559
#### Repository & Project Management
583-
- ✏️ **`create_repository`**: Create a new GitLab project
584-
- 📖 **`get_project`**: Get details of a specific project
585-
- 📖 **`list_projects`**: List GitLab projects with flexible scoping. DEFAULT (no group_id): Lists YOUR accessible projects across GitLab (owned/member/starred). GROUP SCOPE (with group_id): Lists all projects within a specific group/organization. Parameters automatically validate based on scope.
586-
- 📖 **`search_repositories`**: Search for GitLab projects
587-
- 📖 **`list_project_members`**: List members of a GitLab project
588-
589-
#### Branch Management
590-
- ✏️ **`create_branch`**: Create a new branch in a GitLab project
591-
- 📖 **`get_branch_diffs`**: Get the changes/diffs between two branches or commits in a GitLab project
592-
- ✏️ **`fork_repository`**: Fork a GitLab project to your account or specified namespace
560+
- 📖 **`browse_projects`**: PROJECT DISCOVERY: Find, browse, or inspect GitLab projects. Actions: "search" finds projects by name/topic, "list" browses accessible projects, "get" retrieves full details.
561+
- ✏️ **`manage_repository`**: REPOSITORY MANAGEMENT: Create or fork GitLab projects. Actions: "create" starts new project, "fork" creates your copy of existing project.
562+
- 📖 **`list_project_members`**: List members of a GitLab project with access levels.
593563

594-
#### Comments & General Notes
595-
- ✏️ **`create_note`**: Create a new note (comment) to an issue or merge request
596-
- 📖 **`download_attachment`**: Download an uploaded file from a GitLab project by secret and filename
564+
#### Namespaces & Groups
565+
- 📖 **`browse_namespaces`**: NAMESPACE OPERATIONS: Explore groups and user namespaces. Actions: "list" discovers namespaces, "get" retrieves details, "verify" checks if path exists.
566+
- ✏️ **`create_group`**: Create a new GitLab group/namespace. Can create subgroups with parent_id.
597567

598568
#### Commits & History
599-
- 📖 **`get_commit`**: Get details of a specific commit
600-
- 📖 **`get_commit_diff`**: Get changes/diffs of a specific commit
601-
- 📖 **`list_commits`**: List repository commits with filtering options
602-
603-
#### Namespaces & Users
604-
- 📖 **`get_namespace`**: Get details of a namespace by ID or path
605-
- 📖 **`list_namespaces`**: List all namespaces available to the current user
606-
- 📖 **`verify_namespace`**: Verify if a namespace path exists
607-
- 📖 **`get_users`**: Get GitLab user details by usernames
569+
- 📖 **`browse_commits`**: COMMIT HISTORY: Explore repository commit history. Actions: "list" browses commits with filters, "get" retrieves commit metadata, "diff" shows code changes.
570+
- ✏️ **`create_branch`**: Create a new branch in a GitLab project from existing ref.
608571

609572
#### Events & Activity
610-
- 📖 **`get_project_events`**: List all visible events for a specified project. Note: before/after parameters accept date format YYYY-MM-DD only
611-
- 📖 **`list_events`**: List all events for the currently authenticated user. Note: before/after parameters accept date format YYYY-MM-DD only
612-
- 📖 **`list_group_iterations`**: List group iterations with filtering options
573+
- 📖 **`browse_events`**: ACTIVITY FEED: Track GitLab activity. Actions: "user" shows your activity, "project" monitors project activity. Filter by date/action type.
574+
- 📖 **`list_group_iterations`**: List group iterations/sprints for agile planning. Requires GitLab Premium.
575+
576+
#### Users & Utilities
577+
- 📖 **`get_users`**: Search GitLab users with smart pattern detection. Auto-detects emails, usernames, or names.
578+
- 📖 **`download_attachment`**: Download file attachments from issues/MRs by secret and filename.
579+
580+
#### Todos (Task Queue)
581+
- 📖 **`list_todos`**: View your GitLab todos (notifications requiring action). Filter by state, action type, or target type.
582+
- ✏️ **`manage_todos`**: Manage todo items. Actions: "mark_done" completes single todo, "mark_all_done" clears queue, "restore" undoes completed todo.
613583

614584
### Labels Management (5 tools)
615585
Requires USE_LABELS=true environment variable (enabled by default). Supports both project and group labels.
@@ -620,41 +590,23 @@ Requires USE_LABELS=true environment variable (enabled by default). Supports bot
620590
- 📖 **`get_label`**: Get a single label from a project or group
621591
- 📖 **`list_labels`**: List labels for a project or group
622592

623-
### Merge Requests Management (17 tools)
624-
Requires USE_MRS=true environment variable (enabled by default).
625-
626-
#### Merge Request Operations
627-
- ✏️ **`create_merge_request`**: Create a new merge request in a GitLab project
628-
- ✏️ **`update_merge_request`**: Update a merge request (Either mergeRequestIid or branchName must be provided)
629-
- ✏️ **`merge_merge_request`**: Merge a merge request in a GitLab project
630-
- 📖 **`get_merge_request`**: Get details of a merge request (Either mergeRequestIid or branchName must be provided)
631-
- 📖 **`get_merge_request_diffs`**: Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
632-
- 📖 **`list_merge_request_diffs`**: List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
633-
- 📖 **`list_merge_requests`**: List merge requests in a GitLab project with filtering options
634-
- 📖 **`mr_discussions`**: List discussion items for a merge request
635-
636-
#### MR Comments & Discussions
637-
- ✏️ **`create_merge_request_thread`**: Create a new thread on a merge request
638-
- ✏️ **`create_merge_request_note`**: Add a new note to an existing merge request thread
639-
- ✏️ **`update_merge_request_note`**: Modify an existing merge request thread note
640-
641-
#### MR Draft Notes
642-
- ✏️ **`create_draft_note`**: Create a draft note for a merge request
643-
- ✏️ **`update_draft_note`**: Update an existing draft note
644-
- ✏️ **`delete_draft_note`**: Delete a draft note
645-
- ✏️ **`publish_draft_note`**: Publish a single draft note
646-
- ✏️ **`bulk_publish_draft_notes`**: Publish all draft notes for a merge request
647-
- 📖 **`get_draft_note`**: Get a single draft note from a merge request
648-
- 📖 **`list_draft_notes`**: List draft notes for a merge request
649-
650-
### File Operations (5 tools)
651-
Requires USE_FILES=true environment variable (enabled by default).
652-
653-
- ✏️ **`create_or_update_file`**: Create or update a single file in a GitLab project
654-
- ✏️ **`push_files`**: Push multiple files to a GitLab project in a single commit
655-
- 📖 **`get_file_contents`**: Get the contents of a file or directory from a GitLab project
656-
- 📖 **`get_repository_tree`**: Get the repository tree for a GitLab project (list files and directories)
657-
- ✏️ **`upload_markdown`**: Upload a file to a GitLab project for use in markdown content
593+
### Merge Requests Management (5 CQRS tools)
594+
Requires USE_MRS=true environment variable (enabled by default). Uses CQRS pattern with action-based tools.
595+
596+
#### Merge Request Browsing (Query)
597+
- 📖 **`browse_merge_requests`**: BROWSE merge requests. Actions: "list" shows MRs with filtering, "get" retrieves single MR by IID or branch, "diffs" shows file changes, "compare" diffs two branches/commits.
598+
- 📖 **`browse_mr_discussions`**: BROWSE MR discussions and draft notes. Actions: "list" shows all discussion threads, "drafts" lists unpublished draft notes, "draft" gets single draft note.
599+
600+
#### Merge Request Management (Command)
601+
- ✏️ **`manage_merge_request`**: MANAGE merge requests. Actions: "create" creates new MR, "update" modifies existing MR, "merge" merges approved MR into target branch.
602+
- ✏️ **`manage_mr_discussion`**: MANAGE MR discussions. Actions: "comment" adds comment to issue/MR, "thread" starts new discussion, "reply" responds to existing thread, "update" modifies note.
603+
- ✏️ **`manage_draft_notes`**: MANAGE draft notes. Actions: "create" creates draft note, "update" modifies draft, "publish" publishes single draft, "publish_all" publishes all drafts, "delete" removes draft.
604+
605+
### File Operations (2 CQRS tools)
606+
Requires USE_FILES=true environment variable (enabled by default). Uses CQRS pattern with action-based tools.
607+
608+
- 📖 **`browse_files`**: BROWSE repository files. Actions: "tree" lists files/folders with pagination, "content" reads file contents. Use for exploring project structure or reading source code.
609+
- ✏️ **`manage_files`**: MANAGE repository files. Actions: "single" creates/updates one file, "batch" commits multiple files atomically, "upload" adds markdown attachments.
658610

659611
### CI/CD Variables (5 tools)
660612
Requires USE_VARIABLES=true environment variable (enabled by default). Supports both project-level and group-level variables.
@@ -865,4 +817,3 @@ This GitLab MCP Server is developed and maintained with care for the community.
865817

866818
**Maintained with ❤️ by [Dmitry Prudnikov](https://github.com/polaz)**
867819
**Original work by [zereight](https://github.com/zereight) - Thank you for the foundation!**
868-
# Version 5.0.0

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@
8282
"@typescript-eslint/eslint-plugin": "^8.53.0",
8383
"@typescript-eslint/parser": "^8.53.0",
8484
"auto-changelog": "^2.5.0",
85+
"conventional-changelog-conventionalcommits": "^9.1.0",
8586
"cross-env": "^10.1.0",
8687
"dotenv": "^17.2.3",
8788
"eslint": "^9.39.2",

0 commit comments

Comments
 (0)