{"record":{"id":"98a11e94e82acc10","repo":"siyuan-note/siyuan","slug":"property-q-x-mcp-header-can-only-be-applied-to-p","errorCode":null,"errorMessage":"property %q: x-mcp-header can only be applied to primitive types (integer, string, boolean), got %q","messagePattern":"property %q: x-mcp-header can only be applied to primitive types \\(integer, string, boolean\\), got %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/mcp/tools/validation.go","lineNumber":245,"sourceCode":"\tvar walk func(map[string]any, string) error\n\twalk = func(props map[string]any, prefix string) error {\n\t\tfor propertyName, rawProperty := range props {\n\t\t\tproperty, ok := rawProperty.(map[string]any)\n\t\t\tif !ok {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tpath := propertyName\n\t\t\tif prefix != \"\" {\n\t\t\t\tpath = prefix + \".\" + propertyName\n\t\t\t}\n\t\t\tif rawHeader, exists := property[\"x-mcp-header\"]; exists {\n\t\t\t\theader, ok := rawHeader.(string)\n\t\t\t\tif !ok || header == \"\" {\n\t\t\t\t\treturn fmt.Errorf(`property %q: x-mcp-header must be a non-empty string`, path)\n\t\t\t\t}\n\t\t\t\tpropertyType, _ := property[\"type\"].(string)\n\t\t\t\tif propertyType != \"string\" && propertyType != \"integer\" && propertyType != \"boolean\" {\n\t\t\t\t\treturn fmt.Errorf(\n\t\t\t\t\t\t`property %q: x-mcp-header can only be applied to primitive types (integer, string, boolean), got %q`,\n\t\t\t\t\t\tpath, propertyType)\n\t\t\t\t}\n\t\t\t\tif !validHTTPFieldName(header) {\n\t\t\t\t\treturn fmt.Errorf(`property %q: x-mcp-header value %q is not a valid HTTP field name`, path, header)\n\t\t\t\t}\n\t\t\t\tnormalized := strings.ToLower(header)\n\t\t\t\tif seen[normalized] {\n\t\t\t\t\treturn fmt.Errorf(`property %q: duplicate x-mcp-header value %q`, path, header)\n\t\t\t\t}\n\t\t\t\tseen[normalized] = true\n\t\t\t}\n\t\t\tnested, _ := property[\"properties\"].(map[string]any)\n\t\t\tif err := walk(nested, path); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t\treturn nil","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/mcp/tools/validation.go#L227-L263","documentation":"Thrown by validateParamHeaderAnnotations when a property carries x-mcp-header but its declared type is not one of the allowed primitive types (\"string\", \"integer\", \"boolean\"). Header binding only makes sense for scalar values that can be serialized into a single header line; objects and arrays are rejected.","triggerScenarios":"Registering a tool whose input schema has a property such as {\"type\": \"array\", \"items\": {...}, \"x-mcp-header\": \"X-Tags\"} or {\"type\": \"object\", \"x-mcp-header\": \"X-Meta\"}.","commonSituations":"A developer adds x-mcp-header to a property intended to carry structured data; a schema is reused and the header annotation is left on a now-array-typed property; missing type defaults to \"\" which also fails this check.","solutions":["Change the property type to string, integer, or boolean if header binding is intended.","If the property must remain an object/array, remove the x-mcp-header annotation and bind it to the request body instead.","If you need multiple header values, model them as separate primitive properties each with their own x-mcp-header."],"exampleFix":"// before\n{\"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}, \"x-mcp-header\": \"X-Tags\"}}\n// after: bind each tag to its own header\n{\"tag1\": {\"type\": \"string\", \"x-mcp-header\": \"X-Tag-1\"}}","handlingStrategy":"validation","validationCode":"if _, hasHeader := prop[\"x-mcp-header\"]; hasHeader {\n    t, _ := prop[\"type\"].(string)\n    if t != \"string\" && t != \"integer\" && t != \"boolean\" {\n        return fmt.Errorf(\"x-mcp-header on non-primitive type %q\", t)\n    }\n}","typeGuard":"func headerTypeAllowed(prop map[string]any) bool {\n    if _, ok := prop[\"x-mcp-header\"]; !ok { return true }\n    t, _ := prop[\"type\"].(string)\n    return t == \"string\" || t == \"integer\" || t == \"boolean\"\n}","tryCatchPattern":null,"preventionTips":["Only attach x-mcp-header to scalar properties.","For multi-value headers, model distinct primitive properties per header.","Review reused schema fragments after changing a property's type."],"tags":["mcp","json-schema","http-header","annotation","type-error"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}