{"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":244,"sourceCode":"\tseen := map[string]bool{}\n\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}","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/mcp/tools/validation.go#L226-L262","documentation":"The x-mcp-header keyword may only be attached to properties whose declared schema type is string, integer, or boolean, because HTTP header values are flat primitives. Validation rejects it on other types (object, array, number, etc.) and reports the actual type in the error.","triggerScenarios":"A tool schema property with type \"object\", \"array\", \"number\", or missing type carries an x-mcp-header annotation and the schema is validated during MCP tool registration.","commonSituations":"Copying the annotation to a complex property, expecting nested object fields to map to headers, or omitting the type keyword so the type check fails.","solutions":["Declare the property with type \"string\", \"integer\", or \"boolean\" when using x-mcp-header","Move x-mcp-header to a sibling primitive property instead of a nested object/array","Remove the annotation if the value must be structured"],"exampleFix":"// before\n{\"type\":\"object\",\"properties\":{...},\"x-mcp-header\":\"X-Data\"}\n// after\n{\"type\":\"string\",\"x-mcp-header\":\"X-Data\"}","handlingStrategy":"validation","validationCode":"function checkHeaderTypes(schema) {\n  for (const [name, prop] of Object.entries(schema.properties || {})) {\n    if ('x-mcp-header' in prop && !['string','integer','boolean'].includes(prop.type)) {\n      throw new Error(`property ${name}: x-mcp-header requires primitive type, got ${prop.type}`);\n    }\n  }\n}","typeGuard":"const headerEligible = (p) => ['string','integer','boolean'].includes(p.type);","tryCatchPattern":"try { registerTool(schema) } catch (e) { if (String(e).includes('primitive types')) moveHeaderToPrimitiveProperty(schema); else throw e; }","preventionTips":["Only annotate scalar properties with x-mcp-header","Always declare an explicit type on properties using x-mcp-header","Keep structured data in body properties, not headers"],"tags":["json-schema","mcp","validation","http-headers"],"backgroundTag":"incompatible-source-type","analyzedSha":"9f775e8a12daef8255556097396f9b2739078892","analyzedAt":"2026-09-19T03:17:15.984Z","contentChangedAt":"2026-09-19T03:17:15.984Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}