Search SEC Filings

Instructions

Implementation Reference

• src/tools/sec.ts:83-112 (handler)

  The async handler function for search_sec_filings. It calls apiGet to /api/v1/sec/filings with optional parameters (cik, form_type, company_name, date_from, date_to, limit), returns results as formatted text, or an error message on failure.

  async ({ cik, form_type, company_name, date_from, date_to, limit }) => {
    const res = await apiGet<SecFilingsResponse>("/api/v1/sec/filings", {
      cik,
      form_type,
      company_name,
      date_from,
      date_to,
      limit: limit ?? 25,
    });
  
    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} SEC filing(s).`;
    const json = JSON.stringify(data, null, 2);
  
    return {
      content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
    };
  },

• src/tools/sec.ts:49-81 (schema)

  Input schema for search_sec_filings using Zod: optional cik (string), form_type (string), company_name (string), date_from (string YYYY-MM-DD), date_to (string YYYY-MM-DD), and limit (number 1-100).

  inputSchema: {
    cik: z
      .string()
      .optional()
      .describe(
        "Central Index Key — SEC's unique company identifier (e.g. 0001652044 for Alphabet)",
      ),
    form_type: z
      .string()
      .optional()
      .describe(
        "SEC form type (e.g. 10-K, 10-Q, 8-K, S-1, DEF 14A). Case-insensitive.",
      ),
    company_name: z
      .string()
      .optional()
      .describe("Company name to search for (partial match)"),
    date_from: z
      .string()
      .optional()
      .describe("Start date for filing date range (YYYY-MM-DD)"),
    date_to: z
      .string()
      .optional()
      .describe("End date for filing date range (YYYY-MM-DD)"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Maximum number of results (default 25, max 100)"),
  },

• src/tools/sec.ts:41-113 (registration)

  Registration of the 'search_sec_filings' tool via server.registerTool() with title, description, inputSchema, and the async handler callback.

  server.registerTool(
    "search_sec_filings",
    {
      title: "Search SEC Filings",
      description:
        "Search SEC EDGAR filings by CIK number, form type (10-K, 10-Q, 8-K, etc.), " +
        "company name, and date range. Returns filing metadata including accession number, " +
        "filing date, and document URLs. Source: SEC EDGAR, updated every 15 minutes.",
      inputSchema: {
        cik: z
          .string()
          .optional()
          .describe(
            "Central Index Key — SEC's unique company identifier (e.g. 0001652044 for Alphabet)",
          ),
        form_type: z
          .string()
          .optional()
          .describe(
            "SEC form type (e.g. 10-K, 10-Q, 8-K, S-1, DEF 14A). Case-insensitive.",
          ),
        company_name: z
          .string()
          .optional()
          .describe("Company name to search for (partial match)"),
        date_from: z
          .string()
          .optional()
          .describe("Start date for filing date range (YYYY-MM-DD)"),
        date_to: z
          .string()
          .optional()
          .describe("End date for filing date range (YYYY-MM-DD)"),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .optional()
          .describe("Maximum number of results (default 25, max 100)"),
      },
    },
    async ({ cik, form_type, company_name, date_from, date_to, limit }) => {
      const res = await apiGet<SecFilingsResponse>("/api/v1/sec/filings", {
        cik,
        form_type,
        company_name,
        date_from,
        date_to,
        limit: limit ?? 25,
      });
  
      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} SEC filing(s).`;
      const json = JSON.stringify(data, null, 2);
  
      return {
        content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
      };
    },
  );

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

  Top-level registration call: registerSecTools(server) in the main server setup, which registers all SEC tools including search_sec_filings.

  registerSecTools(server);

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

  The apiGet helper function used by the handler to make HTTP GET requests to the Verilex API. It builds the URL, sends the request, and returns parsed JSON with status metadata.

  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,
    };
  }