[Schema Consistency] 🔍 Schema Consistency Check - 2025-11-11: Network & MCP Integration Analysis

[github-actions[bot]]

🔍 Schema Consistency Check - 2025-11-11

This analysis examined network permissions, MCP tool configurations, and cache-memory patterns across the schema, parser implementation, documentation, and actual workflow usage using a new Network Configuration & MCP Tool Integration Analysis strategy. The focus was on integration points between different configuration systems rather than individual field validation.

Key Discovery: Found a critical schema-parser mismatch where cache-memory.docker-image is defined in the schema but not implemented in the parser, making this advertised feature non-functional.

Full Analysis Report

Summary

Inconsistencies Found: 4 (1 critical, 2 moderate, 1 info)
Categories Analyzed: Schema, Parser, Documentation, Workflows
Strategy Used: Network Configuration & MCP Tool Integration Analysis
New Strategy: Yes (radically different approach focusing on integration patterns)

---

Critical Issues

1. ❌ Schema Field Not Implemented: cache-memory.docker-image

Severity: Critical
Files:

• Schema: pkg/parser/schemas/main_workflow_schema.json:2041
• Parser: pkg/workflow/cache.go:19-24

Problem:
The schema advertises a docker-image configuration option for cache-memory that allows users to customize the memory MCP server Docker image:

"docker-image": {
  "type": "string",
  "description": "Docker image to use for the memory MCP server (default: mcp/memory)"
}

However, the Go parser struct completely omits this field:

type CacheMemoryEntry struct {
    ID            string `yaml:"id"`
    Key           string `yaml:"key,omitempty"`
    Description   string `yaml:"description,omitempty"`
    RetentionDays *int   `yaml:"retention-days,omitempty"`
    // DockerImage field is MISSING
}

Impact:

• Users trying to customize the memory MCP server image will have their configuration silently ignored
• Schema validation passes but feature doesn't work
• Creates false expectations about supported functionality

Recommendation:

1. Option A (Implement): Add DockerImage string \yaml:"docker-image,omitempty"`toCacheMemoryEntry` struct and implement handling in the cache-memory MCP server generation code
2. Option B (Remove): If this feature is not intended to be supported, remove it from the schema

---

Documentation Gaps

2. ⚠️ Missing Network Documentation Section

Severity: Moderate
**(redacted) docs/src/content/docs/reference/frontmatter.md:25

Problem:
The network field is mentioned as a frontmatter element but lacks a dedicated documentation section in the main frontmatter reference. Network configuration IS documented in engines.md (line 73-100) in the context of Copilot engine, but this creates discoverability and consistency issues.

Impact:

• Discoverability issue: users may not find network permissions feature
• Inconsistent documentation structure
• Confusion about whether network is engine-specific or workflow-level

Recommendation:
Add a dedicated ### Network Permissions section to frontmatter.md that:

1. Explains purpose: workflow-level network access control for AI engines
2. Shows basic examples with ecosystem identifiers
3. Links to engines.md for engine-specific details (AWF firewall for Copilot)
4. Distinguishes from MCP network configuration (which serves a different purpose)

3. ⚠️ Misleading cache-memory Classification

Severity: Minor
**(redacted) docs/src/content/docs/reference/frontmatter.md:25

Problem:
Documentation lists cache-memory as a "frontmatter element" at the same level as top-level fields like engine, network, permissions, etc. However, cache-memory is actually a tools configuration (properties.tools.properties.cache-memory), not a top-level frontmatter field.

Impact:
Minor confusion about configuration structure. Users might try to place cache-memory: at the top level instead of inside tools:.

Recommendation:
Update the documentation introduction to categorize fields more accurately:

• Top-level frontmatter: on, permissions, engine, network, strict, etc.
• Tools configuration: cache-memory, bash, edit, github, mcp, etc.

---

Schema Design Observations

4. ℹ️ Two Different "network" Fields - Clarification Needed

Severity: Info (by design, but documentation could be clearer)

Observation:
There are TWO distinct network configurations with similar names but different purposes:

Aspect	Engine Network	MCP Network
Location	Top-level network:	tools.mcp[server-name].network:
Schema	main_workflow_schema.json:1573	mcp_config_schema.json:63
Purpose	AI engine network access control	Container-based MCP server isolation
Controls	web-fetch, web-search tools	Container network access
Features	Ecosystem identifiers, AWF firewall	Domain allowlist, proxy-args

Good News:

• ✅ Both use identical domain regex patterns (consistent validation)
• ✅ Schema correctly distinguishes them (no collision)
• ✅ Implementation correctly handles both separately
• ✅ Semantically appropriate: different levels for different purposes

Recommendation:
Add a note in documentation clarifying:

• Engine network: controls what the AI can access (web-fetch/search)
• MCP network: controls what containerized MCP servers can access
• These are complementary security boundaries, not alternatives

---

Positive Findings

What's Working Well

1. ✅ Network domain patterns are consistent - Both engine network and MCP network use identical regex patterns for domain validation
2. ✅ Cache vs cache-memory properly separated - Actions cache and cache-memory MCP are correctly distinguished
3. ✅ MCP schema modularity - mcp_config_schema.json is well-structured and properly referenced
4. ✅ Parser implementation quality - Most schema fields are correctly parsed and validated
5. ✅ Field coverage - 9 out of 10 analyzed fields have correct schema-parser alignment

---

Strategy Performance

Strategy Details:

• Name: Network Configuration & MCP Tool Integration Analysis
• Type: New radically different approach
• Focus: Integration patterns and cross-system consistency
• Method: Traced network/MCP/cache features through schema → parser → docs → workflows

Results:

• Findings Count: 4 issues
• Critical Findings: 1 (docker-image not implemented)
• Moderate Findings: 2 (documentation gaps)
• Info Findings: 1 (design clarification)
• Effectiveness: High - discovered issues missed by field-level strategies

Why This Strategy Worked:
Previous strategies focused on individual field validation. This strategy examined how different configuration systems interact (network permissions + MCP network, cache + cache-memory), revealing:

• Schema fields that exist but aren't used (docker-image)
• Documentation inconsistencies (network location)
• Terminology overlaps that need clarification (dual "network" fields)

Should Reuse: Yes, highly recommended for periodic checks (every 4-5 analyses)

---

Recommendations

Immediate Actions (P0)

Fix critical schema-parser mismatch:

• Add DockerImage field to CacheMemoryEntry struct in pkg/workflow/cache.go
• Implement docker-image handling in extractCacheMemoryConfig function
• OR remove docker-image from schema if not intended to be supported
• Add test coverage for docker-image configuration

High Priority (P1)

Improve documentation discoverability:

• Add dedicated "Network Permissions" section to docs/src/content/docs/reference/frontmatter.md
• Include basic examples and link to engines.md for advanced features
• Explain difference between engine network and MCP network

Medium Priority (P2)

Documentation consistency:

• Reclassify cache-memory in documentation as tools configuration, not top-level frontmatter
• Add disambiguation note explaining the two different "network" fields
• Consider adding a diagram showing network control boundaries (engine vs MCP)

---

Detailed Field Analysis

Schema ↔ Parser Comparison

Field Path	Schema Status	Parser Status	Match
network (top-level)	✅ Defined	✅ Implemented	✅
network.allowed	✅ Defined	✅ Implemented	✅
network.firewall	✅ Defined	✅ Implemented	✅
tools.mcp[name].network	✅ Defined	✅ Implemented	✅
tools.mcp[name].network.allowed	✅ Defined	✅ Implemented	✅
tools.mcp[name].network.proxy-args	✅ Defined	✅ Implemented	✅
tools.mcp[name].allowed	✅ Defined	✅ Implemented	✅
tools.cache-memory.id	✅ Defined	✅ Implemented	✅
tools.cache-memory.key	✅ Defined	✅ Implemented	✅
tools.cache-memory.description	✅ Defined	✅ Implemented	✅
tools.cache-memory.retention-days	✅ Defined	✅ Implemented	✅
tools.cache-memory.docker-image	✅ Defined	❌ MISSING	❌ CRITICAL

Match Rate: 91.7% (11/12 fields)

---

Files Analyzed

Schema Files:

• pkg/parser/schemas/main_workflow_schema.json - main workflow schema (31688 tokens)
• pkg/parser/schemas/mcp_config_schema.json - MCP server configuration schema

Parser/Compiler Files:

• pkg/workflow/cache.go - cache-memory configuration extraction
• pkg/workflow/engine.go - engine and network permissions types
• pkg/workflow/domains.go - domain resolution and ecosystem bundles
• pkg/workflow/mcp-config.go - MCP server configuration rendering
• pkg/workflow/mcp_servers.go - MCP server handling logic

Documentation Files:

• docs/src/content/docs/reference/frontmatter.md - main frontmatter reference
• docs/src/content/docs/reference/frontmatter-full.md - schema-generated reference
• docs/src/content/docs/reference/engines.md - AI engines documentation
• docs/src/content/docs/reference/cache-memory.md - cache-memory documentation

Workflow Samples:

• .github/workflows/artifacts-summary.md - uses network.firewall: true
• .github/workflows/ci-doctor.md - uses cache-memory: true
• 64 workflows total use tools: configuration
• 3+ workflows use network: configuration

---

Methodology

This analysis used a new strategy focusing on integration patterns rather than individual field validation:

1. Network Configuration Analysis

   • Traced network permissions from schema → parser → docs
   • Compared top-level network vs MCP network configurations
   • Validated domain pattern consistency across both

2. MCP Configuration Validation

   • Examined mcp_config_schema.json structure
   • Cross-referenced with parser implementation
   • Checked MCP network isolation features

3. Cache Pattern Analysis

   • Compared Actions cache vs cache-memory MCP
   • Validated all cache-memory schema fields against struct
   • Discovered docker-image mismatch

4. Documentation Cross-Reference

   • Checked field mentions in frontmatter.md
   • Validated dedicated documentation sections
   • Assessed discoverability and consistency

5. Real-World Usage Validation

   • Sampled actual workflows using network and cache-memory
   • Confirmed configuration patterns match documentation

This approach revealed integration issues that field-by-field analysis might miss, such as the classification inconsistency and the dual-purpose "network" terminology.

---

Analysis Date: 2025-11-11
Strategy: Network Configuration & MCP Tool Integration Analysis (NEW)
Total Files Analyzed: 13 schema/parser files, 4 documentation files, 64+ workflows sampled

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

✅ Agentic Plan Command completed successfully.

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.