feat!: hosted server with Event Registry login, mentions, aggregates and a single search tool

[eriknovak]

Summary

Adds a hosted server with Event Registry login, three new data surfaces (aggregates, breaking events, mentions), and replaces the three search tools with one search tool whose queries are composed server-side. The redesign was driven by an internal benchmark aimed at validating every tool, cutting NewsAPI.ai token spend and the MCP instruction/schema context, while keeping answer quality.

Changes

• Hosted server (src/http.ts): stateless Streamable HTTP entry point for https://mcp.newsapi.ai/mcp. The MCP client runs the OAuth login against auth.id.eventregistry.org; the server verifies the JWT (iss, aud, exp, JWKS via OpenID discovery), serves protected-resource metadata and runs each request on the caller's bearer token. Ships as a Docker image with GET /healthz; configured via MCP_PUBLIC_URL, MCP_AUTH_ISSUER, PORT. Deployment guide in docs/deployment.md.
• Local server login (src/oauth.ts): without NEWSAPI_KEY, npx newsapi-mcp logs in through the browser (authorization code + PKCE on loopback ports 51337–51339), keeps tokens in the OS credential store with a file fallback, refreshes with rotation and retries once on 401. login/logout subcommands manage the stored login; NEWSAPI_KEY still selects API-key mode. Tool errors explain an unlinked account or an expired login per auth mode.
• Hosted results marked as source material: results carry audience: ["assistant"], sit inside <source_material> tags and tell the model to report key points with links rather than paste raw results. No client currently honours the audience annotation, so it is a hint only.
• Aggregate result types: article and event searches accept resultType (timeAggr, sourceAggr, authorAggr, keywordAggr, locAggr, conceptAggr, categoryAggr, sentimentAggr, langAggr) rendered as label/count rows.
• get_breaking_events wraps event/getBreakingEvents with count, page and minimum score.
• Mentions (kind: "mentions"): sentences tagged with an event type (acquisition, layoffs, launch, recall…) with entities, sentiment, fact level and article link; mention-only filters (eventTypeUri, industryUri, sdgUri, sasbUri, esgUri, factLevel…) and eventTypeAggr. suggest(type: "eventTypes") resolves event type names.
• Single search tool (breaking): search_articles / search_events / search_mentions become search({kind}) with generic page, count, sortBy, options.sortByAsc. Kind-only params are tagged in their descriptions and rejected with a corrective 400 for other kinds. Static session-start cost drops from ~15.8k to ~10.5k tokens.
• Server-side query composition (src/query.ts): flat filters given alongside an advanced query are merged (leaf filters ANDed, ignore* → $not, duplicate/sentiment/rank flags → $filter); arrays and $not lists normalised; boolean keyword strings ("Tesla AND (recall OR lawsuit) NOT Musk") switch to keywordSearchMode: exact automatically; query-shaped 400s return rewrite guidance.
• Cost guards: a 31-day window is applied when no date filter is given (an unbounded search costs 65×); searches costing more than 1 API token say why under the result; default count is 50 (scans ask for 100); the response cap is 50k chars so oversized results are truncated instead of dropped by the client.
• Output: scan rows (articleBodyLen: 0) are one compact row per article (# | uri | date | source | title), with get_article_details supplying text and URL; rows print YYYY-MM-DD HH:MM and date-sorted article pages are re-sorted by publish time (the API sorts by crawl time). Rarely used filters live under one options object.
• Housekeeping: suggest cache removed (no measurable benefit), lock file bumped to clear npm audit, README/CHANGELOG/skill/guide updated, CONTEXT.md added.

Breaking changes: the three search tools are gone (use search with kind); articlesPage/Count/SortBy etc. become page/count/sortBy; sentiment, source rank, author/location/source-group filters, secondary ignore* filters, date-mention filters, dataType and *SortByAsc are accepted only inside options; searches without a date filter cover the last 31 days.

Test plan

• npm test → 11 files, 396 tests passed (unit, server integration via InMemoryTransport, hosted server with locally signed JWTs, loopback login flow).
• Internal benchmark (15 questions, live API, headless claude -p client with Sonnet and Haiku): NewsAPI tokens for the question set fell from 105 to 47 (Sonnet) and 133 to 56 (Haiku), session-start context from ~15.8k to ~10.5k tokens, answer quality flat to slightly up; single runs, indicative only.

Decisions

• Login goes through Event Registry (hosted: client-run OAuth; local: loopback PKCE) rather than API keys.
• The hosted server is stateless, fresh McpServer per request.
• Hosted results are marked as source material; the audience annotation is kept as a hint although no client honours it.
• 31-day default window kept despite changing behaviour for intentional archive searches: the cost cliff is 65× and a note tells the model how to widen.
• Three search tools merged into one search with kind, no aliases for the old names.
• A natural-language → query tool (Sentry pattern) was not pursued; composition plus boolean strings covered the benchmark cases without an extra LLM call.