gitlab-mcp 1.3.0 → 1.4.0

package/dist/tools/gitlab.js

@@ -1,24 +1,31 @@
 import { Kind, parse } from "graphql";
 import { z } from "zod";
 import { GitLabApiError } from "../lib/gitlab-client.js";
+import { bodySchema, displayNameSchema, nullableOptional, optionalBodySchema, optionalDisplayNameSchema, optionalProjectIdSchema, optionalRefLikeSchema, optionalUrlOrPathSchema, projectIdSchema, refLikeSchema, slugSchema } from "../lib/tool-schema.js";
 import { getSessionAuth } from "../lib/auth-context.js";
 import { stripNullsDeep } from "../lib/sanitize.js";
 import { getMergeRequestCodeContext, mergeRequestCodeContextSchema } from "./mr-code-context.js";
-const optionalString = z.preprocess((value) => (value === null ? undefined : value), z.string().optional());
-const optionalNumber = z.preprocess((value) => (value === null ? undefined : value), z.number().optional());
-const optionalBoolean = z.preprocess((value) => (value === null ? undefined : value), z.boolean().optional());
-const optionalStringArray = z.preprocess((value) => (value === null ? undefined : value), z.array(z.string()).optional());
-const optionalNumberArray = z.preprocess((value) => (value === null ? undefined : value), z.array(z.number()).optional());
-const optionalStringOrNumber = z.preprocess((value) => (value === null ? undefined : value), z.union([z.string(), z.number()]).optional());
-const optionalStringOrStringArray = z.preprocess((value) => (value === null ? undefined : value), z.union([z.string(), z.array(z.string())]).optional());
-const optionalRecord = z.preprocess((value) => (value === null ? undefined : value), z.record(z.string(), z.unknown()).optional());
+const readCapabilities = ["read"];
+const writeCapabilities = ["write"];
+const deleteCapabilities = ["delete"];
+const adminCapabilities = ["admin"];
+const readGraphqlCapabilities = ["read", "graphql"];
+const writeGraphqlCapabilities = ["write", "graphql"];
+const optionalString = nullableOptional(z.string());
+const optionalNumber = nullableOptional(z.number());
+const optionalBoolean = nullableOptional(z.boolean());
+const optionalStringArray = nullableOptional(z.array(z.string()));
+const optionalNumberArray = nullableOptional(z.array(z.number()));
+const optionalStringOrNumber = nullableOptional(z.union([z.string(), z.number()]));
+const optionalStringOrStringArray = nullableOptional(z.union([z.string(), z.array(z.string())]));
+const optionalRecord = nullableOptional(z.record(z.string(), z.unknown()));
 const pipelineInputValueSchema = z.union([
     z.string(),
     z.number(),
     z.boolean(),
     z.array(z.union([z.string(), z.number(), z.boolean()]))
 ]);
-const optionalPipelineInputsRecord = z.preprocess((value) => (value === null ? undefined : value), z.record(z.string(), pipelineInputValueSchema).optional());
+const optionalPipelineInputsRecord = nullableOptional(z.record(z.string(), pipelineInputValueSchema));
 const paginationShape = {
     page: optionalNumber,
     per_page: optionalNumber
@@ -28,7 +35,7 @@ export function registerGitLabTools(server, context) {
     const disableGraphqlTools = shouldDisableGraphqlTools(context.env.GITLAB_ALLOWED_PROJECT_IDS, context.env.GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE);
     const filtered = context.policy.filterTools(definitions.map((item) => ({
         name: item.name,
-        mutating: item.mutating,
+        capabilities: item.capabilities,
         requiresFeature: item.requiresFeature
     })));
     const enabledNames = new Set(filtered.map((item) => item.name));
@@ -50,7 +57,7 @@ export function registerGitLabTools(server, context) {
             try {
                 context.policy.assertCanExecute({
                     name: definition.name,
-                    mutating: definition.mutating,
+                    capabilities: definition.capabilities,
                     requiresFeature: definition.requiresFeature
                 });
                 if (definition.requiresAuth ?? true) {
@@ -90,9 +97,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_project",
             title: "Get Project",
             description: "Get project details by ID or path.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional()
+                project_id: optionalProjectIdSchema
             },
             handler: async (args, context) => {
                 const projectId = resolveProjectId(args, context, true);
@@ -103,7 +110,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_projects",
             title: "List Projects",
             description: "List projects available to the current user.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 search: optionalString,
                 search_namespaces: optionalBoolean,
@@ -127,15 +134,15 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_repository",
             title: "Create Repository",
             description: "Create a new GitLab project/repository.",
-            mutating: true,
+            capabilities: adminCapabilities,
             inputSchema: {
-                name: optionalString,
+                name: displayNameSchema,
                 description: optionalString,
                 visibility: z.enum(["private", "internal", "public"]).optional(),
                 initialize_with_readme: optionalBoolean,
                 path: optionalString,
-                namespace_id: optionalString,
-                default_branch: optionalString
+                namespace_id: optionalProjectIdSchema,
+                default_branch: optionalRefLikeSchema
             },
             handler: async (args, context) => context.gitlab.createRepository({
                 name: getString(args, "name"),
@@ -151,9 +158,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_project_members",
             title: "List Project Members",
             description: "List members of a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 query: optionalString,
                 user_ids: optionalNumberArray,
                 skip_users: optionalNumberArray,
@@ -171,7 +178,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_group_projects",
             title: "List Group Projects",
             description: "List projects under a group.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 group_id: z.string(),
                 include_subgroups: optionalBoolean,
@@ -202,7 +209,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_group_iterations",
             title: "List Group Iterations",
             description: "List iterations for a group.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 group_id: z.string().min(1),
                 state: optionalString,
@@ -228,7 +235,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_search_repositories",
             title: "Search Repositories",
             description: "Search repositories by keyword.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 search: z.string().min(1),
                 ...paginationShape
@@ -241,11 +248,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_search_code_blobs",
             title: "Search Code Blobs",
             description: "Search repository code blobs in a specific project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 search: z.string().min(1),
-                ref: optionalString,
+                ref: optionalRefLikeSchema,
                 ...paginationShape
             },
             handler: async (args, context) => context.gitlab.searchCodeBlobs(resolveProjectId(args, context, true), getString(args, "search"), { query: toQuery(omit(args, ["project_id", "search"])) })
@@ -254,11 +261,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_repository_tree",
             title: "Get Repository Tree",
             description: "List files and directories in a repository tree.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 path: optionalString,
-                ref: optionalString,
+                ref: optionalRefLikeSchema,
                 recursive: optionalBoolean,
                 ...paginationShape
             },
@@ -273,11 +280,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_file_contents",
             title: "Get File Contents",
             description: "Get a file in repository by path and ref.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 file_path: z.string().min(1),
-                ref: optionalString
+                ref: optionalRefLikeSchema
             },
             handler: async (args, context) => {
                 const projectId = resolveProjectId(args, context, true);
@@ -293,11 +300,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_or_update_file",
             title: "Create Or Update File",
             description: "Create or update one file in repository.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 file_path: z.string().min(1),
-                branch: z.string().min(1),
+                branch: refLikeSchema,
                 content: z.string(),
                 commit_message: z.string().min(1),
                 previous_path: optionalString,
@@ -328,10 +335,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_push_files",
             title: "Push Files",
             description: "Create a commit with multiple file actions.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                branch: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                branch: refLikeSchema,
                 commit_message: z.string().min(1),
                 actions: z
                     .array(z.object({
@@ -391,11 +398,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_branch",
             title: "Create Branch",
             description: "Create a new branch from an existing ref.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                branch: z.string().min(1),
-                ref: optionalString
+                project_id: optionalProjectIdSchema,
+                branch: refLikeSchema,
+                ref: optionalRefLikeSchema
             },
             handler: async (args, context) => {
                 const projectId = resolveProjectId(args, context, true);
@@ -414,11 +421,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_branch_diffs",
             title: "Get Branch Diffs",
             description: "Compare two branches/refs and return diffs.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                from: z.string().min(1),
-                to: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                from: refLikeSchema,
+                to: refLikeSchema,
                 straight: optionalBoolean,
                 excluded_file_patterns: optionalStringArray
             },
@@ -438,10 +445,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_commits",
             title: "List Commits",
             description: "List commits in a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                ref_name: optionalString,
+                project_id: optionalProjectIdSchema,
+                ref_name: optionalRefLikeSchema,
                 since: optionalString,
                 until: optionalString,
                 path: optionalString,
@@ -464,9 +471,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_commit",
             title: "Get Commit",
             description: "Get one commit by SHA.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 sha: z.string().min(1),
                 stats: optionalBoolean
             },
@@ -481,9 +488,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_commit_diff",
             title: "Get Commit Diff",
             description: "Get diff for one commit.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 sha: z.string().min(1),
                 full_diff: optionalBoolean,
                 ...paginationShape
@@ -499,9 +506,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_merge_requests",
             title: "List Merge Requests",
             description: "List merge requests for a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 assignee_id: optionalStringOrNumber,
                 assignee_username: optionalString,
                 author_id: optionalStringOrNumber,
@@ -527,8 +534,8 @@ function getGitLabToolDefinitions() {
                 ])
                     .optional(),
                 sort: z.enum(["asc", "desc"]).optional(),
-                source_branch: optionalString,
-                target_branch: optionalString,
+                source_branch: optionalRefLikeSchema,
+                target_branch: optionalRefLikeSchema,
                 search: optionalString,
                 wip: z.enum(["yes", "no"]).optional(),
                 with_labels_details: optionalBoolean,
@@ -547,11 +554,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request",
             title: "Get Merge Request",
             description: "Get one merge request.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: optionalString,
-                source_branch: optionalString
+                source_branch: optionalRefLikeSchema
             },
             handler: async (args, context) => {
                 const projectId = resolveProjectId(args, context, true);
@@ -580,14 +587,14 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_merge_request",
             title: "Create Merge Request",
             description: "Create a merge request.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                source_branch: z.string().min(1),
-                target_branch: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                source_branch: refLikeSchema,
+                target_branch: refLikeSchema,
                 title: z.string().min(1),
                 description: optionalString,
-                target_project_id: optionalString,
+                target_project_id: optionalProjectIdSchema,
                 assignee_ids: optionalNumberArray,
                 reviewer_ids: optionalNumberArray,
                 labels: optionalStringOrStringArray,
@@ -618,16 +625,16 @@ function getGitLabToolDefinitions() {
             name: "gitlab_fork_repository",
             title: "Fork Repository",
             description: "Fork an existing project to another namespace.",
-            mutating: true,
+            capabilities: adminCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 namespace: optionalString,
-                namespace_id: optionalString,
+                namespace_id: optionalProjectIdSchema,
                 path: optionalString,
-                name: optionalString,
+                name: optionalDisplayNameSchema,
                 description: optionalString,
                 visibility: z.enum(["private", "internal", "public"]).optional(),
-                default_branch: optionalString
+                default_branch: optionalRefLikeSchema
             },
             handler: async (args, context) => context.gitlab.forkRepository(resolveProjectId(args, context, true), {
                 namespace: getOptionalString(args, "namespace"),
@@ -643,14 +650,14 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_merge_request",
             title: "Update Merge Request",
             description: "Update merge request fields.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
-                source_branch: optionalString,
+                source_branch: optionalRefLikeSchema,
                 title: optionalString,
                 description: optionalString,
-                target_branch: optionalString,
+                target_branch: optionalRefLikeSchema,
                 assignee_ids: optionalNumberArray,
                 reviewer_ids: optionalNumberArray,
                 reviewers: optionalStringArray,
@@ -682,11 +689,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_merge_merge_request",
             title: "Merge Merge Request",
             description: "Merge an existing merge request.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: optionalString,
-                source_branch: optionalString,
+                source_branch: optionalRefLikeSchema,
                 auto_merge: optionalBoolean,
                 merge_when_pipeline_succeeds: optionalBoolean,
                 merge_commit_message: optionalString,
@@ -723,9 +730,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_diffs",
             title: "Get Merge Request Diffs",
             description: "Get MR diffs with changed files.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 view: z.enum(["inline", "parallel"]).optional(),
                 excluded_file_patterns: optionalStringArray
@@ -736,9 +743,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_merge_request_diffs",
             title: "List Merge Request Diffs",
             description: "List detailed MR diffs (versions/changes view).",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 page: optionalNumber,
                 per_page: optionalNumber,
@@ -750,7 +757,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_code_context",
             title: "Get Merge Request Code Context",
             description: "High-signal MR code context with include/exclude filters, sorting, and token-budgeted output.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: mergeRequestCodeContextSchema,
             handler: async (args, context) => getMergeRequestCodeContext({
                 projectId: resolveProjectId(args, context, true),
@@ -771,9 +778,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_merge_request_versions",
             title: "List Merge Request Versions",
             description: "List MR diff versions.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.listMergeRequestVersions(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -782,9 +789,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_version",
             title: "Get Merge Request Version",
             description: "Get one MR diff version.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 version_id: z.string().min(1),
                 unidiff: optionalBoolean
@@ -795,9 +802,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_approve_merge_request",
             title: "Approve Merge Request",
             description: "Approve a merge request.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 sha: optionalString,
                 approval_password: optionalString
@@ -808,9 +815,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_unapprove_merge_request",
             title: "Unapprove Merge Request",
             description: "Remove current user approval from MR.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.unapproveMergeRequest(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -819,9 +826,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_approval_state",
             title: "Get Merge Request Approval State",
             description: "Get approval state for MR.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getMergeRequestApprovalState(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -830,9 +837,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_conflicts",
             title: "Get Merge Request Conflicts",
             description: "Get conflict details for MR.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getMergeRequestConflicts(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -841,9 +848,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_merge_request_discussions",
             title: "List Merge Request Discussions",
             description: "List MR discussions.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 ...paginationShape
             },
@@ -853,11 +860,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_merge_request_thread",
             title: "Create Merge Request Thread",
             description: "Create a new MR discussion thread (supports diff positions).",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
-                body: z.string().min(1),
+                body: bodySchema,
                 position: optionalRecord,
                 created_at: optionalString
             },
@@ -871,9 +878,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_mr_discussions",
             title: "Merge Request Discussions (Alias)",
             description: "Backward-compatible alias of gitlab_list_merge_request_discussions.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 ...paginationShape
             },
@@ -883,12 +890,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_merge_request_discussion_note",
             title: "Create MR Discussion Note",
             description: "Add note to existing MR discussion thread.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 discussion_id: z.string().min(1),
-                body: z.string().min(1),
+                body: bodySchema,
                 created_at: optionalString
             },
             handler: async (args, context) => context.gitlab.createMergeRequestDiscussionNote(resolveProjectId(args, context, true), getString(args, "merge_request_iid"), getString(args, "discussion_id"), {
@@ -900,13 +907,13 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_merge_request_discussion_note",
             title: "Update MR Discussion Note",
             description: "Update note body/resolved state in MR discussion.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 discussion_id: z.string().min(1),
                 note_id: z.string().min(1),
-                body: optionalString,
+                body: optionalBodySchema,
                 resolved: optionalBoolean
             },
             handler: async (args, context) => {
@@ -927,10 +934,10 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_merge_request_discussion_note",
             title: "Delete MR Discussion Note",
-            description: "Delete note from MR discussion thread.",
-            mutating: true,
+            description: "Delete an MR discussion note permanently. Irreversible. Requires merge_request_iid, discussion_id, and note_id. Recommended pre-check: gitlab_list_merge_request_discussions.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 discussion_id: z.string().min(1),
                 note_id: z.string().min(1)
@@ -941,9 +948,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_resolve_merge_request_thread",
             title: "Resolve Merge Request Thread",
             description: "Resolve/unresolve an MR discussion note.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 discussion_id: z.string().min(1),
                 note_id: z.string().min(1),
@@ -955,9 +962,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_merge_request_notes",
             title: "List Merge Request Notes",
             description: "List top-level notes for an MR.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 sort: optionalString,
                 order_by: optionalString,
@@ -969,9 +976,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_notes",
             title: "Get Merge Request Notes (Alias)",
             description: "Backward-compatible alias of gitlab_list_merge_request_notes.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 sort: optionalString,
                 order_by: optionalString,
@@ -983,9 +990,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_draft_note",
             title: "Get Draft Note",
             description: "Get a single merge-request draft note.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 draft_note_id: z.string().min(1)
             },
@@ -995,9 +1002,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_draft_notes",
             title: "List Draft Notes",
             description: "List draft notes on a merge request.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.listDraftNotes(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -1006,11 +1013,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_draft_note",
             title: "Create Draft Note",
             description: "Create a merge-request draft note.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
-                body: z.string().min(1),
+                body: bodySchema,
                 position: optionalRecord,
                 resolve_discussion: optionalBoolean
             },
@@ -1024,12 +1031,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_draft_note",
             title: "Update Draft Note",
             description: "Update a merge-request draft note.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 draft_note_id: z.string().min(1),
-                body: optionalString,
+                body: optionalBodySchema,
                 position: optionalRecord,
                 resolve_discussion: optionalBoolean
             },
@@ -1049,10 +1056,10 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_draft_note",
             title: "Delete Draft Note",
-            description: "Delete a merge-request draft note.",
-            mutating: true,
+            description: "Delete a merge-request draft note permanently. Irreversible. Requires merge_request_iid and draft_note_id. Recommended pre-check: gitlab_get_draft_note or gitlab_list_draft_notes.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 draft_note_id: z.string().min(1)
             },
@@ -1062,9 +1069,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_publish_draft_note",
             title: "Publish Draft Note",
             description: "Publish one merge-request draft note.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 draft_note_id: z.string().min(1)
             },
@@ -1074,9 +1081,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_bulk_publish_draft_notes",
             title: "Bulk Publish Draft Notes",
             description: "Publish all merge-request draft notes.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.bulkPublishDraftNotes(resolveProjectId(args, context, true), getString(args, "merge_request_iid"))
@@ -1085,9 +1092,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_merge_request_note",
             title: "Get Merge Request Note",
             description: "Get a single MR note.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 note_id: z.string().min(1)
             },
@@ -1097,11 +1104,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_merge_request_note",
             title: "Create Merge Request Note",
             description: "Create a top-level MR note.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
-                body: z.string().min(1)
+                body: bodySchema
             },
             handler: async (args, context) => context.gitlab.createMergeRequestNote(resolveProjectId(args, context, true), getString(args, "merge_request_iid"), getString(args, "body"))
         },
@@ -1109,12 +1116,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_note",
             title: "Create Note",
             description: "Create a note on an issue or merge request.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 noteable_type: z.enum(["issue", "merge_request"]),
                 noteable_iid: z.string().min(1),
-                body: z.string().min(1)
+                body: bodySchema
             },
             handler: async (args, context) => context.gitlab.createNote(resolveProjectId(args, context, true), getString(args, "noteable_type"), getString(args, "noteable_iid"), getString(args, "body"))
         },
@@ -1122,22 +1129,22 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_merge_request_note",
             title: "Update Merge Request Note",
             description: "Update MR note body.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 note_id: z.string().min(1),
-                body: z.string().min(1)
+                body: bodySchema
             },
             handler: async (args, context) => context.gitlab.updateMergeRequestNote(resolveProjectId(args, context, true), getString(args, "merge_request_iid"), getString(args, "note_id"), getString(args, "body"))
         },
         {
             name: "gitlab_delete_merge_request_note",
             title: "Delete Merge Request Note",
-            description: "Delete an MR note.",
-            mutating: true,
+            description: "Delete a top-level MR note permanently. Irreversible. Requires merge_request_iid and note_id. Recommended pre-check: gitlab_get_merge_request_note or gitlab_list_merge_request_notes.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 merge_request_iid: z.string().min(1),
                 note_id: z.string().min(1)
             },
@@ -1147,9 +1154,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_issues",
             title: "List Issues",
             description: "List issues in project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 assignee_id: optionalStringOrNumber,
                 assignee_username: optionalStringArray,
                 author_id: optionalStringOrNumber,
@@ -1183,9 +1190,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_my_issues",
             title: "My Issues",
             description: "List issues assigned to the current authenticated user.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 state: z.enum(["opened", "closed", "all"]).optional(),
                 labels: optionalStringOrStringArray,
                 milestone: optionalString,
@@ -1208,9 +1215,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_issue",
             title: "Get Issue",
             description: "Get issue by IID.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getIssue(resolveProjectId(args, context, true), getString(args, "issue_iid"))
@@ -1219,9 +1226,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_issue",
             title: "Create Issue",
             description: "Create a new issue.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 title: z.string().min(1),
                 description: optionalString,
                 labels: optionalStringOrStringArray,
@@ -1246,9 +1253,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_issue",
             title: "Update Issue",
             description: "Update issue fields.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 title: optionalString,
                 description: optionalString,
@@ -1276,10 +1283,10 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_issue",
             title: "Delete Issue",
-            description: "Delete an issue.",
-            mutating: true,
+            description: "Delete an issue permanently. Irreversible. Requires issue_iid. Recommended pre-check: gitlab_get_issue.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.deleteIssue(resolveProjectId(args, context, true), getString(args, "issue_iid"))
@@ -1288,9 +1295,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_issue_discussions",
             title: "List Issue Discussions",
             description: "List issue discussions.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 ...paginationShape
             },
@@ -1300,12 +1307,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_issue_note",
             title: "Create Issue Note",
             description: "Create issue comment (top-level or discussion note).",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 discussion_id: optionalString,
-                body: z.string().min(1),
+                body: bodySchema,
                 created_at: optionalString
             },
             handler: async (args, context) => context.gitlab.createIssueNote(resolveProjectId(args, context, true), getString(args, "issue_iid"), {
@@ -1318,13 +1325,13 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_issue_note",
             title: "Update Issue Note",
             description: "Update an issue discussion note body or resolved state.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 discussion_id: z.string().min(1),
                 note_id: z.string().min(1),
-                body: optionalString,
+                body: optionalBodySchema,
                 resolved: optionalBoolean
             },
             handler: async (args, context) => {
@@ -1343,9 +1350,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_issue_links",
             title: "List Issue Links",
             description: "List related issue links for an issue.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.listIssueLinks(resolveProjectId(args, context, true), getString(args, "issue_iid"))
@@ -1354,9 +1361,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_issue_link",
             title: "Get Issue Link",
             description: "Get a single issue link by ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 issue_link_id: z.string().min(1)
             },
@@ -1366,11 +1373,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_issue_link",
             title: "Create Issue Link",
             description: "Create a relation between two issues.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
-                target_project_id: z.string().min(1),
+                target_project_id: projectIdSchema,
                 target_issue_iid: z.string().min(1),
                 link_type: z.enum(["relates_to", "blocks", "is_blocked_by"]).optional()
             },
@@ -1383,10 +1390,10 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_issue_link",
             title: "Delete Issue Link",
-            description: "Delete a relation between issues.",
-            mutating: true,
+            description: "Delete an issue link permanently. Irreversible for that relation. Requires issue_iid and issue_link_id. Recommended pre-check: gitlab_get_issue_link or gitlab_list_issue_links.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 issue_iid: z.string().min(1),
                 issue_link_id: z.string().min(1)
             },
@@ -1396,10 +1403,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_wiki_pages",
             title: "List Wiki Pages",
             description: "List wiki pages in a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "wiki",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 with_content: optionalBoolean,
                 ...paginationShape
             },
@@ -1411,11 +1418,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_wiki_page",
             title: "Get Wiki Page",
             description: "Get wiki page by slug.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "wiki",
             inputSchema: {
-                project_id: z.string().optional(),
-                slug: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                slug: slugSchema,
                 version: optionalString
             },
             handler: async (args, context) => context.gitlab.getWikiPage(resolveProjectId(args, context, true), getString(args, "slug"), {
@@ -1426,10 +1433,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_wiki_page",
             title: "Create Wiki Page",
             description: "Create a wiki page.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "wiki",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 title: z.string().min(1),
                 content: z.string().min(1),
                 format: optionalString
@@ -1444,11 +1451,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_wiki_page",
             title: "Update Wiki Page",
             description: "Update wiki page by slug.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "wiki",
             inputSchema: {
-                project_id: z.string().optional(),
-                slug: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                slug: slugSchema,
                 content: z.string().min(1),
                 title: optionalString,
                 format: optionalString
@@ -1462,12 +1469,12 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_wiki_page",
             title: "Delete Wiki Page",
-            description: "Delete wiki page by slug.",
-            mutating: true,
+            description: "Delete a wiki page permanently. Irreversible. Requires slug. Recommended pre-check: gitlab_get_wiki_page or gitlab_list_wiki_pages.",
+            capabilities: deleteCapabilities,
             requiresFeature: "wiki",
             inputSchema: {
-                project_id: z.string().optional(),
-                slug: z.string().min(1)
+                project_id: optionalProjectIdSchema,
+                slug: slugSchema
             },
             handler: async (args, context) => context.gitlab.deleteWikiPage(resolveProjectId(args, context, true), getString(args, "slug"))
         },
@@ -1475,10 +1482,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_pipelines",
             title: "List Pipelines",
             description: "List pipelines for a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 scope: z.enum(["running", "pending", "finished", "branches", "tags"]).optional(),
                 status: z
                     .enum([
@@ -1495,7 +1502,7 @@ function getGitLabToolDefinitions() {
                     "scheduled"
                 ])
                     .optional(),
-                ref: optionalString,
+                ref: optionalRefLikeSchema,
                 sha: optionalString,
                 yaml_errors: optionalBoolean,
                 username: optionalString,
@@ -1514,10 +1521,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_pipeline",
             title: "Get Pipeline",
             description: "Get one pipeline.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 pipeline_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getPipeline(resolveProjectId(args, context, true), getString(args, "pipeline_id"))
@@ -1526,12 +1533,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_deployments",
             title: "List Deployments",
             description: "List deployments in a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 environment: optionalString,
-                ref: optionalString,
+                ref: optionalRefLikeSchema,
                 sha: optionalString,
                 status: optionalString,
                 updated_after: optionalString,
@@ -1550,10 +1557,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_deployment",
             title: "Get Deployment",
             description: "Get one deployment by ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 deployment_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getDeployment(resolveProjectId(args, context, true), getString(args, "deployment_id"))
@@ -1562,11 +1569,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_environments",
             title: "List Environments",
             description: "List environments in a project.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
-                name: optionalString,
+                project_id: optionalProjectIdSchema,
+                name: optionalDisplayNameSchema,
                 search: optionalString,
                 states: z.enum(["available", "stopped"]).optional(),
                 ...paginationShape
@@ -1579,10 +1586,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_environment",
             title: "Get Environment",
             description: "Get one environment by ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 environment_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getEnvironment(resolveProjectId(args, context, true), getString(args, "environment_id"))
@@ -1591,10 +1598,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_pipeline_jobs",
             title: "List Pipeline Jobs",
             description: "List jobs in a pipeline.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 pipeline_id: z.string().min(1),
                 scope: z
                     .enum([
@@ -1617,10 +1624,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_pipeline_trigger_jobs",
             title: "List Pipeline Trigger Jobs",
             description: "List downstream/bridge trigger jobs in a pipeline.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 pipeline_id: z.string().min(1),
                 scope: z
                     .enum([
@@ -1646,10 +1653,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_pipeline_job",
             title: "Get Pipeline Job",
             description: "Get one job by job ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getPipelineJob(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1658,10 +1665,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_pipeline_job_output",
             title: "Get Pipeline Job Output",
             description: "Get raw job trace output.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getPipelineJobOutput(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1670,10 +1677,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_job_artifacts",
             title: "List Job Artifacts",
             description: "List files and directories inside a job artifacts archive.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1),
                 path: optionalString,
                 recursive: optionalBoolean
@@ -1684,10 +1691,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_download_job_artifacts",
             title: "Download Job Artifacts",
             description: "Download the full job artifacts archive as base64 content.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.downloadJobArtifacts(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1696,11 +1703,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_download_job_artifacts_local",
             title: "Download Job Artifacts Local",
             description: "Download the full job artifacts archive to a local directory.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             requiresLocalFileTools: true,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1),
                 local_path: optionalString
             },
@@ -1710,10 +1717,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_job_artifact_file",
             title: "Get Job Artifact File",
             description: "Return one file from a job artifacts archive as inline UTF-8 or base64 content.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1),
                 artifact_path: z.string().min(1)
             },
@@ -1723,11 +1730,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_job_artifact_file_local",
             title: "Get Job Artifact File Local",
             description: "Save one file from a job artifacts archive to a local directory.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             requiresLocalFileTools: true,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1),
                 artifact_path: z.string().min(1),
                 local_path: optionalString
@@ -1738,11 +1745,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_pipeline",
             title: "Create Pipeline",
             description: "Trigger a new pipeline.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
-                ref: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                ref: refLikeSchema,
                 inputs: optionalPipelineInputsRecord,
                 variables: z
                     .array(z.object({
@@ -1762,10 +1769,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_retry_pipeline",
             title: "Retry Pipeline",
             description: "Retry failed jobs in pipeline.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 pipeline_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.retryPipeline(resolveProjectId(args, context, true), getString(args, "pipeline_id"))
@@ -1774,10 +1781,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_cancel_pipeline",
             title: "Cancel Pipeline",
             description: "Cancel a running pipeline.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 pipeline_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.cancelPipeline(resolveProjectId(args, context, true), getString(args, "pipeline_id"))
@@ -1786,10 +1793,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_retry_pipeline_job",
             title: "Retry Pipeline Job",
             description: "Retry one failed job.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.retryPipelineJob(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1798,10 +1805,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_cancel_pipeline_job",
             title: "Cancel Pipeline Job",
             description: "Cancel one running job.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.cancelPipelineJob(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1810,10 +1817,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_play_pipeline_job",
             title: "Play Pipeline Job",
             description: "Play a manual job.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "pipeline",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 job_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.playPipelineJob(resolveProjectId(args, context, true), getString(args, "job_id"))
@@ -1822,10 +1829,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_milestones",
             title: "List Milestones",
             description: "List project milestones.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 iids: optionalNumberArray,
                 state: optionalString,
                 title: optionalString,
@@ -1843,10 +1850,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_milestone",
             title: "Get Milestone",
             description: "Get a milestone by ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getMilestone(resolveProjectId(args, context, true), getString(args, "milestone_id"))
@@ -1855,10 +1862,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_milestone",
             title: "Create Milestone",
             description: "Create a milestone.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 title: z.string().min(1),
                 description: optionalString,
                 due_date: optionalString,
@@ -1875,10 +1882,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_milestone",
             title: "Update Milestone",
             description: "Update milestone fields.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1),
                 title: optionalString,
                 description: optionalString,
@@ -1892,10 +1899,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_edit_milestone",
             title: "Edit Milestone (Alias)",
             description: "Backward-compatible alias of gitlab_update_milestone.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1),
                 title: optionalString,
                 description: optionalString,
@@ -1908,11 +1915,11 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_milestone",
             title: "Delete Milestone",
-            description: "Delete a milestone.",
-            mutating: true,
+            description: "Delete a milestone permanently. Irreversible. Requires milestone_id. Recommended pre-check: gitlab_get_milestone or gitlab_list_milestones.",
+            capabilities: deleteCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.deleteMilestone(resolveProjectId(args, context, true), getString(args, "milestone_id"))
@@ -1921,10 +1928,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_milestone_issue",
             title: "Get Milestone Issues",
             description: "List issues assigned to a milestone.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.getMilestoneIssues(resolveProjectId(args, context, true), getString(args, "milestone_id"))
@@ -1933,10 +1940,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_milestone_merge_requests",
             title: "Get Milestone Merge Requests",
             description: "List merge requests assigned to a milestone.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1),
                 ...paginationShape
             },
@@ -1946,10 +1953,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_promote_milestone",
             title: "Promote Milestone",
             description: "Promote a project milestone to a group milestone.",
-            mutating: true,
+            capabilities: adminCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.promoteMilestone(resolveProjectId(args, context, true), getString(args, "milestone_id"))
@@ -1958,10 +1965,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_milestone_burndown_events",
             title: "Get Milestone Burndown Events",
             description: "List burndown events for a milestone.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "milestone",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 milestone_id: z.string().min(1),
                 ...paginationShape
             },
@@ -1971,10 +1978,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_releases",
             title: "List Releases",
             description: "List project releases.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 order_by: z.enum(["released_at", "created_at"]).optional(),
                 sort: z.enum(["asc", "desc"]).optional(),
                 include_html_description: optionalBoolean,
@@ -1988,11 +1995,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_release",
             title: "Get Release",
             description: "Get one release by tag name.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                tag_name: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                tag_name: refLikeSchema,
                 include_html_description: optionalBoolean
             },
             handler: async (args, context) => context.gitlab.getRelease(resolveProjectId(args, context, true), getString(args, "tag_name"), { query: toQuery(omit(args, ["project_id", "tag_name"])) })
@@ -2001,15 +2008,15 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_release",
             title: "Create Release",
             description: "Create a release.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                name: optionalString,
-                tag_name: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                name: optionalDisplayNameSchema,
+                tag_name: refLikeSchema,
                 tag_message: optionalString,
                 description: optionalString,
-                ref: optionalString,
+                ref: optionalRefLikeSchema,
                 released_at: optionalString,
                 milestones: optionalStringArray,
                 assets: optionalRecord
@@ -2020,12 +2027,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_release",
             title: "Update Release",
             description: "Update existing release.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                tag_name: z.string().min(1),
-                name: optionalString,
+                project_id: optionalProjectIdSchema,
+                tag_name: refLikeSchema,
+                name: optionalDisplayNameSchema,
                 description: optionalString,
                 released_at: optionalString,
                 milestones: optionalStringArray,
@@ -2036,12 +2043,12 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_release",
             title: "Delete Release",
-            description: "Delete a release by tag.",
-            mutating: true,
+            description: "Delete the release record for tag_name permanently. Irreversible for the release entry. Requires tag_name. Recommended pre-check: gitlab_get_release or gitlab_list_releases.",
+            capabilities: deleteCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                tag_name: z.string().min(1)
+                project_id: optionalProjectIdSchema,
+                tag_name: refLikeSchema
             },
             handler: async (args, context) => context.gitlab.deleteRelease(resolveProjectId(args, context, true), getString(args, "tag_name"))
         },
@@ -2049,11 +2056,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_release_evidence",
             title: "Create Release Evidence",
             description: "Create evidence for an existing release.",
-            mutating: true,
+            capabilities: writeCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                tag_name: z.string().min(1)
+                project_id: optionalProjectIdSchema,
+                tag_name: refLikeSchema
             },
             handler: async (args, context) => context.gitlab.createReleaseEvidence(resolveProjectId(args, context, true), getString(args, "tag_name"))
         },
@@ -2061,11 +2068,11 @@ function getGitLabToolDefinitions() {
             name: "gitlab_download_release_asset",
             title: "Download Release Asset",
             description: "Download a release asset using its direct asset path.",
-            mutating: false,
+            capabilities: readCapabilities,
             requiresFeature: "release",
             inputSchema: {
-                project_id: z.string().optional(),
-                tag_name: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                tag_name: refLikeSchema,
                 direct_asset_path: z.string().min(1)
             },
             handler: async (args, context) => context.gitlab.downloadReleaseAsset(resolveProjectId(args, context, true), getString(args, "tag_name"), getString(args, "direct_asset_path"))
@@ -2074,9 +2081,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_labels",
             title: "List Labels",
             description: "List project labels.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 with_counts: optionalBoolean,
                 include_ancestor_groups: optionalBoolean,
                 search: optionalString,
@@ -2090,10 +2097,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_label",
             title: "Get Label",
             description: "Get one label by ID.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                label_id: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                label_id: displayNameSchema,
                 include_ancestor_groups: optionalBoolean
             },
             handler: async (args, context) => context.gitlab.getLabel(resolveProjectId(args, context, true), getString(args, "label_id"), {
@@ -2104,10 +2111,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_create_label",
             title: "Create Label",
             description: "Create a label.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                name: z.string().min(1),
+                project_id: optionalProjectIdSchema,
+                name: displayNameSchema,
                 color: z.string().min(1),
                 description: optionalString,
                 priority: optionalNumber
@@ -2118,12 +2125,12 @@ function getGitLabToolDefinitions() {
             name: "gitlab_update_label",
             title: "Update Label",
             description: "Update a label.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                name: optionalString,
-                label_id: optionalString,
-                new_name: optionalString,
+                project_id: optionalProjectIdSchema,
+                name: optionalDisplayNameSchema,
+                label_id: optionalDisplayNameSchema,
+                new_name: optionalDisplayNameSchema,
                 color: optionalString,
                 description: optionalString,
                 priority: optionalNumber
@@ -2142,12 +2149,12 @@ function getGitLabToolDefinitions() {
         {
             name: "gitlab_delete_label",
             title: "Delete Label",
-            description: "Delete a label by name.",
-            mutating: true,
+            description: "Delete a label permanently. Irreversible. Requires name or label_id. Recommended pre-check: gitlab_get_label or gitlab_list_labels.",
+            capabilities: deleteCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                name: optionalString,
-                label_id: optionalString
+                project_id: optionalProjectIdSchema,
+                name: optionalDisplayNameSchema,
+                label_id: optionalDisplayNameSchema
             },
             handler: async (args, context) => {
                 const labelName = getOptionalString(args, "name") ?? getOptionalString(args, "label_id");
@@ -2161,7 +2168,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_namespaces",
             title: "List Namespaces",
             description: "List namespaces visible to user.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 search: optionalString,
                 owned: optionalBoolean,
@@ -2173,10 +2180,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_namespace",
             title: "Get Namespace",
             description: "Get namespace by ID or path.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                namespace_id_or_path: optionalString,
-                namespace_id: optionalString
+                namespace_id_or_path: optionalProjectIdSchema,
+                namespace_id: optionalProjectIdSchema
             },
             handler: async (args, context) => {
                 const namespaceId = getOptionalString(args, "namespace_id_or_path") ??
@@ -2191,7 +2198,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_verify_namespace",
             title: "Verify Namespace",
             description: "Verify if namespace path exists.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 path: z.string().min(1)
             },
@@ -2201,7 +2208,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_users",
             title: "Get Users",
             description: "Search users.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 username: optionalString,
                 search: optionalString,
@@ -2216,7 +2223,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_list_events",
             title: "List Events",
             description: "List current user events.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
                 action: optionalString,
                 target_type: optionalString,
@@ -2232,9 +2239,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_get_project_events",
             title: "Get Project Events",
             description: "List events for a specific project.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 action: optionalString,
                 target_type: optionalString,
                 before: optionalString,
@@ -2250,9 +2257,9 @@ function getGitLabToolDefinitions() {
             name: "gitlab_upload_markdown",
             title: "Upload Markdown",
             description: "Upload markdown file/attachment to project.",
-            mutating: true,
+            capabilities: writeCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
+                project_id: optionalProjectIdSchema,
                 content: optionalString,
                 filename: z.string().default("upload.md"),
                 file_path: optionalString
@@ -2274,10 +2281,10 @@ function getGitLabToolDefinitions() {
             name: "gitlab_download_attachment",
             title: "Download Attachment",
             description: "Download attachment by URL/path and return base64.",
-            mutating: false,
+            capabilities: readCapabilities,
             inputSchema: {
-                project_id: z.string().optional(),
-                url_or_path: optionalString,
+                project_id: optionalProjectIdSchema,
+                url_or_path: optionalUrlOrPathSchema,
                 secret: optionalString,
                 filename: optionalString
             },
@@ -2316,7 +2323,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_execute_graphql_query",
             title: "Execute GraphQL Query",
             description: "Execute read-only GraphQL query.",
-            mutating: false,
+            capabilities: readGraphqlCapabilities,
             inputSchema: {
                 query: z.string().min(1),
                 variables: optionalRecord
@@ -2333,7 +2340,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_execute_graphql_mutation",
             title: "Execute GraphQL Mutation",
             description: "Execute GraphQL mutation (disabled in read-only mode).",
-            mutating: true,
+            capabilities: writeGraphqlCapabilities,
             inputSchema: {
                 query: z.string().min(1),
                 variables: optionalRecord
@@ -2350,7 +2357,7 @@ function getGitLabToolDefinitions() {
             name: "gitlab_execute_graphql",
             title: "Execute GraphQL (Compat)",
             description: "Backward-compatible GraphQL executor. Mutation payloads still honor read-only policy.",
-            mutating: false,
+            capabilities: readGraphqlCapabilities,
             inputSchema: {
                 query: z.string().min(1),
                 variables: optionalRecord
@@ -2360,7 +2367,7 @@ function getGitLabToolDefinitions() {
                 if (containsGraphqlMutation(query)) {
                     context.policy.assertCanExecute({
                         name: "gitlab_execute_graphql",
-                        mutating: true
+                        capabilities: writeGraphqlCapabilities
                     });
                 }
                 return context.gitlab.executeGraphql(query, getOptionalRecord(args, "variables"));