Newsintel README

Code

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

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

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

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

Code

 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)

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

For AI agents, use the MCP server 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

Terminal

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:

Terminal

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

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:

config.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:

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/ for tool-use and agent patterns.

Architecture

Code

                     +------------------+
                     |   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`	System overview and data flow
`docs/api-reference.md`	Endpoints, params, examples
`docs/configuration.md`	Environment variables
`docs/observability.md`	Metrics, logging, tracing
`docs/operations.md`	Docker, hardening, troubleshooting
`SECURITY.md`	Vulnerability reporting, credential rotation
`SUPPORT.md`	Community support channels

Development

Terminal

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 for the full guide.

Fork and create a feature branch
Make scoped changes with tests
Run: npm run lint && npm run typecheck && npm test && npm run build
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

License

ISC - use it however you want.

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