list_organization_filings

Instructions

Implementation Reference

• src/tools/list-organization-filings.ts:27-49 (handler)

  The main handler function for list_organization_filings. Calls client.getOrganization(args.ein), then either returns raw filing arrays (verbose mode) or sorted, curated summaries via summarizeFiling().

  export async function handler(
    client: ProPublicaClient,
    args: z.infer<z.ZodObject<typeof inputSchema>>,
  ) {
    try {
      const result = await client.getOrganization(args.ein);
  
      if (args.verbose) {
        return jsonResult({
          filings_with_data: result.filings_with_data,
          filings_without_data: result.filings_without_data,
        });
      }
  
      const filings = [...result.filings_with_data, ...result.filings_without_data]
        .sort((a, b) => filingTaxPeriod(b) - filingTaxPeriod(a))
        .map((filing) => summarizeFiling(filing));
  
      return jsonResult(filings);
    } catch (error) {
      return errorResult(error);
    }
  }

• src/tools/list-organization-filings.ts:12-21 (schema)

  Input schema for list_organization_filings: requires 'ein' (string, min 1) and optional 'verbose' (boolean).

  export const inputSchema = {
    ein: z
      .string()
      .min(1)
      .describe("The nonprofit EIN, with or without punctuation."),
    verbose: z
      .boolean()
      .optional()
      .describe("Return the raw filings_with_data and filings_without_data arrays when true."),
  };

• src/index.ts:44-51 (registration)

  Registration of list_organization_filings tool in the MCP server using server.registerTool(), with name, description, inputSchema, and handler.

  server.registerTool(
    listOrganizationFilings.name,
    {
      description: listOrganizationFilings.description,
      inputSchema: listOrganizationFilings.inputSchema,
    },
    (args) => listOrganizationFilings.handler(client, args),
  );

• src/tools/list-organization-filings.ts:23-25 (helper)

  Helper function filingTaxPeriod that extracts the tax period from a filing object, used for sorting filings newest first.

  function filingTaxPeriod(filing: FilingWithData | FilingWithoutData): number {
    return filing.tax_prd ?? filing.tax_prd_yr ?? 0;
  }

• src/curation.ts:46-69 (helper)

  The summarizeFiling helper used by the handler to curate filing data into a FilingSummary with revenue, expenses, assets, CEO compensation, employees etc.

  export function summarizeFiling(
    filing: FilingWithData | FilingWithoutData,
  ): FilingSummary {
    const withData = filing as FilingWithData;
    const hasData =
      withData.totrevenue !== undefined ||
      withData.totfuncexpns !== undefined ||
      withData.totassetsend !== undefined ||
      withData.totnetassetend !== undefined ||
      withData.compnsatncurrofcr !== undefined ||
      withData.noemplyeesw3cnt !== undefined;
  
    return {
      tax_period: filingTaxPeriod(filing),
      total_revenue: hasData ? (withData.totrevenue ?? null) : null,
      total_expenses: hasData ? (withData.totfuncexpns ?? null) : null,
      total_assets: hasData ? (withData.totassetsend ?? null) : null,
      net_assets: hasData ? (withData.totnetassetend ?? null) : null,
      ceo_compensation: hasData ? (withData.compnsatncurrofcr ?? null) : null,
      employees: hasData ? (withData.noemplyeesw3cnt ?? null) : null,
      source: filingSource(filing),
      has_data: hasData,
    };
  }