numenews

MCP server and one-shot CLI that reads the news numerologically.

numenews fetches news from several public APIs, extracts numbers, dates and names, computes numerology (digit reduction, master numbers 11/22/33, gematria), finds patterns with hybrid vector search in Qdrant, and builds a daily forecast — while keeping every number activation as long-term memory.

It is a pet project that takes its subject seriously and itself not very: the numerology layer is pure, deterministic and property-tested, the retrieval is a real hybrid search over a real vector store, and the default demo path needs no API keys at all. v0.1.0 is out and both interfaces work.

What it does

• Nine MCP tools over stdio, so Claude Desktop, Cursor or any MCP host can fetch news, extract numbers, find patterns, build a forecast and query the memory.

• Six one-shot commands — today, forecast, history, search, patterns, mcp — each printing one JSON document on stdout and nothing else, so they pipe straight into jq.

• Five news sources (GDELT, NewsAPI, GNews, Mediastack, Currents) behind one NewsSource Protocol, with an aggregator that degrades gracefully when a feed is down or rate-limited, and an RFC 9111 cache so a repeated run does not re-hit the network.

• Local embeddings only — two bge models through fastembed. No embedding API, ever.

• Six Qdrant collections with semantic and hybrid (reciprocal-rank-fusion) search, and payload indexes that make filtered queries cheap.

• Four pydantic-ai agents — extract numbers, find patterns, build the forecast, summarise old news — every one returning a validated Pydantic model rather than free-form JSON.

• A pipeline that composes them: ingest → analyze → forecast, with a sliding window over the last week and a digest for everything older.

• Long-term memory: every number activation is logged, folded into a per-day frequency, and fed back into the forecast over a thirty-day window.

• A ragas evaluation of the retrieval path, isolated in its own environment so LangChain never reaches the runtime.

Related MCP server: Google News MCP Agent

Quick start

uv sync --all-extras        # install the environment (Python 3.14+, uv)
make dev                    # start Qdrant (Docker Compose) and wait until healthy
cp .env.example .env        # optional: the default demo path needs no API keys
make lint && make test      # ruff + mypy --strict, pytest with coverage

Qdrant's dashboard is then at http://localhost:6333/dashboard.

Over the CLI

today needs Qdrant and an LLM endpoint; history, search and patterns need Qdrant only. The full command surface is in docs/USER_FLOW.md.

uv run numenews today | jq .dominant_number   # ingest the window and read the day
uv run numenews forecast --date tomorrow      # a stored/derived reading, no fetch
uv run numenews history --number 11 --days 30 # when 11 was active
uv run numenews search -q "число 7 и деньги"  # hybrid search over stored news
uv run numenews patterns --min-strength 0.7   # the strong patterns, strongest first
uv run numenews --help

Over MCP

The server starts without Qdrant or an API key and builds each dependency on the first tool call that needs it, so it can be attached to a host right away. Cursor's project config ships in .cursor/mcp.json; Claude Desktop takes the same command in its own claude_desktop_config.json. The nine tools, their examples and the failure semantics are in docs/MCP_TOOLS.md.

make mcp                                            # serve stdio (Ctrl-D to stop)
uv run pytest tests/integration/test_mcp_stdio.py   # the same handshake, as a test

What the output looks like

The pipeline builds this, the CLI serializes it, and stdout is always JSON:

{
  "date": "2026-09-21",
  "dominant_number": 11,
  "master_active": true,
  "patterns": [
    {
      "id": "8bb3a3e4-53cd-5333-92ab-5309c63d3b78",
      "type": "resonance",
      "numbers": [11, 22],
      "news_ids": ["b371bc46-7b4b-5b38-92db-cdf94a550f33"],
      "strength": 0.87,
      "interpretation": "Числа 11 и 22 резонируют в новостях о технологиях",
      "discovered_at": "2026-09-21T12:00:00Z"
    }
  ],
  "forecast": "День благоприятен для начинаний, связанных с коммуникацией",
  "advice": "Избегайте конфликтов — число 11 усиливает эмоции",
  "warnings": ["Возможны повторяющиеся события из прошлого"]
}

How OpenSpec is used here

Specs are the source of truth for behaviour, and they live in the repository next to the code.

• openspec/specs/ holds what the project ships today, one capability per directory. Two exist so far: mcp-surface (the nine tools — inputs, return shapes, error reporting) and cli-surface (the six commands — JSON-only stdout, the --date grammar, exit codes, idempotency). The internals are not specified yet; they get a capability the first time a change really touches them.

• openspec/changes/ holds work in flight: a proposal, the spec deltas it would make, a design when the approach needs deciding, and a task list.

• The loop is propose → review → implement → archive. openspec list shows what is active, openspec validate "<name>" --strict checks a change, and archiving merges its spec deltas into openspec/specs/.

• New work starts as a change, not as an edit. An idea that is not a change yet lives in a GitHub issue.

docs/MCP_TOOLS.md and docs/USER_FLOW.md remain the narrative companions to the two specs: the specs say what the behaviour must be, those documents show how to use it.

Project layout

src/numenews/
├── config.py       # pydantic-settings
├── logging.py      # structlog + contextvars correlation
├── models/         # Pydantic v2 domain models
├── numerology/     # pure logic: reduction, master numbers, gematria (no I/O)
├── news/           # GDELT, NewsAPI, GNews, Mediastack, Currents behind one Protocol
├── embeddings/     # fastembed wrapper
├── vector/         # Qdrant client, collections, hybrid search
├── agents/         # pydantic-ai: extract, pattern, forecast, summarize
├── pipeline/       # the RAG chain, the sliding window, step timings
├── mcp/            # MCP server and 9 tools
└── cli/            # one-shot Typer commands

openspec/
├── specs/          # behaviour that ships, one capability per directory
└── changes/        # proposals in flight

Commands

make help          # list every target
make install       # uv sync --all-extras
make lint          # ruff check + format check + mypy
make test          # unit + integration (with coverage)
make test-eval     # ragas evaluation in .venv-eval (needs an LLM endpoint; see docs/EVAL.md)
make eval-env      # build .venv-eval (ragas; ADR 0013)
make dev           # docker compose up -d --wait
make dev-down      # stop Qdrant, keep the volume
make clean         # stop Qdrant, delete volumes and caches
make run           # sample one-shot CLI run (needs Qdrant and an LLM endpoint)
make mcp           # start the MCP server (stdio)

make test runs the unit and integration suites with coverage and then checks the per-layer floors (numerology ≥ 95 %, pipeline/agents ≥ 80 %, vector/news ≥ 70 %); the levels, the doubles and the dated coverage snapshot are in docs/TESTING.md.

Documentation

• docs/ARCHITECTURE.md — the layers, the data flow and the runtime topology

• docs/STACK.md — every tool, why it was chosen and what it costs

• docs/TESTING.md — the test levels, the doubles and the coverage floors

• docs/coverage_report.md — the dated coverage snapshot and the floors

• docs/TOOL_USE.md — which MCP tool answers which question

• docs/GLOSSARY.md — MCP, RAG, gematria, master number and the rest

• docs/FAQ.md — "why numerology?", "do I need API keys?", "how do I connect Cursor?"

• docs/NUMEROLOGY.md — terminology and rules

• docs/NEWS_SOURCES.md — the five news APIs, their limits and the cache

• docs/QDRANT_COLLECTIONS.md — the six collections, payloads and indexes

• docs/EMBEDDINGS.md — the local models, the cache and why two of them

• docs/PROMPTS.md — every agent prompt, verbatim, with its rationale

• docs/RAG_PIPELINE.md — the chain, its degradation rules and its tests

• docs/CONTEXT_MANAGEMENT.md — the window, the history and the digest

• docs/MCP_TOOLS.md — the nine MCP tools, their examples and the client configs

• docs/USER_FLOW.md — the one-shot CLI, its commands and their JSON

• docs/EVAL.md — the ragas evaluation: how to run it and how to read the report

• docs/eval_report.md — the latest committed eval run

• docs/adr/ — architecture decision records

• docs/agentic/ — how AI coding agents work here, and their guardrails

• AGENTS.md — the rules for AI coding agents in this repository

Contributing

It is a solo pet project, so there is no ceremony — but there is a workflow, and CONTRIBUTING.md spells it out. The short version: work starts as an OpenSpec change rather than a direct edit, one tasks.md item is one atomic task, and make lint && make test has to be green. Issues and ideas are welcome; there is no CI, on purpose, which is why the commands are the gate.

License

MIT