Claude Code Plugin: fecfile

Claude Code Plugin: fecfile

This repo contains a Claude Code plugin for analyzing FEC (Federal Election Commission) campaign finance filings. It includes an Agent Skill and an MCP server for secure API access.

Key Details

• Plugin name: fecfile
• Skill name: fecfile
• MCP server: fec-api (provides search_committees and get_filings tools)
• Dependencies: fecfile, mcp, httpx, keyring - managed via inline script metadata (PEP 723), auto-installed by uv run
• Data sources:
  • Public: docquery.fec.gov
  • Authenticated: api.open.fec.gov (via MCP server)
• Python: Requires 3.9+

Project Structure

agent-fecfile/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest (version source of truth)
│   └── marketplace.json         # Marketplace catalog for plugin distribution
├── .mcp.json                    # MCP server configuration
├── mcp-server/
│   └── server.py                # MCP server (authenticated FEC API)
├── skills/fecfile/
│   ├── SKILL.md                 # Agent Skill instructions
│   ├── references/              # Form and schedule documentation
│   │   ├── FORMS.md             # Reference for FEC form types (F1, F2, F3, F99)
│   │   └── SCHEDULES.md         # Field mappings for Schedules A, B, C, D, E
│   └── scripts/
│       └── fetch_filing.py      # Fetches FEC filing data (public API)
├── README.md                    # Installation and usage for end users
├── CHANGELOG.md                 # Version history
└── release.sh                   # Automated release script

Development Commands

Public API (no key required):

• uv run skills/fecfile/scripts/fetch_filing.py <FILING_ID>: Fetch a full filing as JSON
• uv run skills/fecfile/scripts/fetch_filing.py <FILING_ID> --summary-only: Summary only
• uv run skills/fecfile/scripts/fetch_filing.py <FILING_ID> --schedule A: Limit to a single schedule
• uv run skills/fecfile/scripts/fetch_filing.py <FILING_ID> --stream: JSONL streaming

MCP Server:

• The MCP server is automatically started by Claude Code when loaded as a plugin
• For other runtimes, configure MCP to run: uv run mcp-server/server.py
• The server loads the FEC API key from keyring once at startup

Coding Style & Naming Conventions

• Python uses 4-space indentation and standard library argparse conventions
• MCP server uses the official mcp Python SDK with async/await
• Keep functions small and descriptive (e.g., build_options, stream_filing)
• Prefer straightforward, readable logic over clever abstractions
• No formatter is enforced; keep code PEP 8–friendly

Testing Guidelines

• There is no automated test suite in this repository
• Validate changes manually by running scripts with a known filing ID
• For MCP server changes, test with claude --plugin-dir . from the repo root
• For large filings, verify --summary-only or --stream behavior

Releases

Releases use semver tags (e.g., 2.0.0) plus a latest tag that always points to the most recent stable release.

Versioning Strategy

The version is tracked in three places that must stay in sync:

1. .claude-plugin/plugin.json - Primary source of truth
2. skills/fecfile/SKILL.md - Metadata frontmatter
3. CHANGELOG.md - Version history

Release Process

1. Update the version in .claude-plugin/plugin.json:

   {
     "version": "2.1.0"
   }
   

2. Update the version in skills/fecfile/SKILL.md frontmatter:

   metadata:
     author: Matt Hodges
     version: "2.1.0"
   

3. Update CHANGELOG.md:

   • Add a new section at the top (below the header) for the new version
   • Use the format ## [X.Y.Z] - YYYY-MM-DD
   • Document changes under ### Added, ### Changed, ### Fixed, or ### Removed
   • Add a comparison link at the bottom: [X.Y.Z]: https://github.com/hodgesmr/agent-fecfile/compare/PREV...X.Y.Z

4. Commit the version bump and changelog update

5. Run the release script:

   ./release.sh
   

The script extracts the version from plugin.json, creates the version tag, updates the latest tag, and pushes both.

Architecture Notes

MCP Server

The MCP server (mcp-server/server.py) provides secure API access:

• Loads FEC API key from system keyring once at startup
• Key held in memory, never exposed to the model
• Exposes search_committees and get_filings as MCP tools
• Uses stdio transport for communication with Claude Code
• Works with any MCP-compatible runtime (Claude Code, Codex, etc.)

Agent Skill

The skill (skills/fecfile/SKILL.md) provides:

• Instructions for analyzing FEC filings
• Documentation of MCP tools
• Field reference for forms and schedules
• Large filing handling strategies

Acknowledgments

• Built on the fecfile library by Evan Sonderegger
• Inspired by llm-fecfile by Derek Willis