briefing-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Jordan Shelley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# briefing-mcp
+
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/briefing-service-wholemind-workers-dev) [![briefing-mcp on Glama](https://glama.ai/mcp/servers/jshelley/briefing-mcp/badges/score.svg)](https://glama.ai/mcp/servers/jshelley/briefing-mcp) [![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-jshelley-briefing-mcp-3acc4c9f/badge.svg)](https://tensorblock.co/mcp/servers/github-jshelley-briefing-mcp-3acc4c9f)
+
+MCP server for [Briefing Service](https://briefing-service.wholemind.workers.dev): every hour an LLM editor ranks ~100 feeds per topic (AI, frontier labs, markets, US sports, European football, US news, world) and publishes the result as structured JSON, a rendered 480x800 e-ink page, a multi-page Morning Paper PDF, and a free provenance dump of every candidate it saw.
+
+This package runs locally over stdio and calls the public REST API. The same tools are served remotely (streamable HTTP, no install) at `https://briefing-service.wholemind.workers.dev/mcp`.
+
+## Install
+
+Claude Desktop / Claude Code / Cursor / any stdio client:
+
+```json
+{
+  "mcpServers": {
+    "briefings": {
+      "command": "npx",
+      "args": ["-y", "github:jshelley/briefing-mcp"],
+      "env": { "BRIEFING_KEY": "" }
+    }
+  }
+}
+```
+
+Claude Code one-liner:
+
+```bash
+claude mcp add briefings -- npx -y github:jshelley/briefing-mcp
+```
+
+Claude Desktop, one click: download [briefing-mcp-0.1.0.mcpb](https://github.com/jshelley/briefing-mcp/releases/download/v0.1.0/briefing-mcp-0.1.0.mcpb) and open it (MCP bundle; it asks for the optional Reader key).
+
+## Tools
+
+| tool | what it returns | cost |
+|---|---|---|
+| `list_briefings` | keys, names and prices | free |
+| `get_briefing(key)` | lead, ranked stories, research, why-it-matters, key points | 25 free/IP/day, then key or x402 |
+| `get_summary(key)` | headlines and one-liners | free |
+| `get_candidates(key)` | every candidate this hour: canonical link, outlets, `selected`, collapsed duplicates with `duplicate_of` | free |
+| `get_page(key, page, wide)` | 480x800 1-bit PNG (or 800x480 wide front page) | 25 free/IP/day |
+| `render_briefing(feeds, persona)` | rank and render your own feeds | Reader key or x402 |
+
+## Pricing
+
+- Free: 25 JSON/page/tool calls per IP per day, plus the summary and candidates endpoints.
+- Reader key: $9/month, unlimited reads, Morning Paper delivery, 10 custom renders/day. Set it as `BRIEFING_KEY`. Buy at https://briefing-service.wholemind.workers.dev/billing/checkout
+- Per call: x402 (USDC on Base) against the remote endpoint.
+
+Docs for agents: https://briefing-service.wholemind.workers.dev/llms.txt
+
+## How it works
+
+`index.js` is the whole server: it registers six tools with `@modelcontextprotocol/sdk` and answers each by calling the public Briefing Service REST API over HTTPS (`GET /v1/briefings/...`, `POST /v1/render`). It stores nothing, runs no shell commands, and reads only two environment variables (`BRIEFING_KEY`, `BRIEFING_BASE_URL`). The `Dockerfile` builds the same thing; `docker run -i` speaks MCP over stdio.
+
+Run the smoke test locally:
+
+```bash
+npm install
+node client-test.mjs   # lists tools and calls list_briefings, get_summary, get_candidates, get_page, get_briefing
+```
+
+Write-up of the pipeline (collect, entity-overlap dedupe, LLM editor, 1-bit render) and what the first week taught: https://dev.to/jshelley/i-built-an-hourly-newspaper-for-e-ink-and-turned-the-pipeline-into-an-mcp-server-1ebg. Each briefing also has an Atom feed at `/v1/briefings/{key}/feed.xml`; the Morning Paper PDF carries an outline per story, front-page go-to links and a clickable source URL on every story page.
+
+## Environment
+
+- `BRIEFING_KEY`: optional Reader key (sent as `Authorization: Bearer`).
+- `BRIEFING_BASE_URL`: override the API base (default: the public service).
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// briefing-mcp: stdio MCP server for Briefing Service (hourly LLM-ranked news
+// briefings, rendered e-ink pages, Morning Paper, provenance dump).
+// It is a thin client over the public REST API; the same tools are also served
+// remotely at https://briefing-service.wholemind.workers.dev/mcp.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BASE = (process.env.BRIEFING_BASE_URL || "https://briefing-service.wholemind.workers.dev").replace(/\/$/, "");
+const KEY = process.env.BRIEFING_KEY || "";
+const VERSION = "0.1.0";
+
+function headers(extra = {}) {
+  const h = { "user-agent": `briefing-mcp/${VERSION}`, accept: "application/json", ...extra };
+  if (KEY) h.authorization = `Bearer ${KEY}`;
+  return h;
+}
+
+async function get(path, accept) {
+  const res = await fetch(`${BASE}${path}`, { headers: headers(accept ? { accept } : {}) });
+  return res;
+}
+
+function paywallText(res, body) {
+  if (res.status === 402) {
+    return (
+      `Payment required (free trial of ${res.headers.get("x-trial-per-day") || "25"} calls per IP per day is used up). ` +
+      `Options: set BRIEFING_KEY to a Reader key ($9/month, ${BASE}/billing/checkout) or pay per call with x402 (USDC on Base) against the remote endpoint ${BASE}/mcp. ` +
+      `Docs: ${BASE}/llms.txt`
+    );
+  }
+  return `error ${res.status}: ${body.slice(0, 500)}`;
+}
+
+const server = new McpServer(
+  { name: "briefing-mcp", version: VERSION, title: "Briefing Service: hourly ranked news" },
+  {
+    instructions:
+      "Hourly LLM-ranked news briefings (AI, frontier labs, markets, US sports, European football, US news, world) as structured JSON, rendered e-ink pages and a provenance dump. " +
+      "Call list_briefings first, then get_briefing(key). get_page returns a 480x800 1-bit PNG. get_candidates returns every source item the editor saw this hour with dedupe metadata. " +
+      "render_briefing ranks your own feeds (paid). Free: 25 calls per IP per day; then a Reader key in BRIEFING_KEY ($9/month) or x402 on the remote endpoint. Docs: " + BASE + "/llms.txt",
+  },
+);
+
+server.registerTool(
+  "list_briefings",
+  { description: "List the hourly briefings available (key and name), with prices.", inputSchema: {} },
+  async () => {
+    const res = await get("/v1/briefings");
+    const text = await res.text();
+    return res.ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text: paywallText(res, text) }], isError: true };
+  },
+);
+
+server.registerTool(
+  "get_briefing",
+  {
+    description: "One briefing as structured JSON: lead story, ranked stories and research items with summaries, why-it-matters and key points, plus when it was ranked.",
+    inputSchema: { key: z.string().describe("briefing key from list_briefings, e.g. 'ai'") },
+  },
+  async ({ key }) => {
+    const res = await get(`/v1/briefings/${encodeURIComponent(key)}`);
+    const text = await res.text();
+    return res.ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text: paywallText(res, text) }], isError: true };
+  },
+);
+
+server.registerTool(
+  "get_summary",
+  {
+    description: "Free, small: headlines and one-line summaries of a briefing (for widgets and quick reads).",
+    inputSchema: { key: z.string().describe("briefing key, e.g. 'world'") },
+  },
+  async ({ key }) => {
+    const res = await get(`/v1/briefings/${encodeURIComponent(key)}/summary`);
+    const text = await res.text();
+    return res.ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text: paywallText(res, text) }], isError: true };
+  },
+);
+
+server.registerTool(
+  "get_candidates",
+  {
+    description: "Free provenance dump: every candidate the editor saw this hour with canonical_link, published time, feed weight, the other outlets that ran the story (also_in), a selected flag, and collapsed duplicates (duplicate_of, dup_rule, dup_score).",
+    inputSchema: { key: z.string().describe("briefing key, e.g. 'ai'") },
+  },
+  async ({ key }) => {
+    const res = await get(`/v1/briefings/${encodeURIComponent(key)}/candidates`);
+    const text = await res.text();
+    return res.ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text: paywallText(res, text) }], isError: true };
+  },
+);
+
+server.registerTool(
+  "get_page",
+  {
+    description: "One rendered page of a briefing as a 480x800 1-bit PNG (page 0 is the front page; story pages follow). Made for e-ink and small displays. wide=true returns the 800x480 landscape front page.",
+    inputSchema: { key: z.string(), page: z.number().int().min(0).max(32).default(0), wide: z.boolean().default(false) },
+  },
+  async ({ key, page, wide }) => {
+    const q = wide && page === 0 ? "?size=wide" : "";
+    const res = await get(`/v1/briefings/${encodeURIComponent(key)}/pages/${page}.png${q}`, "image/png");
+    if (!res.ok) return { content: [{ type: "text", text: paywallText(res, await res.text()) }], isError: true };
+    const data = Buffer.from(await res.arrayBuffer()).toString("base64");
+    return { content: [{ type: "image", data, mimeType: "image/png" }] };
+  },
+);
+
+server.registerTool(
+  "render_briefing",
+  {
+    description: "Rank and render a briefing from your own feeds and persona (one editor run; needs a Reader key with render credits, or use x402 on the remote endpoint). Returns JSON and page URLs.",
+    inputSchema: { feeds: z.array(z.string().url()).min(1).max(30), persona: z.string().max(2000) },
+  },
+  async ({ feeds, persona }) => {
+    const res = await fetch(`${BASE}/v1/render`, { method: "POST", headers: headers({ "content-type": "application/json" }), body: JSON.stringify({ feeds, persona }) });
+    const text = await res.text();
+    return res.ok ? { content: [{ type: "text", text }] } : { content: [{ type: "text", text: paywallText(res, text) }], isError: true };
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "briefing-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Briefing Service: hourly LLM-ranked news briefings (AI, markets, sports, world) as JSON, rendered e-ink pages and a free provenance dump",
+  "type": "module",
+  "bin": { "briefing-mcp": "index.js" },
+  "files": ["index.js", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "keywords": ["mcp", "model-context-protocol", "news", "briefing", "e-ink", "x402"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/jshelley/briefing-mcp" },
+  "homepage": "https://briefing-service.wholemind.workers.dev",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  }
+}