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 "

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](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 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: @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

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

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.