From 561d38f287dd8b2c7d232ff28aa881a1842c0693 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Mar 2026 12:18:50 +0000 Subject: [PATCH 1/3] Initial plan From 66a58bd7766785b08444938ce3acfa450e77e07c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Mar 2026 12:28:05 +0000 Subject: [PATCH 2/3] Update MCP server docs with editor configs, Docker setup, and custom agent section Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../src/content/docs/agent-factory-status.mdx | 1 + .../docs/reference/gh-aw-as-mcp-server.md | 153 ++++++++++++++---- 2 files changed, 124 insertions(+), 30 deletions(-) diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 11760e6e858..11aa8659b7b 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -10,6 +10,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | Workflow | Agent | Status | Schedule | Command | |:---------|:-----:|:------:|:--------:|:-------:| | [/cloclo](https://github.com/github/gh-aw/blob/main/.github/workflows/cloclo.md) | claude | [![/cloclo](https://github.com/github/gh-aw/actions/workflows/cloclo.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/cloclo.lock.yml) | - | `/cloclo` | +| [ACE Editor Session](https://github.com/github/gh-aw/blob/main/.github/workflows/ace-editor.md) | copilot | [![ACE Editor Session](https://github.com/github/gh-aw/actions/workflows/ace-editor.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/ace-editor.lock.yml) | - | `/ace` | | [Agent Container Smoke Test](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-test-tools.md) | copilot | [![Agent Container Smoke Test](https://github.com/github/gh-aw/actions/workflows/smoke-test-tools.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/smoke-test-tools.lock.yml) | - | - | | [Agent Performance Analyzer - Meta-Orchestrator](https://github.com/github/gh-aw/blob/main/.github/workflows/agent-performance-analyzer.md) | copilot | [![Agent Performance Analyzer - Meta-Orchestrator](https://github.com/github/gh-aw/actions/workflows/agent-performance-analyzer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/agent-performance-analyzer.lock.yml) | - | - | | [Agent Persona Explorer](https://github.com/github/gh-aw/blob/main/.github/workflows/agent-persona-explorer.md) | copilot | [![Agent Persona Explorer](https://github.com/github/gh-aw/actions/workflows/agent-persona-explorer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/agent-persona-explorer.lock.yml) | - | - | diff --git a/docs/src/content/docs/reference/gh-aw-as-mcp-server.md b/docs/src/content/docs/reference/gh-aw-as-mcp-server.md index e386876ef36..02d3a29b300 100644 --- a/docs/src/content/docs/reference/gh-aw-as-mcp-server.md +++ b/docs/src/content/docs/reference/gh-aw-as-mcp-server.md @@ -9,19 +9,6 @@ The `gh aw mcp-server` command exposes the GitHub Agentic Workflows CLI commands This allows your chat system or other workflows to interact with GitHub Agentic Workflows, check their status, download logs, and perform audits programmatically, all while respecting repository permissions and security best practices. -Start the server: - -```bash wrap -gh aw mcp-server -``` - -Or configure for any Model Context Protocol (MCP) host: - -```yaml wrap -command: gh -args: [aw, mcp-server] -``` - ## Configuration Options ### HTTP Server Mode @@ -64,49 +51,155 @@ Restricted tools (logs, audit) require: - Minimum role: write, maintain, or admin - Permission check via GitHub API: `GET /repos/{owner}/{repo}/collaborators/{username}/permission` -## Configuring with GitHub Copilot Agent +## Configuring in Editors + +The MCP server uses stdio transport by default. Most editors accept a `command` and `args` pair to launch it. Run `gh aw init` for automatic setup, or add the configuration manually to your editor's MCP config file. -Configure GitHub Copilot Agent to use gh-aw MCP server: +### Quick Setup ```bash wrap gh aw init ``` -This creates `.github/workflows/copilot-setup-steps.yml` that sets up Go, GitHub CLI, and gh-aw extension before agent sessions start, making workflow management tools available to the agent. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. +`gh aw init` creates `.vscode/mcp.json` and `.github/workflows/copilot-setup-steps.yml` so the server is available in VS Code Copilot Chat and GitHub Copilot Agent sessions. Use `gh aw init --no-mcp` to skip MCP configuration. -## Configuring with Copilot CLI +### VS Code -To add the MCP server in the interactive Copilot CLI session, start `copilot` and run: +Create or update `.vscode/mcp.json` in your repository: -```text -/mcp add github-agentic-workflows gh aw mcp-server +```json title=".vscode/mcp.json" +{ + "servers": { + "github-agentic-workflows": { + "command": "gh", + "args": ["aw", "mcp-server"], + "cwd": "${workspaceFolder}" + } + } +} ``` -## Configuring with VS Code +Reload VS Code after making changes. -Configure VS Code Copilot Chat to use gh-aw MCP server: +### Cursor -```bash wrap -gh aw init +Add the server to `~/.cursor/mcp.json` (create the file if it does not exist): + +```json title="~/.cursor/mcp.json" +{ + "mcpServers": { + "github-agentic-workflows": { + "command": "gh", + "args": ["aw", "mcp-server"] + } + } +} ``` -This creates `.vscode/mcp.json` and `.github/workflows/copilot-setup-steps.yml`. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. +Restart Cursor after saving the file. -Alternatively, create `.vscode/mcp.json` manually: +### Windsurf -```json wrap +Add the server to `~/.codeium/windsurf/mcp_config.json`: + +```json title="~/.codeium/windsurf/mcp_config.json" { - "servers": { + "mcpServers": { + "github-agentic-workflows": { + "command": "gh", + "args": ["aw", "mcp-server"] + } + } +} +``` + +### Claude Desktop + +Locate your Claude Desktop configuration file: + +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +Add the server to the `mcpServers` object: + +```json title="claude_desktop_config.json" +{ + "mcpServers": { "github-agentic-workflows": { "command": "gh", "args": ["aw", "mcp-server"], - "cwd": "${workspaceFolder}" + "env": { + "GITHUB_ACTOR": "YOUR_GITHUB_USERNAME" + } } } } ``` -Reload VS Code after making changes. +Replace `YOUR_GITHUB_USERNAME` with your GitHub username. Restart Claude Desktop after saving. + +### Copilot CLI + +To add the MCP server in the interactive Copilot CLI session, start `copilot` and run: + +```text +/mcp add github-agentic-workflows gh aw mcp-server +``` + +### Any MCP Host (Generic) + +For any MCP-compatible host that accepts a `command` and `args`: + +```yaml wrap +command: gh +args: [aw, mcp-server] +``` + +Or in JSON format: + +```json wrap +{ + "command": "gh", + "args": ["aw", "mcp-server"] +} +``` + +### Docker-based Setup + +If `gh` is not installed locally, use the `ghcr.io/github/gh-aw` Docker image. The image ships with the GitHub CLI and gh-aw pre-installed. + +```json wrap +{ + "command": "docker", + "args": [ + "run", "--rm", "-i", + "-e", "GITHUB_TOKEN", + "-e", "GITHUB_ACTOR", + "ghcr.io/github/gh-aw:latest", + "mcp-server" + ] +} +``` + +Pass your GitHub token via the `GITHUB_TOKEN` environment variable. Add `--validate-actor` to the `args` array to enforce permission checks based on `GITHUB_ACTOR`. + +## Configuring the Custom Agent + +The `agentic-workflows` custom agent provides specialized instructions for creating, updating, importing, and debugging agentic workflows. It works with VS Code Agent Mode, GitHub Copilot Chat, and the Copilot CLI. + +Install the agent with: + +```bash wrap +gh aw init +``` + +This creates `.github/agents/agentic-workflows.agent.md` in your repository. Once installed, invoke it from any supported editor: + +```text wrap +/agent agentic-workflows create a workflow that triages issues +``` + +See [GH-AW Agent](/gh-aw/reference/custom-agent-for-aw/) for the full list of available commands and usage examples. ## Available Tools From 9f17cb3f9fda27ecea0b468dc323e8780a63f1f6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Mar 2026 12:49:11 +0000 Subject: [PATCH 3/3] docs: keep only Docker section, revert other editor/custom-agent changes Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/reference/gh-aw-as-mcp-server.md | 138 ++++-------------- 1 file changed, 32 insertions(+), 106 deletions(-) diff --git a/docs/src/content/docs/reference/gh-aw-as-mcp-server.md b/docs/src/content/docs/reference/gh-aw-as-mcp-server.md index 02d3a29b300..fd3ab6e94e2 100644 --- a/docs/src/content/docs/reference/gh-aw-as-mcp-server.md +++ b/docs/src/content/docs/reference/gh-aw-as-mcp-server.md @@ -9,6 +9,19 @@ The `gh aw mcp-server` command exposes the GitHub Agentic Workflows CLI commands This allows your chat system or other workflows to interact with GitHub Agentic Workflows, check their status, download logs, and perform audits programmatically, all while respecting repository permissions and security best practices. +Start the server: + +```bash wrap +gh aw mcp-server +``` + +Or configure for any Model Context Protocol (MCP) host: + +```yaml wrap +command: gh +args: [aw, mcp-server] +``` + ## Configuration Options ### HTTP Server Mode @@ -51,122 +64,53 @@ Restricted tools (logs, audit) require: - Minimum role: write, maintain, or admin - Permission check via GitHub API: `GET /repos/{owner}/{repo}/collaborators/{username}/permission` -## Configuring in Editors - -The MCP server uses stdio transport by default. Most editors accept a `command` and `args` pair to launch it. Run `gh aw init` for automatic setup, or add the configuration manually to your editor's MCP config file. +## Configuring with GitHub Copilot Agent -### Quick Setup +Configure GitHub Copilot Agent to use gh-aw MCP server: ```bash wrap gh aw init ``` -`gh aw init` creates `.vscode/mcp.json` and `.github/workflows/copilot-setup-steps.yml` so the server is available in VS Code Copilot Chat and GitHub Copilot Agent sessions. Use `gh aw init --no-mcp` to skip MCP configuration. +This creates `.github/workflows/copilot-setup-steps.yml` that sets up Go, GitHub CLI, and gh-aw extension before agent sessions start, making workflow management tools available to the agent. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. -### VS Code +## Configuring with Copilot CLI -Create or update `.vscode/mcp.json` in your repository: - -```json title=".vscode/mcp.json" -{ - "servers": { - "github-agentic-workflows": { - "command": "gh", - "args": ["aw", "mcp-server"], - "cwd": "${workspaceFolder}" - } - } -} -``` - -Reload VS Code after making changes. - -### Cursor - -Add the server to `~/.cursor/mcp.json` (create the file if it does not exist): +To add the MCP server in the interactive Copilot CLI session, start `copilot` and run: -```json title="~/.cursor/mcp.json" -{ - "mcpServers": { - "github-agentic-workflows": { - "command": "gh", - "args": ["aw", "mcp-server"] - } - } -} +```text +/mcp add github-agentic-workflows gh aw mcp-server ``` -Restart Cursor after saving the file. - -### Windsurf +## Configuring with VS Code -Add the server to `~/.codeium/windsurf/mcp_config.json`: +Configure VS Code Copilot Chat to use gh-aw MCP server: -```json title="~/.codeium/windsurf/mcp_config.json" -{ - "mcpServers": { - "github-agentic-workflows": { - "command": "gh", - "args": ["aw", "mcp-server"] - } - } -} +```bash wrap +gh aw init ``` -### Claude Desktop - -Locate your Claude Desktop configuration file: - -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +This creates `.vscode/mcp.json` and `.github/workflows/copilot-setup-steps.yml`. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. -Add the server to the `mcpServers` object: +Alternatively, create `.vscode/mcp.json` manually: -```json title="claude_desktop_config.json" +```json wrap { - "mcpServers": { + "servers": { "github-agentic-workflows": { "command": "gh", "args": ["aw", "mcp-server"], - "env": { - "GITHUB_ACTOR": "YOUR_GITHUB_USERNAME" - } + "cwd": "${workspaceFolder}" } } } ``` -Replace `YOUR_GITHUB_USERNAME` with your GitHub username. Restart Claude Desktop after saving. - -### Copilot CLI - -To add the MCP server in the interactive Copilot CLI session, start `copilot` and run: - -```text -/mcp add github-agentic-workflows gh aw mcp-server -``` - -### Any MCP Host (Generic) - -For any MCP-compatible host that accepts a `command` and `args`: - -```yaml wrap -command: gh -args: [aw, mcp-server] -``` - -Or in JSON format: - -```json wrap -{ - "command": "gh", - "args": ["aw", "mcp-server"] -} -``` +Reload VS Code after making changes. -### Docker-based Setup +## Configuring with Docker -If `gh` is not installed locally, use the `ghcr.io/github/gh-aw` Docker image. The image ships with the GitHub CLI and gh-aw pre-installed. +If `gh` is not installed locally, use the `ghcr.io/github/gh-aw` Docker image. The image ships with the GitHub CLI and gh-aw pre-installed and uses `mcp-server` as the default command. ```json wrap { @@ -183,24 +127,6 @@ If `gh` is not installed locally, use the `ghcr.io/github/gh-aw` Docker image. T Pass your GitHub token via the `GITHUB_TOKEN` environment variable. Add `--validate-actor` to the `args` array to enforce permission checks based on `GITHUB_ACTOR`. -## Configuring the Custom Agent - -The `agentic-workflows` custom agent provides specialized instructions for creating, updating, importing, and debugging agentic workflows. It works with VS Code Agent Mode, GitHub Copilot Chat, and the Copilot CLI. - -Install the agent with: - -```bash wrap -gh aw init -``` - -This creates `.github/agents/agentic-workflows.agent.md` in your repository. Once installed, invoke it from any supported editor: - -```text wrap -/agent agentic-workflows create a workflow that triages issues -``` - -See [GH-AW Agent](/gh-aw/reference/custom-agent-for-aw/) for the full list of available commands and usage examples. - ## Available Tools The MCP server exposes the following tools for workflow management: