NewMCPServerCommand creates the mcp-server command
()
| 13 | |
| 14 | // NewMCPServerCommand creates the mcp-server command |
| 15 | func NewMCPServerCommand() *cobra.Command { |
| 16 | var port int |
| 17 | var cmdPath string |
| 18 | var validateActor bool |
| 19 | |
| 20 | cmd := &cobra.Command{ |
| 21 | Use: "mcp-server", |
| 22 | Short: "Run an MCP (Model Context Protocol) server exposing gh aw commands as tools", |
| 23 | Long: `Run an MCP server that exposes gh aw CLI commands as MCP tools. |
| 24 | |
| 25 | This command starts an MCP server that wraps the gh aw CLI, spawning subprocess |
| 26 | calls for each tool invocation. This design ensures that GitHub tokens and other |
| 27 | secrets are not shared with the MCP server process itself. |
| 28 | |
| 29 | The server provides the following tools: |
| 30 | - status - Show status of agentic workflow files |
| 31 | - compile - Compile Markdown workflows to GitHub Actions YAML |
| 32 | - logs - Download and analyze workflow logs (requires write access or higher) |
| 33 | - audit - Investigate a workflow run, job, or step and generate a report (requires write access or higher) |
| 34 | - checks - Classify CI check state for a pull request |
| 35 | - mcp-inspect - Inspect MCP servers in workflows and list available tools |
| 36 | - add - Add workflows from remote repositories to .github/workflows |
| 37 | - update - Update workflows from their source repositories |
| 38 | - fix - Apply automatic codemod-style fixes to workflow files |
| 39 | |
| 40 | Access Control: |
| 41 | The GITHUB_ACTOR environment variable specifies the GitHub username for role-based |
| 42 | access control. The actor's repository role (admin, maintain, write, etc.) determines |
| 43 | which tools are available. Tools requiring elevated permissions (logs, audit) are always |
| 44 | mounted but will return permission denied errors if the actor lacks write access or higher. |
| 45 | |
| 46 | Use the --validate-actor flag to enforce actor validation. When enabled, logs and audit |
| 47 | tools will return permission denied errors if GITHUB_ACTOR is not set. When disabled |
| 48 | (default), these tools will work without actor validation. |
| 49 | |
| 50 | By default, the server uses stdio transport. Use the --port flag to run |
| 51 | an HTTP server with SSE (Server-Sent Events) transport instead.`, |
| 52 | Example: ` gh aw mcp-server # Run with stdio transport (default for MCP clients) |
| 53 | gh aw mcp-server --validate-actor # Run with actor validation enforced |
| 54 | gh aw mcp-server --port 8080 # Run HTTP server on port 8080 with SSE transport (for web-based clients) |
| 55 | gh aw mcp-server --cmd ./gh-aw # Use custom gh-aw binary path |
| 56 | GITHUB_ACTOR=octocat gh aw mcp-server # Set actor via environment variable for access control |
| 57 | DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server # Run with verbose debug logging and actor set via environment variable`, |
| 58 | RunE: func(cmd *cobra.Command, args []string) error { |
| 59 | return runMCPServer(cmd.Context(), port, cmdPath, validateActor) |
| 60 | }, |
| 61 | } |
| 62 | |
| 63 | cmd.Flags().IntVarP(&port, "port", "p", 0, "Port to run HTTP server on (uses stdio if not specified)") |
| 64 | cmd.Flags().StringVar(&cmdPath, "cmd", "", "Path to gh aw command to use (defaults to 'gh aw')") |
| 65 | cmd.Flags().BoolVar(&validateActor, "validate-actor", false, "Enforce actor validation (logs/audit tools return errors without GITHUB_ACTOR)") |
| 66 | |
| 67 | return cmd |
| 68 | } |
| 69 | |
| 70 | // runMCPServer starts the MCP server on stdio or HTTP transport |
| 71 | func runMCPServer(ctx context.Context, port int, cmdPath string, validateActor bool) error { |