go-mcp-persisted-handler-unavailable

Answer

UHLP U-GAP-019 fix — tool_registry.go

The root cause: persisted MCP custom tool definitions loaded from disk after a restart were wired to a stub handler that fabricated success text (e.g. "tool executed successfully"), so clients believed an unexecuted tool had run. Since live closures over in-memory state cannot be serialized, the correct behavior is to fail loudly with a typed, machine-readable error directing the client to re-register.

1. New error const + typed error (tool_registry.go):

// ToolErrorCode is a stable, machine-readable category for MCP tool failures.
type ToolErrorCode string

const (
    // ErrorToolUnavailable marks a persisted tool definition whose live handler
    // could not be reconstructed after a server restart. The caller must
    // re-register the tool through the tools API.
    ErrorToolUnavailable ToolErrorCode = "TOOL_UNAVAILABLE"
)

// ToolError is the error type returned by MCP tool execution handlers.
// Callers recover the machine code with errors.As.
type ToolError struct {
    Code    ToolErrorCode
    Message string
}

func (e *ToolError) Error() string { return e.Message }

func NewToolError(code ToolErrorCode, format string, args ...any) *ToolError {
    return &ToolError{Code: code, Message: fmt.Sprintf(format, args...)}
}

const reRegisterEndpoint = "/api/v1/apps/{id}/mcp/tools"

2. The stub handler now returns the typed error instead of fake success:

// stubPersistedHandler is installed for tool definitions loaded from disk.
// It must NOT fabricate a result; it returns a ToolError with code
// TOOL_UNAVAILABLE telling the caller to re-register the tool.
func stubPersistedHandler(appID, toolName string) func(args map[string]any) (any, error) {
    return func(args map[string]any) (any, error) {
        return nil, NewToolError(
            ErrorToolUnavailable,
            "persisted tool %q for app %q has no live handler after server restart; re-register via POST %s",
            toolName, appID, reRegisterEndpoint,
        )
    }
}

3. Registry wiring unchanged, but now installs the failing stub:

func (r *toolRegistry) loadPersistedTools(appID string, persisted []string) {
    for _, name := range persisted {
        r.handlers[name] = stubPersistedHandler(appID, name) // previously: fake-success stub
    }
}

4. Regression unit test (tool_registry_test.go) — asserts ToolError code via errors.As:

func TestStubPersistedHandlerReturnsToolUnavailable(t *testing.T) {
    handler := stubPersistedHandler("app-123", "legacy-tool")

    result, err := handler(map[string]any{"q": "what is 2+2"})
    if err == nil {
        t.Fatalf("stub handler returned fake success: result=%v, err=nil", result)
    }

    var toolErr *ToolError
    if !errors.As(err, &toolErr) {
        t.Fatalf("expected error to unwrap to *ToolError, got %T", err)
    }
    if toolErr.Code != ErrorToolUnavailable {
        t.Fatalf("ToolError.Code = %q, want %q", toolErr.Code, ErrorToolUnavailable)
    }
    if !strings.Contains(toolErr.Message, reRegisterEndpoint) {
        t.Fatalf("message %q must reference re-registration endpoint", toolErr.Message)
    }
}