List AsyncAPI Spec Versions

Instructions

Implementation Reference

• src/tools.ts:15-40 (registration)

  Registration of the 'list_asyncapi_spec_versions' tool on the MCP server. Calls listAsyncApiSpecVersions() and formats the JSON response with count and versions array.

  mcpServer.registerTool(
      'list_asyncapi_spec_versions',
      {
          title: 'List AsyncAPI Spec Versions',
          description: 'List stable AsyncAPI specification versions available as GitHub tags.',
      },
      async () => {
          try {
              const versions = await listAsyncApiSpecVersions();
              const output = {
                  count: versions.length,
                  versions,
              };
  
              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:179-179 (handler)

  The exported handler function 'listAsyncApiSpecVersions' that delegates to fetchVersionTags().

  export const listAsyncApiSpecVersions = async (): Promise<VersionTag[]> => fetchVersionTags();

• src/asyncapi-spec.ts:115-144 (helper)

  The 'fetchVersionTags' helper that fetches GitHub tags from the asyncapi/spec repository, filters stable version tags (e.g. v3.0.0), and caches them for 10 minutes.

  const fetchVersionTags = async (): Promise<VersionTag[]> => {
      if (tagCache && Date.now() - tagCache.fetchedAt.getTime() < TAG_CACHE_TTL_MS) {
          return tagCache.tags;
      }
  
      const response = await fetch(ASYNCAPI_SPEC_REPO_TAGS_URL, {
          headers: {
              Accept: 'application/vnd.github+json',
              'User-Agent': 'asyncapi-mcp',
          },
      });
  
      if (!response.ok) {
          throw new Error(`GitHub tags API returned ${response.status} ${response.statusText}`);
      }
  
      const tags = (await response.json()) as GitHubTag[];
      const versionTags = tags
          .map(tag => tag.name)
          .filter(isStableVersionTag)
          .map(tag => ({ tag, version: versionFromTag(tag) }))
          .sort((a, b) => a.version.localeCompare(b.version, undefined, { numeric: true }));
  
      tagCache = {
          tags: versionTags,
          fetchedAt: new Date(),
      };
  
      return versionTags;
  };

• src/asyncapi-spec.ts:58-61 (schema)

  The VersionTag type used as the return type of listAsyncApiSpecVersions, with 'version' (normalized) and 'tag' (original GitHub tag name) fields.

  type VersionTag = {
      version: string;
      tag: string;
  };

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

  The 'isStableVersionTag' regex helper used to filter tags matching a stable semver pattern like v?X.Y.Z.

  const isStableVersionTag = (tag: string): boolean => /^v?\d+\.\d+\.\d+$/.test(tag);