npm package: @missionsquad/mcp-nyt
Description: MCP server interface for the New York Times API
Author: Mission Squad AI
Latest version: 0.1.0

# @missionsquad/mcp-nyt

MCP server interface for the New York Times API (`https://api.nytimes.com`).

This server exposes NYT API operations for article search, top stories, real-time news, most popular articles, archives, and book best sellers via FastMCP tools.

## Features

- FastMCP stdio server (`mcp-nyt`)
- NYT API key support via hidden tool arg (`apiKey`) or env fallback (`NYT_API_KEY`)
- NYT base URL configurable via env (`NYT_BASE_URL`)
- Strict TypeScript and Zod-validated tool inputs
- Clean, formatted API responses
- Build/test CI and npm publish workflow

## Verified API Coverage

- Article Search (`search/v2/articlesearch.json`)
- Top Stories (`topstories/v2/{section}.json`)
- Times Wire (`news/v3/content/all/all.json`)
- Most Popular (`mostpopular/v2/{type}/{period}.json`)
- Archive (`archive/v1/{year}/{month}.json`)
- Books (`books/v3/lists/current/{list}.json`)

## Requirements

- Node.js `>=20`
- Yarn
- NYT API Key (get one at [NYT Developer Portal](https://developer.nytimes.com/))

## Installation

```bash
yarn install
yarn build
yarn start
```

Run as CLI after install/publish:

```bash
mcp-nyt
```

## Configuration

Copy `.env.example` to `.env`.

| Variable | Required | Default | Description |
|---|---|---|---|
| `NYT_API_KEY` | No | unset | NYT API key fallback when hidden `apiKey` is not passed |
| `NYT_BASE_URL` | No | `https://api.nytimes.com/svc` | Base URL for NYT API endpoints |
| `NYT_HTTP_TIMEOUT_MS` | No | `30000` | Request timeout in milliseconds |

## Hidden Arguments

The following are intentionally not in tool schemas and should be passed as hidden extra args:

- `apiKey`: NYT API key for request authentication

Resolution order per request:

1. Hidden extra arg
2. Environment fallback (`NYT_API_KEY`)

If no API key is available, the tool returns a user-facing error.

## Tool Surface

### Article Search

- `nyt_article_search` — Search NYT articles by keyword with optional date filtering and sorting.

### Top Stories

- `nyt_top_stories` — Get the current top stories from the New York Times by section.

### Times Wire

- `nyt_times_wire` — Get real-time news feed from the NYT Times Wire service.

### Most Popular

- `nyt_most_popular` — Get the most popular NYT articles by views, shares, or emails over a time period.

### Archive

- `nyt_archive` — Get all NYT article metadata for a given month and year.

### Books

- `nyt_books` — Get the current NYT Best Sellers list by list name.

## Response Format

All tool handlers return deterministic JSON text strings. Parse text content on the client side if structured access is needed.

## Usage Examples

### JSON-RPC tools/call with hidden API key

```json
{
  "method": "tools/call",
  "params": {
    "name": "nyt_article_search",
    "arguments": {
      "query": "artificial intelligence",
      "apiKey": "your-nyt-api-key"
    }
  }
}
```

### FastMCP-style client call

```ts
await client.callTool('nyt_top_stories', {
  section: 'technology',
  apiKey: 'your-nyt-api-key',
})
```

### Article Search

```ts
await client.callTool('nyt_article_search', {
  query: 'climate change',
  sort: 'newest',
  begin_date: '20250101',
  end_date: '20250401',
  apiKey: 'your-nyt-api-key',
})
```

### Most Popular

```ts
await client.callTool('nyt_most_popular', {
  type: 'viewed',
  time_period: '7',
  apiKey: 'your-nyt-api-key',
})
```

### Times Wire

```ts
await client.callTool('nyt_times_wire', {
  limit: 10,
  source: 'nyt',
  apiKey: 'your-nyt-api-key',
})
```

### Archive

```ts
await client.callTool('nyt_archive', {
  year: 2025,
  month: 3,
  apiKey: 'your-nyt-api-key',
})
```

### Books

```ts
await client.callTool('nyt_books', {
  list: 'hardcover-fiction',
  apiKey: 'your-nyt-api-key',
})
```

## Development

Scripts:

- `yarn build`
- `yarn start`
- `yarn dev`
- `yarn inspect`
- `yarn test`
- `yarn test:coverage`

## CI/CD

- `.github/workflows/build.yaml`: build + test on PR open/sync
- `.github/workflows/publish.yaml`: build + test + publish on `main` push (markdown-only changes ignored)

## License

MIT