# newsintel [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/stabem/newsintel-api  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/newsintel

## Description
Personalized news intelligence for AI agents — 100+ sources, ranked briefings.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "newsintel": {
    "url": "https://img.shields.io/badge/%E2%9A%A1-NewsIntel_API-1d9bf0?style=for-the-badge&labelColor=0d1117"
  }
}
```

## Documentation & README

<h1 align="center">
  <br />
  <img src="https://img.shields.io/badge/%E2%9A%A1-NewsIntel_API-1d9bf0?style=for-the-badge&labelColor=0d1117" alt="NewsIntel API" />
  <br />
</h1>

```
    _   __                 ____      __       __     ___    ____  ____
   / | / /__ _      _____|  _/___  / /____  / /    /   |  / __ \/  _/
  /  |/ / _ \ | /| / / __|/ // _ \/ __/ _ \/ /    / /| | / /_/ // /
 / /|  /  __/ |/ |/ /\__ \ // ___/ /_/  __/ /    / ___ |/ ____// /
/_/ |_/\___/|__/|__//___/___/\___/\__/\___/_/    /_/  |_/_/   /___/
```

<p align="center">
  <strong>Personalized news intelligence for AI agents, MCP integrations, and developer workflows.</strong>
  <br />
  <sub>20+ sources. Real-time ranking. Agent-ready digests. Self-serve onboarding.</sub>
</p>

<p align="center">
  <a href="https://github.com/stabem/newsintel-api/actions/workflows/ci.yml"><img src="https://github.com/stabem/newsintel-api/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/LICENSE"><img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="License: ISC"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white" alt="Node"></a>
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/Dockerfile"><img src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white" alt="Docker"></a>
  <br />
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/integrations/newsintel-mcp/"><img src="https://img.shields.io/badge/MCP-compatible-6f42c1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMyAyTDMgMTRoOWwtMSA4IDEwLTEyaC05bDEtOHoiLz48L3N2Zz4=&logoColor=white" alt="MCP"></a>
  <a href="https://biomejs.dev/"><img src="https://img.shields.io/badge/code_style-biome-60a5fa.svg?logo=biome&logoColor=white" alt="Biome"></a>
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
  <a href="https://github.com/stabem/newsintel-api/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"><img src="https://img.shields.io/github/issues/stabem/newsintel-api/good%20first%20issue?color=7057ff&label=good%20first%20issues" alt="Good First Issues"></a>
</p>

<p align="center">
  <a href="https://newsintelapi.com/portal"><strong>Try the Portal</strong></a> &nbsp;&bull;&nbsp;
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/docs/api-reference.md"><strong>API Reference</strong></a> &nbsp;&bull;&nbsp;
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/integrations/newsintel-mcp/"><strong>MCP Server</strong></a> &nbsp;&bull;&nbsp;
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/docs/architecture.md"><strong>Architecture</strong></a> &nbsp;&bull;&nbsp;
  <a href="https://github.com/stabem/newsintel-api/blob/HEAD/CONTRIBUTING.md"><strong>Contributing</strong></a>
</p>

---

## Why NewsIntel?

Most news APIs give you raw feeds. NewsIntel gives you **intelligence** — ranked, deduplicated, bias-aware briefings ready for AI consumption.

- **For AI agents**: get structured briefings via MCP or REST in one call
- **For developers**: self-serve API keys, OpenAPI schema, Prometheus metrics out of the box
- **For teams**: multi-workspace isolation, feedback-driven ranking, Grafana dashboards

```bash
# Get a personalized briefing in 10 seconds
curl -sS "https://newsintelapi.com/v1/briefing?format=digest&limit=6" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

## Features

```
 INGEST           PROCESS              DELIVER             OBSERVE
 ------           -------              -------             -------
 RSS (20+)  -->  Dedup & Normalize    REST API            Prometheus
 GDELT       -->  Bias-aware ranking   Agent digests       Grafana
 Guardian    -->  Topic inference      MCP server          Sentry
 X signals   -->  Feedback loop        Self-serve portal   OpenTelemetry
```

| | Feature | Details |
|---|---|---|
| **News** | Multi-source aggregation | RSS (20+ sources), GDELT, Guardian API, X following signals |
| **AI** | Agent-ready output | `/briefing/agent` endpoint + standalone MCP server |
| **Ranking** | Smart filtering | Bias diversity gates, source reliability scoring, recency weighting |
| **Auth** | Multi-workspace | Per-workspace API keys, dynamic key provisioning, X OAuth self-serve |
| **Feedback** | Learning loop | Like/skip/save/irrelevant signals influence future ranking |
| **Ops** | Production-ready | Prometheus metrics, Grafana dashboards, Sentry, OpenTelemetry |

## Quickstart

### Option A: Use the hosted API (recommended)

1. Open **[newsintelapi.com/portal](https://newsintelapi.com/portal)**
2. Connect with X (OAuth) and get your API key
3. Start making requests

For AI agents, use the [MCP server](https://github.com/stabem/newsintel-api/blob/HEAD/integrations/newsintel-mcp/) for native tool integration.

### Option B: Self-host with Docker (safe baseline)

```bash
git clone https://github.com/stabem/newsintel-api.git && cd newsintel-api
cp .env.example .env
# REQUIRED before first run: replace all CHANGE_ME_* placeholders in .env
# example internal DB URL: postgresql://newsintel:<strong-password>@postgres:5432/newsintel
# generate strong secrets, e.g.:
#   API_KEYS=$(openssl rand -hex 24)
#   OPS_ADMIN_KEY=$(openssl rand -hex 32)
#   TOKEN_ENCRYPTION_SECRET=$(openssl rand -hex 32)

docker compose up --build -d

# Verify
curl -sS http://localhost:8090/healthz
```

> The primary `docker-compose.yml` is **safe-by-default**: no built-in weak DB/Grafana credentials and no published Postgres/Redis ports. You still must replace the `CHANGE_ME_*` placeholders in `.env` before using it outside throwaway local testing.

### Option C: Local development

```bash
npm ci && cp .env.example .env
# For local dev, replace the CHANGE_ME_* placeholders with local-only values first.
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres redis
npm run migrate:up && npm run dev
```

For an all-in-one local stack with convenience defaults and published dev ports:

```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d
```

> **Local dev services**: API `localhost:8090` | Postgres `localhost:5436` | Redis `localhost:6386`

## API Overview

Full reference: [`docs/api-reference.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/api-reference.md) | OpenAPI schema: `GET /openapi.json`

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/healthz` | - | Liveness check |
| `GET` | `/readyz` | - | Readiness (DB/Redis/queue) |
| `GET` | `/metrics` | - | Prometheus metrics |
| `GET` | `/v1/briefing` | Bearer | Personalized briefing |
| `GET` | `/v1/briefing/agent` | Bearer | Agent-optimized digest |
| `GET` | `/v1/news/search` | Bearer | Search & aggregate news |
| `POST` | `/v1/profile/sync` | Bearer | Sync profile (manual/x-browser/x-api) |
| `POST` | `/v1/keys` | Bearer | Provision dynamic API key |
| `GET` | `/v1/ops/status` | Admin | Operational health dashboard |

## AI Integration

### MCP Server (for Claude Desktop, Cursor, Windsurf, etc.)

Ships a standalone MCP server — plug into any MCP-compatible client:

```bash
cd integrations/newsintel-mcp && npm install
```

Or add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "newsintel": {
      "command": "node",
      "args": ["integrations/newsintel-mcp/server.mjs"],
      "env": { "NEWSINTEL_API_BASE": "https://newsintelapi.com" }
    }
  }
}
```

Tools: `sync_profile` | `get_profile` | `get_news_briefing`

See [`integrations/newsintel-mcp/README.md`](https://github.com/stabem/newsintel-api/blob/HEAD/integrations/newsintel-mcp/README.md) for full docs.

### Anthropic SDK (tool use + agents)

Build AI agents that use NewsIntel as a tool — examples in TypeScript and Python:

```bash
# TypeScript — agentic loop
cd examples/agent-sdk-typescript && npm install
ANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... npx tsx agent.ts

# Python — agentic loop
cd examples/agent-sdk-python && pip install -r requirements.txt
ANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... python agent.py
```

See [`examples/`](https://github.com/stabem/newsintel-api/blob/HEAD/examples/) for tool-use and agent patterns.

## Architecture

```
                     +------------------+
                     |   Self-serve     |
                     |   Portal (HTML)  |
                     +--------+---------+
                              |
  AI Agents (MCP) --+        |        +-- Prometheus
                    |        v        |
                    +-> [ Fastify ] <--+-- Grafana
                    |   [ API    ]    |
                    +-> [ Server ] <--+-- Sentry
                        +---+---+
                            |
            +-------+-------+-------+-------+
            |       |       |       |       |
          RSS    GDELT  Guardian  X API   pg-boss
         (20+)                           (queue)
            |       |       |       |       |
            +-------+-------+---+---+-------+
                                |
                    +-----------+-----------+
                    |                       |
                PostgreSQL              Redis
              (profiles, news,       (briefing cache,
               feedback, jobs)        enrichment cache)
```

## Documentation

| Document | Description |
|---|---|
| [`docs/architecture.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/architecture.md) | System overview and data flow |
| [`docs/api-reference.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/api-reference.md) | Endpoints, params, examples |
| [`docs/configuration.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/configuration.md) | Environment variables |
| [`docs/observability.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/observability.md) | Metrics, logging, tracing |
| [`docs/operations.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/operations.md) | Docker, hardening, troubleshooting |
| [`SECURITY.md`](https://github.com/stabem/newsintel-api/blob/HEAD/SECURITY.md) | Vulnerability reporting, credential rotation |
| [`SUPPORT.md`](https://github.com/stabem/newsintel-api/blob/HEAD/SUPPORT.md) | Community support channels |

## Development

```bash
npm run lint         # Biome linter
npm run typecheck    # TypeScript type checking
npm test             # Full test suite (127 tests)
npm run build        # Compile to dist/
```

OpenAPI contract snapshot: `npm run test:openapi-snapshot:update` when schema changes.

## Contributing

See [`CONTRIBUTING.md`](https://github.com/stabem/newsintel-api/blob/HEAD/CONTRIBUTING.md) for the full guide.

1. Fork and create a feature branch
2. Make scoped changes with tests
3. Run: `npm run lint && npm run typecheck && npm test && npm run build`
4. Open a PR linking the issue

## Roadmap

See [`docs/OPEN_SOURCE_ROADMAP.md`](https://github.com/stabem/newsintel-api/blob/HEAD/docs/OPEN_SOURCE_ROADMAP.md) for the full roadmap.

- Source registry: file-based -> DB-managed
- News persistence: optimize bulk inserts
- API pagination and richer query semantics
- Plugin system for custom news providers

## Star History

<p align="center">
  <a href="https://star-history.com/#stabem/newsintel-api&Date">
    <img src="https://api.star-history.com/svg?repos=stabem/newsintel-api&type=Date" width="600" alt="Star History" />
  </a>
</p>

## License

[ISC](https://github.com/stabem/newsintel-api/blob/HEAD/LICENSE) - use it however you want.

---

<p align="center">
  <sub>Built with Fastify, TypeScript, PostgreSQL, Redis, and pg-boss.</sub>
  <br />
  <a href="https://github.com/stabem/newsintel-api"><sub>Star the repo if NewsIntel helps your workflow.</sub></a>
</p>