[Schema Consistency] Network & MCP Integration Analysis - 2 Issues Found, 2 Previous Issues Resolved

[github-actions[bot]]

Summary

• Strategy: Network Configuration & MCP Tool Integration Analysis (strategy-011)
• Inconsistencies Found: 2 (1 moderate, 1 minor)
• Positive Validations: 6
• Previous Issues Resolved: 2
• Last Run: 2025-11-11 (44 days ago)

This analysis focused on integration patterns between network permissions, MCP tool configurations, and cache systems. The strategy successfully validated improvements from the previous run while discovering one new moderate issue.

Full Report

Key Finding

The system demonstrates excellent separation of concerns between:

• Top-level network: - Controls AI engine network access (200-line dedicated docs)
• MCP network: - Controls container-based MCP server network access (stdio_mcp_tool only)

However, http_mcp_tool lacks network configuration while stdio_mcp_tool has it, creating an undocumented inconsistency.

Moderate Issues

1. http_mcp_tool Missing Network Property

Location: pkg/parser/schemas/main_workflow_schema.json - $defs.http_mcp_tool

Issue: stdio_mcp_tool includes a network property with allowed domains and proxy-args, but http_mcp_tool has no network configuration at all.

Evidence:

# stdio_mcp_tool has network property
jq '."$defs".stdio_mcp_tool.properties.network' main_workflow_schema.json
# Returns network object with allowed and proxy-args

# http_mcp_tool missing network
jq '."$defs".http_mcp_tool.properties.network' main_workflow_schema.json  
# Returns null

Impact:

• HTTP-based MCP servers cannot configure network access
• Only container-based MCP servers support network configuration
• May be intentional (HTTP servers run externally) but not documented

Recommendation:

• If intentional: Add $comment to http_mcp_tool explaining why network config is not needed
• If oversight: Add network property to http_mcp_tool for consistency
• Document the design decision in MCPs guide

Files: pkg/parser/schemas/main_workflow_schema.json, docs/src/content/docs/guides/mcps.md

Minor Issues

1. MCP Network Configuration Lacks Prominent Documentation

Location: docs/src/content/docs/reference/tools.md, docs/src/content/docs/guides/mcps.md

Issue: Top-level network configuration has 200 lines of documentation, but MCP stdio network configuration is only briefly mentioned without examples.

Impact:

• Users may not discover MCP network configuration capability
• No guidance on configuring network access for container-based MCP servers

Recommendation: Add MCP network configuration section to MCPs guide with:

• Example of stdio_mcp_tool with network.allowed domains
• Explanation of when network config is needed
• Comparison with top-level network permissions

Positive Findings

1. Network Field Disambiguation ✅

Two "network" fields with clear separation:

• Top-level: properties.network for AI engine access (web-fetch, web-search)
• MCP: $defs.stdio_mcp_tool.properties.network for container servers

Both have $comment fields explaining scope. Parser uses NetworkPermissions struct at pkg/workflow/engine.go:29-35.

2. Cache vs Cache-Memory Separation ✅

Well-designed separation:

• cache: - GitHub Actions caching (actions/cache) for dependencies
• cache-memory: - MCP persistent memory for agent data across runs

Separate handlers in pkg/workflow/cache.go, different schema locations, distinct use cases.

3. Playwright Integration ✅

Playwright tool reuses GetAllowedDomains() logic for consistent domain resolution:

// pkg/workflow/mcp_servers.go:675-696
playwrightNetwork := &NetworkPermissions{}
resolvedDomains := GetAllowedDomains(playwrightNetwork)

4. Strict Mode Validation ✅

Clear $comment in schema:

"$comment": "Strict mode requirements: When strict=true, the 'network' field must be present and cannot contain wildcard '*'"

Validated in pkg/workflow/strict_mode_validation.go and documented in frontmatter.md.

5. Firewall Deprecation ✅

Consistent deprecation with migration path:

"deprecated": true,
"x-deprecation-message": "Use 'sandbox.agent: false' instead"

6. Previous Issues Resolved ✅

Fixed since 2025-11-11:

1. ✅ Network documentation added - Now has comprehensive 200-line page
2. ✅ cache-memory.docker-image removed - Field no longer in schema

Recommendations

High Priority:

1. Document http_mcp_tool network behavior (add $comment or network property)

Medium Priority:
2. Add MCP network configuration examples to MCPs guide
3. Cross-link network.md to MCP network docs

Low Priority:
4. Architectural review: Should http_mcp_tool support network config?

Strategy Performance

• Effectiveness: Very High
• New Issues: 2 (1 moderate, 1 minor)
• Resolved Issues: 2 from previous run
• Positive Validations: 6
• Should Reuse: Yes - every 6-8 analyses

Key Strength: Integration-focused analysis validates architectural decisions and discovers cross-system issues invisible to field-level validation.

Progress: Critical issues from last run resolved, network docs added, cache-memory.docker-image removed.

Files Analyzed

Schema: main_workflow_schema.json, included_file_schema.json
Parser: engine.go, cache.go, mcp_servers.go, strict_mode_validation.go
Docs: network.md (NEW!), tools.md, frontmatter.md
Workflows: shared/mcp/context7.md, audit-workflows.md

References:

• [Network Permissions Documentation]((redacted)
• [MCP Guide]((redacted)
• [Tools Reference]((redacted)

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰