_ __ ____ __ __ ___ ____ ____
/ | / /__ _ _____| _/___ / /____ / / / | / __ \/ _/
/ |/ / _ \ | /| / / __|/ // _ \/ __/ _ \/ / / /| | / /_/ // /
/ /| / __/ |/ |/ /\__ \ // ___/ /_/ __/ / / ___ |/ ____// /
/_/ |_/\___/|__/|__//___/___/\___/\__/\___/_/ /_/ |_/_/ /___/
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)
- 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)
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.ymlis safe-by-default: no built-in weak DB/Grafana credentials and no published Postgres/Redis ports. You still must replace theCHANGE_ME_*placeholders in.envbefore 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| Postgreslocalhost:5436| Redislocalhost: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.
- 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
<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 - 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>