Search AsyncAPI Spec

Instructions

Implementation Reference

• src/tools.ts:72-116 (registration)

  Registration of the 'search_asyncapi_spec' tool with input schema (version, query, limit) and handler that fetches the spec and calls searchSpec.

  mcpServer.registerTool(
      'search_asyncapi_spec',
      {
          title: 'Search AsyncAPI Spec',
          description: 'Search the latest AsyncAPI markdown specification and return matching snippets.',
          inputSchema: z.object({
              version: z
                  .string()
                  .optional()
                  .describe('Optional spec version, for example "3.0.0". Defaults to latest from master.'),
              query: z.string().min(1).describe('Search query to find in the AsyncAPI specification.'),
              limit: z
                  .number()
                  .int()
                  .min(1)
                  .max(20)
                  .default(10)
                  .describe('Maximum number of matching snippets to return.'),
          }),
      },
      async ({ version, query, limit }) => {
          try {
              const entry = await fetchAsyncApiSpec(version);
              const results = searchSpec(entry.text, query, limit);
              const output = {
                  version: entry.version ?? null,
                  requestedVersion: entry.requestedVersion ?? null,
                  resolvedTag: entry.resolvedTag ?? null,
                  query,
                  count: results.length,
                  results,
              };
  
              return {
                  content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
                  structuredContent: output,
              };
          } catch (error) {
              return {
                  isError: true,
                  content: [{ type: 'text', text: formatUnknownError(error) }],
              };
          }
      }
  );

• src/tools.ts:77-91 (schema)

  Input schema for the search_asyncapi_spec tool using Zod validation.

      inputSchema: z.object({
          version: z
              .string()
              .optional()
              .describe('Optional spec version, for example "3.0.0". Defaults to latest from master.'),
          query: z.string().min(1).describe('Search query to find in the AsyncAPI specification.'),
          limit: z
              .number()
              .int()
              .min(1)
              .max(20)
              .default(10)
              .describe('Maximum number of matching snippets to return.'),
      }),
  },

• src/tools.ts:92-115 (handler)

  Handler function that fetches the AsyncAPI spec, runs searchSpec, and returns matching snippets.

  async ({ version, query, limit }) => {
      try {
          const entry = await fetchAsyncApiSpec(version);
          const results = searchSpec(entry.text, query, limit);
          const output = {
              version: entry.version ?? null,
              requestedVersion: entry.requestedVersion ?? null,
              resolvedTag: entry.resolvedTag ?? null,
              query,
              count: results.length,
              results,
          };
  
          return {
              content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
              structuredContent: output,
          };
      } catch (error) {
          return {
              isError: true,
              content: [{ type: 'text', text: formatUnknownError(error) }],
          };
      }
  }

• src/asyncapi-spec.ts:294-328 (helper)

  Core search function that takes spec text, a query, and a limit, returning matching snippets with line number and heading context.

  export const searchSpec = (text: string, query: string, limit: number): SpecSearchResult[] => {
      const normalizedQuery = query.trim().toLowerCase();
  
      if (!normalizedQuery) {
          return [];
      }
  
      const lines = text.split(/\r?\n/);
      const results: SpecSearchResult[] = [];
      let currentHeading: string | undefined;
  
      lines.forEach((line, index) => {
          const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
          const headingTitle = cleanHeadingTitle(headingMatch?.[2] ?? '');
          if (headingTitle) {
              currentHeading = headingTitle;
          }
  
          if (results.length >= limit || !line.toLowerCase().includes(normalizedQuery)) {
              return;
          }
  
          const start = Math.max(0, index - 1);
          const end = Math.min(lines.length, index + 2);
          const snippet = lines.slice(start, end).join('\n').trim();
  
          results.push({
              line: index + 1,
              heading: currentHeading,
              snippet,
          });
      });
  
      return results;
  };