[Code Quality] Create MCP configuration best practices guide

[github-actions]

Description

Create comprehensive documentation for MCP server configuration patterns to address 30+ toolset variations and 95 workflows (57%) missing explicit mode specification. Establish canonical patterns for common use cases and provide clear decision guides for mode/toolset selection.

Current Problem

Configuration chaos:

• 95 workflows out of 166 (57%) missing explicit MCP mode specification
• 30+ variations of GitHub toolset patterns with no clear standard
• Examples of inconsistency:
  • toolsets: [default] (39 workflows)
  • toolsets: [repos, issues, pull_requests] (multiple orderings)
  • toolsets: [all] (3 workflows)
  • toolsets: empty/unclear (15 workflows)

Impact:

• New workflow authors face decision paralysis
• Developers copy inconsistent patterns
• Lack of guidance on best practices
• Trial-and-error development workflow

Documentation Requirements

Create file at: docs/src/content/docs/reference/mcp-configuration-patterns.md

Structure:

1. Mode Selection Guide (remote vs local)

   • When to use mode: remote (hosted MCP servers, production workflows)
   • When to use mode: local (Docker-based, development, custom servers)
   • Default behavior if mode not specified
   • Performance and security considerations

2. GitHub Toolset Patterns (canonical examples)

   # Pattern 1: Basic (recommended for most workflows)
   github:
     mode: remote
     toolsets: [default]
   
   # Pattern 2: Repository management
   github:
     mode: remote
     toolsets: [repos, issues, pull_requests]
   
   # Pattern 3: Code security
   github:
     mode: remote
     toolsets: [repos, code_security]
   
   # Pattern 4: Full access (use sparingly)
   github:
     mode: remote
     toolsets: [all]

3. Toolset Reference

   • Document what [default] includes (link to GitHub MCP server docs)
   • List all available toolsets with descriptions
   • Explain ordering doesn't matter (deduplicated internally)

4. Decision Tree

   • Flowchart or decision table for choosing mode and toolsets
   • Common use cases with recommended patterns
   • Migration guide for workflows missing mode specification

5. Troubleshooting & Best Practices

   • Common configuration mistakes
   • Performance optimization tips
   • Security considerations

Additional Changes

Add validation warning in pkg/workflow/mcp_config_validation.go:

if mcpServer.Mode == "" {
    warnings = append(warnings, fmt.Sprintf(
        "MCP server '%s' missing 'mode' specification. Defaulting to 'remote'. Consider explicitly setting mode for clarity. See: docs/reference/mcp-configuration-patterns",
        serverName))
}

Link from existing docs:

• Update docs/src/content/docs/setup/mcp-server.md to reference new patterns guide
• Add reference in AGENTS.md MCP section
• Include in docs/src/content/docs/guides/getting-started-mcp.md

Success Criteria

• Documentation covers remote vs local mode selection criteria
• GitHub toolset patterns documented with use case examples
• Decision tree for choosing toolsets included
• Examples for common scenarios (basic, advanced, custom)
• Migration guide for workflows missing mode specification
• Validation warning added for missing mode configuration
• Linked from at least 3 existing documentation pages
• make agent-finish passes without errors

Priority

High - Addresses 95 workflows and reduces developer friction

Estimated Effort

Medium (1-2 days) - Documentation creation + validation update

Source

Extracted from MCP Server Integration Quality Report #11508 (Task 2)

Workflow Run: §21287628398

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 9:09 PM UTC