diff --git a/AGENTS.md b/AGENTS.md index a5f1b9f0..03315f0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,17 +21,24 @@ Quick reference for AI agents working with MCP Gateway (Go-based MCP proxy serve ## Project Structure +- `internal/auth/` - Authentication header parsing and middleware - `internal/cmd/` - CLI (Cobra) - `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 with enhanced error logging -- `internal/launcher/` - Backend process management +- `internal/difc/` - Data Information Flow Control +- `internal/envutil/` - Environment variable utilities - `internal/guard/` - Security guards (NoopGuard active) -- `internal/auth/` - Authentication header parsing and middleware +- `internal/launcher/` - Backend process management - `internal/logger/` - Debug logging framework (micro logger) +- `internal/mcp/` - MCP protocol types with enhanced error logging +- `internal/middleware/` - HTTP middleware (jq schema processing) +- `internal/server/` - HTTP server (routed/unified modes) +- `internal/sys/` - System utilities +- `internal/testutil/` - Test utilities and helpers - `internal/timeutil/` - Time formatting utilities +- `internal/tty/` - Terminal detection utilities +- `internal/version/` - Version management ## Key Tech diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 126d0654..47c378f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -211,26 +211,42 @@ awmg/ ├── Dockerfile # Container image ├── Makefile # Build automation └── internal/ + ├── auth/ # Authentication header parsing and middleware ├── cmd/ # CLI commands (cobra) ├── config/ # Configuration loading (TOML/JSON) + ├── difc/ # Data Information Flow Control + ├── envutil/ # Environment variable utilities + ├── guard/ # Security guards (NoopGuard active) ├── launcher/ # Backend server management + ├── logger/ # Debug logging framework ├── mcp/ # MCP protocol types & connection + ├── middleware/ # HTTP middleware (jq schema processing) ├── server/ # HTTP server (routed/unified modes) - ├── guard/ # Security guards (NoopGuard active) - ├── logger/ # Debug logging framework + ├── sys/ # System utilities + ├── testutil/ # Test utilities and helpers ├── timeutil/ # Time formatting utilities - └── tty/ # Terminal detection utilities + ├── tty/ # Terminal detection utilities + └── version/ # Version management ``` ### Key Directories +- **`internal/auth/`** - Authentication header parsing and middleware - **`internal/cmd/`** - CLI implementation using Cobra framework - **`internal/config/`** - Configuration parsing for TOML and JSON formats -- **`internal/server/`** - HTTP server with routed and unified modes -- **`internal/mcp/`** - MCP protocol types and JSON-RPC handling -- **`internal/launcher/`** - Backend process management (Docker, stdio) +- **`internal/difc/`** - Data Information Flow Control +- **`internal/envutil/`** - Environment variable utilities - **`internal/guard/`** - Guard framework for resource labeling +- **`internal/launcher/`** - Backend process management (Docker, stdio) - **`internal/logger/`** - Micro logger for debug output +- **`internal/mcp/`** - MCP protocol types and JSON-RPC handling +- **`internal/middleware/`** - HTTP middleware (jq schema processing) +- **`internal/server/`** - HTTP server with routed and unified modes +- **`internal/sys/`** - System utilities +- **`internal/testutil/`** - Test utilities and helpers +- **`internal/timeutil/`** - Time formatting utilities +- **`internal/tty/`** - Terminal detection utilities +- **`internal/version/`** - Version management ## Coding Conventions diff --git a/README.md b/README.md index 39794313..398ba78a 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,7 @@ See **[Configuration Specification](https://github.com/github/gh-aw/blob/main/do **Configuration Alternatives**: - **`payloadSizeThreshold`** is not supported in JSON stdin format. Use: - - CLI flag: `--payload-size-threshold ` (default: 1024) + - CLI flag: `--payload-size-threshold ` (default: 10240) - Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=` - Payloads **larger** than this threshold are stored to disk and return metadata - Payloads **smaller than or equal** to this threshold are returned inline @@ -278,7 +278,7 @@ Flags: -l, --listen string HTTP server listen address (default "127.0.0.1:3000") --log-dir string Directory for log files (falls back to stdout if directory cannot be created) (default "/tmp/gh-aw/mcp-logs") --payload-dir string Directory for storing large payload files (segmented by session ID) (default "/tmp/jq-payloads") - --payload-size-threshold int Size threshold (in bytes) for storing payloads to disk. Payloads larger than this are stored, smaller ones returned inline (default 1024) + --payload-size-threshold int Size threshold (in bytes) for storing payloads to disk. Payloads larger than this are stored, smaller ones returned inline (default 10240) --routed Run in routed mode (each backend at /mcp/) --sequential-launch Launch MCP servers sequentially during startup (parallel launch is default) --unified Run in unified mode (all backends at /mcp) @@ -316,7 +316,7 @@ When running locally (`run.sh`), these variables are optional (warnings shown if | `MODE` | Gateway mode flag | `--routed` | | `MCP_GATEWAY_LOG_DIR` | Log file directory (sets default for `--log-dir` flag) | `/tmp/gh-aw/mcp-logs` | | `MCP_GATEWAY_PAYLOAD_DIR` | Large payload storage directory (sets default for `--payload-dir` flag) | `/tmp/jq-payloads` | -| `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `1024` | +| `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `10240` | ### Docker Configuration