Newsintel

[NewsIntel API]

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

Personalized news intelligence for AI agents, MCP integrations, and developer workflows.
_{20+ sources. Real-time ranking. Agent-ready digests. Self-serve onboarding.}

[CI] [License: ISC] [TypeScript] [Node] [Docker]
[MCP] [Biome] [PRs Welcome] [Good First Issues]

Try the Portal  •  API Reference  •  MCP Server  •  Architecture  •  Contributing

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

# Get a personalized briefing in 10 secondscurl -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

Quickstart

Option A: Use the hosted API (recommended)

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

For AI agents, use the MCP server for native tool integration.

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

git clone https://github.com/stabem/newsintel-api.git && cd newsintel-apicp .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
# Verifycurl -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

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 redisnpm run migrate:up && npm run dev

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

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 | OpenAPI schema: GET /openapi.json

AI Integration

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

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

cd integrations/newsintel-mcp && npm install

Or add to your .mcp.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 for full docs.

Anthropic SDK (tool use + agents)

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

# TypeScript — agentic loopcd examples/agent-sdk-typescript && npm installANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... npx tsx agent.ts
# Python — agentic loopcd examples/agent-sdk-python && pip install -r requirements.txtANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... python agent.py

See 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

Development

npm run lint         # Biome linternpm run typecheck    # TypeScript type checkingnpm 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 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 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

[Star History]

License

ISC - use it however you want.

_{Built with Fastify, TypeScript, PostgreSQL, Redis, and pg-boss.
Star the repo if NewsIntel helps your workflow.}