cd mcp-osint
npm install
npm run build

claude mcp add -s user -t stdio mcp-osint \
  -e LEGISCAN_API_KEY=your-key \
  -e COURTLISTENER_API_KEY=your-key \
  -e FRED_API_KEY=your-key \
  -e FIRECRAWL_API_KEY=your-key \
  -- node /path/to/mcp-osint/dist/index.js

{
  "mcpServers": {
    "mcp-osint": {
      "command": "node",
      "args": ["/path/to/mcp-osint/dist/index.js"],
      "env": {
        "LEGISCAN_API_KEY": "your-key",
        "COURTLISTENER_API_KEY": "your-key",
        "FRED_API_KEY": "your-key",
        "FIRECRAWL_API_KEY": "your-key",
        "POLITE_EMAIL": "you@example.com"
      }
    }
  }
}

"EPA air quality data California"       → Data.gov
"Michigan renewable energy bill 2024"   → LegiScan
"Brown v. Board of Education"           → CourtListener
"population by county Texas"            → Census
"machine learning medical diagnosis"    → OpenAlex/PubMed
"Apple 10-K filing 2024"                → SEC EDGAR
"GDP quarterly growth rate"             → FRED
"Russian sanctions oligarchs"           → OpenSanctions
"Ukraine conflict news"                 → GDELT
"microsoft.com subdomains"              → crt.sh

osint_get target="https://example.com/article"
osint_get target="https://example.com/paper.pdf" output_path="./downloads/paper.pdf"
osint_get target="pubmed:paper:12345:abstract" question="key findings"

npm install       # Install dependencies
npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm start         # Run server

# Test connector metadata and identifiers
npx tsx test/test-all-connectors.ts

# Test data retrieval (downloads files)
npx tsx test/test-data-retrieval.ts

# Test Firecrawl HTML+Markdown
npx tsx test/test-firecrawl.ts

# Run comprehensive MCP tool tests
npx tsx test/test-mcp-scenarios.ts

src/
├── index.ts              # MCP server entry point
├── types.ts              # Shared types
├── intent.ts             # Query parsing and routing
├── router.ts             # Connector selection
├── logger.ts             # Logging utility
├── cache.ts              # SQLite + file caching
├── retry.ts              # Retry with backoff
└── connectors/
    ├── base.ts           # Base connector class
    ├── data-gov.ts       # Data.gov/CKAN
    ├── legiscan.ts       # LegiScan
    ├── courtlistener.ts  # CourtListener
    ├── census.ts         # Census Bureau
    ├── openalex.ts       # OpenAlex
    ├── semantic-scholar.ts
    ├── pubmed.ts         # PubMed/NCBI
    ├── core.ts           # CORE
    ├── sec-edgar.ts      # SEC EDGAR
    ├── fred.ts           # FRED
    ├── opensanctions.ts  # OpenSanctions
    ├── gdelt.ts          # GDELT
    ├── wikidata.ts       # Wikidata
    ├── crt-sh.ts         # crt.sh
    └── firecrawl.ts      # Firecrawl