nteract/semiotic

Instructions

Implementation Reference

• ai/mcp-server.ts:335-364 (handler)

  MCP tool handler for 'diagnoseConfig' that validates component props and reports diagnostic findings.

  async function diagnoseConfigHandler(args: { component?: string; props?: Record<string, any> }): Promise<ToolResult> {
    const component = args.component
    const props: Record<string, any> = args.props ?? {}
  
    if (!component) {
      return {
        content: [{ type: "text" as const, text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
        isError: true,
      }
    }
  
    const result = diagnoseConfig(component, props)
    if (result.ok) {
      const warnings = result.diagnoses.filter((d: any) => d.severity === "warning")
      const msg = warnings.length > 0
        ? `Configuration looks good with ${warnings.length} warning(s):\n${warnings.map((w: any) => `⚠ [${w.code}] ${w.message}\n  Fix: ${w.fix}`).join("\n")}`
        : `✓ Configuration looks good — no issues detected.`
      return { content: [{ type: "text" as const, text: msg }] }
    }
  
    const lines = result.diagnoses.map((d: any) => {
      const icon = d.severity === "error" ? "✗" : "⚠"
      const fixLine = d.fix ? `\n  Fix: ${d.fix}` : ""
      return `${icon} [${d.code}] ${d.message}${fixLine}`
    })
    return {
      content: [{ type: "text" as const, text: lines.join("\n") }],
      isError: true,
    }
  }

• src/components/charts/shared/diagnoseConfig.ts:434-477 (handler)

  Core implementation of 'diagnoseConfig' which orchestrates various diagnostic checks for Semiotic chart configurations.

  export function diagnoseConfig(
    componentName: string,
    props: Record<string, any>
  ): DiagnosisResult {
    const diagnoses: Diagnosis[] = []
  
    // Run validateProps first
    const validation = validateProps(componentName, props)
    for (const err of validation.errors) {
      diagnoses.push({
        severity: "error",
        code: "VALIDATION",
        message: err,
        fix: "", // validateProps errors already contain guidance
      })
    }
  
    // If component is unknown, skip further checks
    if (!VALIDATION_MAP[componentName]) {
      return { ok: diagnoses.length === 0, diagnoses }
    }
  
    // Run anti-pattern checks
    checkEmptyData(componentName, props, diagnoses)
    checkBadDimensions(componentName, props, diagnoses)
    checkAccessorFieldMissing(componentName, props, diagnoses)
    checkHierarchyDataAsArray(componentName, props, diagnoses)
    checkNetworkMissingEdges(componentName, props, diagnoses)
    checkDateWithoutFormat(componentName, props, diagnoses)
    checkLinkedChartsWithoutSelection(componentName, props, diagnoses)
    checkNonZeroBaseline(componentName, props, diagnoses)
    checkDataGaps(componentName, props, diagnoses)
    checkMarginOverflow(componentName, props, diagnoses)
    checkDegenerateExtent(componentName, props, diagnoses)
    checkBarPaddingInvisible(componentName, props, diagnoses)
    checkBottomMarginWithLegend(componentName, props, diagnoses)
    checkLegendMarginTight(componentName, props, diagnoses)
    checkHeatmapStringAccessor(componentName, props, diagnoses)
  
    return {
      ok: diagnoses.every(d => d.severity === "warning"),
      diagnoses,
    }
  }

• ai/mcp-server.ts:430-438 (registration)

  Registration of the 'diagnoseConfig' MCP tool within the McpServer instance.

  srv.tool(
    "diagnoseConfig",
    "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, etc). Returns a human-readable diagnostic report with actionable fixes.",
    {
      component: z.string().describe("Chart component name, e.g. 'LineChart'"),
      props: z.record(z.string(), z.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
    },
    diagnoseConfigHandler
  )