{
  "markdown": "<h1 align=\"center\">\n  <br />\n  <img src=\"https://img.shields.io/badge/%E2%9A%A1-NewsIntel_API-1d9bf0?style=for-the-badge&labelColor=0d1117\" alt=\"NewsIntel API\" />\n  <br />\n</h1>\n\n```\n    _   __                 ____      __       __     ___    ____  ____\n   / | / /__ _      _____|  _/___  / /____  / /    /   |  / __ \\/  _/\n  /  |/ / _ \\ | /| / / __|/ // _ \\/ __/ _ \\/ /    / /| | / /_/ // /\n / /|  /  __/ |/ |/ /\\__ \\ // ___/ /_/  __/ /    / ___ |/ ____// /\n/_/ |_/\\___/|__/|__//___/___/\\___/\\__/\\___/_/    /_/  |_/_/   /___/\n```\n\n<p align=\"center\">\n  <strong>Personalized news intelligence for AI agents, MCP integrations, and developer workflows.</strong>\n  <br />\n  <sub>20+ sources. Real-time ranking. Agent-ready digests. Self-serve onboarding.</sub>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/stabem/newsintel-api/actions/workflows/ci.yml\"><img src=\"https://github.com/stabem/newsintel-api/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-ISC-blue.svg\" alt=\"License: ISC\"></a>\n  <a href=\"https://www.typescriptlang.org/\"><img src=\"https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white\" alt=\"TypeScript\"></a>\n  <a href=\"https://nodejs.org/\"><img src=\"https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white\" alt=\"Node\"></a>\n  <a href=\"./Dockerfile\"><img src=\"https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white\" alt=\"Docker\"></a>\n  <br />\n  <a href=\"./integrations/newsintel-mcp/\"><img src=\"https://img.shields.io/badge/MCP-compatible-6f42c1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMyAyTDMgMTRoOWwtMSA4IDEwLTEyaC05bDEtOHoiLz48L3N2Zz4=&logoColor=white\" alt=\"MCP\"></a>\n  <a href=\"https://biomejs.dev/\"><img src=\"https://img.shields.io/badge/code_style-biome-60a5fa.svg?logo=biome&logoColor=white\" alt=\"Biome\"></a>\n  <a href=\"./CONTRIBUTING.md\"><img src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" alt=\"PRs Welcome\"></a>\n  <a href=\"https://github.com/stabem/newsintel-api/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22\"><img src=\"https://img.shields.io/github/issues/stabem/newsintel-api/good%20first%20issue?color=7057ff&label=good%20first%20issues\" alt=\"Good First Issues\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://newsintelapi.com/portal\"><strong>Try the Portal</strong></a> &nbsp;&bull;&nbsp;\n  <a href=\"./docs/api-reference.md\"><strong>API Reference</strong></a> &nbsp;&bull;&nbsp;\n  <a href=\"./integrations/newsintel-mcp/\"><strong>MCP Server</strong></a> &nbsp;&bull;&nbsp;\n  <a href=\"./docs/architecture.md\"><strong>Architecture</strong></a> &nbsp;&bull;&nbsp;\n  <a href=\"./CONTRIBUTING.md\"><strong>Contributing</strong></a>\n</p>\n\n---\n\n## Why NewsIntel?\n\nMost news APIs give you raw feeds. NewsIntel gives you **intelligence** — ranked, deduplicated, bias-aware briefings ready for AI consumption.\n\n- **For AI agents**: get structured briefings via MCP or REST in one call\n- **For developers**: self-serve API keys, OpenAPI schema, Prometheus metrics out of the box\n- **For teams**: multi-workspace isolation, feedback-driven ranking, Grafana dashboards\n\n```bash\n# Get a personalized briefing in 10 seconds\ncurl -sS \"https://newsintelapi.com/v1/briefing?format=digest&limit=6\" \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\"\n```\n\n## Features\n\n```\n INGEST           PROCESS              DELIVER             OBSERVE\n ------           -------              -------             -------\n RSS (20+)  -->  Dedup & Normalize    REST API            Prometheus\n GDELT       -->  Bias-aware ranking   Agent digests       Grafana\n Guardian    -->  Topic inference      MCP server          Sentry\n X signals   -->  Feedback loop        Self-serve portal   OpenTelemetry\n```\n\n| | Feature | Details |\n|---|---|---|\n| **News** | Multi-source aggregation | RSS (20+ sources), GDELT, Guardian API, X following signals |\n| **AI** | Agent-ready output | `/briefing/agent` endpoint + standalone MCP server |\n| **Ranking** | Smart filtering | Bias diversity gates, source reliability scoring, recency weighting |\n| **Auth** | Multi-workspace | Per-workspace API keys, dynamic key provisioning, X OAuth self-serve |\n| **Feedback** | Learning loop | Like/skip/save/irrelevant signals influence future ranking |\n| **Ops** | Production-ready | Prometheus metrics, Grafana dashboards, Sentry, OpenTelemetry |\n\n## Quickstart\n\n### Option A: Use the hosted API (recommended)\n\n1. Open **[newsintelapi.com/portal](https://newsintelapi.com/portal)**\n2. Connect with X (OAuth) and get your API key\n3. Start making requests\n\nFor AI agents, use the [MCP server](./integrations/newsintel-mcp/) for native tool integration.\n\n### Option B: Self-host with Docker (safe baseline)\n\n```bash\ngit clone https://github.com/stabem/newsintel-api.git && cd newsintel-api\ncp .env.example .env\n# REQUIRED before first run: replace all CHANGE_ME_* placeholders in .env\n# example internal DB URL: postgresql://newsintel:<strong-password>@postgres:5432/newsintel\n# generate strong secrets, e.g.:\n#   API_KEYS=$(openssl rand -hex 24)\n#   OPS_ADMIN_KEY=$(openssl rand -hex 32)\n#   TOKEN_ENCRYPTION_SECRET=$(openssl rand -hex 32)\n\ndocker compose up --build -d\n\n# Verify\ncurl -sS http://localhost:8090/healthz\n```\n\n> 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.\n\n### Option C: Local development\n\n```bash\nnpm ci && cp .env.example .env\n# For local dev, replace the CHANGE_ME_* placeholders with local-only values first.\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres redis\nnpm run migrate:up && npm run dev\n```\n\nFor an all-in-one local stack with convenience defaults and published dev ports:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d\n```\n\n> **Local dev services**: API `localhost:8090` | Postgres `localhost:5436` | Redis `localhost:6386`\n\n## API Overview\n\nFull reference: [`docs/api-reference.md`](./docs/api-reference.md) | OpenAPI schema: `GET /openapi.json`\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/healthz` | - | Liveness check |\n| `GET` | `/readyz` | - | Readiness (DB/Redis/queue) |\n| `GET` | `/metrics` | - | Prometheus metrics |\n| `GET` | `/v1/briefing` | Bearer | Personalized briefing |\n| `GET` | `/v1/briefing/agent` | Bearer | Agent-optimized digest |\n| `GET` | `/v1/news/search` | Bearer | Search & aggregate news |\n| `POST` | `/v1/profile/sync` | Bearer | Sync profile (manual/x-browser/x-api) |\n| `POST` | `/v1/keys` | Bearer | Provision dynamic API key |\n| `GET` | `/v1/ops/status` | Admin | Operational health dashboard |\n\n## AI Integration\n\n### MCP Server (for Claude Desktop, Cursor, Windsurf, etc.)\n\nShips a standalone MCP server — plug into any MCP-compatible client:\n\n```bash\ncd integrations/newsintel-mcp && npm install\n```\n\nOr add to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"newsintel\": {\n      \"command\": \"node\",\n      \"args\": [\"integrations/newsintel-mcp/server.mjs\"],\n      \"env\": { \"NEWSINTEL_API_BASE\": \"https://newsintelapi.com\" }\n    }\n  }\n}\n```\n\nTools: `sync_profile` | `get_profile` | `get_news_briefing`\n\nSee [`integrations/newsintel-mcp/README.md`](./integrations/newsintel-mcp/README.md) for full docs.\n\n### Anthropic SDK (tool use + agents)\n\nBuild AI agents that use NewsIntel as a tool — examples in TypeScript and Python:\n\n```bash\n# TypeScript — agentic loop\ncd examples/agent-sdk-typescript && npm install\nANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... npx tsx agent.ts\n\n# Python — agentic loop\ncd examples/agent-sdk-python && pip install -r requirements.txt\nANTHROPIC_API_KEY=sk-... NEWSINTEL_API_KEY=ni_live_... python agent.py\n```\n\nSee [`examples/`](./examples/) for tool-use and agent patterns.\n\n## Architecture\n\n```\n                     +------------------+\n                     |   Self-serve     |\n                     |   Portal (HTML)  |\n                     +--------+---------+\n                              |\n  AI Agents (MCP) --+        |        +-- Prometheus\n                    |        v        |\n                    +-> [ Fastify ] <--+-- Grafana\n                    |   [ API    ]    |\n                    +-> [ Server ] <--+-- Sentry\n                        +---+---+\n                            |\n            +-------+-------+-------+-------+\n            |       |       |       |       |\n          RSS    GDELT  Guardian  X API   pg-boss\n         (20+)                           (queue)\n            |       |       |       |       |\n            +-------+-------+---+---+-------+\n                                |\n                    +-----------+-----------+\n                    |                       |\n                PostgreSQL              Redis\n              (profiles, news,       (briefing cache,\n               feedback, jobs)        enrichment cache)\n```\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [`docs/architecture.md`](./docs/architecture.md) | System overview and data flow |\n| [`docs/api-reference.md`](./docs/api-reference.md) | Endpoints, params, examples |\n| [`docs/configuration.md`](./docs/configuration.md) | Environment variables |\n| [`docs/observability.md`](./docs/observability.md) | Metrics, logging, tracing |\n| [`docs/operations.md`](./docs/operations.md) | Docker, hardening, troubleshooting |\n| [`SECURITY.md`](./SECURITY.md) | Vulnerability reporting, credential rotation |\n| [`SUPPORT.md`](./SUPPORT.md) | Community support channels |\n\n## Development\n\n```bash\nnpm run lint         # Biome linter\nnpm run typecheck    # TypeScript type checking\nnpm test             # Full test suite (127 tests)\nnpm run build        # Compile to dist/\n```\n\nOpenAPI contract snapshot: `npm run test:openapi-snapshot:update` when schema changes.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full guide.\n\n1. Fork and create a feature branch\n2. Make scoped changes with tests\n3. Run: `npm run lint && npm run typecheck && npm test && npm run build`\n4. Open a PR linking the issue\n\n## Roadmap\n\nSee [`docs/OPEN_SOURCE_ROADMAP.md`](./docs/OPEN_SOURCE_ROADMAP.md) for the full roadmap.\n\n- Source registry: file-based -> DB-managed\n- News persistence: optimize bulk inserts\n- API pagination and richer query semantics\n- Plugin system for custom news providers\n\n## Star History\n\n<p align=\"center\">\n  <a href=\"https://star-history.com/#stabem/newsintel-api&Date\">\n    <img src=\"https://api.star-history.com/svg?repos=stabem/newsintel-api&type=Date\" width=\"600\" alt=\"Star History\" />\n  </a>\n</p>\n\n## License\n\n[ISC](./LICENSE) - use it however you want.\n\n---\n\n<p align=\"center\">\n  <sub>Built with Fastify, TypeScript, PostgreSQL, Redis, and pg-boss.</sub>\n  <br />\n  <a href=\"https://github.com/stabem/newsintel-api\"><sub>Star the repo if NewsIntel helps your workflow.</sub></a>\n</p>\n",
  "bytes": 11140,
  "sha": "4fe489802926b750e06b3169f99ab30f641359cf16d49319c8461ca73ee78a02",
  "repo_slug": "stabem/newsintel-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_stabem_newsintel_657a72e2/readme"
}