osint-mcp-server

Instructions

Implementation Reference

• src/censys/index.ts:69-97 (handler)

  The handler function that executes the censys_hosts tool logic by calling the Censys API.

  export async function censysHosts(query: string, auth: CensysAuth, perPage = 25): Promise<CensysHostsResult> {
    const data = await censysFetch("POST", "/hosts/search", auth, {
      q: query,
      per_page: Math.min(perPage, 100),
    });
  
    const result = data.result ?? {};
    const hosts: CensysHost[] = (result.hits ?? []).map((h: any) => ({
      ip: h.ip,
      services: (h.services ?? []).map((s: any) => ({
        port: s.port,
        serviceName: s.service_name ?? s.extended_service_name ?? "",
        transportProtocol: s.transport_protocol ?? "TCP",
        certificate: s.certificate,
      })),
      location: h.location
        ? { country: h.location.country, city: h.location.city, province: h.location.province }
        : undefined,
      autonomousSystem: h.autonomous_system
        ? { asn: h.autonomous_system.asn, name: h.autonomous_system.name, bgpPrefix: h.autonomous_system.bgp_prefix }
        : undefined,
      lastUpdatedAt: h.last_updated_at,
      operatingSystem: h.operating_system
        ? { product: h.operating_system.product, version: h.operating_system.version }
        : undefined,
    }));
  
    return { total: result.total ?? 0, hosts, query };
  }

• src/censys/index.ts:23-27 (schema)

  Schema/Interface defining the structure of the Censys host search result.

  interface CensysHostsResult {
    total: number;
    hosts: CensysHost[];
    query: string;
  }

• src/protocol/tools.ts:276-287 (registration)

  Registration of the 'censys_hosts' tool definition in the protocol tools file.

  const censysHostsTool: ToolDef = {
    name: "censys_hosts",
    description: "Search Censys for hosts matching a query. Returns IPs, services, ports, location, ASN. Requires CENSYS_API_ID + CENSYS_API_SECRET.",
    schema: {
      query: z.string().describe("Censys search query"),
      per_page: z.number().optional().describe("Results per page (max 100, default: 25)"),
    },
    execute: async (args, ctx) => {
      const id = requireApiKey(ctx.config.censysApiId, "Censys", "CENSYS_API_ID");
      const secret = requireApiKey(ctx.config.censysApiSecret, "Censys", "CENSYS_API_SECRET");
      return json(await censysHosts(args.query as string, { id, secret }, args.per_page as number | undefined));
    },