Draft: Add filters to the save_work_item_saved_view MCP tool

What does this MR do and why?

!269309 adds save_work_item_saved_view, an MCP tool that creates a saved view with a name, display settings, sort and visibility. This MR, on top of that branch, adds the filters argument, so the agent can create a view like "open issues with the bug label".

Merge order

  1. !269309: save_work_item_saved_view without filters.
  2. This MR: the filters argument. Targets the branch of 1.
  3. !265189: update support. Targets this branch.

!268921 (merged) (granular token permission for filterWarnings) is merged already.

What filters accepts

The board asked for this on 636789: filters declares the common list_work_items keys plus not and or. or has its own plural keys (assignee_usernames, author_usernames, label_names). On Premium and Ultimate, status (by name) and health_status_filter are declared too. The object stays open, so other WorkItemSavedViewFilterInput arguments still pass through.

The UI and the GraphQL mutation take readable values, like label names and usernames. Before saving, WorkItems::SavedViews::FilterNormalizerService turns them into IDs, so label_name: ["bug"] is stored as label IDs. When you read the view back, the type turns the IDs back into names. So the agent can pass the same readable filters a user would type:

{
  "group_id": "gitlab-org",
  "name": "Open bugs",
  "filters": { "state": "opened", "label_name": ["bug"] }
}

Filter keys can be snake_case or camelCase. The tool converts them to the camelCase names that WorkItemSavedViewFilterInput expects. Unknown keys fail with the GraphQL error. A spec checks every declared key against the GraphQL input types.

Telling the agent when a filter was not saved

The normalizer has one catch. If a value matches nothing, like a label that doesn't exist or a typo in a username, it drops that value silently and the save still succeeds. The saved view also has a filterWarnings field, but that only covers stored IDs that stop resolving later (for example, a label deleted after the save). So right after a save it is always empty.

Without a fix, the agent would tell the user "done, I added the bug label filter" when that filter was never saved. So the tool compares the filters it sent with the filters that came back, and adds a warning for each one that is missing or lost some values:

"filterWarnings": [
  { "field": "milestoneTitle", "message": "No matching value found, so this filter was not saved." }
]

This works for nested not and or filters too. Empty or null filters such as label_name: [] are skipped, so they don't warn. Other object filters are compared by presence only. Moving this check into the API is #638188.

The docs get the filters row, a note about filterWarnings, a history line for filters, and an example prompt with a label filter.

Notes for reviewers
  • status takes a name only. The API used to drop a status given by ID. #638187 (closed) fixed that on master, so the tool spec now checks that a status by ID is saved without a warning. The tool schema still takes the name only. Can we add IDs in a follow-up if agents need them?
  • Comparing lists: saved lists come back without duplicates, so ["bug", "bug"] is not reported as a dropped value.
  • Governance: filters.full_path can name another project or group, and get_saved_view_work_items later reads work items from it. So it is governed too, and the tool rules for that namespace apply. The normalizer already checks read_project / read_group, so this is not about an access bypass. It just keeps tool rules consistent. Both full_path and fullPath camelize to one key before the mutation runs, so governance reads that camelized value and governs exactly what gets saved.
  • Fine-grained tokens and filterWarnings: WorkItemSavedViewFilterWarningType had no granular token directive, so a fine-grained token failed as soon as the list had an item. Fixed in !268921 (merged), merged. This MR cannot hit it, because the list is always empty right after a create, but the update tool can.
  • Danger EE: true warning: the tool is available in CE, only the status and health_status_filter schema keys are EE. So the changelog stays without EE: true.

References

Screenshots or screen recordings

Duo Agentic Chat creates a saved view with a label filter

From the gitlab-org work items list, I asked Create a saved view in group gitlab-org called "Bugs to triage" that shows open issues with the bug label. Chat calls save_work_item_saved_view once and asks for approval first. After approval it reports the view and its filters, says no filter was dropped, and links the new view. The view opens with the State, Type and Label filters applied.

How to set up and validate locally

Make sure group gitlab-org has a label called bug.

With Duo Agentic Chat

If you have Duo Agentic Chat working locally, you can test the filters from chat:

  1. Make sure the top-level group has Settings > GitLab Duo > External MCP tools turned on. Without it, chat doesn't get the GitLab MCP tools.

  2. Open the gitlab-org work items list, open GitLab Duo Chat, pick the GitLab Duo agent, and send:

    Create a saved view in group gitlab-org called "Open bugs" that shows open issues with the bug label
  3. Approve the save work item saved view tool call.

  4. Open the link in Duo's reply. You should see open items with the bug label.

  5. Clean up: delete the Open bugs saved view.

With the Rails console

  1. Open a Rails console (gdk rails c):

    user = User.find_by_username('root')
    call = ->(arguments) do
      tool = Mcp::Tools::Manager.new.get_tool(name: 'save_work_item_saved_view')
      tool.set_cred(current_user: user)
      tool.execute(params: { arguments: arguments })
    end
    
    result = call.({
      group_id: 'gitlab-org',
      name: 'Open bugs',
      filters: { state: 'opened', label_name: ['bug'], milestone_title: ['does-not-exist'] }
    })
    result[:structuredContent]
  2. Check that:

    • filters is {"state" => "opened", "labelName" => ["bug"]}. The milestone is gone.
    • filterWarnings has one entry, for milestoneTitle.
  3. Open the shareUrl in the browser. You should see open items with the bug label.

  4. Check the unknown key error:

    call.({ group_id: 'gitlab-org', name: 'x', filters: { colour: 'red' } }).dig(:content, 0, :text)
    # => includes "Field is not defined on WorkItemSavedViewFilterInput"
  5. Clean up: delete the Open bugs view from the work items list.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

🤖 Generated with Claude Code

Edited by Rajan Mistry

Merge request reports

Loading
Loading