sc-elections-mcp 0.5.0

package/dist/tools/vrems.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { getElectionYears, getElections, searchCandidates, getCandidateDetailHtml } from '../api/vrems-client.js';
+import { parseCandidateDetail } from '../parsers/candidate-detail.js';
+export function registerVremsTools(server) {
+    server.tool('list_elections', 'List SC elections by type and year. Returns election IDs needed for search_candidates. Types: General (statewide primaries + general), Special, Local. Use keyword to filter by location or type (e.g. "Sumter", "Primary"). Default limit 50 results (0 for all) — Local elections can have 200+ entries statewide. Start here for race research.', {
+        election_type: z.enum(['General', 'Special', 'Local']).describe('Election type'),
+        year: z.number().optional().describe('Specific year. Omit to get available years for this type.'),
+        keyword: z.string().optional().describe('Filter election names containing this keyword (case-insensitive, e.g. "Sumter", "Greenville", "Primary")'),
+        limit: z.number().optional().describe('Max results to return (default 50, 0 for all). Local elections can have 200+ entries per year.'),
+    }, async ({ election_type, year, keyword, limit }) => {
+        try {
+            if (year) {
+                let elections = await getElections(election_type, year);
+                // Apply keyword filter
+                if (keyword) {
+                    const needle = keyword.toLowerCase();
+                    elections = elections.filter((e) => (e.electionName || '').toLowerCase().includes(needle) ||
+                        (e.displayName || '').toLowerCase().includes(needle));
+                }
+                // Apply limit
+                const effectiveLimit = limit === undefined ? 50 : limit;
+                const totalCount = elections.length;
+                const limited = effectiveLimit > 0 ? elections.slice(0, effectiveLimit) : elections;
+                const limitNote = effectiveLimit > 0 && totalCount > effectiveLimit
+                    ? `\nShowing ${effectiveLimit} of ${totalCount}. Use limit=0 for all.`
+                    : '';
+                return {
+                    content: [{
+                            type: 'text',
+                            text: limited.length === 0
+                                ? `No ${election_type} elections found for ${year}${keyword ? ` matching "${keyword}"` : ''}`
+                                : `${totalCount} election(s)${keyword ? ` matching "${keyword}"` : ''}:${limitNote}\n${JSON.stringify(limited, null, 2)}`,
+                        }],
+                };
+            }
+            else {
+                const years = await getElectionYears(election_type);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: years.length === 0
+                                ? `No years found for ${election_type} elections`
+                                : `Available years for ${election_type} elections:\n${JSON.stringify(years, null, 2)}`,
+                        }],
+                };
+            }
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool('search_candidates', 'Search for candidates in a specific SC election. Returns contact info, filing fee, address, status. Default limit 50 results (0 for all) — statewide elections can return 500+. Get election_id from list_elections. To bridge to campaign finance, use search_filers with candidate names — the two systems don\'t share IDs. Try last name only if no match.', {
+        election_id: z.string().describe('Election ID from list_elections results'),
+        office: z.string().optional().describe('Office filter code (-1 for all). Common: 380=State House, 379=State Senate, 469=County Council District'),
+        county: z.string().optional().describe('County code (e.g. "23" for Greenville). Omit for all counties.'),
+        party: z.string().optional().describe('Party filter: Republican, Democratic, Libertarian, Nonpartisan, or All'),
+        status: z.string().optional().describe('Status filter: All, Active, Elected, DefeatedInPrimary, Withdrew, etc.'),
+        first_name: z.string().optional().describe('Candidate first name search'),
+        last_name: z.string().optional().describe('Candidate last name search'),
+        limit: z.number().optional().describe('Max candidates to return (default 50, 0 for all). Statewide elections can return hundreds.'),
+    }, async ({ election_id, office, county, party, status, first_name, last_name, limit }) => {
+        try {
+            const result = await searchCandidates({
+                electionId: election_id,
+                office,
+                county,
+                party,
+                status,
+                firstName: first_name,
+                lastName: last_name,
+            });
+            const effectiveLimit = limit === undefined ? 50 : limit;
+            if (result.candidates.length > 0) {
+                const totalCount = result.candidates.length;
+                const limited = effectiveLimit > 0 ? result.candidates.slice(0, effectiveLimit) : result.candidates;
+                const limitNote = effectiveLimit > 0 && totalCount > effectiveLimit
+                    ? `\nShowing ${effectiveLimit} of ${totalCount}. Use limit=0 for all.`
+                    : '';
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${totalCount} candidate(s) found (rich data from CSV export):${limitNote}\n${JSON.stringify(limited, null, 2)}`,
+                        }],
+                };
+            }
+            if (result.fallback && result.fallback.length > 0) {
+                const totalCount = result.fallback.length;
+                const limited = effectiveLimit > 0 ? result.fallback.slice(0, effectiveLimit) : result.fallback;
+                const limitNote = effectiveLimit > 0 && totalCount > effectiveLimit
+                    ? `\nShowing ${effectiveLimit} of ${totalCount}. Use limit=0 for all.`
+                    : '';
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${totalCount} candidate(s) found (basic data from HTML — CSV export unavailable):${limitNote}\n${JSON.stringify(limited, null, 2)}`,
+                        }],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: 'No candidates found matching filters' }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool('get_candidate_details', 'Get filing details for a specific candidate: address, filing date, status, document links (filing form PDF, fee receipt). Use candidateId and electionId from search_candidates. candidateId is only available from HTML results, not CSV export.', {
+        candidate_id: z.string().describe('Candidate ID from search_candidates results'),
+        election_id: z.string().describe('Election ID from list_elections or search_candidates results'),
+    }, async ({ candidate_id, election_id }) => {
+        try {
+            const html = await getCandidateDetailHtml(candidate_id, election_id);
+            const detail = parseCandidateDetail(html);
+            if (!detail.name) {
+                return {
+                    content: [{ type: 'text', text: 'Could not parse candidate detail page. The page structure may have changed.' }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=vrems.js.map

package/dist/tools/vrems.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,430 @@
+/** Search result from filer name search */
+export interface EthicsFiler {
+    candidate: string;
+    address: string;
+    lastSubmission: string;
+    lastSeiReport: string;
+    lastCampaignDisclosureReport: string;
+    isAccountConsolidated: boolean;
+    universalUserId: number;
+    candidateFilerId: number;
+    seiFilerId: number;
+    officeId: number;
+    officeName: string;
+    accountType: number;
+    percentageAccuracy: number;
+}
+/** Result from office-based filer search (26-letter sweep) */
+export interface OfficeFilerResult {
+    filers: EthicsFiler[];
+    totalSearched: number;
+    totalFailed: number;
+}
+/** Filer profile with positions and offices */
+export interface FilerProfile {
+    name: string;
+    address: {
+        addressLine1: string;
+        addressLine2: string;
+        city: string;
+        zipCode: string;
+        county: string;
+        state: string;
+    };
+    phone: string;
+    accountType: number;
+    hasSei: boolean;
+    hasCandidate: boolean;
+    isCandidateSeiMismatch: boolean;
+    allPositions: FilerPosition[];
+    recentPositions: string[];
+    openOffices: FilerOffice[];
+    closedOffices: FilerOffice[];
+}
+export interface FilerPosition {
+    id: number;
+    reportId: number;
+    reportYear: string;
+    position: string;
+    entity: string;
+    start: string;
+    startYear: string;
+    end: string;
+    endYear: string;
+    categoryType: string;
+    positionType: string;
+}
+export interface FilerOffice {
+    filerId: number;
+    campaignId: number;
+    name: string;
+    isClosed: boolean;
+    start: string;
+    end: string;
+}
+/** Campaign report summary (open/closed offices with balances) */
+export interface CampaignSummary {
+    name: string | null;
+    address: string | null;
+    openReports: CampaignOfficeReport[];
+    closedReports: CampaignOfficeReport[];
+}
+export interface CampaignOfficeReport {
+    filerId: number;
+    officeId: number;
+    officeName: string;
+    initialReportFiledDate: string;
+    lastReportSubmitted: string;
+    latestActivity: string;
+    balance: number;
+    officeClosedDate: string | null;
+    contributions: number;
+}
+/** Metadata header prepended to contribution/expenditure responses for verification */
+export interface CampaignContext {
+    candidateName: string;
+    officeName: string;
+    campaignId: number;
+    candidateFilerId: number;
+    campaignStatus: 'open' | 'closed';
+}
+/** Aggregated contribution view — top donors, totals by type */
+export interface ContributionSummary {
+    context: CampaignContext;
+    totalCount: number;
+    totalAmount: number;
+    dateRange: {
+        earliest: string;
+        latest: string;
+    } | null;
+    byType: Record<string, {
+        count: number;
+        amount: number;
+    }>;
+    selfFundingTotal: number;
+    topDonors: {
+        name: string;
+        totalAmount: number;
+        count: number;
+    }[];
+}
+/** Aggregated expenditure view — top vendors, totals by type */
+export interface ExpenditureSummary {
+    context: CampaignContext;
+    totalCount: number;
+    totalAmount: number;
+    dateRange: {
+        earliest: string;
+        latest: string;
+    } | null;
+    byType: Record<string, {
+        count: number;
+        amount: number;
+    }>;
+    topVendors: {
+        name: string;
+        totalAmount: number;
+        count: number;
+    }[];
+}
+/** Office name with extracted district/body for normalization */
+export interface NormalizedOffice {
+    raw: string;
+    normalized: string;
+    district?: string;
+    body?: string;
+}
+/** Grouped filer result — one entry per person, with all their office filings */
+export interface GroupedFiler {
+    candidate: string;
+    address: string;
+    universalUserId: number;
+    candidateFilerId: number;
+    seiFilerId: number;
+    lastSubmission: string;
+    offices: {
+        officeName: string;
+        officeId: number;
+        lastSubmission: string;
+        campaignStatus?: 'open' | 'closed';
+        balance?: number;
+        campaignId?: number;
+    }[];
+    primaryOfficeName?: string;
+    campaignStatus?: 'open' | 'closed';
+    balance?: number;
+    campaignId?: number;
+    normalizedOffice?: NormalizedOffice;
+}
+/** Individual campaign report entry */
+export interface CampaignReport {
+    reportId: number;
+    report: string;
+    reportType: string;
+    electionDate: string;
+    filingPeriod: string;
+    contributions: number;
+    expenses: number;
+    balance: number;
+    dateSubmitted: string;
+    lastAmendment: string | null;
+    year: number;
+}
+/** Detailed breakdown of a single campaign report */
+export interface CampaignReportDetails {
+    reportType: string;
+    filingPeriod: string;
+    electionDate: string;
+    electionType: string;
+    filerName: string;
+    isAmendment: boolean;
+    overview: {
+        reportSequenceNumber: number;
+        submittedDate: string;
+        filingFeeAmount: number;
+        filingFeePaymentMethod: string;
+        income: ReportLineItem[];
+        expenditures: ReportLineItem[];
+        totals: ReportLineItem[];
+    };
+    contributions: unknown[];
+    expenditures: unknown[];
+    loans: unknown[];
+}
+export interface ReportLineItem {
+    type: string;
+    filingPeriod: number;
+    electionCycleTotal: number;
+}
+/** Individual contribution record */
+export interface CampaignContribution {
+    id: number;
+    date: string;
+    report: string;
+    paidBy: string;
+    credit: number;
+    type: string;
+    electionCycle: string;
+    description: string;
+    isRunoff: boolean;
+    isDebtSetOff: boolean;
+    filingDate: string;
+}
+/** Individual expenditure record */
+export interface CampaignExpenditure {
+    id: number;
+    date: string;
+    report: string;
+    paidTo: string;
+    debit: number;
+    type: string;
+    electionCycle: string;
+    description: string;
+    isRunoff: boolean;
+    isDebtSetOff: boolean;
+    filingDate: string;
+}
+/** Cross-candidate expenditure search result */
+export interface CrossSearchExpenditure {
+    candidateFilerId: number;
+    credentialId: number;
+    campaignId: number;
+    office: string;
+    candidateName: string;
+    expDate: string;
+    expId: number;
+    vendorName: string;
+    amount: number;
+    address: string;
+    expDesc: string;
+}
+/** Cross-candidate contribution search result */
+export interface CrossSearchContribution {
+    contributionId: number;
+    officeRunId: number;
+    candidateId: number;
+    date: string;
+    amount: number;
+    candidateName: string;
+    officeName: string;
+    electionDate: string;
+    contributorName: string;
+    contributorOccupation: string;
+    group: string;
+    contributorAddress: string;
+    description: string | null;
+}
+export interface SeiReport {
+    seiFilerId: number;
+    seiReportId: number;
+    year: number;
+    reportType: string;
+    dateSubmitted: string;
+    status: string;
+}
+export interface SeiReportBody {
+    seiFilerId: number;
+    seiReportId: number;
+    getUnfiled: boolean;
+}
+export interface SeiPosition {
+    id: number;
+    reportId: number;
+    reportYear: string;
+    position: string;
+    entity: string;
+    start: string;
+    startYear: string;
+    end: string;
+    endYear: string;
+    categoryType: string;
+    positionType: string;
+}
+export interface SeiBusinessInterest {
+    seiFilerId: number;
+    seiReportId: number;
+    businessInterestsId: number;
+    businessName: string;
+    relationship: string;
+    isDeleted: boolean;
+}
+export interface SeiIncomeSource {
+    seiFilerId: number;
+    seiReportId: number;
+    incomeAndBenefitsId: number;
+    source: string;
+    type: string;
+    amount: number;
+    isDeleted: boolean;
+    incomeType: string;
+}
+export interface SeiGift {
+    seiFilerId: number;
+    seiReportId: number;
+    source: string;
+    description: string;
+    value: number;
+    isDeleted: boolean;
+}
+export interface SeiTravel {
+    seiFilerId: number;
+    seiReportId: number;
+    destination: string;
+    purpose: string;
+    paidBy: string;
+    dates: string;
+    isDeleted: boolean;
+}
+export interface SeiCreditor {
+    seiFilerId: number;
+    seiReportId: number;
+    creditorName: string;
+    amount: number;
+    isDeleted: boolean;
+}
+export interface SeiLobbyist {
+    seiFilerId: number;
+    seiReportId: number;
+    lobbyistName: string;
+    isDeleted: boolean;
+}
+export interface SeiDetails {
+    seiFilerId: number;
+    seiReportId: number;
+    reportYear: number;
+    dateSubmitted: string;
+    positions: SeiPosition[];
+    businessInterests: SeiBusinessInterest[];
+    privateIncome: SeiIncomeSource[];
+    governmentIncome: SeiIncomeSource[];
+    familyPrivateIncome: SeiIncomeSource[];
+    familyGovernmentIncome: SeiIncomeSource[];
+    gifts: SeiGift[];
+    travel: SeiTravel[];
+    governmentContracts: unknown[];
+    creditors: SeiCreditor[];
+    lobbyistFamily: SeiLobbyist[];
+    lobbyistPurchases: SeiLobbyist[];
+    regulatedBusinessAssociations: unknown[];
+    propertyTransactions: unknown[];
+    propertyImprovements: unknown[];
+    propertyConflicts: unknown[];
+    additionalInformation: unknown[];
+}
+export interface VremsElectionYear {
+    electionYear: number;
+}
+export interface VremsElection {
+    electionId: string;
+    electionName: string;
+    displayName: string;
+    electionDate: string;
+    filingPeriodBeginDate: string;
+}
+/** Rich candidate record from CSV export (25 fields) */
+export interface VremsCandidate {
+    ballotSortOrder: string;
+    filingLevel: string;
+    electionName: string;
+    office: string;
+    district: string;
+    counties: string;
+    ballotFirstMiddle: string;
+    ballotLastSuffix: string;
+    runningMate: string;
+    firstName: string;
+    middleName: string;
+    lastName: string;
+    suffix: string;
+    party: string;
+    filingLocation: string;
+    dateFiled: string;
+    timeFiled: string;
+    filingFee: string;
+    status: string;
+    statusDate: string;
+    address: string;
+    phone: string;
+    email: string;
+    runningMateOffice: string;
+}
+/** Lighter candidate record from HTML table parsing (fallback) */
+export interface VremsSearchCandidate {
+    candidateId: string;
+    electionId: string;
+    office: string;
+    counties: string;
+    name: string;
+    runningMate: string;
+    party: string;
+    filingLocation: string;
+    status: string;
+}
+/** Candidate detail from HTML detail page */
+export interface VremsCandidateDetail {
+    name: string;
+    election: string;
+    office: string;
+    nameOnBallot: string;
+    party: string;
+    address: string;
+    status: string;
+    dateFiled: string;
+    locationFiled: string;
+    documents: VremsDocument[];
+}
+export interface VremsDocument {
+    name: string;
+    type: string;
+    url: string;
+}
+export interface CandidateSearchParams {
+    electionId: string;
+    office?: string;
+    county?: string;
+    status?: string;
+    firstName?: string;
+    lastName?: string;
+    party?: string;
+    filingLocation?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// ============================================================
+// Ethics Commission types (ethicsfiling.sc.gov)
+// ============================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,gDAAgD;AAChD,+DAA+D"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "sc-elections-mcp",
+  "version": "0.5.0",
+  "description": "MCP server for South Carolina elections: campaign finance, contributions, expenditures, SEI disclosures, and candidate filings",
+  "type": "module",
+  "bin": {
+    "sc-elections-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "south-carolina",
+    "elections",
+    "campaign-finance",
+    "ethics"
+  ],
+  "author": "Alex Reynolds",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asreynolds1000/sc-elections-mcp.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "node-html-parser": "^7.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.19.4",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}