# sellthenews-mcp

A read-only MCP (Model Context Protocol) server that wraps [sellthenews.org](https://sellthenews.org) API endpoints, making financial news and options data available as tools for LLMs like Claude.

## Architecture

```
sellthenews.org API  →  Adapters  →  Services  →  MCP Tools & Resources
```

**Four layers, each with one job:**

| Layer | What it does | Files |
|-------|-------------|-------|
| **Domain** | Defines TypeScript types for all data shapes | `src/domain/*.types.ts` |
| **Adapters** | Fetch raw JSON from upstream APIs (no processing) | `src/adapters/*.adapters.ts` |
| **Services** | Normalize raw data into clean domain objects | `src/services/*.service.ts` |
| **MCP** | Expose tools and resources to LLM clients | `src/mcp/*.tools.ts` |

Data flows left to right: the MCP layer calls services, services call adapters, adapters call the HTTP client.

## Upstream APIs

| Endpoint | Description |
|----------|-------------|
| `GET /api/live/recent` | Latest news feed with pinned stories |
| `GET /api/wsb/latest` | Wall Street Bets daily analysis snapshot |
| `GET /api/search` | Keyword-based news search |
| `GET /api/options/chain` | Options chain, GEX, and greek exposure |

## MCP Tools

| Tool | Description | Key inputs |
|------|-------------|------------|
| `get_recent_news` | Latest news stories | `limit`, `offset`, `lang`, `sources`, `marketOnly` |
| `get_wsb_snapshot` | WSB daily analysis | `lang` |
| `search_news` | Search news by keyword | `query`, `limit`, `offset`, `lang`, `sources`, `sort` |
| `get_options_chain` | Full options chain for a ticker | `ticker`, `expiration`, `greeks` |
| `get_options_summary` | Concise options exposure summary | `ticker` |

## MCP Resources

| URI | Description |
|-----|-------------|
| `sellthenews://news/recent` | Latest news feed (ambient context) |
| `sellthenews://wsb/latest` | Latest WSB snapshot (ambient context) |

## Setup

```bash
npm install
npm run build
```

## Run Locally

```bash
npm start
```

The server runs over stdio, so it is meant to be launched by an MCP client such as Claude Desktop or an MCP inspector rather than opened in a browser.

For private single-user compatibility testing, the HTTP client can also read `SELLTHENEWS_USER_AGENT`, `SELLTHENEWS_COOKIE`, `SELLTHENEWS_ACCEPT_LANGUAGE`, and `SELLTHENEWS_REFERER` from the environment and forward them as request headers when present.

## Usage with Claude Desktop

Add this to your Claude Desktop MCP config file. On macOS it's at `~/Library/Application Support/Claude/claude_desktop_config.json`, on Windows it's at `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sellthenews": {
      "command": "node",
      "args": ["/REPLACE/WITH/YOUR/ACTUAL/PATH/sellthenews_MCP/dist/index.js"]
    }
  }
}
```

> **Important:** Replace the path above with the actual absolute path to `dist/index.js` on your machine. For example, on Windows it might be `C:\\Users\\yourname\\Desktop\\sellthenews_MCP\\dist\\index.js`.

## Project Structure

```
src/
  domain/
    shared.types.ts       # Common types (SourceInfo, TickerMention, etc.)
    news.types.ts         # News domain: raw API types + clean domain types
    options.types.ts      # Options domain: raw API types + clean domain types
  infra/
    http-client.ts        # HTTP client wrapping fetch()
  adapters/
    news.adapters.ts      # 3 news adapters (live/recent, wsb, search)
    options.adapters.ts   # 1 options adapter (options/chain)
  services/
    news.service.ts       # News normalization logic
    options.service.ts    # Options normalization logic
  mcp/
    news.tools.ts         # News MCP tools + resources + Zod schemas
    options.tools.ts      # Options MCP tools + Zod schemas
  index.ts                # Entry point: wires layers, starts server
```

## Current Status

Stage 2A is complete. The repository now performs real upstream GET requests, normalizes raw responses into domain objects, and exposes live MCP tools/resources that return consistent JSON text.

**Implemented now:**
1. `HttpClient.get()` with URL building, timeout handling, JSON parsing, and clearer error messages
2. Real adapters for all four identified sellthenews endpoints
3. Service-layer normalization for news feeds, WSB snapshots, options chains, and options summaries
4. Live MCP tool and resource handlers wired to the service layer
5. Optional env-driven compatibility headers for private single-user testing when plain server-side requests hit upstream protection

**Still pending:**
1. Automated tests for adapters, services, and MCP smoke coverage
2. Better operational hardening if upstream failures or Cloudflare issues show up in practice
3. Stage 3 concerns such as caching, rate limiting, and production logging

## Quick Smoke Check

1. Run `npm run build`
2. Run `npm start`
3. Connect the server from Claude Desktop or an MCP inspector
4. Call `get_recent_news` with `{ "limit": 2 }` or `get_options_summary` with `{ "ticker": "MU" }`

If upstream access works, the response should be pretty-printed JSON instead of placeholder text.

If upstream blocks plain server-side requests, retry your local run with `SELLTHENEWS_USER_AGENT`, `SELLTHENEWS_COOKIE`, `SELLTHENEWS_ACCEPT_LANGUAGE`, and `SELLTHENEWS_REFERER` set in the environment as needed.