feat(core)!: add Duo project settings and GitLab 16.0+ version policy

.github/workflows/release-please.yml

@@ -56,6 +56,24 @@ jobs:
         with:
           token: ${{ steps.app-token.outputs.token }}
 
+      # The packages are version-locked and the core release already carries both
+      # MCPB bundles, so the db GitHub release only duplicates it. Its tag must stay:
+      # release-please locates the previous db release by that tag (skip-github-release
+      # would not create one, leaving the next release without a base), so delete the
+      # release object alone and mark the core release as latest.
+      - name: Drop the duplicate db GitHub release
+        if: steps.release.outputs['packages/gitlab-mcp-db--tag_name'] != ''
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_REPO: ${{ github.repository }}
+          DB_TAG: ${{ steps.release.outputs['packages/gitlab-mcp-db--tag_name'] }}
+          CORE_TAG: ${{ steps.release.outputs['packages/gitlab-mcp--tag_name'] }}
+        run: |
+          gh release delete "$DB_TAG" --yes
+          if [ -n "$CORE_TAG" ]; then
+            gh release edit "$CORE_TAG" --latest
+          fi
+
       # Without a root (".") component, release-please-action does not populate the
       # aggregate `pr` output -- only per-package ones -- so the release PR must be
       # resolved by its deterministic branch instead. The branch is empty when no
@@ -323,11 +341,11 @@ jobs:
       # was extracted to the workspace root.
       - name: Authenticate to MCP Registry (OIDC)
         working-directory: packages/gitlab-mcp
-        run: $GITHUB_WORKSPACE/mcp-publisher login github-oidc
+        run: '"$GITHUB_WORKSPACE/mcp-publisher" login github-oidc'
 
       - name: Publish to MCP Registry
         working-directory: packages/gitlab-mcp
-        run: $GITHUB_WORKSPACE/mcp-publisher publish
+        run: '"$GITHUB_WORKSPACE/mcp-publisher" publish'
 
   # Job 3: Sync generated metadata into the open release PR
   # When release-please updates (not merges) the release PR, regenerate the
@@ -437,23 +455,25 @@ jobs:
     steps:
       - name: Summary
         run: |
-          echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-
-          if [[ "${{ needs.release-please.outputs.release-created }}" == "true" ]]; then
-            echo "🚀 New version released: v${{ needs.release-please.outputs.release-version }}" >> $GITHUB_STEP_SUMMARY
-
-            if [[ "${{ needs.post-release.result }}" == "success" ]]; then
-              echo "✅ All publish steps completed" >> $GITHUB_STEP_SUMMARY
-              echo "📦 npm: @structured-world/gitlab-mcp@${{ needs.release-please.outputs.release-version }}" >> $GITHUB_STEP_SUMMARY
-              echo "🐳 Docker: ghcr.io/${{ env.IMAGE_NAME }}:${{ needs.release-please.outputs.release-version }}" >> $GITHUB_STEP_SUMMARY
-              echo "📦 MCPB: gitlab-mcp-${{ needs.release-please.outputs.release-version }}.mcpb" >> $GITHUB_STEP_SUMMARY
-              echo "🌐 MCP Registry: io.github.structured-world/gitlab-mcp" >> $GITHUB_STEP_SUMMARY
+          {
+            echo "## Release Summary"
+            echo ""
+
+            if [[ "${{ needs.release-please.outputs.release-created }}" == "true" ]]; then
+              echo "🚀 New version released: v${{ needs.release-please.outputs.release-version }}"
+
+              if [[ "${{ needs.post-release.result }}" == "success" ]]; then
+                echo "✅ All publish steps completed"
+                echo "📦 npm: @structured-world/gitlab-mcp@${{ needs.release-please.outputs.release-version }}"
+                echo "🐳 Docker: ghcr.io/${{ env.IMAGE_NAME }}:${{ needs.release-please.outputs.release-version }}"
+                echo "📦 MCPB: gitlab-mcp-${{ needs.release-please.outputs.release-version }}.mcpb"
+                echo "🌐 MCP Registry: io.github.structured-world/gitlab-mcp"
+              else
+                echo "❌ Post-release publish failed"
+              fi
+            elif [[ -n "${{ needs.release-please.outputs.pr-number }}" ]]; then
+              echo "📋 Release PR updated: #${{ needs.release-please.outputs.pr-number }}"
             else
-              echo "❌ Post-release publish failed" >> $GITHUB_STEP_SUMMARY
+              echo "ℹ️ No release-worthy changes detected"
             fi
-          elif [[ -n "${{ needs.release-please.outputs.pr-number }}" ]]; then
-            echo "📋 Release PR updated: #${{ needs.release-please.outputs.pr-number }}" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "ℹ️ No release-worthy changes detected" >> $GITHUB_STEP_SUMMARY
-          fi
+          } >> "$GITHUB_STEP_SUMMARY"

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+Guidance for coding agents and reviewers working on this repository.
+
+## GitLab version support
+
+This server supports **GitLab 16.0 and later** (`MIN_SUPPORTED_VERSION` in
+`packages/gitlab-mcp/src/services/InstanceCapabilities.ts`). It talks to GitLab only
+through REST API v4 and GraphQL.
+
+### Smart MCP, not an API proxy
+
+Tools are an agent-facing layer over GitLab, not a 1:1 proxy: they compose calls,
+translate parameters, filter and reshape results, and emulate behaviour an older or
+lower-tier instance lacks. When a capability is missing on some instances, prefer, in
+order: emulate or degrade (older equivalent, client-side filtering, another endpoint or
+query, dropping a non-essential field), then report partial effect in the result, and
+only then hide or refuse, when GitLab itself cannot provide it. Never gate away
+behaviour a handler already emulates; read the handler before changing its gates.
+
+### Rules
+
+1. **Everything is available from 16.0 unless declared otherwise.** A tool, action or
+   parameter that needs a newer GitLab declares it in its `requirements`
+   (`default`, `actions.<action>` or `parameters.<name>`, each `{ tier, minVersion }`).
+   The registry hides whatever the connected instance does not meet.
+2. **Declare `minVersion` only above the floor.** A value at or below 16.0 is ignored
+   by the gate and must not be written; it only misleads readers.
+3. **Verify every version against GitLab's own sources, never from memory.** For each
+   new or changed endpoint, parameter, GraphQL field, argument or fragment type:
+   - REST: the `{{< history >}}` notes in `doc/api/*.md`, and the Grape
+     `optional`/`requires` declaration in `lib/api` or `ee/lib` at the release tag
+     (`vX.Y.0-ee`). Docs often omit the version of a single parameter; the source at
+     the tag is authoritative.
+   - GraphQL: `doc/api/graphql/reference` at the release tag. GitLab rejects the
+     **whole** query when any selected field, argument or inline-fragment type is
+     unknown, so a single new field gates the entire query and every action using it.
+4. **Version-dependent behaviour in handlers** uses `instanceAtLeast` /
+   `currentInstance` from `packages/gitlab-mcp/src/entities/instance-version.ts` to
+   pick the native path or the emulation. `assertInstanceAtLeast` (a clear error) is
+   only for capabilities GitLab cannot provide on that instance, never a substitute
+   for an emulation that is possible.
+5. **A 200 response is not proof a setting was applied.** GitLab ignores unknown REST
+   parameters and drops license-, add-on- or feature-flag-gated attributes without an
+   error. Where that matters, compare the returned entity with the request (see
+   `packages/gitlab-mcp/src/entities/core/duo-settings.ts`).
+
+### For reviewers
+
+For every added or changed `minVersion`, endpoint, REST parameter or GraphQL selection,
+check the claimed version against the GitLab API documentation or source at that
+release. Flag any GitLab API surface newer than 16.0 that is used without a gate or an
+emulation, any `minVersion` at or below 16.0, and any gate that hides behaviour the
+handler could emulate.

packages/gitlab-mcp/docs/advanced/context-switching.md

@@ -120,11 +120,15 @@ On instance switch:
 
 ### Version Compatibility
 
-| GitLab Version | Work Items API | Iterations | OKRs |
-|----------------|----------------|------------|------|
-| 17.0+ | Full support | Full | Full |
-| 16.x | Partial | Full | Limited |
-| 15.x | Not available | Partial | Not available |
+The server supports GitLab 16.0 and later. Where an older instance lacks newer API
+surface, tools fall back to an equivalent it does have; only actions GitLab itself
+cannot perform there are hidden (and refused if called), for example:
+
+| GitLab Version | Work items |
+|----------------|------------|
+| 18.1+ | All actions, using namespace-level queries |
+| 16.4 - 18.0 | All actions; listing goes through project or group queries, as does lookup by IID where the namespace query is missing |
+| 16.0 - 16.3 | All actions except `add_link` / `remove_link` |
 
 ## Namespace Tier Cache
 

packages/gitlab-mcp/docs/guide/authentication.md

@@ -220,6 +220,6 @@ The server warns when a token expires within 7 days.
 
 ### Scope detection not working
 
-The `/personal_access_tokens/self` endpoint requires GitLab 14.0+. On older versions, the server falls back to attempting operations directly.
+Scope detection uses the `/personal_access_tokens/self` endpoint, available on every supported GitLab version (16.0+). If it fails, the server falls back to attempting operations directly.
 
 For more connection issues, see [Troubleshooting](/troubleshooting/connection).

packages/gitlab-mcp/docs/guide/authentication.md.in

@@ -220,6 +220,6 @@ The server warns when a token expires within 7 days.
 
 ### Scope detection not working
 
-The `/personal_access_tokens/self` endpoint requires GitLab 14.0+. On older versions, the server falls back to attempting operations directly.
+Scope detection uses the `/personal_access_tokens/self` endpoint, available on every supported GitLab version (16.0+). If it fails, the server falls back to attempting operations directly.
 
 For more connection issues, see [Troubleshooting](/troubleshooting/connection).

packages/gitlab-mcp/docs/prompts/ci-cd/trigger-deploy.md

@@ -73,8 +73,8 @@ For pipelines using GitLab's typed inputs feature:
 }
 ```
 
-::: info GitLab 15.5+ Required
-Pipeline inputs require GitLab 15.5 or later. Check your `.gitlab-ci.yml` for `spec.inputs` to see available inputs.
+::: info GitLab 17.10+ Required
+Passing pipeline inputs when creating a pipeline through the API requires GitLab 17.10 or later. Check your `.gitlab-ci.yml` for `spec.inputs` to see available inputs.
 :::
 
 ## Trigger Manual Deploy Jobs

packages/gitlab-mcp/docs/tools/ci-cd.md

@@ -181,7 +181,7 @@ Trigger and control pipeline execution.
 
 :::
 
-### Pipeline Inputs (GitLab 15.5+)
+### Pipeline Inputs (GitLab 17.10+)
 
 For pipelines with typed inputs defined in `.gitlab-ci.yml`:
 
@@ -217,7 +217,7 @@ Trigger with inputs:
 
 ::: tip Variables vs Inputs
 - **`variables`**: Legacy key-value pairs, no type validation
-- **`inputs`**: Typed parameters with schema validation (requires GitLab 15.5+)
+- **`inputs`**: Typed parameters with schema validation (requires GitLab 17.10+ for the pipeline creation API)
 
 You can use both in the same request if needed.
 :::

packages/gitlab-mcp/src/cli/list-tools.ts

@@ -4,7 +4,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { RegistryManager } from '../registry-manager';
-import { getHighestTier, resolveRequirement } from '../services/InstanceCapabilities';
+import {
+  effectiveMinVersion,
+  getHighestTier,
+  resolveRequirement,
+} from '../services/InstanceCapabilities';
 import { EnhancedToolDefinition, ToolRequirements } from '../types';
 import { ProfileLoader, Preset, Profile } from '../profiles';
 
@@ -1747,10 +1751,10 @@ export async function main() {
       const output = filteredTools.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        // Mirror the documented ToolRequirement defaults (tier→free, minVersion→8.0)
-        // when requirements are declared; only an absent requirements block is 'unknown'.
+        // Mirror the documented ToolRequirement defaults (tier->free, minVersion->the
+        // supported floor) when requirements are declared; only an absent block is 'unknown'.
         tier: tool.requirements ? (tool.requirements.default.tier ?? 'free') : 'unknown',
-        minVersion: tool.requirements ? (tool.requirements.default.minVersion ?? '8.0') : undefined,
+        minVersion: tool.requirements ? effectiveMinVersion(tool.requirements.default) : undefined,
         parameters: tool.inputSchema,
       }));
       console.log(JSON.stringify(output, null, 2));

packages/gitlab-mcp/src/entities/access_tokens/registry.ts

@@ -3,12 +3,51 @@
 import { ManageAccessTokenSchema } from './schema';
 import { gitlab, toQuery } from '../../utils/gitlab-api';
 import { ToolRegistry, EnhancedToolDefinition } from '../../types';
-import { assertActionAllowed } from '../utils';
+import { assertActionAllowed, GITLAB_MAX_PER_PAGE } from '../utils';
+import { instanceAtLeast } from '../instance-version';
 
-// Personal/project/group access tokens are Free tier. Project access tokens
-// landed in 13.0, group access tokens in 14.7; the tool degrades per-action
-// rather than gating the whole pair, so the lowest floor is declared here.
-const FREE_REQ = { tier: 'free', minVersion: '13.0' } as const;
+// Personal/project/group access tokens are Free tier; every endpoint used here
+// predates the supported version floor.
+const FREE_REQ = { tier: 'free' } as const;
+
+/** A project/group token list page; `active` drives the client-side state filter. */
+const ListedTokensSchema = z.array(z.looseObject({ active: z.boolean() }));
+
+/**
+ * List project/group tokens, honouring `state`. The server-side filter landed in
+ * GitLab 17.2 (older instances ignore it and return every token), so there it is
+ * applied client-side on each token's `active` flag, before pagination: GitLab's
+ * pages are walked until the requested filtered page is complete or the list ends.
+ */
+async function listScopedTokens(
+  path: string,
+  query: { state?: 'active' | 'inactive'; per_page: number; page?: number },
+) {
+  const { state, per_page: perPage, page = 1 } = query;
+  if (!state || instanceAtLeast('17.2')) {
+    return gitlab.get(path, { query: toQuery(query, []) });
+  }
+  const wanted = page * perPage;
+  const matches: Array<z.infer<typeof ListedTokensSchema>[number]> = [];
+  for (let serverPage = 1; matches.length < wanted; serverPage++) {
+    const parsed = ListedTokensSchema.safeParse(
+      await gitlab.get(path, {
+        query: toQuery({ per_page: GITLAB_MAX_PER_PAGE, page: serverPage }, []),
+      }),
+    );
+    if (!parsed.success) {
+      throw new Error(
+        `GitLab API error: unexpected access tokens response (${parsed.error.issues[0]?.message ?? 'invalid'})`,
+      );
+    }
+    const batch = parsed.data;
+    for (const token of batch) {
+      if (token.active === (state === 'active')) matches.push(token);
+    }
+    if (batch.length < GITLAB_MAX_PER_PAGE) break;
+  }
+  return matches.slice(wanted - perPage, wanted);
+}
 
 const NEW_TOKEN_NOTICE =
   'This response contains a token value shown only once. Store it securely; it cannot be retrieved again.';
@@ -77,16 +116,15 @@
 
           case 'list_project': {
             const { action: _action, project_id, ...query } = input;
-            return gitlab.get(`projects/${encodeURIComponent(project_id)}/access_tokens`, {
-              query: toQuery(query, []),
-            });
+            return listScopedTokens(
+              `projects/${encodeURIComponent(project_id)}/access_tokens`,
+              query,
+            );
           }
 
           case 'list_group': {
             const { action: _action, group_id, ...query } = input;
-            return gitlab.get(`groups/${encodeURIComponent(group_id)}/access_tokens`, {
-              query: toQuery(query, []),
-            });
+            return listScopedTokens(`groups/${encodeURIComponent(group_id)}/access_tokens`, query);
           }
 
           case 'get':

packages/gitlab-mcp/src/entities/audit_events/registry.ts

@@ -5,9 +5,8 @@ import { ToolRegistry, EnhancedToolDefinition } from '../../types';
 import { assertActionAllowed } from '../utils';
 
 // Audit events are a Premium/Ultimate feature; the tier gate hides the tool on
-// lower-tier instances. Instance audit events landed in 12.4, group/project in
-// 12.5/13.1 - the lowest floor is declared here and the tier gate does the rest.
-const PREMIUM_REQ = { tier: 'premium', minVersion: '12.4', notes: 'Audit Events' } as const;
+// lower-tier instances. All endpoints predate the supported version floor.
+const PREMIUM_REQ = { tier: 'premium', notes: 'Audit Events' } as const;
 
 /**
  * Resolve the REST collection path for a single audit event (get action).

packages/gitlab-mcp/src/entities/container_registry/registry.ts

@@ -98,7 +98,9 @@ export const containerRegistryToolRegistry: ToolRegistry = new Map<string, Enhan
       description:
         "Inspect the GitLab Container Registry. Actions: list_repositories (a project's image repositories), get_repository (single repository by ID), list_tags (tags of a repository), get_tag (single tag with manifest digest, size, and timestamps). Related: manage_registry to delete repositories and tags (including regex bulk cleanup).",
       inputSchema: z.toJSONSchema(BrowseRegistrySchema),
-      requirements: { default: { tier: 'free', minVersion: '12.0' } },
+      // Newer detail fields are @optional in the documents, so every action works
+      // from the supported floor and returns what the instance has.
+      requirements: { default: { tier: 'free' } },
       gate: { envVar: 'USE_REGISTRY', defaultValue: true },
       handler: async (args: unknown): Promise<unknown> => {
         const input = BrowseRegistrySchema.parse(args);
@@ -190,7 +192,7 @@ export const containerRegistryToolRegistry: ToolRegistry = new Map<string, Enhan
       description:
         'Delete GitLab Container Registry repositories and tags. Actions: delete_repository (remove a whole repository), delete_tag (remove one tag), delete_tags_bulk (regex cleanup with keep_n/older_than retention - destructive). Related: browse_registry to inspect before deleting.',
       inputSchema: z.toJSONSchema(ManageRegistrySchema),
-      requirements: { default: { tier: 'free', minVersion: '12.0' } },
+      requirements: { default: { tier: 'free' } },
       gate: { envVar: 'USE_REGISTRY', defaultValue: true },
       handler: async (args: unknown): Promise<unknown> => {
         const input = ManageRegistrySchema.parse(args);