MCP: Implement Structured Error Categories for Agent Decision-making

[sneharathod7]

Problem

Currently, MCP handlers return most CLI failures as raw strings:

fmt.Errorf("%w\n%s", err, string(out))

This works for humans, but it is difficult for agents to reliably reason about failures. Parsing CLI output is fragile and dependent on message formatting.

For example, an agent should be able to distinguish between:

• build failures
• registry authentication issues
• Kubernetes connectivity problems
• read-only mode violations

without relying on string matching.

---

Proposed Solution

Introduce structured error categories in MCP responses.

Proposed Model

type McpErrorResponse struct {
    Category string `json:"category"`
    Code     int    `json:"code"`
    Message  string `json:"message"`
}

Suggested Categories

• VALIDATION_ERROR
• BUILD_ERROR
• REGISTRY_ERROR
• CLUSTER_ERROR
• READONLY_ERROR
• TIMEOUT_ERROR

---

Why This Helps

Structured errors would allow agents to make better decisions programmatically.

Example:

if error.category == "REGISTRY_ERROR":
    suggest("Run 'func config registry'")

instead of parsing raw CLI output.

---

Possible Implementation Area

pkg/mcp/mcp.go
pkg/mcp/*

The handlers can map known failure cases into stable categories while still preserving existing human-readable messages.

---

Strategic Alignment

This aligns well with the "agent-native toolchain" direction and would improve:

• autonomous workflows
• guided remediation
• IDE integrations
• conversational debugging

[sneharathod7]

/assign

[lkingland]

Quick note linking this issue to the work that came out of the PR #3753 discussion:

The functional need described here — structured, machine-readable errors so MCP agents can dispatch on failures — is now being delivered across a dependency chain:

• Add --json output mode to every func subcommand, including errors #3769 — --json output mode on every func subcommand (producer-side; prerequisite)
• MCP: consume func --json output and forward structured errors via CallToolResult.StructuredContent #3770 — MCP consumes func --json and forwards structured errors via CallToolResult.StructuredContent (the direct fulfillment of this issue; depends on Add --json output mode to every func subcommand, including errors #3769)
• MCP server should call pkg/functions directly, not shell out to the func binary #3771 — MCP calls pkg/functions directly (the end-state architecture; once it lands, --json shellouts go away and typed errors flow through Go calls)

So this issue effectively closes when #3770 lands. Leaving it open as the user-facing tracking artifact so anyone hitting "my agent can't dispatch on MCP errors" finds the live work via this thread.