Validate AsyncAPI Spec

Instructions

Implementation Reference

• src/asyncapi-parser.ts:58-71 (handler)

  The main handler function that validates an AsyncAPI spec string using @asyncapi/parser and returns validation errors, warnings, and counts.

  export const validateAsyncApiSpec = async (spec: string): Promise<AsyncApiValidationResult> => {
      const diagnostics = await parser.validate(spec);
      const issues = diagnostics.map(diagnosticToIssue);
      const errors = issues.filter(issue => issue.severity === 'error');
      const warnings = issues.filter(issue => issue.severity === 'warning' || issue.severity === 'info' || issue.severity === 'hint');
  
      return {
          valid: errors.length === 0,
          errorCount: errors.length,
          warningCount: warnings.length,
          errors,
          warnings,
      };
  };

• src/asyncapi-parser.ts:3-10 (schema)

  Type definition for a single validation issue (message, path, code, severity, line, character).

  export type AsyncApiValidationIssue = {
      message: string;
      path?: string;
      code?: string | number;
      severity: 'error' | 'warning' | 'info' | 'hint' | 'unknown';
      line?: number;
      character?: number;
  };

• src/asyncapi-parser.ts:12-18 (schema)

  Type definition for the validation result (valid, errorCount, warningCount, errors, warnings).

  export type AsyncApiValidationResult = {
      valid: boolean;
      errorCount: number;
      warningCount: number;
      errors: AsyncApiValidationIssue[];
      warnings: AsyncApiValidationIssue[];
  };

• src/tools.ts:118-142 (registration)

  Tool registration at the MCP server level – connects the tool name 'validate_asyncapi_spec' to its input schema and handler callback.

  mcpServer.registerTool(
      'validate_asyncapi_spec',
      {
          title: 'Validate AsyncAPI Spec',
          description: 'Validate raw AsyncAPI YAML or JSON content and return validation errors if the spec is invalid.',
          inputSchema: z.object({
              spec: z.string().min(1).describe('Raw AsyncAPI document content as YAML or JSON.'),
          }),
      },
      async ({ spec }) => {
          try {
              const validation = await validateAsyncApiSpec(spec);
  
              return {
                  content: [{ type: 'text', text: JSON.stringify(validation, null, 2) }],
                  structuredContent: validation,
              };
          } catch (error) {
              return {
                  isError: true,
                  content: [{ type: 'text', text: formatUnknownError(error) }],
              };
          }
      }
  );

• src/asyncapi-parser.ts:22-56 (helper)

  Helper functions: severityLabel maps DiagnosticSeverity to a label string, pathToString converts diagnostic path to dot-notation, diagnosticToIssue transforms a Diagnostic into an AsyncApiValidationIssue.

  const severityLabel = (severity: Diagnostic['severity']): AsyncApiValidationIssue['severity'] => {
      switch (severity) {
          case DiagnosticSeverity.Error:
              return 'error';
          case DiagnosticSeverity.Warning:
              return 'warning';
          case DiagnosticSeverity.Information:
              return 'info';
          case DiagnosticSeverity.Hint:
              return 'hint';
          default:
              return 'unknown';
      }
  };
  
  const pathToString = (path: Diagnostic['path']): string | undefined => {
      if (!Array.isArray(path) || path.length === 0) {
          return undefined;
      }
  
      return path.map(segment => String(segment)).join('.');
  };
  
  const diagnosticToIssue = (diagnostic: Diagnostic): AsyncApiValidationIssue => {
      const start = diagnostic.range?.start;
  
      return {
          message: diagnostic.message,
          path: pathToString(diagnostic.path),
          code: diagnostic.code,
          severity: severityLabel(diagnostic.severity),
          line: typeof start?.line === 'number' ? start.line + 1 : undefined,
          character: typeof start?.character === 'number' ? start.character + 1 : undefined,
      };
  };