Add package documentation to 9 MCP core files

actions/setup/js/create_pull_request.cjs

@@ -82,9 +82,7 @@ async function main(config = {}) {
   }
 
   // Extract triggering issue number from context (for auto-linking PRs to issues)
-  const triggeringIssueNumber = context.payload?.issue?.number && !context.payload?.issue?.pull_request
-    ? context.payload.issue.number
-    : undefined;
+  const triggeringIssueNumber = context.payload?.issue?.number && !context.payload?.issue?.pull_request ? context.payload.issue.number : undefined;
 
   // Check if we're in staged mode
   const isStaged = process.env.GH_AW_SAFE_OUTPUTS_STAGED === "true";

pkg/workflow/mcp_config_builtin.go

@@ -1,3 +1,99 @@
+// Package workflow provides built-in MCP server configuration rendering.
+//
+// # Built-in MCP Servers
+//
+// This file implements rendering functions for gh-aw's built-in MCP servers:
+// safe-outputs, agentic-workflows, and their variations. These servers provide
+// core functionality for AI agent workflows including controlled output storage,
+// workflow execution, and memory management.
+//
+// Key responsibilities:
+//   - Rendering safe-outputs MCP server configuration (HTTP transport)
+//   - Rendering agentic-workflows MCP server configuration (stdio transport)
+//   - Engine-specific format handling (JSON vs TOML)
+//   - Managing HTTP server endpoints and authentication
+//   - Configuring Docker containers for stdio servers
+//   - Handling environment variable passthrough
+//
+// Built-in MCP servers:
+//
+// 1. Safe-outputs MCP server:
+//   - Transport: HTTP (runs on host, accessed via HTTP)
+//   - Port: 3001 (configurable via GH_AW_SAFE_OUTPUTS_PORT)
+//   - Authentication: API key in Authorization header
+//   - Purpose: Provides controlled storage for AI agent outputs
+//   - Tools: add_issue_comment, create_issue, update_issue, upload_asset, etc.
+//
+// 2. Agentic-workflows MCP server:
+//   - Transport: stdio (runs in Docker container)
+//   - Container: Alpine Linux with gh-aw binary mounted
+//   - Entrypoint: /opt/gh-aw/gh-aw mcp-server
+//   - Purpose: Enables workflow compilation, validation, and execution
+//   - Tools: compile, validate, list, status, run, etc.
+//
+// HTTP vs stdio transport:
+// - HTTP: Server runs on host, accessible via HTTP URL with authentication
+// - stdio: Server runs in Docker container, communicates via stdin/stdout
+//
+// Engine compatibility:
+// The renderer supports multiple output formats:
+//   - JSON (Copilot, Claude, Custom): JSON-like MCP configuration
+//   - TOML (Codex): TOML-like MCP configuration
+//
+// Copilot-specific features:
+// When IncludeCopilotFields is true, the renderer adds:
+//   - "type" field: Specifies transport type (http or stdio)
+//   - Backslash-escaped variables: \${VAR} for MCP passthrough
+//
+// Safe-outputs configuration:
+// Safe-outputs runs as an HTTP server and requires:
+//   - Port and API key from step outputs
+//   - Config files: config.json, tools.json, validation.json
+//   - Environment variables for feature configuration
+//
+// The HTTP URL uses either:
+//   - host.docker.internal: When agent runs in firewall container
+//   - localhost: When agent firewall is disabled (sandbox.agent.disabled)
+//
+// Agentic-workflows configuration:
+// Agentic-workflows runs in a stdio container and requires:
+//   - Mounted gh-aw binary from /opt/gh-aw
+//   - Mounted workspace for workflow files
+//   - Mounted temp directory for logs
+//   - GITHUB_TOKEN for GitHub API access
+//
+// Related files:
+//   - mcp_renderer.go: Main renderer that calls these functions
+//   - mcp_setup_generator.go: Generates setup steps for these servers
+//   - safe_outputs.go: Safe-outputs configuration and validation
+//   - safe_inputs.go: Safe-inputs configuration (similar pattern)
+//
+// Example safe-outputs config:
+//
+//	{
+//	  "safe_outputs": {
+//	    "type": "http",
+//	    "url": "http://host.docker.internal:$GH_AW_SAFE_OUTPUTS_PORT",
+//	    "headers": {
+//	      "Authorization": "$GH_AW_SAFE_OUTPUTS_API_KEY"
+//	    }
+//	  }
+//	}
+//
+// Example agentic-workflows config:
+//
+//	{
+//	  "agentic_workflows": {
+//	    "type": "stdio",
+//	    "container": "alpine:3.20",
+//	    "entrypoint": "/opt/gh-aw/gh-aw",
+//	    "entrypointArgs": ["mcp-server"],
+//	    "mounts": ["/opt/gh-aw:/opt/gh-aw:ro", ...],
+//	    "env": {
+//	      "GITHUB_TOKEN": "$GITHUB_TOKEN"
+//	    }
+//	  }
+//	}
 package workflow
 
 import (

pkg/workflow/mcp_config_playwright_renderer.go

@@ -1,3 +1,62 @@
+// Package workflow provides Playwright MCP server configuration and Docker setup.
+//
+// # Playwright MCP Server
+//
+// This file handles the configuration and rendering of the Playwright MCP server,
+// which provides AI agents with browser automation capabilities through the
+// Model Context Protocol (MCP). Playwright enables agents to interact with
+// web pages, take screenshots, extract content, and perform accessibility testing.
+//
+// Key responsibilities:
+//   - Generating Playwright MCP server configuration
+//   - Managing Docker container setup for Playwright
+//   - Handling allowed domains for browser navigation
+//   - Processing custom Playwright arguments
+//   - Extracting and managing domain secrets from expressions
+//   - Rendering configuration for different AI engines
+//
+// Container configuration:
+// Playwright runs in a Docker container using the official Microsoft Playwright
+// MCP image (mcr.microsoft.com/playwright/mcp). The container is configured with:
+//   - --init flag for proper signal handling
+//   - --network host for network access
+//   - Volume mounts for log storage
+//   - Output directory for screenshots and artifacts
+//
+// Domain restrictions:
+// For security, Playwright is restricted to specific allowed domains configured
+// in the workflow frontmatter. These domains are passed via:
+//   - --allowed-hosts: Domains the browser can navigate to
+//   - --allowed-origins: Domains that can be used as origins
+//
+// Expression handling:
+// When allowed_domains contains GitHub Actions expressions like ${{ secrets.DOMAIN }},
+// these are extracted and made available as environment variables. The actual
+// secret values are resolved at runtime and passed to the Playwright container.
+//
+// Engine compatibility:
+// The renderer supports multiple AI engines with engine-specific formatting:
+//   - Copilot: Includes "type" field, inline args
+//   - Claude/Custom: Multi-line args, simplified format
+//   - All engines: Same core configuration structure
+//
+// Related files:
+//   - mcp_playwright_config.go: Playwright configuration types and parsing
+//   - mcp_renderer.go: Main MCP renderer that calls this function
+//   - mcp_setup_generator.go: Includes Playwright in setup sequence
+//
+// Example configuration:
+//
+//	tools:
+//	  playwright:
+//	    version: v1.41.0
+//	    allowed_domains:
+//	      - github.com
+//	      - api.github.com
+//	      - ${{ secrets.CUSTOM_DOMAIN }}
+//	    custom_args:
+//	      - --debug
+//	      - --timeout=30000
 package workflow
 
 import (

pkg/workflow/mcp_config_utils.go

@@ -1,3 +1,45 @@
+// Package workflow provides utility functions for MCP configuration processing.
+//
+// # MCP Configuration Utilities
+//
+// This file contains helper functions for processing and transforming MCP
+// configuration data during workflow compilation. These utilities handle
+// common operations needed across different MCP server types.
+//
+// Key functionality:
+//   - URL rewriting for Docker networking
+//   - Localhost to host.docker.internal translation
+//
+// URL rewriting:
+// When MCP servers run on the host machine (like safe-outputs HTTP server
+// on port 3001) but need to be accessed from within a Docker container
+// (like the firewall container running the AI agent), localhost URLs must
+// be rewritten to use host.docker.internal.
+//
+// This ensures that containerized AI agents can communicate with MCP servers
+// running on the host system while maintaining network isolation.
+//
+// Supported URL patterns:
+//   - http://localhost:port → http://host.docker.internal:port
+//   - https://localhost:port → https://host.docker.internal:port
+//   - http://127.0.0.1:port → http://host.docker.internal:port
+//   - https://127.0.0.1:port → https://host.docker.internal:port
+//
+// Use cases:
+//   - Safe-outputs HTTP server accessed from firewall container
+//   - Safe-inputs HTTP server accessed from firewall container
+//   - Custom HTTP MCP servers on localhost
+//
+// Related files:
+//   - mcp_renderer.go: Uses URL rewriting for HTTP MCP servers
+//   - safe_outputs.go: Safe outputs HTTP server configuration
+//   - safe_inputs.go: Safe inputs HTTP server configuration
+//
+// Example:
+//
+//	// Before: http://localhost:3001
+//	// After:  http://host.docker.internal:3001
+//	url := rewriteLocalhostToDockerHost("http://localhost:3001")
 package workflow
 
 import (

pkg/workflow/mcp_environment.go

@@ -1,3 +1,48 @@
+// Package workflow provides environment variable management for MCP server execution.
+//
+// # MCP Environment Variables
+//
+// This file is responsible for collecting and managing all environment variables
+// required by MCP servers during workflow execution. Environment variables are
+// used to pass configuration, authentication tokens, and runtime settings to
+// MCP servers running in the gateway.
+//
+// Key responsibilities:
+//   - Collecting MCP-related environment variables from workflow configuration
+//   - Managing GitHub MCP server tokens (custom, default, and GitHub App tokens)
+//   - Handling safe-outputs and safe-inputs environment variables
+//   - Processing Playwright domain secrets
+//   - Extracting secrets from HTTP MCP server headers
+//   - Managing agentic-workflows GITHUB_TOKEN
+//
+// Environment variable categories:
+//   - GitHub MCP: GITHUB_MCP_SERVER_TOKEN, GITHUB_MCP_LOCKDOWN
+//   - Safe Outputs: GH_AW_SAFE_OUTPUTS_*, GH_AW_ASSETS_*
+//   - Safe Inputs: GH_AW_SAFE_INPUTS_PORT, GH_AW_SAFE_INPUTS_API_KEY
+//   - Serena: GH_AW_SERENA_PORT (local mode only)
+//   - Playwright: Domain secrets from allowed_domains expressions
+//   - HTTP MCP: Custom secrets from headers and env sections
+//
+// Token precedence for GitHub MCP:
+//  1. GitHub App token (if app configuration exists)
+//  2. Custom github-token from tool configuration
+//  3. Top-level github-token from frontmatter
+//  4. Default GITHUB_TOKEN secret
+//
+// The environment variables collected here are passed to both the
+// "Start MCP gateway" step and the "MCP Gateway" step to ensure
+// MCP servers have access to necessary configuration and secrets.
+//
+// Related files:
+//   - mcp_setup_generator.go: Uses collected env vars in gateway setup
+//   - mcp_github_config.go: GitHub-specific token and configuration
+//   - safe_outputs.go: Safe outputs configuration
+//   - safe_inputs.go: Safe inputs configuration
+//
+// Example usage:
+//
+//	envVars := collectMCPEnvironmentVariables(tools, mcpTools, workflowData, hasAgenticWorkflows)
+//	// Returns map[string]string with all required environment variables
 package workflow
 
 import (

pkg/workflow/mcp_gateway_config.go

@@ -1,3 +1,48 @@
+// Package workflow provides MCP gateway configuration management for agentic workflows.
+//
+// # MCP Gateway Configuration
+//
+// The MCP gateway acts as a proxy between AI engines and MCP servers, providing
+// protocol translation, connection management, and security features. This file
+// handles the configuration and setup of the MCP gateway for workflow execution.
+//
+// Key responsibilities:
+//   - Setting default MCP gateway container and version
+//   - Ensuring gateway configuration exists with sensible defaults
+//   - Building gateway configuration for MCP config files
+//   - Managing gateway port, domain, and API key settings
+//
+// The gateway configuration includes:
+//   - Container image and version (defaults to githubnext/gh-aw-mcpg)
+//   - Network port (default: 80)
+//   - Domain for gateway access (localhost or host.docker.internal)
+//   - API key for authentication
+//   - Volume mounts for workspace and temporary directories
+//
+// Configuration flow:
+//  1. ensureDefaultMCPGatewayConfig: Sets defaults if not provided
+//  2. buildMCPGatewayConfig: Builds gateway config for MCP files
+//  3. isSandboxDisabled: Checks if sandbox features are disabled
+//
+// When sandbox is disabled (sandbox: false), the gateway is skipped entirely
+// and MCP servers communicate directly without the gateway proxy.
+//
+// Related files:
+//   - mcp_gateway_constants.go: Gateway version and container constants
+//   - mcp_setup_generator.go: Setup step generation with gateway startup
+//   - mcp_renderer.go: YAML rendering for MCP configurations
+//
+// Example gateway configuration:
+//
+//	sandbox:
+//	  mcp:
+//	    container: githubnext/gh-aw-mcpg
+//	    version: v0.0.12
+//	    port: 80
+//	    domain: host.docker.internal
+//	    mounts:
+//	      - /opt:/opt:ro
+//	      - /tmp:/tmp:rw
 package workflow
 
 import (

pkg/workflow/mcp_gateway_constants.go

@@ -1,3 +1,33 @@
+// Package workflow provides constants for MCP gateway configuration.
+//
+// # MCP Gateway Constants
+//
+// This file defines default values and constants used by the MCP gateway
+// throughout the workflow compilation process. These constants ensure
+// consistent configuration across different components.
+//
+// Gateway default values:
+//   - Port: 80 (HTTP standard port)
+//
+// The MCP gateway port is used when:
+//   - No custom port is specified in sandbox.mcp.port
+//   - Building gateway configuration in mcp_gateway_config.go
+//   - Generating gateway startup commands in mcp_setup_generator.go
+//
+// Historical note:
+// This constant was originally used with the awmg gateway binary.
+// The binary has been removed but the constant is retained for
+// backwards compatibility with existing workflow configurations.
+//
+// Related files:
+//   - mcp_gateway_config.go: Uses DefaultMCPGatewayPort for configuration
+//   - mcp_setup_generator.go: Uses port for gateway startup
+//   - constants/constants.go: Other MCP-related constants (versions, containers)
+//
+// Related constants in pkg/constants:
+//   - DefaultMCPGatewayVersion: Gateway container version
+//   - DefaultMCPGatewayContainer: Gateway container image
+//   - DefaultGitHubMCPServerVersion: GitHub MCP server version
 package workflow
 
 const (