vigile-mcp

Instructions

Implementation Reference

• src/tools/check-skill.ts:7-73 (handler)

  The main handler function that executes the vigile_check_skill tool logic. It fetches skill trust data from the Vigile API, handles 404 errors for unregistered skills, and formats the response with trust score, level, metadata, and security findings.

  export async function checkSkill(
    baseUrl: string,
    apiKey: string,
    name: string
  ): Promise<string> {
    const { ok, status, data } = await fetchVigile(
      baseUrl,
      apiKey,
      `/api/v1/registry/skills/${encodeURIComponent(name)}`
    );
  
    if (!ok) {
      if (status === 404) {
        return [
          `## Agent Skill: ${name}`,
          "",
          "**Not found in the Vigile registry.**",
          "",
          "This skill hasn't been scanned yet. You can submit its content for",
          "scanning using the `vigile_scan_content` tool.",
          "",
          "⚠️ An unscanned skill should be reviewed manually before use.",
        ].join("\n");
      }
      return `Error looking up skill "${name}": ${data?.detail || `HTTP ${status}`}`;
    }
  
    const emoji = trustLevelEmoji(data.trust_level);
    const lines = [
      `## ${emoji} ${data.name}`,
      "",
      `**Trust Score:** ${formatScore(data.trust_score)}`,
      `**Trust Level:** ${data.trust_level}`,
      `**File Type:** ${data.file_type}`,
      `**Platform:** ${data.platform}`,
      `**Source:** ${data.source}`,
    ];
  
    if (data.description) {
      lines.push(`**Description:** ${data.description}`);
    }
    if (data.author) {
      lines.push(`**Author:** ${data.author}`);
    }
    if (data.last_scanned) {
      lines.push(`**Last Scanned:** ${new Date(data.last_scanned).toLocaleDateString()}`);
    }
  
    // Findings summary
    if (data.latest_findings && data.latest_findings.length > 0) {
      lines.push("", "### Security Findings");
      for (const f of data.latest_findings.slice(0, 5)) {
        const severity = f.severity === "critical" ? "🔴" : f.severity === "high" ? "🟠" : "🟡";
        lines.push(`- ${severity} **[${f.severity.toUpperCase()}]** ${f.title}`);
        if (f.recommendation) {
          lines.push(`  → ${f.recommendation}`);
        }
      }
    }
  
    lines.push(
      "",
      `🔗 [Full report on Vigile](https://vigile.dev/skill/${encodeURIComponent(data.name)})`
    );
  
    return lines.join("\n");
  }

• src/index.ts:79-91 (registration)

  Registration of the vigile_check_skill tool with the MCP server. Uses server.tool() to register the tool name, description, input schema, and handler function that calls checkSkill().

  // ── Tool: vigile_check_skill ──
  
  server.tool(
    "vigile_check_skill",
    "Look up the trust score for an agent skill (claude.md, .cursorrules, skill.md, etc.) in the Vigile registry. Returns trust score, trust level, findings summary.",
    {
      name: z.string().min(1).max(200).describe("Agent skill name (e.g., 'react-component-builder')"),
    },
    async ({ name }) => {
      const result = await checkSkill(API_BASE, API_KEY, name);
      return { content: [{ type: "text" as const, text: result }] };
    }
  );

• src/index.ts:84-86 (schema)

  Zod schema definition for the vigile_check_skill tool input. Validates that 'name' is a string between 1-200 characters with a helpful description.

  {
    name: z.string().min(1).max(200).describe("Agent skill name (e.g., 'react-component-builder')"),
  },

• src/tools/api.ts:5-65 (helper)

  Helper utilities used by checkSkill: fetchVigile() makes HTTP requests to the Vigile API with error sanitization, trustLevelEmoji() converts trust level strings to emoji indicators, and formatScore() formats numeric scores as 'X/100'.

  export async function fetchVigile(
    baseUrl: string,
    apiKey: string,
    path: string,
    options?: { method?: string; body?: string }
  ): Promise<{ ok: boolean; status: number; data: any }> {
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      "User-Agent": "vigile-mcp/0.1.7",
    };
  
    if (apiKey) {
      headers["Authorization"] = `Bearer ${apiKey}`;
    }
  
    try {
      const res = await fetch(`${baseUrl}${path}`, {
        method: options?.method || "GET",
        headers,
        body: options?.body,
      });
  
      const data = await res.json().catch(() => null);
      return { ok: res.ok, status: res.status, data };
    } catch (error: any) {
      // Sanitize error message — don't leak internal details like
      // hostnames, ports, file paths, or stack traces
      const rawMsg = error?.message || "Unknown error";
      const safeMsg = rawMsg.includes("ECONNREFUSED") || rawMsg.includes("ENOTFOUND")
        ? "API server unreachable"
        : rawMsg.includes("ETIMEDOUT") || rawMsg.includes("timeout")
        ? "Request timed out"
        : rawMsg.includes("ECONNRESET")
        ? "Connection reset"
        : "Connection failed";
      return {
        ok: false,
        status: 0,
        data: { detail: safeMsg },
      };
    }
  }
  
  export function trustLevelEmoji(level: string): string {
    switch (level) {
      case "trusted":
        return "🟢";
      case "caution":
        return "🟡";
      case "risky":
        return "🟠";
      case "dangerous":
        return "🔴";
      default:
        return "⚪";
    }
  }
  
  export function formatScore(score: number): string {
    return `${Math.round(score)}/100`;
  }