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
- !269309:
save_work_item_saved_viewwithout filters. - This MR: the
filtersargument. Targets the branch of 1. - !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
statustakes 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_pathcan name another project or group, andget_saved_view_work_itemslater reads work items from it. So it is governed too, and the tool rules for that namespace apply. The normalizer already checksread_project/read_group, so this is not about an access bypass. It just keeps tool rules consistent. Bothfull_pathandfullPathcamelize to one key before the mutation runs, so governance reads that camelized value and governs exactly what gets saved. - Fine-grained tokens and
filterWarnings:WorkItemSavedViewFilterWarningTypehad 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: truewarning: the tool is available in CE, only thestatusandhealth_status_filterschema keys are EE. So the changelog stays withoutEE: true.
References
- Issue: #631461
- Proposal and board approval: #636789
- POC with all three tools: !261265 (closed)
- Granular token directive for
filterWarnings: !268921 (merged)
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:
-
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.
-
Open the
gitlab-orgwork 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 -
Approve the save work item saved view tool call.
-
Open the link in Duo's reply. You should see open items with the
buglabel. -
Clean up: delete the Open bugs saved view.
With the Rails console
-
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] -
Check that:
filtersis{"state" => "opened", "labelName" => ["bug"]}. The milestone is gone.filterWarningshas one entry, formilestoneTitle.
-
Open the
shareUrlin the browser. You should see open items with thebuglabel. -
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" -
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.