newsapi-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build          # TypeScript compilation (tsc)
npm run build:bundle   # Production single-file bundle (esbuild → dist/index.js)
npm run build:http     # Hosted server bundle (esbuild → dist/http.js, used by Dockerfile)
npm run dev            # Dev mode with tsx hot reload
npm test               # Run all tests (vitest)
npm run test:watch     # Tests in watch mode
npx vitest run tests/formatters.test.ts  # Run single test file

CI runs on [ubuntu, windows, macos] × [node 20, 22]. Publishing uses npm publish --provenance triggered by GitHub releases.

Architecture

MCP server for NewsAPI.ai (Event Registry). Provides 8 tools: one search tool (kind: articles, events, mentions), detail lookups, topic pages, suggest and usage.

Two entry points share createServer() from src/server.ts:

• Local server — src/index.ts, stdio. Logs in to Event Registry through a loopback browser flow (src/oauth.ts) unless NEWSAPI_KEY selects API-key mode; login/logout subcommands manage the stored tokens. Published to npm.
• Hosted server — src/http.ts, stateless Streamable HTTP (fresh McpServer per request), login run by the MCP client. Verifies JWT access tokens, then runs the request inside withAccessToken() so client.ts sends Authorization: Bearer instead of the API key. Shipped as a Docker image, not in the npm package.

Request Flow

MCP Client → McpServer (SDK) → ToolRegistry handler → apiPost() → NewsAPI.ai
                                      ↓
                              Response Filter (strip fields)
                                      ↓
                              Formatter (JSON → text, optional)
                                      ↓
                              MCP Response back to client

Key Modules

• src/client.ts — HTTP client. apiPost() for main API. Injects the API key, the local login's bearer token (renewed once and retried on 401), or the hosted caller's bearer token when inside withAccessToken() (AsyncLocalStorage). authMode() tells the error formatter which guidance to give.
• src/oauth.ts — Local login: OAuthSession (PKCE code flow on fixed loopback ports, single-flight refresh with rotation), token stores (@napi-rs/keyring, file fallback), OpenID discovery shared with http.ts.
• src/http.ts — Hosted server: express app, protected-resource metadata, requireBearerAuth with a jose JWT verifier, /healthz. Config from MCP_PUBLIC_URL, MCP_AUTH_ISSUER, PORT.
• src/query.ts — Search request builder shared by the search tools: expands comma lists, folds flat filters into an advanced query ($and leaf, ignore* → $not, $filter), normalises arrays to {"$or"}, auto-detects boolean keyword strings (keywordSearchMode: exact) and applies the 31-day default window; returns notes the registry prints under the result.
• src/tools/registry.ts — ToolRegistry class. Registers all tools at startup. buildZodShape() converts JSON Schema → Zod for MCP SDK registration.
• src/response-filter.ts — Token optimization. includeFields param maps to API include params + post-response field stripping. filterResponse() preserves pagination metadata.
• src/formatters.ts — Converts JSON responses to compact text. All tools with formatters output human-readable numbered text.
• src/tools/search.ts — The search tool: assembles the schema from the shared filters plus each kind's SearchKind config (articlesKind, eventsKind, mentionsKind in their own files), tags kind-only params in their descriptions, maps the generic page/count/sortBy to the API's per-kind names and rejects params the chosen kind does not accept.
• src/tools/*.ts — Tool definitions as ToolDef objects with name, description, schema (JSON Schema), handler, and optional formatter.