{
  "markdown": "# entra-news-mcp\n\n> A searchable knowledge MCP over [Entra.news](https://entra.news) — Merill Fernando's curated weekly digest of Microsoft Entra news, features, and community tools.\n\n[![npm](https://img.shields.io/npm/v/entra-news-mcp)](https://www.npmjs.com/package/entra-news-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/entra-news-mcp)](https://www.npmjs.com/package/entra-news-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## What is this?\n\n**Entra.news** is a high-signal, curated newsletter covering Microsoft Entra (Azure AD) features, announcements, and community tools — published weekly since mid-2023.\n\nThis MCP server exposes the full historical archive as a natural language search interface. Ask questions and get sourced answers directly from past issues — including issue number, date, and canonical URL.\n\n**Zero per-user infrastructure.** Users install an NPX package. That's it.\n\n---\n\n## Quick Start\n\n### Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"entra-news-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"entra-news-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The database (~15–20 MB) will be downloaded on first launch and cached in `~/.entra-news-mcp/`.\n\n### Cursor / Copilot Studio / Any MCP Host\n\n```json\n{\n  \"mcpServers\": {\n    \"entra-news-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"entra-news-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to your MCP config (workspace `.vscode/mcp.json`, or run **MCP: Add Server** from the Command Palette):\n\n```json\n{\n  \"servers\": {\n    \"entra-news-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"entra-news-mcp\"]\n    }\n  }\n}\n```\n\n### Semantic Search (Optional)\n\nBy default the server uses keyword and phrase matching over the SQLite index — no API key needed. For significantly better result quality, set your OpenAI API key to enable semantic + hybrid search:\n\n```json\n{\n  \"mcpServers\": {\n    \"entra-news-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"entra-news-mcp\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Local Database Cache\n\nOn first launch the server downloads the database (~15–20 MB) from GitHub Releases and caches it locally:\n\n| Platform | Cache location |\n|----------|---------------|\n| Windows  | `%USERPROFILE%\\.entra-news-mcp\\` |\n| macOS / Linux | `~/.entra-news-mcp/` |\n\nThe server checks for a newer database release **once per week**. If you want to force an immediate re-download (e.g. after a new issue has been ingested), delete the cache folder and restart your MCP host:\n\n**Windows (PowerShell):**\n```powershell\nRemove-Item \"$env:USERPROFILE\\.entra-news-mcp\" -Recurse -Force\n```\n\n**macOS / Linux:**\n```bash\nrm -rf ~/.entra-news-mcp\n```\n\n---\n\n## Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_entra_news` | Semantic + keyword hybrid search over all issues. Returns sourced excerpts. |\n| `get_issue` | Retrieve the full content of a specific issue by number or date. |\n| `list_issues` | Browse the archive with optional year/month filtering. |\n| `find_tool_mentions` | Discover community tools and GitHub projects mentioned in the archive. |\n\n### Example queries\n\n- *\"What did Entra.news cover about Conditional Access in 2024?\"*\n- *\"Show me the issue from March 2025\"*\n- *\"What PowerShell tools for Entra have been mentioned?\"*\n- *\"Has there been coverage of Verified ID?\"*\n- *\"List all issues from 2024\"*\n\n---\n\n## Architecture\n\n```\nSubstack API (entra.news/api/v1/posts)\n    │\n    ▼\nNode.js ingestion script  ←  OpenAI text-embedding-3-small\n    │\n    ▼\nSQLite (chunks + embeddings, ~15–20 MB)\n    │\n    ▼\nGitHub Release asset  ──→  NPX MCP Server\n                               └─ Downloads DB on first run\n                               └─ Checks for updates weekly\n                               └─ In-memory vector similarity + keyword search\n```\n\n**Cost:** ~$0.01/week (embeddings on new issues only). Zero hosting.\n\n---\n\n## Running the Ingestion Pipeline\n\n> **Note:** You only need to do this if you're maintaining your own fork or building the initial index. End users just run `npx entra-news-mcp` — the database is downloaded automatically.\n\n### Prerequisites\n\n- Node.js 22+\n- An OpenAI API key (`text-embedding-3-small` access)\n\n### Full ingest (first time)\n\n```powershell\n# Set your API key\n$env:OPENAI_API_KEY = \"sk-...\"\n\n# Run the ingestion pipeline\n./scripts/ingest.ps1\n```\n\nOr directly with Node.js:\n\n```bash\nexport OPENAI_API_KEY=sk-...\nnpm install && npm run build\nnode dist/scripts/ingest.js\n```\n\n### Incremental update (new issues only)\n\n```powershell\n./scripts/ingest.ps1 -Incremental\n```\n\n```bash\nnode dist/scripts/ingest.js --incremental\n```\n\nThe output database (`entra-news.db`) should then be uploaded as a GitHub Release asset — the GitHub Actions workflow handles this automatically on a weekly schedule.\n\n---\n\n## Automated Weekly Updates\n\nA GitHub Actions workflow (`.github/workflows/weekly-update.yml`) runs every Monday at 9am Sydney time (Sunday 23:00 UTC), shortly after each new Entra.news issue is published:\n\n1. Downloads the current database from GitHub Releases\n2. Runs the incremental ingestion pipeline\n3. Publishes the updated database as a new GitHub Release\n\n**Required secret:** Add `OPENAI_API_KEY` to your repository secrets (Settings → Secrets).\n\n---\n\n## Releasing (npm + MCP Registry)\n\nPublishing is automated by `.github/workflows/publish-mcp.yml`, triggered by pushing a `v*` tag. Authentication is tokenless (OIDC) for both npm ([Trusted Publishing](https://docs.npmjs.com/trusted-publishers)) and the [MCP Registry](https://modelcontextprotocol.io/registry/github-actions).\n\n1. Bump the version in `package.json` **and** `server.json` (both `version` fields) — the workflow fails if they don't match the tag\n2. Commit, then tag and push — deriving the tag from `package.json` so it always matches the workflow's version gate:\n\n```bash\nVERSION=$(node -p \"require('./package.json').version\")\ngit tag \"v$VERSION\"\ngit push origin main \"v$VERSION\"\n```\n\nThe workflow builds, publishes to npm (with provenance), and publishes the new version to the MCP Registry.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build          # Compile TypeScript\nnpm start              # Run the MCP server\n```\n\n### Project structure\n\n```\nsrc/\n  index.ts             # Entry point\n  server.ts            # MCP server + tool registration\n  db/\n    client.ts          # SQLite client — DB download/cache + search\n  tools/\n    search.ts          # search_entra_news tool\n    get-issue.ts       # get_issue tool\n    list-issues.ts     # list_issues tool\n    find-tool-mentions.ts  # find_tool_mentions tool\n  utils/\n    embeddings.ts      # OpenAI embedding helper\nscripts/\n  ingest.ts            # Full ingestion pipeline (TypeScript)\n  ingest.ps1           # PowerShell wrapper for ingestion\n.github/workflows/\n  weekly-update.yml    # Automated weekly update\n```\n\n---\n\n## Permissions & Content\n\nThe Entra.news content is © Merill Fernando & Joshua Fernando. This tool accesses the publicly available Substack API (not scraping) and is intended for personal/community use. Please reach out to [hey@entra.news](mailto:hey@entra.news) before any public deployment.\n\n---\n\n## Author\n\nBuilt by [Darren Robinson](https://github.com/darrenjrobinson).\n\nEntra.news by [Merill Fernando](https://merill.net).\n",
  "bytes": 7534,
  "sha": "7a723c76be341e895e8ad727aa6c5ce4786ad6bb122a59b2331a1cf556adc8eb",
  "repo_slug": "darrenjrobinson/entranewsmcpserver",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_darrenjrobinson_entra_news_095c0ee9/readme"
}