@cyanheads/openfec-mcp-server 0.2.2

package/dist/mcp-server/tools/definitions/lookup-calendar.tool.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Calendar lookup tool — FEC calendar events, filing deadlines,
+ * and election dates.
+ * @module mcp-server/tools/definitions/lookup-calendar.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
+export const lookupCalendar = tool('openfec_lookup_calendar', {
+    description: 'Look up FEC calendar events, filing deadlines, and election dates.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        mode: z
+            .enum(['events', 'filing_deadlines', 'election_dates'])
+            .default('events')
+            .describe('events = FEC calendar events. filing_deadlines = report due dates. election_dates = upcoming/past elections.'),
+        state: z
+            .string()
+            .optional()
+            .describe('Two-letter state code (e.g., AZ, CA). Primarily for election_dates mode.'),
+        office: z
+            .enum(['H', 'S', 'P'])
+            .optional()
+            .describe('Office sought (H=House, S=Senate, P=President). Election dates mode.'),
+        report_type: z
+            .string()
+            .optional()
+            .describe('Report type code (e.g. "Q1", "Q2"). Filing deadlines mode only.'),
+        report_year: z.number().int().optional().describe('Report year. Filing deadlines mode.'),
+        category: z
+            .string()
+            .optional()
+            .describe('Calendar category ID for events mode. Common values: "32" (reporting deadlines), "33" (election dates), "34" (quarterly filings). Events mode only.'),
+        election_year: z.number().int().optional().describe('Election year. Election dates mode.'),
+        description: z.string().optional().describe('Full-text event description search. Events mode.'),
+        min_date: z.string().optional().describe('Earliest date (YYYY-MM-DD).'),
+        max_date: z.string().optional().describe('Latest date (YYYY-MM-DD).'),
+        page: z.number().int().min(1).default(1).describe('Page number (1-indexed). Default 1.'),
+        per_page: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe('Results per page. Default 20, max 100.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Calendar records — events, filing deadlines, or election dates depending on mode.'),
+        pagination: z
+            .object({
+            page: z.number().describe('Current page number.'),
+            pages: z.number().describe('Total pages available.'),
+            count: z.number().describe('Total result count.'),
+            per_page: z.number().describe('Results per page.'),
+        })
+            .describe('Page-based pagination metadata.'),
+    }),
+    async handler(input, ctx) {
+        const fec = getOpenFecService();
+        const params = {
+            page: input.page,
+            per_page: input.per_page,
+        };
+        if (input.mode === 'filing_deadlines') {
+            // /reporting-dates/ uses min_due_date / max_due_date
+            if (input.min_date)
+                params.min_due_date = input.min_date;
+            if (input.max_date)
+                params.max_due_date = input.max_date;
+            if (input.report_type)
+                params.report_type = input.report_type;
+            if (input.report_year)
+                params.report_year = input.report_year;
+            ctx.log.info('Fetching filing deadlines', {
+                report_type: input.report_type,
+                report_year: input.report_year,
+            });
+            const data = await fec.getReportingDates(params, ctx);
+            return { results: data.results, pagination: data.pagination };
+        }
+        if (input.mode === 'election_dates') {
+            // /election-dates/ uses min_election_date / max_election_date
+            if (input.min_date)
+                params.min_election_date = input.min_date;
+            if (input.max_date)
+                params.max_election_date = input.max_date;
+            if (input.state)
+                params.election_state = input.state;
+            if (input.office)
+                params.office_sought = input.office;
+            if (input.election_year)
+                params.election_year = input.election_year;
+            ctx.log.info('Fetching election dates', {
+                state: input.state,
+                election_year: input.election_year,
+            });
+            const data = await fec.getElectionDates(params, ctx);
+            return { results: data.results, pagination: data.pagination };
+        }
+        /* Default: events mode — /calendar-dates/ uses min_start_date / max_start_date */
+        if (input.min_date)
+            params.min_start_date = input.min_date;
+        if (input.max_date)
+            params.max_start_date = input.max_date;
+        if (input.description)
+            params.description = input.description;
+        if (input.category)
+            params.calendar_category_id = input.category;
+        ctx.log.info('Fetching calendar events', { description: input.description });
+        const data = await fec.getCalendarDates(params, ctx);
+        return { results: data.results, pagination: data.pagination };
+    },
+    format: (result) => {
+        if (result.results.length === 0) {
+            return [
+                {
+                    type: 'text',
+                    text: 'No calendar entries found. Try widening the date range, removing filters, or checking a different mode (events, filing_deadlines, election_dates).',
+                },
+            ];
+        }
+        const lines = result.results.map((r) => {
+            /**
+             * Unified formatting across all three modes. Each mode returns different
+             * field names; we pull from whichever fields are present.
+             */
+            const summary = r.summary ?? r.report_type ?? r.election_type_full ?? '';
+            const description = r.description ?? '';
+            const date = r.start_date ?? r.due_date ?? r.election_date ?? r.event_date ?? '';
+            const endDate = r.end_date ?? '';
+            const state = r.election_state ?? r.state ?? '';
+            const office = r.office_sought ?? '';
+            const year = r.report_year ?? r.election_year ?? '';
+            const category = r.category ?? '';
+            const location = r.location ?? '';
+            const url = r.url ?? '';
+            const parts = [];
+            if (summary)
+                parts.push(`**${summary}**`);
+            if (description && description !== summary)
+                parts.push(String(description));
+            const meta = [];
+            if (date)
+                meta.push(`Date: ${date}${endDate && endDate !== date ? ` to ${endDate}` : ''}`);
+            if (state)
+                meta.push(`State: ${state}`);
+            if (office)
+                meta.push(`Office: ${office}`);
+            if (year)
+                meta.push(`Year: ${year}`);
+            if (category)
+                meta.push(`Category: ${category}`);
+            if (location)
+                meta.push(`Location: ${location}`);
+            if (meta.length > 0)
+                parts.push(meta.join(' | '));
+            if (url)
+                parts.push(`[Link](${url})`);
+            /** Coverage period for filing deadlines. */
+            const covStart = r.coverage_start_date;
+            const covEnd = r.coverage_end_date;
+            if (covStart && covEnd)
+                parts.push(`Coverage: ${covStart} to ${covEnd}`);
+            return parts.join('\n  ');
+        });
+        const { page, pages, count } = result.pagination;
+        lines.push(`\n_${count} result(s) — page ${page}/${pages}_`);
+        return [{ type: 'text', text: lines.join('\n\n') }];
+    },
+});
+//# sourceMappingURL=lookup-calendar.tool.js.map

package/dist/mcp-server/tools/definitions/lookup-calendar.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-calendar.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-calendar.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/lookup-elections.tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Election lookup tool — find federal election races and candidate
+ * financial summaries by office, cycle, state, and district.
+ * @module mcp-server/tools/definitions/lookup-elections.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const lookupElections: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        summary: "summary";
+        search: "search";
+    }>>;
+    office: z.ZodEnum<{
+        president: "president";
+        senate: "senate";
+        house: "house";
+    }>;
+    cycle: z.ZodNumber;
+    state: z.ZodOptional<z.ZodString>;
+    district: z.ZodOptional<z.ZodString>;
+    zip: z.ZodOptional<z.ZodString>;
+    election_full: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    pagination: z.ZodObject<{
+        page: z.ZodNumber;
+        pages: z.ZodNumber;
+        count: z.ZodNumber;
+        per_page: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+//# sourceMappingURL=lookup-elections.tool.d.ts.map

package/dist/mcp-server/tools/definitions/lookup-elections.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-elections.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-elections.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;kBA2I1B,CAAC"}

package/dist/mcp-server/tools/definitions/lookup-elections.tool.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Election lookup tool — find federal election races and candidate
+ * financial summaries by office, cycle, state, and district.
+ * @module mcp-server/tools/definitions/lookup-elections.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
+import { fmt$ } from './utils/format-helpers.js';
+export const lookupElections = tool('openfec_lookup_elections', {
+    description: 'Look up federal election races and candidate financial summaries. ' +
+        "Find who's running in a race with fundraising totals, or get an aggregate race summary.",
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        mode: z
+            .enum(['search', 'summary'])
+            .default('search')
+            .describe('search = candidates in a race with financial totals. summary = aggregate race financial summary.'),
+        office: z
+            .enum(['president', 'senate', 'house'])
+            .describe('Office sought: president, senate, or house.'),
+        cycle: z.number().int().describe('Election cycle year (even years only, e.g. 2024).'),
+        state: z
+            .string()
+            .optional()
+            .describe('Two-letter US state code (e.g., AZ, CA). Required for senate and house races.'),
+        district: z
+            .string()
+            .optional()
+            .describe('Two-digit district number (e.g. "07"). Required for house races.'),
+        zip: z
+            .string()
+            .optional()
+            .describe('ZIP code — finds races covering this ZIP. Search mode only.'),
+        election_full: z
+            .boolean()
+            .default(true)
+            .describe('Expand to full election period (4yr president, 6yr senate, 2yr house). Default true.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Election race records — candidates with financial data, or aggregate summary.'),
+        pagination: z
+            .object({
+            page: z.number().describe('Current page number.'),
+            pages: z.number().describe('Total pages available.'),
+            count: z.number().describe('Total result count.'),
+            per_page: z.number().describe('Results per page.'),
+        })
+            .describe('Page-based pagination metadata.'),
+    }),
+    async handler(input, ctx) {
+        if (input.cycle % 2 !== 0) {
+            throw invalidParams('Election cycles are even years (e.g., 2024, 2026).');
+        }
+        if ((input.office === 'senate' || input.office === 'house') && !input.state) {
+            throw invalidParams('Senate and House election lookups require a state.');
+        }
+        if (input.office === 'house' && !input.district) {
+            throw invalidParams('House election lookups require a district number.');
+        }
+        const fec = getOpenFecService();
+        const params = {
+            office: input.office,
+            cycle: input.cycle,
+            election_full: input.election_full,
+        };
+        if (input.state)
+            params.state = input.state;
+        if (input.district)
+            params.district = input.district;
+        if (input.zip)
+            params.zip = input.zip;
+        if (input.mode === 'summary') {
+            ctx.log.info('Fetching election summary', { office: input.office, cycle: input.cycle });
+            const summary = await fec.getElectionSummary(params, ctx);
+            return {
+                results: [summary],
+                pagination: { page: 1, pages: 1, count: 1, per_page: 1 },
+            };
+        }
+        ctx.log.info('Searching elections', { office: input.office, cycle: input.cycle });
+        const data = await fec.searchElections(params, ctx);
+        return { results: data.results, pagination: data.pagination };
+    },
+    format: (result) => {
+        if (result.results.length === 0) {
+            return [
+                {
+                    type: 'text',
+                    text: 'No election results found. Verify the cycle is an even year, the state code is correct for senate/house races, and the district exists for the given state.',
+                },
+            ];
+        }
+        // Summary mode returns a single flat object with aggregate totals
+        const first = result.results[0];
+        if (first &&
+            'receipts' in first &&
+            'disbursements' in first &&
+            'independent_expenditures' in first) {
+            const lines = [
+                '**Election Summary**',
+                `Candidates: ${first.count ?? 'N/A'}`,
+                `Total Raised: ${fmt$(first.receipts)}`,
+                `Total Spent: ${fmt$(first.disbursements)}`,
+                `Independent Expenditures: ${fmt$(first.independent_expenditures)}`,
+            ];
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        const lines = result.results.map((r) => {
+            const name = r.candidate_name ?? r.candidate_id ?? 'Unknown';
+            const party = r.party_full ?? r.party ?? '';
+            const status = r.incumbent_challenge_full ?? '';
+            const receipts = fmt$(r.total_receipts);
+            const disbursements = fmt$(r.total_disbursements);
+            const cash = fmt$(r.cash_on_hand_end_period);
+            const parts = [`**${name}**`];
+            if (party)
+                parts.push(`(${party})`);
+            if (status)
+                parts.push(`— ${status}`);
+            parts.push(`\n  Raised: ${receipts} | Spent: ${disbursements} | Cash on hand: ${cash}`);
+            const coverage = r.coverage_end_date;
+            if (coverage)
+                parts.push(`| Through: ${coverage}`);
+            return parts.join(' ');
+        });
+        const { page, pages, count } = result.pagination;
+        lines.push(`\n_${count} result(s) — page ${page}/${pages}_`);
+        return [{ type: 'text', text: lines.join('\n\n') }];
+    },
+});
+//# sourceMappingURL=lookup-elections.tool.js.map

package/dist/mcp-server/tools/definitions/lookup-elections.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-elections.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-elections.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search-candidates.tool.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Tool for searching and retrieving FEC candidate records.
+ * Supports full-text search, single-candidate lookup by ID, and optional
+ * financial totals merging from the /candidates/totals/ endpoint.
+ * @module mcp-server/tools/definitions/search-candidates.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const searchCandidates: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    candidate_id: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    district: z.ZodOptional<z.ZodString>;
+    office: z.ZodOptional<z.ZodEnum<{
+        H: "H";
+        S: "S";
+        P: "P";
+    }>>;
+    party: z.ZodOptional<z.ZodString>;
+    cycle: z.ZodOptional<z.ZodNumber>;
+    election_year: z.ZodOptional<z.ZodNumber>;
+    incumbent_challenge: z.ZodOptional<z.ZodEnum<{
+        I: "I";
+        C: "C";
+        O: "O";
+    }>>;
+    candidate_status: z.ZodOptional<z.ZodEnum<{
+        P: "P";
+        C: "C";
+        F: "F";
+        N: "N";
+    }>>;
+    has_raised_funds: z.ZodOptional<z.ZodBoolean>;
+    include_totals: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    candidates: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    totals: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    pagination: z.ZodObject<{
+        page: z.ZodNumber;
+        pages: z.ZodNumber;
+        count: z.ZodNumber;
+        per_page: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+//# sourceMappingURL=search-candidates.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-candidates.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-candidates.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-candidates.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAOjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsL3B,CAAC"}

package/dist/mcp-server/tools/definitions/search-candidates.tool.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Tool for searching and retrieving FEC candidate records.
+ * Supports full-text search, single-candidate lookup by ID, and optional
+ * financial totals merging from the /candidates/totals/ endpoint.
+ * @module mcp-server/tools/definitions/search-candidates.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
+import { fmt$, PaginationSchema, str } from './utils/format-helpers.js';
+import { validateCandidateId } from './utils/id-validators.js';
+export const searchCandidates = tool('openfec_search_candidates', {
+    description: 'Find federal candidates by name, state, office, party, or cycle. ' +
+        'Retrieve a specific candidate by FEC ID with financial totals. ' +
+        'Candidate IDs start with H (House), S (Senate), or P (President) followed by digits.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        query: z.string().optional().describe('Full-text candidate name search.'),
+        candidate_id: z
+            .string()
+            .optional()
+            .describe('FEC candidate ID (e.g., P00003392, H2CO07170). When provided, returns a single candidate with full detail.'),
+        state: z.string().optional().describe('Two-letter US state code (e.g., AZ, CA).'),
+        district: z.string().optional().describe('Two-digit district number for House candidates.'),
+        office: z
+            .enum(['H', 'S', 'P'])
+            .optional()
+            .describe('Filter by office: H=House, S=Senate, P=President.'),
+        party: z.string().optional().describe('Three-letter party code (e.g., DEM, REP, LIB).'),
+        cycle: z.number().optional().describe('Two-year election cycle (even year, e.g., 2024).'),
+        election_year: z.number().optional().describe('Specific election year the candidate ran in.'),
+        incumbent_challenge: z
+            .enum(['I', 'C', 'O'])
+            .optional()
+            .describe('Incumbent status: I=incumbent, C=challenger, O=open seat.'),
+        candidate_status: z
+            .enum(['C', 'F', 'N', 'P'])
+            .optional()
+            .describe('Candidate status: C=present, F=future, N=not yet, P=prior.'),
+        has_raised_funds: z
+            .boolean()
+            .optional()
+            .describe('Only candidates whose committee has received receipts.'),
+        include_totals: z
+            .boolean()
+            .optional()
+            .describe('Include financial totals (receipts, disbursements, cash on hand). Defaults to true when fetching by candidate_id. Adds a second API call.'),
+        page: z.number().optional().describe('Page number (1-indexed). Default 1.'),
+        per_page: z.number().optional().describe('Results per page. Default 20, max 100.'),
+    }),
+    output: z.object({
+        candidates: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Candidate records with candidate_id, name, party, state, office, cycles, etc.'),
+        totals: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true.'),
+        pagination: PaginationSchema.describe('Page-based pagination metadata.'),
+    }),
+    async handler(input, ctx) {
+        const fec = getOpenFecService();
+        if (input.candidate_id)
+            validateCandidateId(input.candidate_id);
+        const shouldIncludeTotals = input.include_totals ?? !!input.candidate_id;
+        let candidateResult;
+        if (input.candidate_id) {
+            // Single candidate lookup
+            ctx.log.info('Fetching candidate by ID', { candidate_id: input.candidate_id });
+            candidateResult = await fec.getCandidate(input.candidate_id, ctx);
+        }
+        else {
+            // Search with filters
+            const params = {
+                q: input.query,
+                state: input.state,
+                district: input.district,
+                office: input.office,
+                party: input.party,
+                cycle: input.cycle,
+                election_year: input.election_year,
+                incumbent_challenge: input.incumbent_challenge,
+                candidate_status: input.candidate_status,
+                has_raised_funds: input.has_raised_funds,
+                page: input.page,
+                per_page: input.per_page,
+            };
+            ctx.log.info('Searching candidates', { query: input.query, state: input.state });
+            candidateResult = await fec.searchCandidates(params, ctx);
+        }
+        const candidates = candidateResult.results;
+        if (input.candidate_id && candidates.length === 0) {
+            throw notFound(`Candidate ${input.candidate_id} not found.`, {
+                candidate_id: input.candidate_id,
+            });
+        }
+        // Fetch financial totals if requested
+        let totals;
+        if (shouldIncludeTotals && candidates.length > 0) {
+            const totalsParams = {
+                candidate_id: input.candidate_id,
+                cycle: input.cycle,
+                election_year: input.election_year,
+                page: input.page,
+                per_page: input.per_page,
+            };
+            // For search results, collect all candidate IDs for the totals call
+            if (!input.candidate_id) {
+                const ids = candidates.map((c) => str(c, 'candidate_id')).filter(Boolean);
+                if (ids.length > 0) {
+                    // The API accepts repeated candidate_id params (?candidate_id=X&candidate_id=Y)
+                    totalsParams.candidate_id = ids;
+                }
+            }
+            ctx.log.info('Fetching candidate totals', { candidate_id: totalsParams.candidate_id });
+            const totalsResult = await fec.getCandidateTotals(totalsParams, ctx);
+            totals = totalsResult.results;
+        }
+        return {
+            candidates,
+            totals,
+            pagination: candidateResult.pagination,
+        };
+    },
+    format(result) {
+        if (result.candidates.length === 0) {
+            return [
+                {
+                    type: 'text',
+                    text: 'No candidates found. Try broadening your search — use a partial name, remove filters like state or office, or check a different election cycle.',
+                },
+            ];
+        }
+        // Build a lookup of totals by candidate_id for merging
+        const totalsMap = new Map();
+        if (result.totals) {
+            for (const t of result.totals) {
+                const id = str(t, 'candidate_id');
+                if (id)
+                    totalsMap.set(id, t);
+            }
+        }
+        const lines = result.candidates.map((c) => {
+            const id = str(c, 'candidate_id');
+            const name = str(c, 'name');
+            const party = str(c, 'party_full') || str(c, 'party');
+            const state = str(c, 'state');
+            const office = str(c, 'office_full') || str(c, 'office');
+            const status = str(c, 'incumbent_challenge_full') || str(c, 'incumbent_challenge');
+            const district = typeof c.district_number === 'number'
+                ? `-${String(c.district_number).padStart(2, '0')}`
+                : '';
+            let line = `**${name}** (${id})\n  ${party} | ${office}${district ? ` ${district}` : ''} | ${state} | ${status}`;
+            const t = totalsMap.get(id);
+            if (t) {
+                line +=
+                    `\n  Receipts: ${fmt$(t.receipts)} | Disbursements: ${fmt$(t.disbursements)}` +
+                        `\n  Cash on Hand: ${fmt$(t.cash_on_hand_end_period)} | Debt: ${fmt$(t.debts_owed_by_committee)}`;
+                const coverageEnd = str(t, 'coverage_end_date');
+                if (coverageEnd)
+                    line += ` | Through: ${coverageEnd}`;
+            }
+            return line;
+        });
+        const { page, pages, count } = result.pagination;
+        lines.push(`\n---\nPage ${page} of ${pages} (${count} total)`);
+        return [{ type: 'text', text: lines.join('\n\n') }];
+    },
+});
+//# sourceMappingURL=search-candidates.tool.js.map

package/dist/mcp-server/tools/definitions/search-candidates.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-candidates.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-candidates.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search-committees.tool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Tool for searching and retrieving FEC committee records.
+ * Supports full-text search, single-committee lookup by ID, and filtering
+ * by candidate affiliation, type, designation, state, and party.
+ * @module mcp-server/tools/definitions/search-committees.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const searchCommittees: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    committee_id: z.ZodOptional<z.ZodString>;
+    candidate_id: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    party: z.ZodOptional<z.ZodString>;
+    committee_type: z.ZodOptional<z.ZodString>;
+    designation: z.ZodOptional<z.ZodString>;
+    cycle: z.ZodOptional<z.ZodNumber>;
+    treasurer_name: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    committees: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    pagination: z.ZodObject<{
+        page: z.ZodNumber;
+        pages: z.ZodNumber;
+        count: z.ZodNumber;
+        per_page: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+//# sourceMappingURL=search-committees.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-committees.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-committees.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-committees.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAOjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;kBA6H3B,CAAC"}