skvil-mcp

Instructions

Implementation Reference

• src/tools.ts:292-333 (handler)

  The skvil_report tool handler registered on the MCP server. Takes hash, reason, and optional details parameters, calls api.report(), and returns a formatted success response with report ID and status.

  // ── skvil_report ──────────────────────────────────────────────────────────
  server.tool(
    'skvil_report',
    'Report a suspicious or malicious AI agent skill to Skvil admins for review. ' +
      'Requires an API key (use skvil_register first). Reports are reviewed by ' +
      'admins and confirmed findings lead to certification revocation.',
    {
      hash: hashSchema,
      reason: z
        .string()
        .min(10)
        .max(1000)
        .describe('Why this skill is suspicious (10-1000 characters)'),
      details: z
        .string()
        .max(5000)
        .optional()
        .describe('Additional details or evidence (optional, max 5000 characters)'),
    },
    async ({ hash, reason, details }) => {
      try {
        const result = await api.report(hash, reason, details);
        return {
          content: [
            {
              type: 'text',
              text:
                '**Report submitted successfully**\n\n' +
                `- **Report ID:** ${result.report_id}\n` +
                `- **Status:** ${result.status}\n` +
                `- **Skill hash:** ${hash}\n\n` +
                'A Skvil admin will review this report. If confirmed, the skill ' +
                'will be flagged as malicious and any existing certification ' +
                'will be revoked.',
            },
          ],
        };
      } catch (error) {
        return { content: [{ type: 'text', text: formatError('report', error) }], isError: true };
      }
    },
  );

• src/tools.ts:298-310 (schema)

  Input validation schema for skvil_report: hash (SHA-256), reason (10-1000 chars), and optional details (max 5000 chars).

  {
    hash: hashSchema,
    reason: z
      .string()
      .min(10)
      .max(1000)
      .describe('Why this skill is suspicious (10-1000 characters)'),
    details: z
      .string()
      .max(5000)
      .optional()
      .describe('Additional details or evidence (optional, max 5000 characters)'),
  },

• src/api.ts:156-165 (helper)

  API function that sends a POST request to /report endpoint with the skill hash, reason, and optional details. Requires authentication.

  /** Report a suspicious skill. */
  export async function report(
    hash: string,
    reason: string,
    details?: string,
  ): Promise<ReportResponse> {
    const body: Record<string, string> = { composite_hash: hash, reason };
    if (details !== undefined) body.details = details;
    return request<ReportResponse>('POST', '/report', { body, auth: true });
  }

• src/types.ts:102-105 (schema)

  ReportResponse type definition containing report_id (number) and status (string).

  export interface ReportResponse {
    report_id: number;
    status: string;
  }