newsintel

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

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

# 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
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-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

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:

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:

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 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

                     +------------------+
                     |   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

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.

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

License

ISC - use it however you want.

---

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