[dandye]

Summary

This pull request adds automated WCAG 2.1 AA accessibility checks to the Sphinx and Furo documentation build and brings the documentation in docs/ up to date with main.

The changes cover two areas:

1. Automated accessibility enforcement and Furo landmark fixes. Pre-build Markdown linting via markdownlint-cli2, high-contrast syntax-highlighting palettes via accessible-pygments, Furo template overrides in docs/_templates/, a Sphinx html-page-context post-processor in docs/conf.py, and a Playwright and axe-core test suite in docs/tests/test_docs_a11y.py catch contrast, ARIA landmark, heading hierarchy, form label, and keyboard-scrolling violations in both light and dark themes.
2. Documentation reconciliation across servers, clients, and guides. All four MCP server reference pages now match the tools registered on main, totaling 128 core tools across secops-mcp, gti-mcp, secops-soar-mcp, and scc-mcp. In addition, docs/adk_agent.md documents the run-with-google-adk package, docs/index.md populates the Furo left navigation tree, and docs/soar_integrations/index.md and docs/toc.md resolve 40 broken cross-reference warnings across all 305 SOAR integration pages.

Accessibility pipeline and Furo theme fixes

Out of the box, Sphinx 9.0.4, MyST 5.1.0, and Furo 2025.12.19 emit axe-core WCAG 2.1 AA and ARIA landmark violations in light and dark modes. This pull request fixes each violation at the source template or build hook and gates pull requests in .github/workflows/deploy-docs.yml:

Finding in axe-core and WCAG	Root cause in Sphinx, MyST, or Furo	Fix in this pull request
color-contrast, WCAG 1.4.3	#1a73e8 link blue against Furo's #f8f9fb sidebar background measures 4.29:1 against the 4.5:1 minimum, and default Pygments comment and keyword tokens fall below 4.5:1	Set light brand primary to #185abc for 6.5:1 contrast and configure accessible-pygments with a11y-high-contrast-light and a11y-high-contrast-dark in docs/conf.py
landmark-unique and region	Three unlabeled <aside> drawers in Furo's page.html and .content-icon-container rendered outside article[role="main"]	Override docs/_templates/page.html with distinct aria-label attributes on each <aside> and move .content-icon-container inside article#furo-main-content[role="main"]
page-has-heading-one	Furo's search.html omits an <h1> heading	Override docs/_templates/search.html with <h1 class="visually-hidden">Search Documentation</h1> and add aria-hidden="true" focusable="false" to decorative SVGs in docs/_templates/sidebar/custom_github_link.html
aria-required-attr, WCAG 4.1.2	Sphinx {toctree} captions render <p class="caption" role="heading"> without aria-level in both page bodies and furo_navigation_tree	Connect _enhance_body_accessibility to html-page-context at priority=900 so it runs after Furo's priority-500 _compute_navigation_tree hook and sets aria-level="2"
scrollable-region-focusable, WCAG 2.1.1	Horizontally scrollable <pre> code blocks and Furo div.table-wrapper wide-table containers lack keyboard focusability	Set tabindex="0" on <pre> and div.table-wrapper elements in docs/conf.py and assert presence across all built HTML pages in docs/tests/test_docs_a11y.py
label, WCAG 4.1.2	MyST tasklist checkboxes emit <input class="task-list-item-checkbox" type="checkbox" disabled> without accessible names	Derive aria-label from the enclosing list item text in docs/conf.py
Authoring regressions MD001, MD025, MD042, MD045, and MD059	Skipped heading levels, missing image alt text, empty links, and non-descriptive link text such as [here](...) in Markdown sources	Add docs/.markdownlint-cli2.jsonc and make -C docs lint-docs across all 333 Markdown files

GitHub Actions workflow hardening

• .github/workflows/deploy-docs.yml now runs lint-docs, make html, and test-a11y on pull_request events touching docs/** or .github/workflows/deploy-docs.yml without uploading Pages artifacts or deploying to GitHub Pages.
• All five GitHub Actions, actions/checkout, actions/setup-python, actions/setup-node, actions/upload-pages-artifact, and actions/deploy-pages, are pinned to full commit SHAs on Node 24 releases. Checkout sets persist-credentials: false, and pages: write and id-token: write permissions apply only to the deploy job. zizmor --pedantic reports zero findings.
• docs/requirements.txt pins every documentation, parser, theme, and accessibility test package version explicitly.

Documentation updates and tool reconciliation

Navigation and cross-references

• docs/index.md adds hidden {toctree} directives under Getting started, MCP servers, and Workflows and reference to populate Furo's left navigation drawer and previous-and-next page links.
• docs/conf.py sets myst_heading_anchors = 4 so H1 through H4 section anchors resolve across documents and excludes docs/superpowers/ scratch files.
• docs/personas/index.md closes an unclosed {toctree} code fence and includes llm_judge.
• docs/soar_integrations/index.md and docs/toc.md match all 305 integration Markdown files in docs/soar_integrations/, resolving 40 myst.xref_missing warnings, and docs/soar_integrations/nozomi_networks.md fixes a malformed :# Nozomi Networks Integration H1 heading.

Guides and agent integrations

• docs/adk_agent.md. Adds a guide for the mcp-security-agent package in run-with-google-adk/, covering CLI commands info, chat, and serve, environment variables, FastAPI endpoints, authenticated Cloud Run deployment with gemini-3.1-pro-preview and GOOGLE_CLOUD_LOCATION="global", custom sub-agents, and unit tests.
• docs/usage_guide.md. Documents the three installation paths: Remote MCP server, PyPI uvx, and local Git clone via uv --directory. Includes client configurations for Gemini CLI, Antigravity, Goose, Claude Code, Claude Desktop, Cursor, VS Code with Cline, and Google ADK, along with gcloud auth login "$ACCOUNT" --update-adc, SOAR_URL discovery, and per-transport proxy and custom TLS CA variables REQUESTS_CA_BUNDLE, SSL_CERT_FILE, and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH.
• docs/remote_server.md. Documents regional Chronicle endpoints at https://<region>-chronicle.googleapis.com/mcp and the US multi-regional endpoint at https://chronicle.us.rep.googleapis.com/mcp, required IAM roles roles/mcp.toolUser, roles/serviceusage.serviceUsageConsumer, and roles/chronicle.*, Streamable HTTP client configs, and 7-tool feed-administration filtering.
• docs/google_secops_extension.md and docs/development_guide.md. Aligns extension paths and skills secops-setup-gemini, secops-setup-antigravity, secops-triage, secops-investigate, and secops-hunt with extensions/google-secops/, adds an inline Remote vs. local tool mapping table, and documents Optional[T] = None FastMCP parameter typing, stderr lazy %s logging, per-server pytest commands, and local documentation checks.

Server tool reference reconciliation

Every @server.tool() and @mcp.tool() function registered in server/ on main is documented, and non-existent tool names and environment variables have been removed:

Server reference page	Registered tools documented	Key updates
docs/servers/secops_mcp.md	69 of 69	Added missing tools across 13 domain groups including update_rule, curated rule sets and detections, rule exclusions, data tables, reference lists, watchlists, investigations, log ingestion, feed management, and parser management, and closed an unclosed code fence
docs/servers/gti_mcp.md	36 of 36	Documented all collection, file, Digital Threat Monitoring, IOC search, standard YARA hunting ruleset, threat profile, network location, and URL tools, distinguished standard GTI YARA rules from Chronicle YARA-L 2.0 rules, and documented the public VirusTotal upload warning on analyse_file
docs/servers/secops_soar_mcp.md	17 of 17 core plus marketplace	Replaced non-existent examples servicenow_create_ticket and csv_export_case with verified marketplace module tool names service_now_create_incident, csv_csv_search_by_entity, csv_save_json_to_csv, jira_create_issue, and okta_disable_user, and removed non-existent SOAR_USERNAME, SOAR_PASSWORD, and SOAR_INTEGRATIONS variables
docs/servers/scc_mcp.md	6 of 6	Documented all Security Command Center v2 tools search_findings, get_finding_details, search_findings_by_compliance, top_vulnerability_findings, get_finding_remediation, and set_finding_mute with project or organization scope and location parameters

Verification

Run the following commands from the repository root to reproduce all checks locally:

VENV_DIR="/tmp/mcp-docs-venv"

python3 -m venv "$VENV_DIR"
"$VENV_DIR/bin/pip" install -r docs/requirements.txt
"$VENV_DIR/bin/playwright" install chromium --only-shell

# Lint all 333 Markdown files for accessibility rules
PATH="$VENV_DIR/bin:$PATH" make -C docs lint-docs

# Build Sphinx HTML documentation cleanly
PATH="$VENV_DIR/bin:$PATH" make -C docs build

# Run static HTML semantic checks across all built pages and headless Chromium axe-core WCAG 2.1 AA scans in light and dark modes
# Set A11Y_FULL_SCAN=1 to run browser axe-core checks across all 305 SOAR integration pages as well
PATH="$VENV_DIR/bin:$PATH" make -C docs test-a11y

# Audit GitHub Actions workflow security and permissions
uvx zizmor --pedantic .github/workflows/deploy-docs.yml

Related issues and pull requests

• Addresses documentation setup, authentication, proxy, and SOAR marketplace guidance raised in Cline is not starting MCP servers insufficient documentation? #85, Docs: Difficulty configuring with GOOGLE_APPLICATION_CREDENTIALS #89, Docs: Troubleshooting MCP server config #112, Docs: setup friction #123, and documentation update/request for SOAR MCP Marketplace Integrations #151.
• Incorporates and expands the Sphinx documentation updates in Add comprehensive documentation for new SecOps MCP tools #105, docs: address setup friction points and client config pitfalls (#123) #312, and docs(servers): add corporate proxy configuration across server READMEs and Sphinx docs #326.