Screen Companies

Instructions

Implementation Reference

• src/tools/company.ts:138-181 (handler)

  The async handler function for the screen_companies tool. Accepts financial/IP/litigation filter parameters, builds query params, calls GET /api/v1/companies/screen, and returns the matching companies as formatted text.

    async (params) => {
      const queryParams: Record<string, string | number | undefined> = {
        sic_code: params.sic_code,
        industry: params.industry,
        min_revenue: params.min_revenue,
        max_revenue: params.max_revenue,
        min_assets: params.min_assets,
        max_assets: params.max_assets,
        max_shell_risk: params.max_shell_risk,
        min_filing_recency: params.min_filing_recency,
        has_patents: params.has_patents != null ? String(params.has_patents) : undefined,
        has_trademarks: params.has_trademarks != null ? String(params.has_trademarks) : undefined,
        has_litigation: params.has_litigation != null ? String(params.has_litigation) : undefined,
        min_short_interest: params.min_short_interest,
        sort_by: params.sort_by,
        limit: params.limit ?? 25,
      };
  
      const res = await apiGet<{ dataset: string; count: number; data: Record<string, unknown>[] }>(
        "/api/v1/companies/screen",
        queryParams,
      );
  
      if (!res.ok) {
        return {
          content: [
            {
              type: "text" as const,
              text: `API error (${res.status}): ${JSON.stringify(res.data)}`,
            },
          ],
          isError: true,
        };
      }
  
      const { count, data } = res.data;
      const summary = `Found ${count} company/companies matching filters.`;
      const json = JSON.stringify(data, null, 2);
  
      return {
        content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
      };
    },
  );

• src/tools/company.ts:70-136 (schema)

  Input schema for screen_companies tool: defines all optional filter parameters (sic_code, industry, revenue range, asset range, shell_risk, filing_recency, has_patents, has_trademarks, has_litigation, short_interest, sort_by, limit) using Zod validation.

  inputSchema: {
    sic_code: z
      .string()
      .optional()
      .describe("SIC industry code (e.g. '7372' for software)"),
    industry: z
      .string()
      .optional()
      .describe("Industry keyword search (partial match)"),
    min_revenue: z
      .number()
      .optional()
      .describe("Minimum revenue in USD"),
    max_revenue: z
      .number()
      .optional()
      .describe("Maximum revenue in USD"),
    min_assets: z
      .number()
      .optional()
      .describe("Minimum total assets in USD"),
    max_assets: z
      .number()
      .optional()
      .describe("Maximum total assets in USD"),
    max_shell_risk: z
      .number()
      .int()
      .min(0)
      .max(100)
      .optional()
      .describe("Maximum shell risk score (0-100)"),
    min_filing_recency: z
      .number()
      .int()
      .min(0)
      .max(100)
      .optional()
      .describe("Minimum filing recency score (0-100)"),
    has_patents: z
      .boolean()
      .optional()
      .describe("Filter to companies with patent activity"),
    has_trademarks: z
      .boolean()
      .optional()
      .describe("Filter to companies with trademark registrations"),
    has_litigation: z
      .boolean()
      .optional()
      .describe("Filter to companies with court cases"),
    min_short_interest: z
      .number()
      .optional()
      .describe("Minimum short interest ratio"),
    sort_by: z
      .string()
      .optional()
      .describe("Sort field: revenue, assets, shell_risk, filing_recency, short_interest"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Maximum results (default 25, max 100)"),
  },

• src/tools/company.ts:61-181 (registration)

  Registration of the 'screen_companies' tool via server.registerTool(), with title 'Screen Companies' and description explaining its cross-dataset screening capabilities.

  server.registerTool(
    "screen_companies",
    {
      title: "Screen Companies",
      description:
        "Screen companies using financial, industry, IP, and litigation filters. " +
        "Combine SIC industry codes, revenue/asset brackets, shell risk scores, " +
        "patent/trademark/litigation flags, and short interest levels. " +
        "Cross-references SEC, OTC, Patents, Trademarks, and PACER datasets.",
      inputSchema: {
        sic_code: z
          .string()
          .optional()
          .describe("SIC industry code (e.g. '7372' for software)"),
        industry: z
          .string()
          .optional()
          .describe("Industry keyword search (partial match)"),
        min_revenue: z
          .number()
          .optional()
          .describe("Minimum revenue in USD"),
        max_revenue: z
          .number()
          .optional()
          .describe("Maximum revenue in USD"),
        min_assets: z
          .number()
          .optional()
          .describe("Minimum total assets in USD"),
        max_assets: z
          .number()
          .optional()
          .describe("Maximum total assets in USD"),
        max_shell_risk: z
          .number()
          .int()
          .min(0)
          .max(100)
          .optional()
          .describe("Maximum shell risk score (0-100)"),
        min_filing_recency: z
          .number()
          .int()
          .min(0)
          .max(100)
          .optional()
          .describe("Minimum filing recency score (0-100)"),
        has_patents: z
          .boolean()
          .optional()
          .describe("Filter to companies with patent activity"),
        has_trademarks: z
          .boolean()
          .optional()
          .describe("Filter to companies with trademark registrations"),
        has_litigation: z
          .boolean()
          .optional()
          .describe("Filter to companies with court cases"),
        min_short_interest: z
          .number()
          .optional()
          .describe("Minimum short interest ratio"),
        sort_by: z
          .string()
          .optional()
          .describe("Sort field: revenue, assets, shell_risk, filing_recency, short_interest"),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .optional()
          .describe("Maximum results (default 25, max 100)"),
      },
    },
    async (params) => {
      const queryParams: Record<string, string | number | undefined> = {
        sic_code: params.sic_code,
        industry: params.industry,
        min_revenue: params.min_revenue,
        max_revenue: params.max_revenue,
        min_assets: params.min_assets,
        max_assets: params.max_assets,
        max_shell_risk: params.max_shell_risk,
        min_filing_recency: params.min_filing_recency,
        has_patents: params.has_patents != null ? String(params.has_patents) : undefined,
        has_trademarks: params.has_trademarks != null ? String(params.has_trademarks) : undefined,
        has_litigation: params.has_litigation != null ? String(params.has_litigation) : undefined,
        min_short_interest: params.min_short_interest,
        sort_by: params.sort_by,
        limit: params.limit ?? 25,
      };
  
      const res = await apiGet<{ dataset: string; count: number; data: Record<string, unknown>[] }>(
        "/api/v1/companies/screen",
        queryParams,
      );
  
      if (!res.ok) {
        return {
          content: [
            {
              type: "text" as const,
              text: `API error (${res.status}): ${JSON.stringify(res.data)}`,
            },
          ],
          isError: true,
        };
      }
  
      const { count, data } = res.data;
      const summary = `Found ${count} company/companies matching filters.`;
      const json = JSON.stringify(data, null, 2);
  
      return {
        content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
      };
    },
  );

• src/index.ts:46-46 (registration)

  Call to registerCompanyTools(server) which registers screen_companies along with company_profile and trader_signals.

  registerCompanyTools(server);

• src/client.ts:44-76 (helper)

  The apiGet helper function used by the screen_companies handler to make the HTTP GET request to the Verilex API.

  export async function apiGet<T = unknown>(
    path: string,
    params?: Record<string, string | number | undefined>,
  ): Promise<ApiResponse<T>> {
    const url = buildUrl(path, params);
  
    const headers: Record<string, string> = {
      Accept: "application/json",
      "User-Agent": "verilex-mcp-server/0.1.0",
    };
  
    // Forward x402 payment token if present in env (for paid endpoints)
    const paymentToken = process.env.VERILEX_PAYMENT_TOKEN;
    if (paymentToken) {
      headers["X-Payment-Token"] = paymentToken;
    }
  
    const res = await fetch(url, { headers });
    const data = (await res.json()) as T;
  
    const stale = res.headers.get("X-Data-Stale");
    const lastUpdated = res.headers.get("X-Data-Last-Updated");
    const ageSeconds = res.headers.get("X-Data-Age-Seconds");
  
    return {
      ok: res.ok,
      status: res.status,
      data,
      stale: stale === "true",
      lastUpdated: lastUpdated ?? undefined,
      ageSeconds: ageSeconds ? Number(ageSeconds) : undefined,
    };
  }