Skip to content

Commit e8d76c0

Browse files
Copilotpelikhan
Copilot
and
pelikhan
committed
Add awmg standalone CLI for MCP gateway
- Create cmd/awmg/main.go - standalone MCP gateway binary - Update Makefile with build-awmg target and build-all updates - Add awmg to .gitignore for all platforms - Update clean target to remove awmg binaries - Update help target to mention new binary - Add docs/awmg.md - documentation for standalone binary - Update DEVGUIDE.md to include awmg build instructions The awmg binary is a standalone version of the mcp-gateway command that can be distributed and run independently of gh-aw. Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
1 parent 8ade5e1 commit e8d76c0

5 files changed

Lines changed: 260 additions & 2 deletions

File tree

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ Thumbs.db
4343
/gh-aw-darwin-arm64
4444
/gh-aw-linux-amd64
4545
/gh-aw-linux-arm64
46+
/awmg
47+
/awmg-darwin-amd64
48+
/awmg-darwin-arm64
49+
/awmg-linux-amd64
50+
/awmg-linux-arm64
51+
/awmg-windows-amd64.exe
4652

4753
# credentials
4854
.credentials/

‎DEVGUIDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,13 @@ make lint
3838
# Build and test the binary
3939
make build
4040
./gh-aw --help
41+
42+
# Build the awmg (MCP gateway) standalone binary
43+
make build-awmg
44+
./awmg --help
45+
46+
# Build both binaries
47+
make all
4148
```
4249

4350
### 4. Install the Extension Locally for Testing

‎Makefile‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,26 @@
22

33
# Variables
44
BINARY_NAME=gh-aw
5+
AWMG_BINARY_NAME=awmg
56
VERSION ?= $(shell git describe --tags --always --dirty)
67

78
# Build flags
89
LDFLAGS=-ldflags "-s -w -X main.version=$(VERSION)"
910

1011
# Default target
1112
.PHONY: all
12-
all: build
13+
all: build build-awmg
1314

1415
# Build the binary, run make deps before this
1516
.PHONY: build
1617
build: sync-templates sync-action-pins
1718
go build $(LDFLAGS) -o $(BINARY_NAME) ./cmd/gh-aw
1819

20+
# Build the awmg (MCP gateway) binary
21+
.PHONY: build-awmg
22+
build-awmg:
23+
go build $(LDFLAGS) -o $(AWMG_BINARY_NAME) ./cmd/awmg
24+
1925
# Build for all platforms
2026
.PHONY: build-all
2127
build-all: build-linux build-darwin build-windows
@@ -24,15 +30,20 @@ build-all: build-linux build-darwin build-windows
2430
build-linux:
2531
GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o $(BINARY_NAME)-linux-amd64 ./cmd/gh-aw
2632
GOOS=linux GOARCH=arm64 go build $(LDFLAGS) -o $(BINARY_NAME)-linux-arm64 ./cmd/gh-aw
33+
GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o $(AWMG_BINARY_NAME)-linux-amd64 ./cmd/awmg
34+
GOOS=linux GOARCH=arm64 go build $(LDFLAGS) -o $(AWMG_BINARY_NAME)-linux-arm64 ./cmd/awmg
2735

2836
.PHONY: build-darwin
2937
build-darwin:
3038
GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o $(BINARY_NAME)-darwin-amd64 ./cmd/gh-aw
3139
GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o $(BINARY_NAME)-darwin-arm64 ./cmd/gh-aw
40+
GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o $(AWMG_BINARY_NAME)-darwin-amd64 ./cmd/awmg
41+
GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o $(AWMG_BINARY_NAME)-darwin-arm64 ./cmd/awmg
3242

3343
.PHONY: build-windows
3444
build-windows:
3545
GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o $(BINARY_NAME)-windows-amd64.exe ./cmd/gh-aw
46+
GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o $(AWMG_BINARY_NAME)-windows-amd64.exe ./cmd/awmg
3647

3748
# Test the code (runs both unit and integration tests)
3849
.PHONY: test
@@ -170,6 +181,7 @@ clean:
170181
@echo "Cleaning build artifacts..."
171182
@# Remove main binary and platform-specific binaries
172183
rm -f $(BINARY_NAME) $(BINARY_NAME)-*
184+
rm -f $(AWMG_BINARY_NAME) $(AWMG_BINARY_NAME)-*
173185
@# Remove bundle-js binary
174186
rm -f bundle-js
175187
@# Remove coverage files
@@ -464,7 +476,8 @@ agent-finish: deps-dev fmt lint build test-all fix recompile dependabot generate
464476
help:
465477
@echo "Available targets:"
466478
@echo " build - Build the binary for current platform"
467-
@echo " build-all - Build binaries for all platforms"
479+
@echo " build-awmg - Build the awmg (MCP gateway) binary for current platform"
480+
@echo " build-all - Build binaries for all platforms (gh-aw and awmg)"
468481
@echo " test - Run Go tests (unit + integration)"
469482
@echo " test-unit - Run Go unit tests only (faster)"
470483
@echo " test-security - Run security regression tests"

‎cmd/awmg/main.go‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
"os"
6+
7+
"github.com/githubnext/gh-aw/pkg/cli"
8+
"github.com/githubnext/gh-aw/pkg/console"
9+
)
10+
11+
// Build-time variables
12+
var (
13+
version = "dev"
14+
)
15+
16+
func main() {
17+
// Set version info
18+
cli.SetVersionInfo(version)
19+
20+
// Create the mcp-gateway command
21+
cmd := cli.NewMCPGatewayCommand()
22+
23+
// Update command usage to reflect standalone binary
24+
cmd.Use = "awmg"
25+
cmd.Short = "MCP Gateway - Aggregate multiple MCP servers into a single HTTP gateway"
26+
cmd.Long = `awmg (Agentic Workflows MCP Gateway) - Aggregate multiple MCP servers into a single HTTP gateway.
27+
28+
The gateway:
29+
- Integrates by default with the sandbox.mcp extension point
30+
- Imports Claude/Copilot/Codex MCP server JSON configuration
31+
- Starts each MCP server and mounts an MCP client on each
32+
- Mounts an HTTP MCP server that acts as a gateway to the MCP clients
33+
- Supports most MCP gestures through the go-MCP SDK
34+
- Provides extensive logging to file in the MCP log folder
35+
36+
Configuration can be provided via:
37+
1. --config flag pointing to a JSON config file
38+
2. stdin (reads JSON configuration from standard input)
39+
40+
Configuration format:
41+
{
42+
"mcpServers": {
43+
"server-name": {
44+
"command": "command",
45+
"args": ["arg1", "arg2"],
46+
"env": {"KEY": "value"}
47+
}
48+
},
49+
"gateway": {
50+
"port": 8080,
51+
"apiKey": "optional-key"
52+
}
53+
}
54+
55+
Examples:
56+
awmg --config config.json # From file
57+
awmg --port 8080 # From stdin
58+
echo '{"mcpServers":{...}}' | awmg # Pipe config
59+
awmg --config config.json --log-dir /tmp/logs # Custom log dir`
60+
61+
// Add version flag
62+
cmd.Version = version
63+
cmd.SetVersionTemplate("awmg version {{.Version}}\n")
64+
65+
// Execute command
66+
if err := cmd.Execute(); err != nil {
67+
fmt.Fprintf(os.Stderr, "%s\n", console.FormatErrorMessage(err.Error()))
68+
os.Exit(1)
69+
}
70+
}

‎docs/awmg.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# awmg - Agentic Workflows MCP Gateway
2+
3+
`awmg` is a standalone binary that implements an MCP (Model Context Protocol) gateway for aggregating multiple MCP servers into a single HTTP endpoint.
4+
5+
## Installation
6+
7+
### From Source
8+
9+
```bash
10+
# Clone the repository
11+
git clone https://github.com/githubnext/gh-aw.git
12+
cd gh-aw
13+
14+
# Build the binary
15+
make build-awmg
16+
17+
# The binary will be created as ./awmg
18+
```
19+
20+
### Pre-built Binaries
21+
22+
Download the latest release from the [GitHub releases page](https://github.com/githubnext/gh-aw/releases).
23+
24+
## Usage
25+
26+
```bash
27+
# Start gateway with config file
28+
awmg --config config.json
29+
30+
# Start gateway reading from stdin
31+
echo '{"mcpServers":{...}}' | awmg --port 8080
32+
33+
# Custom log directory
34+
awmg --config config.json --log-dir /var/log/mcp-gateway
35+
```
36+
37+
## Configuration
38+
39+
The gateway accepts JSON configuration with the following format:
40+
41+
```json
42+
{
43+
"mcpServers": {
44+
"server-name": {
45+
"command": "command-to-run",
46+
"args": ["arg1", "arg2"],
47+
"env": {
48+
"ENV_VAR": "value"
49+
}
50+
},
51+
"another-server": {
52+
"url": "http://localhost:3000"
53+
}
54+
},
55+
"gateway": {
56+
"port": 8080,
57+
"apiKey": "optional-api-key"
58+
}
59+
}
60+
```
61+
62+
### Configuration Fields
63+
64+
- `mcpServers`: Map of MCP server configurations
65+
- Each server can be configured with:
66+
- `command`: Command to execute (for stdio transport)
67+
- `args`: Command arguments
68+
- `env`: Environment variables
69+
- `url`: HTTP URL (for HTTP transport)
70+
- `gateway`: Gateway-specific settings
71+
- `port`: HTTP port (default: 8080)
72+
- `apiKey`: Optional API key for authentication
73+
74+
## Endpoints
75+
76+
Once running, the gateway exposes the following HTTP endpoints:
77+
78+
- `GET /health` - Health check endpoint
79+
- `GET /servers` - List all configured MCP servers
80+
- `POST /mcp/{server}` - Proxy MCP requests to a specific server
81+
82+
## Examples
83+
84+
### Example 1: Single gh-aw MCP Server
85+
86+
```json
87+
{
88+
"mcpServers": {
89+
"gh-aw": {
90+
"command": "gh",
91+
"args": ["aw", "mcp-server"]
92+
}
93+
},
94+
"gateway": {
95+
"port": 8088
96+
}
97+
}
98+
```
99+
100+
### Example 2: Multiple Servers
101+
102+
```json
103+
{
104+
"mcpServers": {
105+
"gh-aw": {
106+
"command": "gh",
107+
"args": ["aw", "mcp-server"],
108+
"env": {
109+
"DEBUG": "cli:*"
110+
}
111+
},
112+
"remote-server": {
113+
"url": "http://localhost:3000"
114+
}
115+
},
116+
"gateway": {
117+
"port": 8088
118+
}
119+
}
120+
```
121+
122+
## Integration with GitHub Agentic Workflows
123+
124+
The awmg binary is designed to work seamlessly with GitHub Agentic Workflows. When you configure `sandbox.mcp` in your workflow, the system automatically sets up the MCP gateway:
125+
126+
```yaml
127+
---
128+
sandbox:
129+
mcp:
130+
container: ghcr.io/githubnext/mcp-gateway
131+
port: 8080
132+
---
133+
```
134+
135+
## Features
136+
137+
- ✅ **Multiple MCP Servers**: Connect to and manage multiple MCP servers
138+
- ✅ **HTTP Gateway**: Expose all servers through a unified HTTP interface
139+
- ✅ **Protocol Support**: Supports initialize, list_tools, call_tool, list_resources, list_prompts
140+
- ✅ **Comprehensive Logging**: Per-server log files with detailed operation logs
141+
- ✅ **Command Transport**: Subprocess-based MCP servers via stdio
142+
- ⏳ **HTTP Transport**: HTTP/SSE transport (planned)
143+
- ⏳ **Docker Support**: Container-based MCP servers (planned)
144+
145+
## Development
146+
147+
```bash
148+
# Run tests
149+
make test
150+
151+
# Build for all platforms
152+
make build-all
153+
154+
# Clean build artifacts
155+
make clean
156+
```
157+
158+
## See Also
159+
160+
- [MCP Gateway Specification](../specs/mcp-gateway.md)
161+
- [MCP Gateway Usage Guide](mcp-gateway.md)
162+
- [GitHub Agentic Workflows Documentation](https://github.com/githubnext/gh-aw)

0 commit comments

Comments
 (0)