news-digest-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server (stdio transport) that aggregates news from Telegram channel previews and RSS/Atom feeds into structured JSON. It's designed to be launched by a host agent (e.g. osaurus) as bun src/server.ts on the host machine directly — no sandbox — so it has network access and a writable filesystem for state.

Commands

bun install               # install deps
bun run lint              # bunx biome lint
bun run format            # bunx biome format
bun run check             # bunx biome check (lint + format + organize imports)
bun run build             # bundle to dist/server.js (what CI publishes; not needed to develop)
bun src/server.ts         # run the MCP server directly (reads stdio)

There is no test suite. Biome is the only linter/formatter; a lefthook pre-commit hook runs bun run check --write on staged JS/TS/JSON/CSS files and re-stages fixes automatically.

To smoke-test the server manually, pipe JSON-RPC messages into it over stdio (see README.md for the exact initialize / tools/call sequence).

Architecture

Entry point: src/server.ts registers two MCP tools (get_news, list_sources) and delegates all logic to src/lib/run.ts. The server itself is just wiring — no business logic lives here. Both tools publish an outputSchema and return the payload as structuredContent and as serialized JSON in a text block (the spec's backwards-compatibility path for clients that read only content). list_sources wraps its list as { sources: [...] } because structuredContent must be a JSON object, not a bare array. Note that the content text block is not merely a fallback: osaurus, the host this was built for, reads only content and ignores structuredContent entirely, so that block is what a host's per-call output cap gets measured against — which is why get_news pages (below), and why its exact shape is configurable (src/lib/envelope.ts).