Fix OpenCode MCP server integration - Enable safe-outputs and GitHub tools

[Copilot]

Problem

The smoke-opencode workflow was experiencing a 100% failure rate because OpenCode agents couldn't access configured MCP tools (safe-outputs, github, etc.). The root cause was a configuration format mismatch:

• gh-aw generates MCP config in Copilot format at /tmp/gh-aw/mcp-config/mcp-servers.json
• OpenCode requires configuration at ~/.config/opencode/opencode.json in its own format
• No transformation bridge existed between these formats

Evidence from audit logs showed:

Output file does not exist: /tmp/gh-aw/safe-outputs/outputs.jsonl
Agent stdio log: "Custom steps execution completed"

The agent was instructed to "use the create-issue tool from the safe-outputs MCP" but had no access to it.

Solution

This PR adds automatic MCP configuration transformation for OpenCode workflows by modifying .github/workflows/shared/opencode.md:

1. Added jq installation for JSON transformation
2. Added "Configure OpenCode MCP servers" step that:
   • Reads the gh-aw MCP config from $GH_AW_MCP_CONFIG
   • Transforms format using jq pipeline
   • Writes OpenCode-compatible config to ~/.config/opencode/opencode.json

Format Transformation

Local (stdio) MCP servers:

// Before (Copilot format)
{
  "command": "docker",
  "args": ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server:v0.19.0"],
  "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "..."}
}

// After (OpenCode format)
{
  "type": "local",
  "command": ["docker", "run", "-i", "--rm", "ghcr.io/github/github-mcp-server:v0.19.0"],
  "enabled": true,
  "environment": {"GITHUB_PERSONAL_ACCESS_TOKEN": "..."}
}

Remote (HTTP) MCP servers:

// Before (Copilot format)
{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "headers": {"API_KEY": "${API_KEY}"}
}

// After (OpenCode format)
{
  "type": "remote",
  "url": "https://api.example.com/mcp",
  "enabled": true,
  "headers": {"API_KEY": "${API_KEY}"}
}

Benefits

• ✅ Fixes 100% failure rate in smoke-opencode workflow
• ✅ Enables OpenCode agents to access safe-outputs MCP tools (create_issue, etc.)
• ✅ Enables access to GitHub MCP server for repository operations
• ✅ Automatic configuration for any MCP server type (local/remote)
• ✅ No workflow-specific changes needed - works for all OpenCode workflows
• ✅ Graceful fallback when no MCP config exists

Testing

• ✅ All unit tests pass: make test-unit
• ✅ Linting passes: make lint
• ✅ Full validation passes: make agent-finish
• ✅ Workflow compiles successfully: gh aw compile smoke-opencode
• ✅ Transformation tested with both local and HTTP MCP servers

Security

• No secrets exposed in configuration
• Secret references (${{ secrets.* }}) preserved during transformation
• jq installed from trusted Ubuntu apt repository
• No changes to permission model

Fixes #2143

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[q] Fix OpenCode MCP server integration - Enable safe-outputs tools</issue_title>
<issue_description># Q Workflow Optimization Report

Issues Found (from live data)

smoke-opencode Workflow

Log Analysis: Analyzed 4 consecutive failed runs of the smoke-opencode workflow
Run IDs Analyzed: 18722224746, 18715612738, 18725510532, 18706992084
Pattern: 100% failure rate - all runs completed successfully but failed to create expected outputs

Issues Identified:

• Missing MCP Tools: OpenCode agent had NO access to safe-outputs MCP server
• Configuration Gap: No opencode.json file created despite MCP servers being configured in workflow
• Agent Behavior: Agent completed tasks but couldn't use create_issue tool from safe-outputs MCP

Evidence from logs (Run githubnext/gh-aw#18722224746):

Output file does not exist: /tmp/gh-aw/safe-outputs/outputs.jsonl

Agent stdio log: "Custom steps execution completed"

The agent was instructed in the prompt: "To create an issue, use the create-issue tool from the safe-outputs MCP" but had no access to this tool.

Root Cause Analysis

Technical Problem

OpenCode requires MCP servers to be configured in ~/.config/opencode/opencode.json:

{
  "$schema": "(redacted)",
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["npx", "mcp-server"],
      "enabled": true
    }
  }
}

Current Implementation (Broken):

• shared/opencode.md installs OpenCode and runs it directly
• No MCP configuration file created
• Agent runs in isolation without access to ANY MCP tools
• GH_AW_MCP_CONFIG environment variable provided but unused

Comparison with GenAIScript (Working):

• GenAIScript accepts --mcp-config CLI parameter
• Reads MCP config from file path at runtime
• Properly configured in shared/genaiscript.md (line 43)

Changes Made

.github/workflows/shared/opencode.md

1. Added jq Installation (Step renamed to "Install OpenCode and jq"):

- name: Install OpenCode and jq
  run: |
    npm install -g opencode-ai@${GH_AW_AGENT_VERSION}
    sudo apt-get update && sudo apt-get install -y jq

Required for JSON transformation between Copilot and OpenCode MCP config formats.

2. Added MCP Configuration Step (New step before "Run OpenCode"):

- name: Configure OpenCode MCP servers
  run: |
    set -e
    
    # Create OpenCode config directory
    mkdir -p ~/.config/opencode
    
    # Check if MCP config exists
    if [ -n "$GH_AW_MCP_CONFIG" ] && [ -f "$GH_AW_MCP_CONFIG" ]; then
      echo "Found MCP configuration at: $GH_AW_MCP_CONFIG"
      
      # Create base OpenCode config with proper schema
      echo '{"$schema": "(redacted)", "mcp": {}}' > ~/.config/opencode/opencode.json
      
      # Transform Copilot-style MCP config to OpenCode format
      jq -r '.mcpServers | to_entries[] | 
        if .value.type == "local" then
          {
            key: .key,
            value: {
              type: "local",
              command: ([.value.command] + (.value.args // [])),
              enabled: true,
              environment: (.value.env // {})
            }
          }
        elif .value.type == "http" then
          {
            key: .key,
            value: {
              type: "remote",
              url: .value.url,
              enabled: true,
              headers: (.value.headers // {})
            }
          }
        else empty end' "$GH_AW_MCP_CONFIG" | \
        jq -s 'reduce .[] as $item ({}; .[$item.key] = $item.value)' > /tmp/mcp-servers.json
      
      # Merge MCP servers into config
      jq --slurpfile servers /tmp/mcp-servers.json '.mcp = $servers[0]' \
        ~/.config/opencode/opencode.json > /tmp/opencode-final.json
      mv /tmp/opencode-final.json ~/.config/opencode/opencode.json
      
      echo "✅ OpenCode MCP configuration created successfully"
      echo "Configuration contents:"
      cat ~/.config/opencode/opencode.json | jq .
    else
      echo "⚠️  No MCP config found - OpenCode will run without MCP tools"
    fi
  env:
    GH_AW_MCP_CONFIG: ${{ env.GH_AW_MCP_CONFIG }}

Key Features:

• Transforms gh-aw's Copilot-style MCP config to OpenCode format
• Handles both local (stdio) and remote (HTTP) MCP servers
• Preserves environment variables and headers
• Merges command and args into single array for OpenCode
• Logs configuration for debugging

3. Updated Documentation (HTML comment section):

• Added MCP Server Integration section
• Documented automatic configuration process
• Listed required dependencies (jq)
• Explained format transformation

Expected Improvements

Immediate Benefits

• ✅ Fixed smoke-opencode failures: Agent will now have access to safe-outputs MCP tools
• ✅ Enabled issue creation: create_issue tool will be available to OpenCode agent
• ✅ 100% → Target 90%+ success rate: Eliminates pr...

Fixes #2164

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

Agentic Changeset Generator triggered by this pull request.