oathe-mcp

Instructions

Implementation Reference

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

  The main handler function that executes the check_audit_status tool logic. It fetches audit status from the API endpoint using the provided audit_id, handles 404 errors for invalid/expired audit IDs, and returns the status data as JSON text.
  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 definition for the check_audit_status tool using zod validation. Defines a single required parameter 'audit_id' as a UUID string that was returned by submit_audit.
  inputSchema: { audit_id: z .string() .describe('UUID returned by submit_audit'), },
• src/tools/check-status.ts:6-51 (registration)

  Complete registration function for the check_audit_status tool. Registers the tool with the MCP server including description, input schema, and handler callback.
  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/lib/types.ts:11-25 (schema)

  Type definition for AuditStatusResponse interface which defines the structure of the API response including audit_id, status, optional stage_label and error_message, and a complete report object with trust_score, verdict, findings, etc.
  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[]; }; }
• src/index.ts:5-20 (registration)

  Main entry point that imports registerCheckStatus and calls it to register the check_audit_status tool with the MCP server instance.
  import { registerCheckStatus } from './tools/check-status.js'; import { registerGetReport } from './tools/get-report.js'; import { registerGetSummary } from './tools/get-summary.js'; import { registerSearchAudits } from './tools/search-audits.js'; const server = new McpServer({ name: 'oathe-mcp', version: '0.1.1', description: 'Security scanner for AI agent skills. Before installing any third-party ' + 'MCP server, plugin, or tool, check it with Oathe first. Returns trust ' + 'scores, verdicts, and detailed findings. Free, no API key required.', }); registerSubmitAudit(server); registerCheckStatus(server);