Skip to content

Fix documentation discrepancies: payload threshold and internal directories #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 2 commits into from
Feb 11, 2026
Merged

Fix documentation discrepancies: payload threshold and internal directories #889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9906684
Initial plan
Claude Feb 11, 2026
895dae4
Fix documentation discrepancies: payload threshold and internal direc…
Claude Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

internal/difc/ is described as “Data Information Flow Control”, but the package docs define DIFC as “Decentralized Information Flow Control” (see internal/difc/DIFC_RULES.md). Please update the wording here for accuracy/consistency.

Suggested change
- `internal/difc/` - Data Information Flow Control
- `internal/difc/` - Decentralized Information Flow Control

Copilot uses AI. Check for mistakes.
- `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

Expand Down
28 changes: 22 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines 213 to +217
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

internal/difc/ is described as “Data Information Flow Control”, but the package documentation defines DIFC as “Decentralized Information Flow Control”. Please update the description here (and keep it consistent across docs).

This issue also appears on line 237 of the same file.

Suggested change
└── internal/
├── auth/ # Authentication header parsing and middleware
├── cmd/ # CLI commands (cobra)
├── config/ # Configuration loading (TOML/JSON)
├── difc/ # Data Information Flow Control
└── internal/
├── auth/ # Authentication header parsing and middleware
├── cmd/ # CLI commands (cobra)
├── config/ # Configuration loading (TOML/JSON)
├── difc/ # Decentralized Information Flow Control

Copilot uses AI. Check for mistakes.
├── 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

Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <bytes>` (default: 1024)
- CLI flag: `--payload-size-threshold <bytes>` (default: 10240)
- Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=<bytes>`
Comment on lines +205 to 206
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README is updated to 10240 bytes for the default payload size threshold, but PAYLOAD_THRESHOLD_IMPLEMENTATION.md in this repo still documents the default as 1024 bytes in multiple places. Please update that doc as well (or remove it if it’s obsolete) to avoid ongoing documentation drift.

Suggested change
- CLI flag: `--payload-size-threshold <bytes>` (default: 10240)
- Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=<bytes>`
- CLI flag: `--payload-size-threshold <bytes>` (default value is implementation-defined)
- Environment variable: `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=<bytes>` (uses the same default as the CLI flag when unset)

Copilot uses AI. Check for mistakes.
- Payloads **larger** than this threshold are stored to disk and return metadata
- Payloads **smaller than or equal** to this threshold are returned inline
Expand Down Expand Up @@ -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/<server>)
--sequential-launch Launch MCP servers sequentially during startup (parallel launch is default)
--unified Run in unified mode (all backends at /mcp)
Expand Down Expand Up @@ -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

Expand Down