user-audit-tool

Instructions

Implementation Reference

• src/tools/user-audit-tool.ts:27-81 (handler)

  The main tool handler function (TOOL_HANDLER) that processes audit-by-user or audit-by-target requests. It extracts args, calls the appropriate API function, and returns structured content.

  const TOOL_HANDLER = async (args: ToolArgs, _extra: unknown) => {
    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
  
    try {
      switch (args.requestType) {
        case UserAuditRequestType.AUDIT_BY_USER: {
          if (!args.userUuid) {
            return createToolStructuredContent<OUTPUT_SCHEMA>({
              error: "userUuid is required for audit-by-user. Use user-tool to find it.",
            });
          }
          const auditEvents = await getAuditFeedForPrincipal(
            args.userUuid,
            args.maxResults ?? undefined,
            requestModifiers,
            sessionId
          );
          return createToolStructuredContent<OUTPUT_SCHEMA>({ auditEvents });
        }
        case UserAuditRequestType.AUDIT_BY_TARGET: {
          if (!args.targetUuid) {
            return createToolStructuredContent<OUTPUT_SCHEMA>({
              error: "targetUuid is required for audit-by-target.",
            });
          }
          const auditEvents = await getAuditFeedForTarget(
            args.targetUuid,
            args.maxResults ?? undefined,
            requestModifiers,
            sessionId
          );
          return createToolStructuredContent<OUTPUT_SCHEMA>({ auditEvents });
        }
      }
    } catch (error: unknown) {
      if (error instanceof Error) {
        return createToolStructuredContent<OUTPUT_SCHEMA>({ error: error.message });
      }
      return createToolStructuredContent<OUTPUT_SCHEMA>({ error: "Unknown error" });
    }
  
    return createToolStructuredContent<OUTPUT_SCHEMA>({ error: "Invalid request type" });
  };
  
  export function createTool(server: McpServer) {
    server.registerTool(
      TOOL_NAME,
      {
        description: TOOL_DESCRIPTION,
        inputSchema: TOOL_ARGS,
        outputSchema: OUTPUT_SCHEMA.shape,
      },
      TOOL_HANDLER
    );
  }

• src/types/user-audit-tool-types.ts:1-53 (schema)

  Type definitions including the enum UserAuditRequestType, input schema (TOOL_ARGS) with Zod validations, AuditEventSchema, and OUTPUT_SCHEMA defining the structure of tool responses.

  import { z } from "zod";
  import { INCLUDE_FIELDS_ARG, FILTER_BY_ARG } from "../util.js";
  
  export enum UserAuditRequestType {
    AUDIT_BY_USER = "audit-by-user",
    AUDIT_BY_TARGET = "audit-by-target",
  }
  
  export const TOOL_ARGS = {
    requestType: z
      .nativeEnum(UserAuditRequestType)
      .describe("The type of audit request to make."),
    userUuid: z
      .string()
      .nullable()
      .describe("User UUID whose actions to audit. Required for 'audit-by-user'. Use user-tool to find this."),
    targetUuid: z
      .string()
      .nullable()
      .describe("Target entity UUID (camera, door, policy, etc.) to see what has been done to it. Required for 'audit-by-target'."),
    maxResults: z
      .number()
      .nullable()
      .describe("Maximum number of audit events to return. Defaults to 50."),
    includeFields: INCLUDE_FIELDS_ARG,
    filterBy: FILTER_BY_ARG,
  };
  const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
  export type ToolArgs = z.infer<typeof TOOL_ARGS_SCHEMA>;
  
  const AuditEventSchema = z.object({
    uuid: z.string().optional(),
    action: z.string().optional(),
    displayText: z.string().optional(),
    principalName: z.string().optional(),
    principalUuid: z.string().optional(),
    targetName: z.string().optional(),
    targetUuid: z.string().optional(),
    timestamp: z.string().optional(),
    failure: z.boolean().optional(),
    sourceIp: z.string().optional(),
    sourceCity: z.string().optional(),
    sourceCountry: z.string().optional(),
  });
  
  export const OUTPUT_SCHEMA = z.object({
    auditEvents: z
      .array(AuditEventSchema)
      .optional()
      .describe("List of audit events, most recent first"),
    error: z.string().optional().describe("An error message if the request failed."),
  });
  export type OUTPUT_SCHEMA = z.infer<typeof OUTPUT_SCHEMA>;

• src/tools/user-audit-tool.ts:71-82 (registration)

  The createTool function that registers the tool with the MCP server using server.registerTool(TOOL_NAME, ..., TOOL_HANDLER).

  export function createTool(server: McpServer) {
    server.registerTool(
      TOOL_NAME,
      {
        description: TOOL_DESCRIPTION,
        inputSchema: TOOL_ARGS,
        outputSchema: OUTPUT_SCHEMA.shape,
      },
      TOOL_HANDLER
    );
  }

• src/api/user-audit-tool-api.ts:1-82 (helper)

  API layer with getAuditFeedForPrincipal and getAuditFeedForTarget functions that call the backend API endpoints, plus mapAuditEvents helper to transform response data.

  import { postApi } from "../network/network.js";
  import type { schema } from "../types/schema.js";
  import type { RequestModifiers } from "../util.js";
  
  interface AuditEvent {
    uuid?: string;
    action?: string;
    displayText?: string;
    principalName?: string;
    principalUuid?: string;
    targetName?: string;
    targetUuid?: string;
    timestamp?: string;
    failure?: boolean;
    sourceIp?: string;
    sourceCity?: string;
    sourceCountry?: string;
  }
  
  function mapAuditEvents(events: schema["Report_AuditEventWeb"][]): AuditEvent[] {
    return events.map(evt => ({
      uuid: evt.uuid ?? undefined,
      action: (evt.action as string) ?? undefined,
      displayText: evt.displayText ?? undefined,
      principalName: evt.principalName ?? undefined,
      principalUuid: evt.principalUuid ?? undefined,
      targetName: evt.targetName ?? undefined,
      targetUuid: evt.targetUuid ?? undefined,
      timestamp: evt.timestamp ?? undefined,
      failure: evt.failure ?? undefined,
      sourceIp: evt.sourceIp ?? undefined,
      sourceCity: evt.sourceCity ?? undefined,
      sourceCountry: evt.sourceCountry ?? undefined,
    }));
  }
  
  export async function getAuditFeedForPrincipal(
    principalUuid: string,
    maxResults?: number,
    requestModifiers?: RequestModifiers,
    sessionId?: string
  ): Promise<AuditEvent[]> {
    const res = await postApi<schema["Report_GetAuditFeedForPrincipalWSResponse"]>({
      route: "/report/getAuditFeedForPrincipal",
      body: {
        principalUuid,
        maxResults: maxResults ?? 50,
      } satisfies schema["Report_GetAuditFeedForPrincipalWSRequest"],
      modifiers: requestModifiers,
      sessionId,
    });
  
    if (res.error) {
      throw new Error(res.errorMsg ?? "Failed to get audit feed for principal");
    }
  
    return mapAuditEvents(res.auditEvents ?? []);
  }
  
  export async function getAuditFeedForTarget(
    targetUuid: string,
    maxResults?: number,
    requestModifiers?: RequestModifiers,
    sessionId?: string
  ): Promise<AuditEvent[]> {
    const res = await postApi<schema["Report_GetAuditFeedForTargetWSResponse"]>({
      route: "/report/getAuditFeedForTarget",
      body: {
        targetUuid,
        maxResults: maxResults ?? 50,
      } satisfies schema["Report_GetAuditFeedForTargetWSRequest"],
      modifiers: requestModifiers,
      sessionId,
    });
  
    if (res.error) {
      throw new Error(res.errorMsg ?? "Failed to get audit feed for target");
    }
  
    return mapAuditEvents(res.auditEvents ?? []);
  }