Merge pull request #59 from githubnext/lpcox/json-schema-v2

feat: Add MCP Gateway configuration spec validation and enhanced secuirty

Author: lpcox

.gitignore

@@ -37,6 +37,8 @@ go.work.sum
 
 # env file
 .env
+.env.*
+.env.githubnext
 
 # Editor/IDE
 # .idea/

AGENTS.md

@@ -17,25 +17,30 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve
 ## Project Structure
 
 - `internal/cmd/` - CLI (Cobra)
-- `internal/config/` - Config parsing (TOML/JSON)
+- `internal/config/` - Config parsing (TOML/JSON) with validation
+  - `validation.go` - Variable expansion and fail-fast validation
+  - `validation_test.go` - 21 comprehensive validation tests
 - `internal/server/` - HTTP server (routed/unified modes)
-- `internal/mcp/` - MCP protocol types
+- `internal/mcp/` - MCP protocol types with enhanced error logging
 - `internal/launcher/` - Backend process management
 - `internal/difc/` - Security labels (not enabled)
 - `internal/guard/` - Security guards (NoopGuard active)
 - `internal/logger/` - Debug logging framework (micro logger)
 - `internal/timeutil/` - Time formatting utilities
-- `internal/tty/` - Terminal detection utilities
 
 ## Key Tech
 
 - **Go 1.25.0** with `cobra`, `toml`, `go-sdk`
 - **Protocol**: JSON-RPC 2.0 over stdio
 - **Routing**: `/mcp/{serverID}` (routed) or `/mcp` (unified)
 - **Docker**: Launches MCP servers as containers
+- **Validation**: Spec-compliant with fail-fast error handling
+- **Variable Expansion**: `${VAR_NAME}` syntax for environment variables
 
 ## Config Examples
 
+**Configuration Spec**: See **[MCP Gateway Configuration Reference](https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md)** for complete specification.
+
 **TOML** (`config.toml`):
 ```toml
 [servers.github]
@@ -45,9 +50,29 @@ args = ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-i", "ghcr.io/gith
 
 **JSON** (stdin):
 ```json
-{"mcpServers": {"github": {"type": "local", "container": "ghcr.io/github/github-mcp-server:latest", "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": ""}}}}
+{
+  "mcpServers": {
+    "github": {
+      "type": "stdio",
+      "container": "ghcr.io/github/github-mcp-server:latest",
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "",
+        "CONFIG_PATH": "${GITHUB_CONFIG_DIR}"
+      }
+    }
+  }
+}
 ```
 
+**Supported Types**: `"stdio"`, `"http"` (not implemented), `"local"` (alias for stdio)
+
+**Validation Features**:
+- Environment variable expansion: `${VAR_NAME}` (fails if undefined)
+- Required fields: `container` for stdio, `url` for http
+- **Note**: The `command` field is not supported - stdio servers must use `container`
+- Port range validation: 1-65535
+- Timeout validation: positive integers only
+
 ## Go Conventions
 
 - Internal packages in `internal/`
@@ -157,12 +182,25 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub auth
 - `DOCKER_API_VERSION` - 1.43 (arm64) or 1.44 (amd64)
 - `PORT`, `HOST`, `MODE` - Server config (via run.sh)
+- `DEBUG` - Enable debug logging (e.g., `DEBUG=*`, `DEBUG=server:*,launcher:*`)
+- `DEBUG_COLORS` - Control colored output (0 to disable, auto-disabled when piping)
+
+## Error Debugging
+
+**Enhanced Error Context**: Command failures include:
+- Full command, args, and environment variables
+- Context-specific troubleshooting suggestions:
+  - Docker daemon connectivity checks
+  - Container image availability
+  - Network connectivity issues
+  - MCP protocol compatibility checks
 
 ## Security Notes
 
 - Auth: `Authorization: Bearer <token>` header
 - Sessions: `Mcp-Session-Id` header
 - DIFC: Implemented but disabled (NoopGuard active)
+- Stdio servers: Containerized execution only (no direct command support)
 
 ## Resources
 

Makefile

@@ -13,12 +13,14 @@ GOLANGCI_LINT_VERSION=v2.2.0
 # Build the CLI binary
 build:
 	@echo "Building $(BINARY_NAME)..."
+	@go mod tidy
 	@go build -o $(BINARY_NAME) .
 	@echo "Build complete: $(BINARY_NAME)"
 
 # Run all linters
 lint:
 	@echo "Running linters..."
+	@go mod tidy
 	@go vet ./...
 	@echo "Running gofmt check..."
 	@test -z "$$(gofmt -l .)" || (echo "The following files are not formatted:"; gofmt -l .; exit 1)
@@ -27,6 +29,7 @@ lint:
 # Run all tests
 test:
 	@echo "Running tests..."
+	@go mod tidy
 	@go test -v ./...
 
 # Run binary integration tests (requires built binary)
@@ -39,7 +42,7 @@ test-integration:
 	@go test -v ./test/integration/...
 
 # Run format, build, lint, and test (for agents before completion)
-agent-finished:
+agent-finished: clean
 	@echo "Running agent-finished checks..."
 	@echo ""
 	@$(MAKE) format
@@ -71,6 +74,7 @@ coverage:
 # Run tests with coverage and JSON output for CI
 test-ci:
 	@echo "Running tests with coverage and JSON output..."
+	@go mod tidy
 	@go test -v -parallel=8 -timeout=3m -coverprofile=coverage.out -json ./... | tee test-result-unit.json
 	@echo "Test results saved to test-result-unit.json"
 	@echo "Coverage profile saved to coverage.out"
@@ -87,6 +91,8 @@ clean:
 	@rm -f $(BINARY_NAME)
 	@rm -f coverage.out
 	@rm -f test-result-unit.json
+	@go mod tidy
+	@go clean
 	@echo "Clean complete!"
 
 # Create and push a release tag

README.md

@@ -4,14 +4,21 @@ A gateway for Model Context Protocol (MCP) servers.
 
 This gateway is used with [GitHub Agentic Workflows](https://github.com/githubnext/gh-aw) via the `sandbox.mcp` configuration to provide MCP server access to AI agents running in sandboxed environments.
 
+📖 **[Full Configuration Specification](https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md)** - Complete reference for all configuration options and validation rules.
+
 ## Features
 
 - **Configuration Modes**: Supports both TOML files and JSON stdin configuration
+  - **Spec-Compliant Validation**: Fail-fast validation with detailed error messages
+  - **Variable Expansion**: Environment variable substitution with `${VAR_NAME}` syntax
+  - **Type Normalization**: Automatic conversion of legacy `"local"` type to `"stdio"`
 - **Routing Modes**: 
   - **Routed**: Each backend server accessible at `/mcp/{serverID}`
   - **Unified**: Single endpoint `/mcp` that routes to configured servers
 - **Docker Support**: Launch backend MCP servers as Docker containers
 - **Stdio Transport**: JSON-RPC 2.0 over stdin/stdout for MCP communication
+- **Container Detection**: Automatic detection of containerized environments with security warnings
+- **Enhanced Debugging**: Detailed error context and troubleshooting suggestions for command failures
 
 ## Getting Started
 
@@ -52,21 +59,75 @@ args = ["/path/to/filesystem-server.js"]
 
 ### JSON Stdin Format
 
+For the complete JSON configuration specification with all validation rules, see the **[MCP Gateway Configuration Reference](https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md)**.
+
 ```json
 {
   "mcpServers": {
     "github": {
-      "type": "local",
+      "type": "stdio",
       "container": "ghcr.io/github/github-mcp-server:latest",
+      "entrypointArgs": ["--verbose"],
       "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
-      },
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "",
+        "EXPANDED_VAR": "${MY_HOME}/config"
+      }
     }
+  },
+  "gateway": {
+    "port": 8080,
+    "apiKey": "your-api-key",
+    "domain": "example.com",
+    "startupTimeout": 30,
+    "toolTimeout": 60
   }
 }
 ```
 
-**Environment Variable Passthrough**: Set the value to an empty string (`""`) to pass through the variable from the host environment.
+#### Server Configuration Fields
+
+- **`type`** (optional): Server transport type
+  - `"stdio"` - Standard input/output transport (default)
+  - `"http"` - HTTP transport (not yet implemented)
+  - `"local"` - Alias for `"stdio"` (backward compatibility)
+
+- **`container`** (required for stdio): Docker container image (e.g., `"ghcr.io/github/github-mcp-server:latest"`)
+  - Automatically wraps as `docker run --rm -i <container>`
+  - **Note**: The `command` field is NOT supported per the specification
+- **`entrypointArgs`** (optional): Arguments passed to container entrypoint
+- **`env`** (optional): Environment variables
+  - Set to `""` (empty string) for passthrough from host environment
+  - Set to `"value"` for explicit value
+  - Use `"${VAR_NAME}"` for environment variable expansion (fails if undefined)
+- **`url`** (required for http): HTTP endpoint URL for `type: "http"` servers
+
+**Validation Rules:**
+
+- **Stdio servers** must specify `container` (required)
+- **HTTP servers** must specify `url` (required)
+- Empty/"local" type automatically normalized to "stdio"
+- Variable expansion with `${VAR_NAME}` fails fast on undefined variables
+- All validation errors include JSONPath and helpful suggestions
+- **The `command` field is not supported** - stdio servers must use `container`
+
+See **[Configuration Specification](https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md)** for complete validation rules.
+
+#### Gateway Configuration Fields (Reserved)
+
+- **`port`** (optional): Gateway HTTP port (default: from `--listen` flag)
+  - Valid range: 1-65535
+- **`apiKey`** (optional): API key for authentication
+- **`domain`** (optional): Domain name for the gateway
+- **`startupTimeout`** (optional): Seconds to wait for backend startup (default: 30)
+  - Must be positive integer
+- **`toolTimeout`** (optional): Seconds to wait for tool execution (default: 60)
+  - Must be positive integer
+
+**Note**: Gateway configuration fields are validated and parsed but not yet fully implemented.
+
+**Environment Variable Features**:
+- **Passthrough**: Set value to empty string (`""`) to pass through from host
+- **Expansion**: Use `${VAR_NAME}` syntax for dynamic substitution (fails if undefined)
 
 ## Usage
 
@@ -109,17 +170,32 @@ Supported JSON-RPC 2.0 methods:
 - `tools/call` - Call a tool with parameters
 - Any other MCP method (forwarded as-is)
 
+## Security Features
+
+### Enhanced Error Debugging
+
+Command failures now include extensive debugging information:
+
+- Full command, arguments, and environment variables
+- Context-specific troubleshooting suggestions:
+  - Docker daemon connectivity checks
+  - Container image availability
+  - Network connectivity issues
+  - MCP protocol compatibility checks
+
 ## Architecture
 
 This Go port focuses on core MCP proxy functionality with optional security features:
 
 ### Core Features (Enabled)
 
-- ✅ TOML and JSON stdin configuration
-- ✅ Stdio transport for backend servers
+- ✅ TOML and JSON stdin configuration with spec-compliant validation
+- ✅ Environment variable expansion (`${VAR_NAME}`) with fail-fast behavior
+- ✅ Stdio transport for backend servers (containerized execution only)
 - ✅ Docker container launching
 - ✅ Routed and unified modes
 - ✅ Basic request/response proxying
+- ✅ Enhanced error debugging and troubleshooting
 
 ### DIFC Integration (Not Yet Enabled)
 

go.mod

@@ -7,6 +7,25 @@ require (
 	github.com/modelcontextprotocol/go-sdk v1.1.0
 	github.com/spf13/cobra v1.10.2
 	golang.org/x/term v0.38.0
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+)
+
+require (
+	github.com/google/jsonschema-go v0.3.0 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sys v0.39.0 // indirect
+)
+
+require (
+	github.com/google/jsonschema-go v0.3.0 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sys v0.39.0 // indirect
 )
 
 require (