List ISM controls

Instructions

Implementation Reference

• src/index.ts:228-245 (handler)

  Handler function for list_controls tool: resolves version, loads flat controls, applies filters via searchControls, maps results through compactControl, and returns paginated output.

  async ({ version, applicability, group, labelPrefix, limit, offset }) => {
    const v = await resolveVersion(version);
    const flat = await loadFlat(v.tag);
    const result = searchControls(flat, {
      applicability: applicability as Applicability | undefined,
      group,
      labelPrefix,
      limit,
      offset,
    });
    return txt({
      version: v.id,
      total: result.total,
      returned: result.items.length,
      offset: offset ?? 0,
      items: result.items.map(compactControl),
    });
  },

• src/index.ts:211-226 (schema)

  Input schema for list_controls tool: optional version, applicability (enum), group substring, labelPrefix, limit (1-500), and offset.

  inputSchema: {
    version: z.string().optional(),
    applicability: ApplicabilitySchema.optional(),
    group: z
      .string()
      .optional()
      .describe("Substring match against group/chapter titles."),
    labelPrefix: z
      .string()
      .optional()
      .describe(
        'Match controls whose label starts with this prefix, e.g. "GOV".',
      ),
    limit: z.number().int().min(1).max(500).optional(),
    offset: z.number().int().min(0).optional(),
  },

• src/index.ts:93-97 (schema)

  Applicability enum schema (NC, OS, P, S, TS) used by list_controls input schema.

  const ApplicabilitySchema = z
    .enum(["NC", "OS", "P", "S", "TS"])
    .describe(
      "Applicability marking: NC=Non-classified, OS=OFFICIAL: Sensitive, P=PROTECTED, S=SECRET, TS=TOP SECRET.",
    );

• src/index.ts:205-246 (registration)

  Registration of the list_controls tool via server.registerTool with its name, metadata, schema, and handler.

  server.registerTool(
    "list_controls",
    {
      title: "List ISM controls",
      description:
        'Returns a paginated, filtered list of ISM controls. Supports filters by applicability, group/section name (substring), and label prefix (e.g. "GOV", "AC", "PHYS").',
      inputSchema: {
        version: z.string().optional(),
        applicability: ApplicabilitySchema.optional(),
        group: z
          .string()
          .optional()
          .describe("Substring match against group/chapter titles."),
        labelPrefix: z
          .string()
          .optional()
          .describe(
            'Match controls whose label starts with this prefix, e.g. "GOV".',
          ),
        limit: z.number().int().min(1).max(500).optional(),
        offset: z.number().int().min(0).optional(),
      },
    },
    async ({ version, applicability, group, labelPrefix, limit, offset }) => {
      const v = await resolveVersion(version);
      const flat = await loadFlat(v.tag);
      const result = searchControls(flat, {
        applicability: applicability as Applicability | undefined,
        group,
        labelPrefix,
        limit,
        offset,
      });
      return txt({
        version: v.id,
        total: result.total,
        returned: result.items.length,
        offset: offset ?? 0,
        items: result.items.map(compactControl),
      });
    },
  );

• src/store.ts:110-139 (helper)

  searchControls function: filters FlatControl array by applicability, group substring, labelPrefix, and supports pagination with limit/offset. Called by the list_controls handler.

  export function searchControls(
    controls: FlatControl[],
    opts: SearchOptions,
  ): SearchResult {
    const q = opts.query?.toLowerCase().trim();
    const groupQ = opts.group?.toLowerCase().trim();
    const labelPrefix = opts.labelPrefix?.toUpperCase().trim();
  
    const filtered = controls.filter((c) => {
      if (opts.applicability && !c.applicability.includes(opts.applicability))
        return false;
      if (groupQ && !c.groupPath.some((g) => g.toLowerCase().includes(groupQ)))
        return false;
      if (labelPrefix && !c.label.toUpperCase().startsWith(labelPrefix))
        return false;
      if (q) {
        const hay =
          `${c.label} ${c.title} ${c.statement} ${c.groupPath.join(" ")}`.toLowerCase();
        if (!hay.includes(q)) return false;
      }
      return true;
    });
  
    const offset = Math.max(0, opts.offset ?? 0);
    const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
    return {
      total: filtered.length,
      items: filtered.slice(offset, offset + limit),
    };
  }

• src/index.ts:74-82 (helper)

  compactControl helper: maps a FlatControl to a compact object with id, label, title, section, and applicability.

  function compactControl(c: FlatControl) {
    return {
      id: c.id,
      label: c.label,
      title: c.title,
      section: c.groupPath.join(" › "),
      applicability: c.applicability,
    };
  }