FEC MCP 서버

연방선거관리위원회(FEC) 선거 자금 조사 및 투명성을 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 공식 FEC 데이터를 사용하여 후보자 검색, 재무 보고서 검색, 기부금 및 지출 분석을 위한 도구를 제공합니다.

기능

• search_candidates: 이름, 선거 연도, 공직, 주 또는 정당별로 연방 후보자 검색

• get_committee_finances: 수입, 지출, 보유 현금 및 소진율을 포함한 재무 요약 조회

• get_receipts: 기부자 세부 정보가 포함된 항목별 기부금(Schedule A) 조회

• get_disbursements: 수령인 및 목적 세부 정보가 포함된 항목별 지출(Schedule B) 조회

• Flagged-first notable analysis: 참조 목록 및 휴리스틱 플래그 사유가 포함된 기부금/지출에 대한 선택적 주요 블록

• get_independent_expenditures: 후보자 찬성 또는 반대를 위한 슈퍼 PAC 지출(Schedule E) 추적

• get_committee_flags: RFAI(추가 정보 요청), 수정안 및 관련 규정 준수 위험 신호 확인

• search_donors: 모든 위원회에 걸쳐 이름, 고용주 또는 직업별로 개인 기부자 검색

• search_spending: 모든 위원회에 걸쳐 설명 또는 수령인별로 선거 캠페인 지출 검색

모든 데이터는 공식 OpenFEC API에서 직접 가져옵니다.

설치

사전 요구 사항

• Node.js 20 이상

• FEC API 키 (api.open.fec.gov에서 무료 발급)

npm에서 설치

npm install -g fec-mcp-server

소스에서 설치

git clone <repository-url>
cd fecmcp
npm install
npm run build

구성

FEC API 키를 환경 변수로 설정하세요:

export FEC_API_KEY=your-api-key-here

또는 프로젝트 루트에 .env 파일을 생성하세요:

FEC_API_KEY=your-api-key-here

Claude Desktop과 함께 사용

Claude Desktop 구성 파일에 서버를 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fec": {
      "command": "npx",
      "args": ["fec-mcp-server"],
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

또는 전역으로 설치된 경우:

{
  "mcpServers": {
    "fec": {
      "command": "fec-mcp-server",
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

도구

search_candidates

이름으로 FEC 후보자 기록을 검색합니다.

매개변수:

• q (필수): 검색할 후보자 이름

• election_year (선택): 선거 연도별 필터링 (예: 2024)

• office (선택): 공직별 필터링 - H (하원), S (상원), P (대통령)

• state (선택): 주별 필터링 (2글자 코드)

• party (선택): 정당 코드별 필터링 (예: "DEM", "REP")

예시:

Search for candidates named "Smith" running for Senate in 2024

get_committee_finances

캠페인 위원회의 재무 요약을 조회합니다.

매개변수:

• committee_id (필수): FEC 위원회 ID (예: "C00401224")

• cycle (선택): 2년 선거 주기 (예: 2024)

반환값:

• 총 수입 및 지출

• 보유 현금

• 부채

• 소진율 (지출/수입 비율)

• 기부금 분류 (개인, PAC, 정당)

• 소액 기부자 비율

예시:

Get the financial summary for committee C00401224

get_receipts

위원회가 받은 항목별 기부금(Schedule A)을 조회합니다.

매개변수:

• committee_id (필수): FEC 위원회 ID

• min_amount (선택): 최소 기부 금액 (기본값: $1,000)

• two_year_transaction_period (선택): 선거 주기 (예: 2024)

• cycle (선택): two_year_transaction_period의 별칭; 재무 주기 사용과 기부금을 자동으로 정렬

• contributor_type (선택): "individual" 또는 "committee"

• include_notable (선택): 플래그 우선 주요 블록 포함 여부 (기본값: true)

• fuzzy_threshold (선택): 참조 목록 플래그에 대한 퍼지 매칭 임계값 (기본값: 90, 범위: 80-99)

• limit (선택): 결과 수 (기본값: 20, 최대: 100)

• sort_by (선택): "amount" 또는 "date" (기본값: "amount")

예시:

Show the top 10 contributions over $5,000 to committee C00401224

get_disbursements

위원회가 지출한 항목별 지출(Schedule B)을 조회합니다.

매개변수:

• committee_id (필수): FEC 위원회 ID

• min_amount (선택): 최소 지출 금액 (기본값: $1,000)

• two_year_transaction_period (선택): 선거 주기

• cycle (선택): two_year_transaction_period의 별칭; 재무 주기 사용과 지출을 자동으로 정렬

• purpose (선택): 목적 키워드별 필터링 (예: "MEDIA", "CONSULTING")

• include_notable (선택): 플래그 우선 주요 블록 포함 여부 (기본값: true)

• fuzzy_threshold (선택): 참조 목록 플래그에 대한 퍼지 매칭 임계값 (기본값: 90, 범위: 80-99)

• limit (선택): 결과 수 (기본값: 20, 최대: 100)

• sort_by (선택): "amount" 또는 "date" (기본값: "amount")

예시:

Show media-related spending over $10,000 by committee C00401224

get_independent_expenditures

독립적 지출(Schedule E)을 조회합니다 - PAC 및 슈퍼 PAC이 후보자를 지원하거나 반대하기 위해 지출한 금액.

매개변수:

• candidate_id (선택): 후보자를 대상으로 한 지출을 확인하기 위한 FEC 후보자 ID

• committee_id (선택): 위원회의 독립적 지출을 확인하기 위한 FEC 위원회 ID

• support_oppose (선택): "support" 또는 "oppose"별 필터링

• min_amount (선택): 최소 지출 금액

• cycle (선택): 2년 선거 주기

• limit (선택): 결과 수 (기본값: 20)

참고: candidate_id 또는 committee_id 중 하나는 필수입니다.

예시:

Show independent expenditures opposing candidate P00009423

get_committee_flags

RFAI 및 수정안을 포함하여 캠페인 위원회의 규정 준수 위험 신호를 확인합니다.

매개변수:

• committee_id (필수): FEC 위원회 ID

• cycle (선택): 2년 선거 주기

반환값:

• RFAI(추가 정보 요청) 수 및 세부 정보

• 수정안 수 및 세부 정보

• 최근 규정 준수 문제

예시:

Check committee C00401224 for any compliance flags

search_donors

이름, 고용주 또는 직업별로 모든 FEC 신고서에 걸쳐 개인 기부자를 검색합니다.

매개변수:

• contributor_name (선택): 검색할 기부자 이름

• contributor_employer (선택): 고용주 이름 (예: "Goldman Sachs")

• contributor_occupation (선택): 직업 (예: "Lobbyist")

• contributor_state (선택): 2글자 주 코드

• min_amount (선택): 최소 기부 금액 (기본값: $200)

• cycle (선택): 2년 선거 주기

• limit (선택): 결과 수 (기본값: 20)

참고: contributor_name, contributor_employer 또는 contributor_occupation 중 하나 이상이 필수입니다.

예시:

Find contributions from employees of "Meta" in California

search_spending

설명 또는 수령인별로 모든 위원회에 걸쳐 캠페인 지출(Schedule B)을 검색합니다.

매개변수:

• description (선택): 지출 설명의 키워드 (예: "travel", "consulting")

• recipient_name (선택): 수령인/업체 이름

• recipient_state (선택): 2글자 주 코드

• min_amount (선택): 최소 금액 (기본값: $500)

• cycle (선택): 2년 선거 주기

• limit (선택): 결과 수 (기본값: 20)

참고: description 또는 recipient_name 중 하나 이상이 필수입니다.

예시:

Find spending on "golf" or "resort" across all committees

개발

설정

npm install

테스트 실행

npm test          # Watch mode
npm run test:run  # Single run
npm run test:coverage  # With coverage

빌드

npm run build

타입 검사

npm run typecheck

실시간 수락 검사

npm run acceptance:fec-day
npm run acceptance:notable

API 속도 제한

FEC API는 API 키를 사용하여 시간당 1,000건의 요청을 허용합니다. 더 높은 제한(시간당 최대 7,200건)이 필요한 경우 FEC에 문의하십시오.

타임아웃 및 API 지연 시간

기본 요청 타임아웃은 30초입니다. 검색 도구(search_candidates, search_donors, search_spending)는 FEC API 엔드포인트가 광범위한 데이터베이스 스캔을 수행하여 본질적으로 느리기 때문에 60초 타임아웃을 사용합니다.

기본 타임아웃을 전역적으로 재정의하려면 FEC_API_TIMEOUT_MS 환경 변수를 설정하세요:

export FEC_API_TIMEOUT_MS=45000  # 45 seconds

Docker

컨테이너 이미지를 로컬에서 빌드하세요:

docker build -t fec-mcp-server .

런타임에 제공된 API 키로 실행하세요:

docker run --rm -i \
  -e FEC_API_KEY=your-api-key-here \
  fec-mcp-server

릴리스

Glama 검사는 GitHub 릴리스를 확인합니다. 다음 저장소 변경 사항을 병합한 후 GitHub에서 또는 다음 명령어로 v1.0.0과 같은 태그를 생성하고 게시하세요:

git tag v1.0.0
git push origin v1.0.0

라이선스

MIT

면책 조항

이 도구는 선거 자금 투명성 연구를 위해 설계되었습니다. 중립적이고 당파적이지 않은 방식으로 공개 FEC 데이터에 대한 액세스를 제공합니다. 이 도구와 그 결과물은 후보자나 정당을 홍보하거나 반대하는 데 사용되어서는 안 됩니다.

리소스

• OpenFEC API 문서

• FEC.gov

• 모델 컨텍스트 프로토콜

• 참조 목록 출처: github/DGA-Research/FEC_Coder_Project_Streamlit (resources/reference-lists/ 아래에 번들된 스냅샷)