@cyanheads/openfec-mcp-server 0.2.2

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

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Tool for searching FEC filings and reports. Covers all
+ * disclosure documents: financial reports (F3/F3P/F3X), statements of
+ * candidacy, organizational filings, and amendments.
+ * @module mcp-server/tools/definitions/search-filings.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
+import { fmt$, PaginationSchema, str } from './utils/format-helpers.js';
+export const searchFilings = tool('openfec_search_filings', {
+    description: 'Search FEC filings and reports by committee, candidate, form type, or date range. ' +
+        'Covers financial reports (F3/F3P/F3X), statements of candidacy (F2), ' +
+        'organizational filings (F1), 24-hour IE notices (F24), and amendments.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        committee_id: z.string().optional().describe('Filing committee ID.'),
+        candidate_id: z.string().optional().describe('Associated candidate ID.'),
+        filer_name: z.string().optional().describe('Full-text filer name search.'),
+        form_type: z
+            .string()
+            .optional()
+            .describe('FEC form type. Common: F3 (House/Senate quarterly), F3P (Presidential), F3X (PAC/party), F24 (24-hour IE notice), F1 (statement of organization), F2 (statement of candidacy), F5 (IE by persons).'),
+        report_type: z
+            .string()
+            .optional()
+            .describe('Report type code. Common: Q1/Q2/Q3 (quarterly), YE (year-end), M3-M12 (monthly), 12G/12P/30G (pre/post election).'),
+        report_year: z.number().optional().describe('Filing year.'),
+        cycle: z.number().optional().describe('Two-year election cycle (even year).'),
+        is_amended: z.boolean().optional().describe('Filter to original or amended filings only.'),
+        most_recent: z
+            .boolean()
+            .optional()
+            .describe('Only the most recent version (filters out superseded amendments). Default true.'),
+        min_receipt_date: z
+            .string()
+            .optional()
+            .describe('Earliest date FEC received the filing (YYYY-MM-DD).'),
+        max_receipt_date: z.string().optional().describe('Latest FEC receipt date (YYYY-MM-DD).'),
+        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({
+        filings: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Filing records with form_type, committee, report_type, financial totals, pdf_url, etc.'),
+        pagination: PaginationSchema.describe('Page-based pagination metadata.'),
+    }),
+    async handler(input, ctx) {
+        const fec = getOpenFecService();
+        const params = {
+            committee_id: input.committee_id,
+            candidate_id: input.candidate_id,
+            q_filer: input.filer_name,
+            form_type: input.form_type,
+            report_type: input.report_type,
+            report_year: input.report_year,
+            cycle: input.cycle,
+            is_amended: input.is_amended,
+            most_recent: input.most_recent ?? true,
+            min_receipt_date: input.min_receipt_date,
+            max_receipt_date: input.max_receipt_date,
+            page: input.page,
+            per_page: input.per_page,
+        };
+        ctx.log.info('Searching filings', {
+            committee_id: input.committee_id,
+            form_type: input.form_type,
+        });
+        const result = await fec.searchFilings(params, ctx);
+        return {
+            filings: result.results,
+            pagination: result.pagination,
+        };
+    },
+    format(result) {
+        if (result.filings.length === 0) {
+            return [
+                {
+                    type: 'text',
+                    text: 'No filings found. Try removing the form_type or report_type filter, broadening the date range, or verifying the committee_id.',
+                },
+            ];
+        }
+        const lines = result.filings.map((f) => {
+            const formType = str(f, 'form_type');
+            const committeeName = str(f, 'committee_name');
+            const committeeId = str(f, 'committee_id');
+            const reportType = str(f, 'report_type_full') || str(f, 'report_type');
+            const receiptDate = str(f, 'receipt_date');
+            const coverageStart = str(f, 'coverage_start_date');
+            const coverageEnd = str(f, 'coverage_end_date');
+            const candidateName = str(f, 'candidate_name');
+            const pdfUrl = str(f, 'pdf_url');
+            let line = `**${formType}** — ${committeeName} (${committeeId})`;
+            if (reportType)
+                line += `\n  Report: ${reportType}`;
+            if (f.report_year)
+                line += ` (${f.report_year})`;
+            if (receiptDate)
+                line += ` | Filed: ${receiptDate}`;
+            if (candidateName)
+                line += `\n  Candidate: ${candidateName}`;
+            // Financial totals
+            const hasFinancials = typeof f.total_receipts === 'number' || typeof f.total_disbursements === 'number';
+            if (hasFinancials) {
+                line += `\n  Receipts: ${fmt$(f.total_receipts)} | Disbursements: ${fmt$(f.total_disbursements)}`;
+                line += ` | Cash: ${fmt$(f.cash_on_hand_end_period)} | Debt: ${fmt$(f.debts_owed_by_committee)}`;
+            }
+            if (coverageStart && coverageEnd) {
+                line += `\n  Coverage: ${coverageStart} to ${coverageEnd}`;
+            }
+            if (f.is_amended === true)
+                line += ' | AMENDED';
+            if (pdfUrl)
+                line += `\n  PDF: ${pdfUrl}`;
+            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-filings.tool.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Legal document search tool — search FEC advisory opinions,
+ * enforcement cases (MURs), alternative dispute resolutions, administrative
+ * fines, and statutes.
+ * @module mcp-server/tools/definitions/search-legal.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const searchLegal: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        advisory_opinions: "advisory_opinions";
+        murs: "murs";
+        adrs: "adrs";
+        admin_fines: "admin_fines";
+        statutes: "statutes";
+    }>>;
+    ao_number: z.ZodOptional<z.ZodString>;
+    case_number: z.ZodOptional<z.ZodString>;
+    respondent: z.ZodOptional<z.ZodString>;
+    regulatory_citation: z.ZodOptional<z.ZodString>;
+    statutory_citation: z.ZodOptional<z.ZodString>;
+    min_penalty_amount: z.ZodOptional<z.ZodNumber>;
+    max_penalty_amount: z.ZodOptional<z.ZodNumber>;
+    min_date: z.ZodOptional<z.ZodString>;
+    max_date: z.ZodOptional<z.ZodString>;
+    from_hit: z.ZodDefault<z.ZodNumber>;
+    hits_returned: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total_count: z.ZodNumber;
+}, z.core.$strip>>;
+//# sourceMappingURL=search-legal.tool.d.ts.map

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

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

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

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Legal document search tool — search FEC advisory opinions,
+ * enforcement cases (MURs), alternative dispute resolutions, administrative
+ * fines, and statutes.
+ * @module mcp-server/tools/definitions/search-legal.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';
+/** Human-readable labels for document type discriminators. */
+const typeLabels = {
+    advisory_opinion: 'Advisory Opinion',
+    mur: 'Matter Under Review (MUR)',
+    adr: 'Alternative Dispute Resolution',
+    admin_fine: 'Administrative Fine',
+    statute: 'Statute',
+};
+export const searchLegal = tool('openfec_search_legal', {
+    description: 'Search FEC legal documents: advisory opinions, enforcement cases (MURs), ' +
+        'alternative dispute resolutions, and administrative fines.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        query: z.string().optional().describe('Full-text search across legal documents.'),
+        type: z
+            .enum(['advisory_opinions', 'murs', 'adrs', 'admin_fines', 'statutes'])
+            .optional()
+            .describe('Document type filter. Omit to search all types.'),
+        ao_number: z.string().optional().describe('Specific advisory opinion number (e.g. "2024-01").'),
+        case_number: z.string().optional().describe('Specific MUR or ADR case number.'),
+        respondent: z.string().optional().describe('Respondent name (enforcement cases).'),
+        regulatory_citation: z.string().optional().describe('CFR citation (e.g. "11 CFR 112.4").'),
+        statutory_citation: z.string().optional().describe('U.S.C. citation (e.g. "52 U.S.C. 30106").'),
+        min_penalty_amount: z
+            .number()
+            .optional()
+            .describe('Minimum penalty amount (enforcement cases).'),
+        max_penalty_amount: z.number().optional().describe('Maximum penalty amount.'),
+        min_date: z.string().optional().describe('Earliest document date (YYYY-MM-DD).'),
+        max_date: z.string().optional().describe('Latest document date (YYYY-MM-DD).'),
+        from_hit: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe('Offset for pagination (0-indexed). Default 0.'),
+        hits_returned: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(20)
+            .describe('Results per page. Default 20, max 200.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Legal documents with a document_type discriminator (advisory_opinion, mur, adr, admin_fine, statute).'),
+        total_count: z.number().describe('Total matching documents across all types.'),
+    }),
+    async handler(input, ctx) {
+        const hasFilter = input.query || input.type || input.ao_number || input.case_number;
+        if (!hasFilter) {
+            throw invalidParams('Provide at least a search query, document type, or specific identifier (ao_number, case_number).');
+        }
+        const fec = getOpenFecService();
+        const params = {
+            from_hit: input.from_hit,
+            hits_returned: input.hits_returned,
+        };
+        if (input.query)
+            params.q = input.query;
+        if (input.type)
+            params.type = input.type;
+        if (input.ao_number)
+            params.ao_no = input.ao_number;
+        if (input.case_number)
+            params.case_no = input.case_number;
+        if (input.respondent)
+            params.case_respondents = input.respondent;
+        if (input.regulatory_citation)
+            params.ao_regulatory_citation = input.regulatory_citation;
+        if (input.statutory_citation)
+            params.ao_statutory_citation = input.statutory_citation;
+        if (input.min_penalty_amount !== undefined)
+            params.min_penalty_amount = input.min_penalty_amount;
+        if (input.max_penalty_amount !== undefined)
+            params.max_penalty_amount = input.max_penalty_amount;
+        if (input.min_date)
+            params.min_date = input.min_date;
+        if (input.max_date)
+            params.max_date = input.max_date;
+        ctx.log.info('Searching legal documents', {
+            query: input.query,
+            type: input.type,
+            resultCount: input.hits_returned,
+        });
+        const data = await fec.searchLegal(params, ctx);
+        // Trim bulky fields to keep payloads manageable for LLM context windows.
+        // Full document lists and verbose highlights can easily exceed 100KB per result.
+        const trimmed = data.results.map((doc) => {
+            const d = { ...doc };
+            // Keep only the first 3 highlights and drop per-document highlight maps
+            if (Array.isArray(d.highlights) && d.highlights.length > 3) {
+                d.highlights = d.highlights.slice(0, 3);
+            }
+            delete d.document_highlights;
+            // Summarize documents as a count + categories instead of full arrays
+            if (Array.isArray(d.documents) && d.documents.length > 0) {
+                const docs = d.documents;
+                const categories = [...new Set(docs.map((dd) => dd.category).filter(Boolean))];
+                d.document_count = docs.length;
+                d.document_categories = categories;
+                delete d.documents;
+            }
+            // Trim verbose commission_votes to just the vote dates
+            if (Array.isArray(d.commission_votes) && d.commission_votes.length > 0) {
+                const votes = d.commission_votes;
+                d.commission_votes = votes.map((v) => ({
+                    vote_date: v.vote_date,
+                    action: typeof v.action === 'string' ? v.action.slice(0, 200) : v.action,
+                }));
+            }
+            return d;
+        });
+        return { results: trimmed, total_count: data.totalCount };
+    },
+    format: (result) => {
+        if (result.results.length === 0) {
+            return [
+                {
+                    type: 'text',
+                    text: 'No legal documents found. Try different search terms, remove the type filter to search all document types, or check the ao_number/case_number format.',
+                },
+            ];
+        }
+        /** Group results by document_type for readable output. */
+        const grouped = new Map();
+        for (const doc of result.results) {
+            const docType = String(doc.document_type ?? 'unknown');
+            let group = grouped.get(docType);
+            if (!group) {
+                group = [];
+                grouped.set(docType, group);
+            }
+            group.push(doc);
+        }
+        const sections = [];
+        for (const [docType, docs] of grouped) {
+            const label = typeLabels[docType] ?? docType;
+            const lines = docs.map((doc) => {
+                const id = doc.ao_no ?? doc.case_no ?? doc.no ?? '';
+                const name = doc.name ?? '';
+                const summary = doc.summary ??
+                    (Array.isArray(doc.highlights) && doc.highlights.length > 0
+                        ? doc.highlights.join(' ... ')
+                        : '');
+                const date = doc.issue_date ?? doc.open_date ?? doc.close_date ?? doc.date ?? '';
+                const penalty = doc.penalty_amount != null ? ` | Penalty: ${fmt$(doc.penalty_amount)}` : '';
+                const parts = [];
+                if (id)
+                    parts.push(`**${id}**`);
+                if (name)
+                    parts.push(String(name));
+                if (date)
+                    parts.push(`(${date})`);
+                if (penalty)
+                    parts.push(penalty);
+                if (summary)
+                    parts.push(`\n  ${String(summary).slice(0, 300)}`);
+                return parts.join(' ');
+            });
+            sections.push(`### ${label}\n${lines.join('\n\n')}`);
+        }
+        sections.push(`\n_${result.total_count} total matching document(s)_`);
+        return [{ type: 'text', text: sections.join('\n\n') }];
+    },
+});
+//# sourceMappingURL=search-legal.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/utils/format-helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared formatting utilities for tool definition format() functions.
+ * Centralizes USD formatting, safe record field access, and the pagination schema
+ * reused across multiple tools.
+ * @module src/mcp-server/tools/definitions/format-helpers
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/** Format a number as USD or return 'N/A' for non-numeric values. */
+export declare const fmt$: (n: unknown) => string;
+/** Safely read a string field from an untyped record. */
+export declare const str: (rec: Record<string, unknown>, key: string) => string;
+/** Reusable page-based pagination output schema. */
+export declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    pages: z.ZodNumber;
+    count: z.ZodNumber;
+    per_page: z.ZodNumber;
+}, z.core.$strip>;
+//# sourceMappingURL=format-helpers.d.ts.map

package/dist/mcp-server/tools/definitions/utils/format-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/utils/format-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,qEAAqE;AACrE,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,KAAG,MACwB,CAAC;AAE3D,yDAAyD;AACzD,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,MAAM,KAAG,MACN,CAAC;AAE3D,oDAAoD;AACpD,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC"}

package/dist/mcp-server/tools/definitions/utils/format-helpers.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared formatting utilities for tool definition format() functions.
+ * Centralizes USD formatting, safe record field access, and the pagination schema
+ * reused across multiple tools.
+ * @module src/mcp-server/tools/definitions/format-helpers
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/** Format a number as USD or return 'N/A' for non-numeric values. */
+export const fmt$ = (n) => typeof n === 'number' ? `$${n.toLocaleString()}` : 'N/A';
+/** Safely read a string field from an untyped record. */
+export const str = (rec, key) => typeof rec[key] === 'string' ? rec[key] : '';
+/** Reusable page-based pagination output schema. */
+export const PaginationSchema = z.object({
+    page: z.number().describe('Current page number (1-indexed).'),
+    pages: z.number().describe('Total number of pages.'),
+    count: z.number().describe('Total result count.'),
+    per_page: z.number().describe('Results per page.'),
+});
+//# sourceMappingURL=format-helpers.js.map

package/dist/mcp-server/tools/definitions/utils/format-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-helpers.js","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/utils/format-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,qEAAqE;AACrE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAU,EAAU,EAAE,CACzC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAE3D,yDAAyD;AACzD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,GAA4B,EAAE,GAAW,EAAU,EAAE,CACvE,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,GAAG,CAAC,GAAG,CAAY,CAAC,CAAC,CAAC,EAAE,CAAC;AAE3D,oDAAoD;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC7D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACpD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACjD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CACnD,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/utils/id-validators.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Shared FEC ID format validators for tool handlers.
+ * Validates candidate_id and committee_id formats before hitting the API,
+ * producing clear error messages instead of silent empty results.
+ * @module src/mcp-server/tools/definitions/id-validators
+ */
+/** Throw invalidParams if `candidateId` doesn't match the FEC candidate ID pattern. */
+export declare function validateCandidateId(candidateId: string): void;
+/** Throw invalidParams if `committeeId` doesn't match the FEC committee ID pattern. */
+export declare function validateCommitteeId(committeeId: string): void;
+//# sourceMappingURL=id-validators.d.ts.map

package/dist/mcp-server/tools/definitions/utils/id-validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-validators.d.ts","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/utils/id-validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAO7D;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAO7D"}

package/dist/mcp-server/tools/definitions/utils/id-validators.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Shared FEC ID format validators for tool handlers.
+ * Validates candidate_id and committee_id formats before hitting the API,
+ * producing clear error messages instead of silent empty results.
+ * @module src/mcp-server/tools/definitions/id-validators
+ */
+import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+const CANDIDATE_ID_RE = /^[HSP][0-9A-Z]+$/i;
+const COMMITTEE_ID_RE = /^C\d+$/i;
+/** Throw invalidParams if `candidateId` doesn't match the FEC candidate ID pattern. */
+export function validateCandidateId(candidateId) {
+    if (!CANDIDATE_ID_RE.test(candidateId)) {
+        throw invalidParams("Invalid candidate ID format. FEC candidate IDs start with H (House), S (Senate), or P (President) followed by digits (e.g., 'P00003392').", { candidate_id: candidateId });
+    }
+}
+/** Throw invalidParams if `committeeId` doesn't match the FEC committee ID pattern. */
+export function validateCommitteeId(committeeId) {
+    if (!COMMITTEE_ID_RE.test(committeeId)) {
+        throw invalidParams("Invalid committee ID format. FEC committee IDs start with 'C' followed by digits (e.g., 'C00358796').", { committee_id: committeeId });
+    }
+}
+//# sourceMappingURL=id-validators.js.map

package/dist/mcp-server/tools/definitions/utils/id-validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-validators.js","sourceRoot":"","sources":["../../../../../src/mcp-server/tools/definitions/utils/id-validators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAC5C,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC,uFAAuF;AACvF,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,MAAM,aAAa,CACjB,2IAA2I,EAC3I,EAAE,YAAY,EAAE,WAAW,EAAE,CAC9B,CAAC;IACJ,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,MAAM,aAAa,CACjB,uGAAuG,EACvG,EAAE,YAAY,EAAE,WAAW,EAAE,CAC9B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/services/openfec/openfec-service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview OpenFEC API service. Wraps all FEC REST API interactions
+ * with timeout, retry, and pagination handling. Single service used by
+ * all tools and resources.
+ * @module src/services/openfec/openfec-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { ElectionSummary, FecParams, LegalResult, PageResult, SeekResult } from './types.js';
+/** Encode `last_indexes` from SEEK pagination into an opaque cursor. */
+export declare function encodeCursor(lastIndexes: Record<string, string>): string;
+/** Decode an opaque cursor back to `last_indexes` query params. */
+export declare function decodeCursor(cursor: string): Record<string, string>;
+export declare class OpenFecService {
+    private readonly config;
+    constructor();
+    /** Build a full URL with query params, injecting the API key. */
+    private buildUrl;
+    /**
+     * Fetch JSON from a page-based endpoint with retry.
+     * Wraps the full pipeline (fetch + JSON parse) in the retry boundary.
+     */
+    private fetchPage;
+    /**
+     * Fetch JSON from a keyset (SEEK) endpoint with retry.
+     * Returns a `nextCursor` from `last_indexes` when more results exist.
+     */
+    private fetchSeek;
+    /** Fetch legal search results with retry. Normalizes type-keyed arrays. */
+    private fetchLegalSearch;
+    /** Validate that the API returned a recognizable envelope, not an HTML error page. */
+    private validateEnvelope;
+    searchCandidates(params: FecParams, ctx: Context): Promise<PageResult>;
+    getCandidate(candidateId: string, ctx: Context): Promise<PageResult>;
+    getCandidateTotals(params: FecParams, ctx: Context): Promise<PageResult>;
+    searchCommittees(params: FecParams, ctx: Context): Promise<PageResult>;
+    getCommittee(committeeId: string, ctx: Context): Promise<PageResult>;
+    searchContributions(params: FecParams, ctx: Context): Promise<SeekResult>;
+    getContributionAggregates(mode: string, params: FecParams, ctx: Context): Promise<PageResult>;
+    searchDisbursements(params: FecParams, ctx: Context): Promise<SeekResult>;
+    getDisbursementAggregates(mode: string, params: FecParams, ctx: Context): Promise<PageResult>;
+    searchExpenditures(params: FecParams, ctx: Context): Promise<SeekResult>;
+    getExpendituresByCandidate(params: FecParams, ctx: Context): Promise<PageResult>;
+    searchFilings(params: FecParams, ctx: Context): Promise<PageResult>;
+    searchElections(params: FecParams, ctx: Context): Promise<PageResult>;
+    /** Fetch election summary — flat response (no pagination wrapper). */
+    getElectionSummary(params: FecParams, ctx: Context): Promise<ElectionSummary>;
+    searchLegal(params: FecParams, ctx: Context): Promise<LegalResult>;
+    getCalendarDates(params: FecParams, ctx: Context): Promise<PageResult>;
+    getReportingDates(params: FecParams, ctx: Context): Promise<PageResult>;
+    getElectionDates(params: FecParams, ctx: Context): Promise<PageResult>;
+}
+export declare function initOpenFecService(): void;
+export declare function getOpenFecService(): OpenFecService;
+//# sourceMappingURL=openfec-service.d.ts.map

package/dist/services/openfec/openfec-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfec-service.d.ts","sourceRoot":"","sources":["../../../src/services/openfec/openfec-service.ts"],"names":[],"mappings":"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"}