primary-sources-mcp

# primary-sources-mcp

<!-- mcp-name: io.github.simonmak-ascent/primary-sources-mcp -->

> **Free primary-source APIs for AI agents.** 50 tools across 8 categories — filings, registries, macro, news, open-data, research, knowledge and tools. SEC EDGAR, HKEXnews, 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.

[![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)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.simonmak--ascent%2Fprimary--sources--mcp-4CAF50)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.simonmak-ascent/primary-sources-mcp)
[![Glama](https://glama.ai/mcp/servers/simonmak-ascent/primary-sources-mcp/badges/score.svg)](https://glama.ai/mcp/servers/simonmak-ascent/primary-sources-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Overview

Zero runtime dependencies. Node >= 20. 50 tools, 47 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 by category

### filings

| Tool | Source | Key |
|------|--------|-----|
| `sec_edgar_fulltext` | SEC EDGAR full-text search (US filings) | none |
| `sec_edgar_company` | SEC EDGAR registrant + recent filings | none |
| `hkex_announcements` | HKEXnews listed-company announcement search (HK) | none |
| `hkex_company` | HKEXnews listed-company resolve + recent filings | none |

### registries

| Tool | Source | Key |
|------|--------|-----|
| `companies_house_search` | UK Companies House search | `COMPANIES_HOUSE_API_KEY` |
| `companies_house_company` | UK Companies House record | `COMPANIES_HOUSE_API_KEY` |
| `gleif_lei` | GLEIF Legal Entity Identifier records (CC0) | none |
| `acra_sg_company` | ACRA Singapore corporate registry (data.gov.sg) | none |
| `vies_vat` | EU VIES VAT validation | none |

### macro

| Tool | Source | Key |
|------|--------|-----|
| `world_bank_indicator` | World Bank development indicators | none |
| `fred_series` | St. Louis Fed FRED series | `FRED_API_KEY` |
| `hkma` | Hong Kong Monetary Authority public API | none |
| `dbnomics_series` | DBnomics (World Bank, IMF, OECD, Eurostat, ECB, BIS, …) | none |
| `ecb_series` | ECB Data Portal (SDMX-JSON) | none |
| `treasury_fiscal` | US Treasury Fiscal Data | none |
| `un_sdg` | UN Sustainable Development Goal indicators | none |
| `un_comtrade` | UN Comtrade trade statistics | none |
| `who_gho` | WHO Global Health Observatory | none |

### news

| Tool | Source | Key |
|------|--------|-----|
| `gdelt_news` | GDELT DOC 2.0 global news | none |
| `hn_search` | Hacker News (Algolia) | none |
| `wikimedia_pageviews` | Wikimedia pageview metrics (CC0) | none |

### open-data

| Tool | Source | Key |
|------|--------|-----|
| `hk_open_data_search` | DATA.GOV.HK catalogue search | none |
| `hk_open_data_filter` | DATA.GOV.HK filter API | none |
| `ckan_search` | CKAN portals (data.gov.uk, data.gov.au) | none |
| `data_europa_search` | data.europa.eu EU open-data catalogue | none |

### research

| Tool | Source | Key |
|------|--------|-----|
| `crossref_works` | Crossref DOI metadata | none |
| `openalex_works` | OpenAlex scholarly works | none |
| `arxiv_search` | arXiv preprints | none |
| `pubmed_search` | PubMed (NCBI E-utilities) | none (optional `NCBI_API_KEY`) |
| `europepmc_search` | Europe PMC | none |
| `datacite_dois` | DataCite research-data DOIs | none |
| `doaj_articles` | Directory of Open Access Journals | none |
| `zenodo_records` | Zenodo research outputs | none |
| `semantic_scholar_works` | Semantic Scholar (rate-limited keyless) | none |

### knowledge

| Tool | Source | Key |
|------|--------|-----|
| `wikidata_search` | Wikidata entities (CC0) | none |
| `wikipedia_summary` | Wikipedia summaries (CC BY-SA) | none |
| `open_library_search` | Open Library books | none |
| `gutendex_books` | Project Gutenberg via Gutendex | none |
| `internet_archive_search` | Internet Archive | none |
| `world_bank_country` | World Bank country reference metadata | none |
| `nominatim_geocode` | OpenStreetMap Nominatim geocoding | none |
| `open_meteo_forecast` | Open-Meteo current weather | none |
| `usgs_earthquakes` | USGS earthquake catalogue | none |
| `gbif_species` | GBIF taxonomic backbone | none |
| `pubchem_compound` | PubChem compound data | none |
| `openfda_drug` | openFDA drug adverse events | none |
| `clinicaltrials_study` | ClinicalTrials.gov studies | none |
| `nasa_apod` | NASA Astronomy Picture of the Day | none (optional `NASA_API_KEY`) |

### tools

| Tool | Source | Key |
|------|--------|-----|
| `mcp_registry_search` | Official MCP Registry | none |
| `jina_read` | Jina Reader (URL → markdown) | none (free tier) |

## Environment

| Variable | Required | Purpose |
|----------|----------|---------|
| `RESEARCH_CONTACT` | no | User-Agent contact string (politeness for SEC/GDELT/OpenAlex). |
| `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. |
| `NCBI_API_KEY` | no | Raises PubMed (NCBI) rate limits. |
| `NASA_API_KEY` | no | Raises NASA APOD limits (falls back to shared `DEMO_KEY`). |

## Provenance & attribution

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.

Source licences vary: GLEIF and Wikidata are CC0; World Bank, Crossref, OpenAlex, DataCite, DOAJ, Zenodo, GBIF, openFDA, ClinicalTrials.gov and US government data are public-domain/open; ACRA is under the Singapore Open Data Licence; Wikipedia is CC BY-SA (attribution required); HKEXnews, GDELT and SEC filings are retrieved link-first and fetched on demand, not redistributed.

## Development

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

## License

MIT — see [LICENSE](LICENSE).