fix(mcp-proxy): isolate MCP reload panics (#2959)

* fix(mcp-proxy): skip invalid OpenAPI parameters

Why this change was needed:
OpenAPI input can contain nil parameter refs or schema refs with neither a value nor a resolved reference. The converter previously dereferenced those shapes while building MCP tool schemas.

What changed:
- Added a schema-ref presence check before marshaling OpenAPI schemas
- Skipped nil, empty, or schema-less parameters instead of building partial parameter schemas
- Reused the same guard for JSON request bodies with empty schema refs
- Added a regression test covering invalid parameter entries

Problem solved:
Bad parameter metadata no longer panics the OpenAPI-to-MCP converter.

* fix(mcp-proxy): isolate MCP reload panics per server

Why this change was needed:
A panic while applying one MCP server reload could interrupt the whole reload round. A panic in concurrent prefetch could also be recovered without being recorded on that server result, making later stats misleading.

What changed:
- Added per-server panic recovery around applyServerChanges processing
- Counted apply panics as load errors while continuing to later servers
- Recorded prefetch panics on the matching serverLoadResult
- Added regression tests for prefetch panic attribution and apply-stage isolation

Problem solved:
Bad data from one MCP server no longer prevents later servers in the same reload round from being applied, and recovered prefetch panics are counted as server load errors.

* fix(mcp-proxy): guard nil MCP reload apply results

Why this change was needed:
A nil server result from reload prefetch could still panic during the apply phase before per-server panic isolation ran, stopping later servers from being applied.

What changed:
- Count nil apply results as reload errors before accessing the server name
- Make apply panic recovery logging safe when the server is nil
- Add a regression test that verifies a nil result does not block a later valid server

Problem solved:
MCP reload now preserves per-server isolation for nil-server apply results, so one malformed result cannot abort the rest of the reload.

* fix(mcp-proxy): report reload panic stack traces

Why this change was needed:
Reload panic isolation logged only the panic value, which made per-server prefetch and apply failures harder to diagnose after recovery.

What changed:
- Added a shared reload panic reporting helper with stack traces
- Reported reload panic phase and MCP server name to Sentry context
- Added a regression test for stack and Sentry report metadata

Problem solved:
Recovered MCP reload panics now retain enough diagnostic context for operations without losing per-server isolation.

* fix(mcp-proxy): preserve tools on failed reload updates

Why this change was needed:
Reload updates could prune existing tools before the new OpenAPI spec update had succeeded, and update failures were counted as skipped reloads.

What changed:
- Apply the new MCP server spec before pruning stale tools
- Return update errors separately from no-op updates
- Count update failures as reload errors instead of skips
- Add regressions for failed update state preservation and error accounting

Problem solved:
A failed MCP reload update no longer leaves the existing server with prematurely removed tools, and reload stats now report update failures accurately.

* docs(mcp-proxy): clarify OpenAPI ref handling in converter

Why this change was needed:
The converter keeps accepting Ref-only schema refs, which can look like it allows dangling refs to reach MCP tool schemas.

What changed:
- Document that LoadFromData resolves valid refs and rejects dangling refs before reload conversion

Problem solved:
Future review of the converter can distinguish production reload behavior from defensive compatibility in the helper.

Author: wklken

src/mcp-proxy/pkg/infra/proxy/converter.go

@@ -44,7 +44,7 @@ func openapiSchemaRefToJSONSchema(schemaRef *openapi3.SchemaRef) jsonschema.Sche
 }
 
 func marshalOpenAPISchemaRefJSON(schemaRef *openapi3.SchemaRef) ([]byte, error) {
-	if schemaRef == nil {
+	if !openapiSchemaRefHasSchema(schemaRef) {
 		return nil, nil
 	}
 	if schemaRef.Value != nil {
@@ -53,6 +53,11 @@ func marshalOpenAPISchemaRefJSON(schemaRef *openapi3.SchemaRef) ([]byte, error)
 	return schemaRef.MarshalJSON()
 }
 
+func openapiSchemaRefHasSchema(schemaRef *openapi3.SchemaRef) bool {
+	// LoadFromData resolves valid refs and rejects dangling refs before reload conversion.
+	return schemaRef != nil && (schemaRef.Value != nil || schemaRef.Ref != "")
+}
+
 func fallbackOpenAPIJSONSchema(schemaJSON []byte) jsonschema.Schema {
 	var rawSchema map[string]any
 	if err := json.Unmarshal(schemaJSON, &rawSchema); err != nil {
@@ -212,58 +217,61 @@ func OpenapiToMcpToolConfig(
 					Type: j.WithSimpleTypes(jsonschema.Object),
 				}
 				for _, param := range operation.Parameters {
-					if param.Value.Schema != nil {
-						jsonSchema := openapiSchemaRefToJSONSchema(param.Value.Schema)
-						if param.Value.Description != "" {
-							jsonSchema.Description = &param.Value.Description
-						}
-						if param.Value.Example != nil {
-							if jsonSchema.ExtraProperties == nil {
-								jsonSchema.ExtraProperties = map[string]any{}
-							}
-							jsonSchema.ExtraProperties["example"] = param.Value.Example
-						}
-						if param.Value.In == "header" {
-							headerParamSchema.WithPropertiesItem(
-								param.Value.Name,
-								jsonschema.SchemaOrBool{
-									TypeObject: &jsonSchema,
-								},
-							)
-							if param.Value.Required {
-								headerParamSchema.Required = append(
-									headerParamSchema.Required,
-									param.Value.Name,
-								)
-							}
+					if param == nil || param.Value == nil ||
+						!openapiSchemaRefHasSchema(param.Value.Schema) {
+						continue
+					}
+					parameter := param.Value
+					jsonSchema := openapiSchemaRefToJSONSchema(parameter.Schema)
+					if parameter.Description != "" {
+						jsonSchema.Description = &parameter.Description
+					}
+					if parameter.Example != nil {
+						if jsonSchema.ExtraProperties == nil {
+							jsonSchema.ExtraProperties = map[string]any{}
 						}
-						if param.Value.In == "query" {
-							queryParamSchema.WithPropertiesItem(
-								param.Value.Name,
-								jsonschema.SchemaOrBool{
-									TypeObject: &jsonSchema,
-								},
+						jsonSchema.ExtraProperties["example"] = parameter.Example
+					}
+					if parameter.In == "header" {
+						headerParamSchema.WithPropertiesItem(
+							parameter.Name,
+							jsonschema.SchemaOrBool{
+								TypeObject: &jsonSchema,
+							},
+						)
+						if parameter.Required {
+							headerParamSchema.Required = append(
+								headerParamSchema.Required,
+								parameter.Name,
 							)
-							if param.Value.Required {
-								queryParamSchema.Required = append(
-									queryParamSchema.Required,
-									param.Value.Name,
-								)
-							}
 						}
-						if param.Value.In == "path" {
-							pathParamSchema.Required = append(
-								pathParamSchema.Required,
-								param.Value.Name,
-							)
-							pathParamSchema.WithPropertiesItem(
-								param.Value.Name,
-								jsonschema.SchemaOrBool{
-									TypeObject: &jsonSchema,
-								},
+					}
+					if parameter.In == "query" {
+						queryParamSchema.WithPropertiesItem(
+							parameter.Name,
+							jsonschema.SchemaOrBool{
+								TypeObject: &jsonSchema,
+							},
+						)
+						if parameter.Required {
+							queryParamSchema.Required = append(
+								queryParamSchema.Required,
+								parameter.Name,
 							)
 						}
 					}
+					if parameter.In == "path" {
+						pathParamSchema.Required = append(
+							pathParamSchema.Required,
+							parameter.Name,
+						)
+						pathParamSchema.WithPropertiesItem(
+							parameter.Name,
+							jsonschema.SchemaOrBool{
+								TypeObject: &jsonSchema,
+							},
+						)
+					}
 				}
 				if len(headerParamSchema.Properties) > 0 {
 					headerParamDesc := "HTTP request header parameters, " +
@@ -299,7 +307,7 @@ func OpenapiToMcpToolConfig(
 
 			if operation.RequestBody != nil && operation.RequestBody.Value != nil {
 				if content, ok := operation.RequestBody.Value.Content["application/json"]; ok &&
-					content != nil && content.Schema != nil {
+					content != nil && openapiSchemaRefHasSchema(content.Schema) {
 					jsonSchema := openapiSchemaRefToJSONSchema(content.Schema)
 					if jsonSchemaDescriptionIsEmpty(&jsonSchema) {
 						bodyParamDesc := bodyParamDefaultDescription

src/mcp-proxy/pkg/infra/proxy/converter_test.go

@@ -284,6 +284,48 @@ var _ = Describe("Converter", func() {
 			Expect(result[0].ParamSchema.Required).To(ContainElement("header_param"))
 		})
 
+		It("should skip invalid parameters without panicking", func() {
+			spec := &openapi3.T{
+				OpenAPI: "3.0.0",
+				Info:    &openapi3.Info{Title: "Test API", Version: "1.0.0"},
+				Servers: []*openapi3.Server{{URL: "https://api.example.com/v1"}},
+				Paths:   &openapi3.Paths{},
+			}
+
+			pathItem := &openapi3.PathItem{
+				Get: &openapi3.Operation{
+					OperationID: "getUsers",
+					Summary:     "Get users",
+					Parameters: openapi3.Parameters{
+						nil,
+						&openapi3.ParameterRef{},
+						&openapi3.ParameterRef{
+							Value: &openapi3.Parameter{
+								Name: "limit",
+								In:   "query",
+							},
+						},
+						&openapi3.ParameterRef{
+							Value: &openapi3.Parameter{
+								Name:   "offset",
+								In:     "query",
+								Schema: &openapi3.SchemaRef{},
+							},
+						},
+					},
+					Responses: &openapi3.Responses{},
+				},
+			}
+			spec.Paths.Set("/users", pathItem)
+
+			var result []*ToolConfig
+			Expect(func() {
+				result = OpenapiToMcpToolConfig(spec, nil, nil)
+			}).NotTo(Panic())
+			Expect(result).To(HaveLen(1))
+			Expect(result[0].ParamSchema.Properties).NotTo(HaveKey("query_param"))
+		})
+
 		It("should skip JSON request body without schema", func() {
 			spec := &openapi3.T{
 				OpenAPI: "3.0.0",

src/mcp-proxy/pkg/mcp/export_test.go

@@ -21,6 +21,7 @@ package mcp
 import (
 	"context"
 
+	"github.com/getkin/kin-openapi/openapi3"
 	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
 
 	"mcp_proxy/pkg/entity/model"
@@ -104,11 +105,33 @@ func NewConfig(resourceVersion int) *Config {
 	}
 }
 
+// NewConfigWithOpenAPISpec creates a Config with OpenAPI data for testing.
+func NewConfigWithOpenAPISpec(resourceVersion int, openapiFileData *openapi3.T) *Config {
+	return &Config{
+		resourceVersion: resourceVersion,
+		openapiFileData: openapiFileData,
+	}
+}
+
 // GetLoadStatsValues returns stats values for testing.
 func GetLoadStatsValues(stats *loadStats) (added, updated, skipped, errorCount int) {
 	return stats.addedCount, stats.updatedCount, stats.skippedCount, stats.errorCount
 }
 
+// GetServerLoadResultError returns the load result error for testing.
+func GetServerLoadResultError(result *serverLoadResult) error {
+	return result.err
+}
+
+// BuildReloadPanicReportForTest exposes buildReloadPanicReport for testing.
+func BuildReloadPanicReportForTest(
+	phase string,
+	serverName string,
+	panicErr any,
+) (string, map[string]string, map[string]any, error) {
+	return buildReloadPanicReport(phase, serverName, panicErr)
+}
+
 // PrefetchServerConfigsForTest exposes prefetchServerConfigs for benchmark testing.
 func PrefetchServerConfigsForTest(
 	ctx context.Context,