Skip to content

Add docs on MCP PSIRT toolset - #16129

Open
empty-usr wants to merge 1 commit into
DefectDojo:bugfixfrom
empty-usr:docs/mcp-psirt
Open

empty-usr wants to merge 1 commit into
DefectDojo:bugfixfrom
empty-usr:docs/mcp-psirt

Conversation

@empty-usr

Copy link
Copy Markdown

Description

Documentation only. The DefectDojo Pro MCP Server gains a fifth toolset, psirt, on top of the always-on core toolset and the existing hierarchy, reporting and dashboards toolsets. The MCP Server page already explains how toolsets are selected (?toolsets=…) and gated (Feature Flags), but has no mention of PSIRT. This PR adds the toolset to the existing tables and lists, adds a section describing what it does, and adds one cross-link from the PSIRT chapter so readers of those pages learn the toolset exists.

Changes in docs/content/metrics_reports/ai/mcp_server_pro.md:

  • Toolset table and connection-URL table gain the psirt row (Feature Flag MCP: PSIRT, which can only be enabled while the PSIRT flag is on — itself dependent on Locations and the PSIRT Advisory Engine licence entitlement) and example URLs for ?toolsets=psirt and the all-toolsets combination ?toolsets=hierarchy,reporting,dashboards,psirt.
  • New "PSIRT Toolset" section, placed after the Dashboards section. It covers: the prerequisites (flag chain, DefectDojo Pro 3.4.100 or later, the /api/v2/psirt/ routes, and the View PSIRT / Change PSIRT permissions the read and write tools run under); a call-out separating the two things the UI calls "advisories" — feed items from external publishers (feed_item_id) and advisories your own team authors (advisory_id) — since every tool name and argument follows that split; a call-out that feed content is third-party text the assistant must not treat as instructions; a table of the 12 read tools (psirt_triage_summary, psirt_get_feed_items, psirt_get_feed_item, psirt_get_feed_sources, psirt_get_rules, psirt_get_rule, psirt_preview_rule, psirt_assess_rule, psirt_get_matches, psirt_get_cases, psirt_get_authored_advisories, psirt_get_sla_clocks); a table of the 6 write tools (psirt_triage_feed_item, psirt_write_rule, psirt_write_prefilter, psirt_set_match_status, psirt_manage_case, psirt_manage_advisory); the shared write-result envelope; the two resources (mcp://resource/psirt/rule-schema.json, mcp://resource/psirt/workflow-guide.md); the three prompts (psirt_daily_triage, psirt_explain_match, psirt_design_rule); and example requests. The write call-out follows the pattern of the other toolsets — one REST write per call under DefectDojo's own permission checks, no preview/approval/undo in the server — and adds the PSIRT-specific point that scheduling or publishing an authored advisory cannot be undone, which is why psirt_manage_advisory is marked destructive as a whole and the assistant is instructed to publish only on explicit request.
  • Reference Resources and Pre-Configured Prompts closing paragraphs list the psirt additions alongside the other add-on toolsets' resources and prompts.
  • Troubleshooting step for a refused toolset names the psirt flag and its prerequisite feature, as it already does for the other three toolsets.

Change in docs/content/psirt/_index.md:

  • One short paragraph after the configuration pages list, pointing to the new MCP section (?toolsets=psirt) and noting it runs under the same permissions as the PSIRT pages.

Each PSIRT page the new section links to (psirt/, psirt/feeds/, psirt/feed-rules/, psirt/matching-rules/, psirt/feed-findings/, psirt/cases/, psirt/advisories/) already exists on bugfix; the section links into their existing headings rather than repeating UI behaviour.

Tool names, arguments, counts, resource URIs, prompt names and the destructive/irreversible wording were checked against the MCP Server source for this release (psirt.go, psirt_write.go, resources/psirt/), and the permission and flag statements against the DefectDojo Pro PSIRT API permission class and feature-flag registry that ship in 3.4.100.

Test results

No code changes. The site was built with Hugo from docs/ with no errors; the rendered MCP page contains the new #psirt-toolset anchor, both tool tables and the three call-outs render as tables/blockquotes (no raw Markdown), and all 23 links from the new section — including every anchor into the PSIRT chapter pages — resolve to an existing page and heading id in the rendered output. The new link from psirt/ to metrics_reports/ai/mcp_server_pro/#psirt-toolset also resolves.

Documentation

This PR is the documentation.

Checklist

  • Submitted against bugfix (patch line; docs for a feature shipping in a patch release)
  • Meaningful PR name
  • Docs updated in docs/
  • Python / migrations / unit tests: not applicable (documentation only)
  • Label: docs

Document the psirt toolset of the DefectDojo Pro MCP Server on the MCP
Server page (toolset and URL tables, a PSIRT Toolset section with the 12
read tools, 6 write tools, 2 resources and 3 prompts, and the resource,
prompt and troubleshooting lists) and cross-link it from the PSIRT
chapter index.

Amp-Thread-ID: https://ampcode.com/threads/T-01a08eca-ec9b-72d9-a1a6-58858715eabd
Co-authored-by: Amp <amp@ampcode.com>
@github-actions github-actions Bot added the docs label Sep 29, 2026
@Maffooch Maffooch added this to the 3.4.0 milestone Sep 29, 2026
@mtesauro
mtesauro marked this pull request as ready for review September 30, 2026 20:13

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants