osint-mcp-server

Instructions

Implementation Reference

• src/virustotal/index.ts:127-159 (handler)

  Implementation of the vtUrl function which submits a URL to VirusTotal for analysis and attempts to fetch the analysis results.

  export async function vtUrl(url: string, apiKey: string): Promise<VtUrlResult> {
    // Submit URL for analysis
    await limiter.acquire();
    const submitRes = await fetch(`${VT_BASE}/urls`, {
      method: "POST",
      headers: { "x-apikey": apiKey, "Content-Type": "application/x-www-form-urlencoded" },
      body: `url=${encodeURIComponent(url)}`,
    });
  
    if (!submitRes.ok) throw new Error(`VirusTotal URL submit failed: ${submitRes.status}`);
    const submitData = await submitRes.json();
    const analysisId = submitData.data?.id;
  
    if (!analysisId) {
      return { url, status: "submitted", analysisId: undefined };
    }
  
    // Try to get analysis results (may not be ready yet)
    try {
      const analysisData = await vtFetch(`/analyses/${analysisId}`, apiKey);
      if (analysisData?.data?.attributes?.status === "completed") {
        return {
          url,
          analysisId,
          analysisStats: analysisData.data.attributes.stats,
          status: "completed",
        };
      }
      return { url, analysisId, status: analysisData?.data?.attributes?.status ?? "queued" };
    } catch {
      return { url, analysisId, status: "queued" };
    }
  }

• src/virustotal/index.ts:45-50 (schema)

  TypeScript interface defining the result structure for vtUrl analysis.

  interface VtUrlResult {
    url: string;
    analysisId?: string;
    analysisStats?: VtAnalysisStats;
    status: string;
  }

• src/protocol/tools.ts:219-229 (registration)

  Registration of the vt_url tool, defining its metadata and the execution logic calling vtUrl.

  const vtUrlTool: ToolDef = {
    name: "vt_url",
    description: "Submit a URL to VirusTotal for scanning and get analysis results (malicious/suspicious/harmless). Requires VT_API_KEY.",
    schema: {
      url: z.string().describe("URL to scan"),
    },
    execute: async (args, ctx) => {
      const key = requireApiKey(ctx.config.vtApiKey, "VirusTotal", "VT_API_KEY");
      return json(await vtUrl(args.url as string, key));
    },
  };