check_audit_status

Instructions

Implementation Reference

• src/tools/check-status.ts:22-49 (handler)

  The main handler function for check_audit_status. Calls the Oathe API endpoint /api/audit/{audit_id} and returns the audit status response. Handles 404 errors (audit not found) and other API errors.

  async ({ audit_id }) => {
    try {
      const res = await apiFetch(`/api/audit/${audit_id}`);
      const data = (await res.json()) as AuditStatusResponse;
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
      };
    } catch (err) {
      if (err instanceof ApiError) {
        if (err.status === 404) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'Audit ID not found — may have expired or be invalid.',
              },
            ],
            isError: true,
          };
        }
        return {
          content: [{ type: 'text' as const, text: err.message }],
          isError: true,
        };
      }
      throw err;
    }
  },

• src/tools/check-status.ts:16-20 (schema)

  Input schema for check_audit_status — accepts a single required 'audit_id' string parameter.

  inputSchema: {
    audit_id: z
      .string()
      .describe('UUID returned by submit_audit'),
  },

• src/tools/check-status.ts:6-51 (registration)

  Registration of the 'check_audit_status' tool on the McpServer via registerTool, including its description and input schema.

  export function registerCheckStatus(server: McpServer): void {
    server.registerTool(
      'check_audit_status',
      {
        description:
          'Check the status of an Oathe security audit submitted via submit_audit. ' +
          'Wait 90 seconds after submission before first poll, then poll every 10 seconds until status is "complete" or "failed". ' +
          'Statuses: queued, scanning, analyzing, summarizing, finalizing, complete, failed. ' +
          'Terminal statuses: complete, failed. ' +
          'When complete, the response includes the full audit report with trust score, verdict, and findings.',
        inputSchema: {
          audit_id: z
            .string()
            .describe('UUID returned by submit_audit'),
        },
      },
      async ({ audit_id }) => {
        try {
          const res = await apiFetch(`/api/audit/${audit_id}`);
          const data = (await res.json()) as AuditStatusResponse;
          return {
            content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
          };
        } catch (err) {
          if (err instanceof ApiError) {
            if (err.status === 404) {
              return {
                content: [
                  {
                    type: 'text' as const,
                    text: 'Audit ID not found — may have expired or be invalid.',
                  },
                ],
                isError: true,
              };
            }
            return {
              content: [{ type: 'text' as const, text: err.message }],
              isError: true,
            };
          }
          throw err;
        }
      },
    );
  }

• src/index.ts:20-20 (registration)

  Top-level call to registerCheckStatus, connecting the tool to the MCP server at startup.

  registerCheckStatus(server);

• src/lib/types.ts:11-25 (helper)

  Type definition for AuditStatusResponse, the structure returned by the check_audit_status API.

  export interface AuditStatusResponse {
    audit_id: string;
    skill_url?: string;
    status: string;
    stage_label?: string;
    error_message?: string;
    report?: {
      trust_score: number;
      verdict: string;
      summary?: string;
      recommendation?: string;
      category_scores?: Record<string, { score: number; weight: number; findings: string[] }>;
      findings?: Finding[];
    };
  }