Vega-Lite MCP Server

Instructions

Implementation Reference

• src/tools/validate.ts:12-106 (handler)

  The core handler function `validateSpec` that executes the tool logic: validates Vega-Lite spec for required properties, valid marks, channels, types, and schema.
  export async function validateSpec( spec: Record<string, unknown> ): Promise<ValidationResult> { const errors: string[] = []; const warnings: string[] = []; // Check required top-level properties if (!spec.$schema) { errors.push("Missing required property: $schema"); } if (!spec.mark && !spec.layer && !spec.hconcat && !spec.vconcat && !spec.concat) { errors.push("Missing required property: must have one of 'mark', 'layer', 'hconcat', 'vconcat', or 'concat'"); } if (!spec.data) { warnings.push("No data specified - spec may not render without data"); } // Check mark type if present if (spec.mark) { const validMarks = [ "arc", "area", "bar", "circle", "geoshape", "image", "line", "point", "rect", "rule", "square", "text", "tick", "trail", ]; const markType = typeof spec.mark === "string" ? spec.mark : (spec.mark as any)?.type; if (markType && !validMarks.includes(markType)) { errors.push(`Invalid mark type: '${markType}'. Valid types are: ${validMarks.join(", ")}`); } } // Check encoding channels if (spec.encoding) { const encoding = spec.encoding as Record<string, unknown>; const validChannels = [ "x", "y", "x2", "y2", "color", "fill", "stroke", "opacity", "fillOpacity", "strokeOpacity", "size", "shape", "angle", "radius", "theta", "text", "tooltip", "href", "url", "row", "column", "facet", "detail", "key", "order", ]; for (const channel of Object.keys(encoding)) { if (!validChannels.includes(channel)) { warnings.push(`Unknown encoding channel: '${channel}'`); } } } // Check data types in encoding if (spec.encoding) { const encoding = spec.encoding as Record<string, any>; const validTypes = ["quantitative", "temporal", "nominal", "ordinal", "geojson"]; for (const [channel, def] of Object.entries(encoding)) { if (def.type && !validTypes.includes(def.type)) { errors.push(`Invalid type '${def.type}' in encoding channel '${channel}'. Valid types are: ${validTypes.join(", ")}`); } if (!def.field && !def.value && !def.datum && channel !== "detail" && channel !== "order") { warnings.push(`Encoding channel '${channel}' has no field, value, or datum specified`); } } } // Check schema version if (spec.$schema && typeof spec.$schema === "string") { if (!spec.$schema.includes("vega-lite")) { errors.push("Schema URL should point to a vega-lite schema"); } } return { valid: errors.length === 0, errors, warnings, spec, }; }
• src/tools/validate.ts:1-6 (schema)

  Type definition for the output `ValidationResult` of the validateSpec handler.
  interface ValidationResult { valid: boolean; errors: string[]; warnings: string[]; spec: Record<string, unknown>; }
• src/index.ts:66-80 (schema)

  Input schema definition for the 'validate_spec' tool as registered in ListTools handler.
  { name: "validate_spec", description: "Validate a Vega-Lite specification and check for errors", inputSchema: { type: "object", properties: { spec: { type: "object", description: "Vega-Lite JSON specification to validate", }, }, required: ["spec"], additionalProperties: false, }, },
• src/index.ts:138-151 (registration)

  Registration of the tool handler in the CallToolRequest switch statement, dispatching to validateSpec.
  case "validate_spec": { if (!args?.spec) { throw new Error("Spec parameter is required"); } const validation = await validateSpec(args.spec as Record<string, unknown>); return { content: [ { type: "text", text: JSON.stringify(validation, null, 2), }, ], }; }