# primary-sources-mcp

[![CI](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/ci.yml)
[![Secret Scan](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/secret-scan.yml)
[![MCP Tool Definition Quality](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/tdqs.yml/badge.svg)](https://github.com/simonmak-ascent/primary-sources-mcp/actions/workflows/tdqs.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **Free primary-source APIs for AI agents.** SEC EDGAR, World Bank, GDELT, DATA.GOV.HK, HKMA, the official MCP Registry, UK Companies House, FRED and Jina Reader — as MCP tools, each result wrapped in a `{ source, retrievedAt, data }` provenance envelope.

Zero runtime dependencies. Node >= 20. 12 tools, 10 of them keyless.

## Quick start

```json
{
  "mcp": {
    "primary-sources": {
      "type": "local",
      "command": ["npx", "-y", "@simonmak-ascent/primary-sources-mcp"],
      "enabled": true,
      "timeout": 120000
    }
  }
}
```

Hosted (Streamable HTTP): `https://primary-sources-mcp.vercel.app/mcp`.

## Tools

| Tool | Source | Key |
|------|--------|-----|
| `sec_edgar_fulltext` | SEC EDGAR full-text search (US filings) | none |
| `sec_edgar_company` | SEC EDGAR registrant + recent filings | none |
| `world_bank_indicator` | World Bank development indicators | none |
| `gdelt_news` | GDELT DOC 2.0 global news | none |
| `hk_open_data_search` | DATA.GOV.HK catalogue search | none |
| `hk_open_data_filter` | DATA.GOV.HK filter API | none |
| `hkma` | Hong Kong Monetary Authority public API | none |
| `mcp_registry_search` | Official MCP Registry | none |
| `jina_read` | Jina Reader (URL → markdown) | none (free tier) |
| `companies_house_search` | UK Companies House search | `COMPANIES_HOUSE_API_KEY` |
| `companies_house_company` | UK Companies House record | `COMPANIES_HOUSE_API_KEY` |
| `fred_series` | St. Louis Fed FRED series | `FRED_API_KEY` |

## Environment

| Variable | Required | Purpose |
|----------|----------|---------|
| `RESEARCH_CONTACT` | no | User-Agent contact string (politeness for SEC/GDELT). |
| `COMPANIES_HOUSE_API_KEY` | for 2 tools | Free key from Companies House. |
| `FRED_API_KEY` | for 1 tool | Free key from the St. Louis Fed. |

## Provenance

Every data tool returns text of the form:

```json
{ "source": "World Bank Indicators", "retrievedAt": "2026-10-02T16:00:00.000Z", "data": { } }
```

so an agent can cite the origin and time of every fact.

## Development

```bash
npm install
npm run typecheck
npm test
npm run build
node dist/index.js   # stdio MCP server
```

## License

MIT — see [LICENSE](LICENSE).