Add token-based output guardrail to MCP server logs command with configurable limit

[Copilot]

✅ Add Token-Based Output Guardrail to MCP Server Logs Command - COMPLETE

Goal: Ensure the MCP server "logs" command has a guardrail to prevent massive output by automatically suggesting a schema+jq approach when output is too large.

Summary

This PR implements a smart token-based guardrail for the MCP server's logs command that prevents overwhelming output while providing helpful guidance to users. When the JSON output exceeds the token limit (default: 12000 tokens, configurable), the command automatically returns a structured response containing:

1. ⚠️ Clear warning message explaining the token limit
2. 📋 Complete JSON schema of the LogsData structure
3. 💡 8 suggested jq queries for common filtering scenarios

Key Features

• Token-based limit - Uses tokens instead of bytes for better AI model compatibility
• 12000 token default - Sensible default that works well with most AI models (~48KB of text)
• Configurable - Optional max_tokens parameter allows customization per request
• Zero breaking changes - Existing functionality completely preserved
• Self-documenting - Schema tells users exactly what data is available
• Actionable guidance - Specific jq queries users can use immediately
• Well-tested - 11 unit tests + integration test, all passing

Implementation Details

Files Added:

• pkg/cli/mcp_logs_guardrail.go - Core implementation with token estimation
• pkg/cli/mcp_logs_guardrail_test.go - Unit tests (11 tests including custom limit tests)
• pkg/cli/mcp_logs_guardrail_integration_test.go - Integration test
• specs/MCP_LOGS_GUARDRAIL.md - Complete documentation

Files Modified:

• pkg/cli/mcp_server.go - Added guardrail check and max_tokens parameter to logs tool
• .gitignore - Exclude manual test scripts

Token Estimation: Uses approximately 4 characters per token (OpenAI's rule of thumb) to estimate token count from text output.

Example Guardrail Response

{
  "message": "⚠️  Output size (15000 tokens) exceeds the limit (12000 tokens). To reduce output size, use the 'jq' parameter with one of the suggested queries below.",
  "output_tokens": 15000,
  "output_size_limit": 12000,
  "schema": {
    "description": "Complete structured data for workflow logs",
    "type": "object",
    "fields": {
      "summary": {"type": "object", "description": "Aggregate metrics..."},
      "runs": {"type": "array", "description": "Array of workflow run data..."},
      ...
    }
  },
  "suggested_queries": [
    {"description": "Get only the summary statistics", "query": ".summary"},
    {"description": "Get first 5 runs", "query": ".runs[:5]"},
    {"description": "Get only failed runs", "query": ".runs | map(select(.conclusion == \"failure\"))"},
    ...8 total queries
  ]
}

Configuring the Token Limit

Users can customize the token limit using the max_tokens parameter:

{
  "name": "logs",
  "arguments": {
    "count": 100,
    "max_tokens": 20000
  }
}

Testing

✅ All Tests Passing:

• 11 unit tests for guardrail logic including token estimation and custom limits
• 1 integration test with MCP server
• All existing tests still passing
• Linter clean
• CodeQL security scan: 0 alerts

Suggested jq Queries

1. .summary - Summary statistics only
2. .runs | map({database_id, workflow_name, status}) - Run IDs and basic info
3. .runs | map(select(.conclusion == "failure")) - Failed runs only
4. {summary, runs: .runs[:5]} - Summary + first 5 runs
5. {errors_and_warnings, missing_tools, mcp_failures} - Diagnostics only
6. .tool_usage - Tool usage statistics
7. .runs | map(select(.token_usage > 10000)) - High token usage
8. .runs | map(select(.workflow_name == "NAME")) - Specific workflow

Documentation

Complete documentation available in specs/MCP_LOGS_GUARDRAIL.md including:

• How the guardrail works
• Token estimation methodology
• Configuring the max_tokens parameter
• All 8 suggested queries with examples
• Implementation details
• Testing instructions
• Future enhancement ideas

Original prompt

Ensure that the "mcp-server" "logs" command has garderail to prevent a massive output. It should automatically change the format of the output to a schema+jq suggestion if too large.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot limit to 10 KB

[Copilot]

@copilot limit to 10 KB

Updated the limit to 10KB in commit c42e863. The constant MaxMCPLogsOutputSize is now set to 10,240 bytes (10KB), and all documentation and tests have been updated accordingly.

[github-actions]

Agentic Changeset Generator triggered by this pull request.

[Copilot]

Pull Request Overview

This PR adds a 10KB output size guardrail to the MCP server's logs command to prevent overwhelming AI models and clients with massive JSON payloads. When output exceeds 10KB, the command returns a structured response containing the data schema and suggested jq filter queries instead of the full output.

Key changes:

• Implements automatic size checking that intercepts outputs >10KB
• Returns schema description and 8 common jq filter patterns when guardrail triggers
• Updates MCP server tool description to document the 10KB limit

Reviewed Changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/cli/mcp_logs_guardrail.go	Core guardrail implementation with size checking, schema generation, and jq query suggestions
pkg/cli/mcp_server.go	Integration of guardrail into MCP logs tool handler and updated tool description
pkg/cli/mcp_logs_guardrail_test.go	Unit tests covering size thresholds, schema generation, and query suggestions
pkg/cli/mcp_logs_guardrail_integration_test.go	Integration tests verifying guardrail behavior in MCP server context
MCP_LOGS_GUARDRAIL.md	Documentation describing the guardrail feature, usage examples, and implementation details
.github/workflows/go.mod	Formatting cleanup (reordering lines)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pelikhan]

@copilot use tokens for the limit default 12000, optional argument to change

[Copilot]

@copilot use tokens for the limit default 12000, optional argument to change

Switched to token-based limit in commit 589fd0c. The default is now 12000 tokens with a configurable max_tokens parameter. Token estimation uses ~4 characters per token (OpenAI's rule of thumb).