io.github.darrenjrobinson/entra-news
Search the Entra.news newsletter archive — a weekly digest of Microsoft Entra news
Open source Open in the app JSON README (API)
About
Search the Entra.news newsletter archive — a weekly digest of Microsoft Entra news
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- darrenjrobinson
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.5
- Stars
- 7
- Forks
- 2
- Open pull requests
- 4
- Last push
- 2026-09-06T23:03:51Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-09-02 01:00:55
- Origin id
io.github.darrenjrobinson/entra-news
README
# entra-news-mcp
> A searchable knowledge MCP over [Entra.news](https://entra.news) — Merill Fernando's curated weekly digest of Microsoft Entra news, features, and community tools.
[](https://www.npmjs.com/package/entra-news-mcp)
[](https://www.npmjs.com/package/entra-news-mcp)
[](LICENSE)
---
## What is this?
**Entra.news** is a high-signal, curated newsletter covering Microsoft Entra (Azure AD) features, announcements, and community tools — published weekly since mid-2023.
This 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.
**Zero per-user infrastructure.** Users install an NPX package. That's it.
---
## Quick Start
### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["entra-news-mcp"]
}
}
}
```
Restart Claude Desktop. The database (~15–20 MB) will be downloaded on first launch and cached in `~/.entra-news-mcp/`.
### Cursor / Copilot Studio / Any MCP Host
```json
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["-y", "entra-news-mcp"]
}
}
}
```
### VS Code
Add to your MCP config (workspace `.vscode/mcp.json`, or run **MCP: Add Server** from the Command Palette):
```json
{
"servers": {
"entra-news-mcp": {
"command": "npx",
"args": ["-y", "entra-news-mcp"]
}
}
}
```
### Semantic Search (Optional)
By 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:
```json
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["entra-news-mcp"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}
```
---
## Local Database Cache
On first launch the server downloads the database (~15–20 MB) from GitHub Releases and caches it locally:
| Platform | Cache location |
|----------|---------------|
| Windows | `%USERPROFILE%\.entra-news-mcp\` |
| macOS / Linux | `~/.entra-news-mcp/` |
The 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:
**Windows (PowerShell):**
```powershell
Remove-Item "$env:USERPROFILE\.entra-news-mcp" -Recurse -Force
```
**macOS / Linux:**
```bash
rm -rf ~/.entra-news-mcp
```
---
## Available MCP Tools
| Tool | Description |
|------|-------------|
| `search_entra_news` | Semantic + keyword hybrid search over all issues. Returns sourced excerpts. |
| `get_issue` | Retrieve the full content of a specific issue by number or date. |
| `list_issues` | Browse the archive with optional year/month filtering. |
| `find_tool_mentions` | Discover community tools and GitHub projects mentioned in the archive. |
### Example queries
- *"What did Entra.news cover about Conditional Access in 2024?"*
- *"Show me the issue from March 2025"*
- *"What PowerShell tools for Entra have been mentioned?"*
- *"Has there been coverage of Verified ID?"*
- *"List all issues from 2024"*
---
## Architecture
```
Substack API (entra.news/api/v1/posts)
│
▼
Node.js ingestion script ← OpenAI text-embedding-3-small
│
▼
SQLite (chunks + embeddings, ~15–20 MB)
│
▼
GitHub Release asset ──→ NPX MCP Server
└─ Downloads DB on first run
└─ Checks for updates weekly
└─ In-memory vector similarity + keyword search
```
**Cost:** ~$0.01/week (embeddings on new issues only). Zero hosting.
---
## Running the Ingestion Pipeline
> **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.
### Prerequisites
- Node.js 22+
- An OpenAI API key (`text-embedding-3-small` access)
### Full ingest (first time)
```powershell
# Set your API key
$env:OPENAI_API_KEY = "sk-..."
# Run the ingestion pipeline
./scripts/ingest.ps1
```
Or directly with Node.js:
```bash
export OPENAI_API_KEY=sk-...
npm install && npm run build
node dist/scripts/ingest.js
```
### Incremental update (new issues only)
```powershell
./scripts/ingest.ps1 -Incremental
```
```bash
node dist/scripts/ingest.js --incremental
```
The 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.
---
## Automated Weekly Updates
A 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:
1. Downloads the current database from GitHub Releases
2. Runs the incremental ingestion pipeline
3. Publishes the updated database as a new GitHub Release
**Required secret:** Add `OPENAI_API_KEY` to your repository secrets (Settings → Secrets).
---
## Releasing (npm + MCP Registry)
Publishing 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).
1. Bump the version in `package.json` **and** `server.json` (both `version` fields) — the workflow fails if they don't match the tag
2. Commit, then tag and push — deriving the tag from `package.json` so it always matches the workflow's version gate:
```bash
VERSION=$(node -p "require('./package.json').version")
git tag "v$VERSION"
git push origin main "v$VERSION"
```
The workflow builds, publishes to npm (with provenance), and publishes the new version to the MCP Registry.
---
## Development
```bash
npm install
npm run build # Compile TypeScript
npm start # Run the MCP server
```
### Project structure
```
src/
index.ts # Entry point
server.ts # MCP server + tool registration
db/
client.ts # SQLite client — DB download/cache + search
tools/
search.ts # search_entra_news tool
get-issue.ts # get_issue tool
list-issues.ts # list_issues tool
find-tool-mentions.ts # find_tool_mentions tool
utils/
embeddings.ts # OpenAI embedding helper
scripts/
ingest.ts # Full ingestion pipeline (TypeScript)
ingest.ps1 # PowerShell wrapper for ingestion
.github/workflows/
weekly-update.yml # Automated weekly update
```
---
## Permissions & Content
The 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.
---
## Author
Built by [Darren Robinson](https://github.com/darrenjrobinson).
Entra.news by [Merill Fernando](https://merill.net).