List ISM versions

Instructions

Implementation Reference

• src/index.ts:114-140 (registration)

  MCP tool registration for 'list_versions'. Defines the tool name, description, input schema (optional 'refresh' boolean and optional 'limit' integer), and the handler callback that calls the underlying listVersions function and formats the result.

  server.registerTool(
    "list_versions",
    {
      title: "List ISM versions",
      description:
        "Lists every published ISM release (historical, current, and any future tags as soon as they appear upstream). Returns tag, version id, commit SHA, and release date parsed from the tag.",
      inputSchema: {
        refresh: z
          .boolean()
          .optional()
          .describe(
            "Force a refresh of the upstream tag list, bypassing the cache.",
          ),
        limit: z.number().int().min(1).max(200).optional(),
      },
    },
    async ({ refresh, limit }) => {
      const versions = await listVersions({ force: refresh });
      const items = limit ? versions.slice(0, limit) : versions;
      return txt({
        latest: versions[0]?.id ?? null,
        count: versions.length,
        versions: items,
        source: "https://github.com/AustralianCyberSecurityCentre/ism-oscal",
      });
    },
  );

• src/index.ts:130-139 (handler)

  Inline handler callback for the 'list_versions' tool. Calls listVersions({ force: refresh }), optionally slices by limit, and returns a JSON response with latest, count, versions array, and source URL.

  async ({ refresh, limit }) => {
    const versions = await listVersions({ force: refresh });
    const items = limit ? versions.slice(0, limit) : versions;
    return txt({
      latest: versions[0]?.id ?? null,
      count: versions.length,
      versions: items,
      source: "https://github.com/AustralianCyberSecurityCentre/ism-oscal",
    });
  },

• src/sources.ts:163-212 (handler)

  Core implementation of listVersions(). Fetches bundled versions from local data, optionally fetches from GitHub API (paginated), merges them, caches the result, and returns sorted IsmVersion[]. Handles offline mode and fallback to bundled/cached data on network error.

  export async function listVersions(
    opts: { force?: boolean } = {},
  ): Promise<IsmVersion[]> {
    const now = Date.now();
    if (!opts.force && tagsMemo && now - tagsMemo.fetchedAt < TAGS_TTL_MS) {
      return tagsMemo.versions;
    }
  
    const bundled = await loadBundleIndex();
    const bundledVersions = (bundled?.versions ?? []).map((v) => ({
      ...v,
      bundled: true,
    }));
  
    if (OFFLINE) {
      if (bundledVersions.length === 0) {
        throw new Error(
          "ISM_MCP_OFFLINE is set but no bundled data was found. " +
            "Run `npm run bundle` (or use a release tarball that includes data/).",
        );
      }
      bundledVersions.sort(compareVersionsDesc);
      tagsMemo = { fetchedAt: now, versions: bundledVersions };
      return bundledVersions;
    }
  
    await ensureCacheDir();
    const cacheFile = join(CACHE_DIR, "tags.json");
  
    try {
      const networkVersions = await fetchAllTagsFromGitHub();
      const merged = mergeVersions(bundledVersions, networkVersions);
      tagsMemo = { fetchedAt: now, versions: merged };
      await writeFile(cacheFile, JSON.stringify(tagsMemo), "utf8");
      return merged;
    } catch (err) {
      if (bundledVersions.length > 0) {
        bundledVersions.sort(compareVersionsDesc);
        tagsMemo = { fetchedAt: now, versions: bundledVersions };
        return bundledVersions;
      }
      if (existsSync(cacheFile)) {
        const raw = await readFile(cacheFile, "utf8");
        const cached = JSON.parse(raw) as CachedTags;
        tagsMemo = cached;
        return cached.versions;
      }
      throw err;
    }
  }

• src/sources.ts:33-44 (schema)

  IsmVersion interface type definition used as the return type of listVersions. Contains tag, id, sha, date, and optional bundled fields.

  export interface IsmVersion {
    /** Tag name, e.g. "v2026.03.24" */
    tag: string;
    /** Semver-ish id without the leading "v", e.g. "2026.03.24" */
    id: string;
    /** Commit SHA the tag points at */
    sha: string;
    /** Publication date parsed from tag (YYYY-MM-DD), best-effort. */
    date: string | null;
    /** Whether this version's data is bundled with the package. */
    bundled?: boolean;
  }

• src/index.ts:889-898 (helper)

  Startup warm-up call to listVersions() in main(), prefetching the version list early and logging a warning on failure.

  async function main(): Promise<void> {
    // Warm up the version list (and surface auth/network errors early), but
    // don't fail startup — the tool can also report this on demand.
    try {
      await listVersions();
    } catch (err) {
      process.stderr.write(
        `[ism-mcp] warning: failed to fetch versions at startup: ${(err as Error).message}\n`,
      );
    }