server_explain

Instructions

Implementation Reference

• src/mcp/tools/serverExplain.ts:11-22 (handler)

  The handler function for the 'server_explain' tool. It calls findCheckById() to look up an audit check, and returns the result via mcpSuccess or an error via mcpError with fuzzy-matching suggestions.

  export async function serverExplainHandler(params: ServerExplainParams) {
    const result = findCheckById(params.checkId);
  
    if (!result.match) {
      return mcpError(
        `Unknown check ID: ${params.checkId}. ${formatSuggestions(result.suggestions)}`,
        "Use server_audit with listChecks action or kastell audit --list-checks to see all available check IDs.",
      );
    }
  
    return mcpSuccess({ ...result.match });
  }

• src/mcp/tools/serverExplain.ts:5-7 (schema)

  Zod schema for the server_explain tool input: requires a single 'checkId' string field with description about case-insensitive and fuzzy matching.

  export const serverExplainSchema = z.object({
    checkId: z.string().describe("Audit check ID to explain (e.g. SSH-PASSWORD-AUTH). Case-insensitive, fuzzy matching supported."),
  });

• src/mcp/server.ts:271-284 (registration)

  Registration of the 'server_explain' tool on the MCP server, including description, inputSchema, annotations (readOnlyHint, idempotentHint), and the async handler that delegates to serverExplainHandler.

  server.registerTool("server_explain", {
    description:
      "Deep-dive into a single audit check. Returns what it does, why it matters, how to fix it, fix tier (SAFE/GUARDED/FORBIDDEN), and compliance references (CIS/PCI-DSS/HIPAA). No SSH connection required. Supports case-insensitive and fuzzy matching for check IDs.",
    inputSchema: serverExplainSchema,
    annotations: {
      title: "Explain Audit Check",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  }, async (params) => {
    return serverExplainHandler(params);
  });

• src/mcp/server.ts:19-19 (registration)

  Import line that pulls in serverExplainSchema and serverExplainHandler from the tools module.

  import { serverExplainSchema, serverExplainHandler } from "./tools/serverExplain.js";

• src/core/audit/explainCheck.ts:74-101 (helper)

  Core lookup logic: findCheckById() performs exact match, case-insensitive match, substring match, and Levenshtein fuzzy matching (distance ≤ 3) to find audit check definitions in the catalog.

  export function findCheckById(checkId: string): FindCheckResult {
    const catalog = getFullCheckCatalog();
  
    // 1. Exact match — O(n) scan on 457 items is fast enough
    const exact = catalog.find((c) => c.id === checkId);
    if (exact) return { match: exact, suggestions: [] };
  
    // 2. Case-insensitive match
    const upper = checkId.toUpperCase();
    const ci = catalog.find((c) => c.id.toUpperCase() === upper);
    if (ci) return { match: ci, suggestions: [] };
  
    // 3. Substring match — e.g. "ssh-password" finds "SSH-PASSWORD-AUTH"
    const subs = catalog.filter((c) => c.id.toUpperCase().includes(upper));
    if (subs.length === 1) return { match: subs[0], suggestions: [] };
    if (subs.length > 1) return { match: null, suggestions: subs.slice(0, 3).map((s) => s.id) };
  
    // 4. Levenshtein ≤ 3
    const scored = catalog
      .map((c) => ({ id: c.id, dist: levenshtein(upper, c.id.toUpperCase()) }))
      .filter((s) => s.dist <= 3)
      .sort((a, b) => a.dist - b.dist);
  
    return {
      match: null,
      suggestions: scored.slice(0, 3).map((s) => s.id),
    };
  }