cablegram-mcp 0.1.0__tar.gz

cablegram_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+
+# Publishes to PyPI when a version tag is pushed. No API token anywhere:
+# PyPI's trusted publishing verifies the workflow's identity directly, so
+# there is no secret to leak, rotate, or accidentally commit.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # this is what trusted publishing checks
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      # The same suite the tests workflow runs. A release that cannot pass it
+      # should not exist, and a tag is the last place to find that out.
+      - run: uv sync --locked
+      - run: uv run pytest -q
+
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

cablegram_mcp-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # 3.12 is the floor the project declares; 3.14 is what a fresh install
+        # gets. The identity of an archived item must not differ between them.
+        python-version: ["3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest -q

cablegram_mcp-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+*.db
+*.db-wal
+*.db-shm
+.coverage
+htmlcov/
+.claude/
+.vscode/
+.idea/
+.DS_Store

cablegram_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

cablegram_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Levon Gabrielyan
+
+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.

cablegram_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: cablegram-mcp
+Version: 0.1.0
+Summary: Raw dispatches from 19 tech, AI and Chinese/Russian sources. Date-filtered only, never ranked.
+Project-URL: Homepage, https://github.com/levongabrielyan/cablegram-mcp
+Project-URL: Repository, https://github.com/levongabrielyan/cablegram-mcp
+Author: Levon Gabrielyan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,mcp,model-context-protocol,news,rss,tech-signals
+Requires-Python: >=3.12
+Requires-Dist: mcp>=2.1.1
+Description-Content-Type: text/markdown
+
+# cablegram-mcp
+
+Raw dispatches from tech, AI and Chinese/Russian sources — filtered by date,
+never ranked.
+
+A *cablegram* was the unedited message that arrived over the submarine cables,
+before an editor turned it into a story. This server is the cable: it brings the
+dispatches. Your model is the editor.
+
+**The point is the cable, not the news.** A launch discussed in Chinese or
+Russian today reaches English-language coverage days later, filtered through
+whoever decided it was worth translating — and often it never arrives at all.
+Nineteen sources in three languages, read directly, put a reader in California
+in the same week as a reader in Shanghai or Moscow.
+
+Headlines are never translated. Each dispatch carries its language, and the
+model reading it has more context for that than any translation step would.
+It also means the same story is kept in every language that carried it: OpenAI
+titles a post *"Pacing model development in an era of cyber-critical
+capabilities"* while a Russian channel titles the same URL *"OpenAI stopped RL
+for two weeks on its latest models"*. Both are stored against the same id, and
+either can be searched.
+
+A full day of all nineteen costs a few thousand tokens. Six hours of them,
+grouped by source with the cuts declared, is around 700.
+
+```
+CABLEGRAM v0.1 | 2026-08-30T09:09Z..2026-08-30T14:09Z | 11 items | 19/19 sources
+CUT   habr=2/4  hn=2/159  kr36=2/3   (newest kept)
+COLS  id hh:mm title    times UTC | body: wire_read(ids=[...])
+---
+
+## cls zh early,finance 1/1
+-- 08-30
+e60e27faa7fc 10:04 AI数据中心扩张“限制性因素”浮现 马斯克：SpaceX正铸造燃气轮机叶片
+
+## data_secrets ru telegram 1/1
+-- 08-30
+a50d137e3147 10:49 Агенты OpenAI одну за одной автономно создали три цивилизации
+
+## hn en community,searchable 2/159
+-- 08-30
+2929f114895f 14:06 METR and Redwood Offer Postmortem of the HuggingFace Hack (thezvi.wordpress.com)
+7901d3fb4e1c 14:04 Google removed the URLs. Only for the people who resell them (scraping.club)
+```
+
+*Five hours of nineteen sources, verbatim. `CUT` says what was left out and how
+much there was; `19/19` is how many answered.*
+
+
+## Status
+
+v0.1 — the nineteen sources work; the tool API may still move. All nineteen sources have an adapter and were verified
+against the live endpoints: eleven RSS feeds, Hacker News through its search
+index, a signed Chinese financial API, and six public Telegram channels.
+
+Two of them are worth knowing about before you rely on them:
+
+* **cls.cn is reverse-engineered.** An undocumented internal API with a signed
+  request. It holds 3.34 days at most and cannot page backwards, so a gap in
+  polling is permanent. `wire_sources` marks it `fragile`.
+* **Telegram is HTML with no contract.** The public preview view can change
+  without a version number to notice it by.
+
+Both are declared in the output rather than explained afterwards.
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+git clone https://github.com/levongabrielyan/cablegram-mcp
+cd cablegram-mcp
+uv sync
+```
+
+Register it with an MCP client — for Claude Code:
+
+```bash
+claude mcp add cablegram --scope user -- \
+  /path/to/cablegram-mcp/.venv/bin/python -m cablegram.cli serve
+```
+
+Then fill the archive, and keep filling it:
+
+```bash
+cablegram poll          # once, now
+cablegram sources       # what it knows about
+```
+
+Feeds expose a window of days, so put `cablegram poll` on a timer — an hour
+nobody polls is an hour no endpoint will serve again. A systemd user unit is in
+[`deploy/`](deploy/).
+
+## The four tools
+
+| Tool | Question |
+| --- | --- |
+| `wire_latest` | What did the sources publish in the last N hours? |
+| `wire_read` | Give me the stored text of these ids |
+| `wire_search` | When did this term start appearing? |
+| `wire_sources` | What exists, and what is currently broken? |
+
+All four are read-only and return plain text. The same information as JSON with
+indent costs roughly six times the tokens and truncates.
+
+## The local archive
+
+RSS feeds expose only their last few dozen entries; last week is unrecoverable.
+So everything fetched is stored in a SQLite file under your platform's data
+directory (`~/.local/share/cablegram/archive.db` on Linux; override with
+`CABLEGRAM_DB`).
+
+It is created on first run and grows by a few megabytes a year. Nothing is
+uploaded anywhere, and no seed database ships with this repository — the server
+fetches on your behalf and does not redistribute anyone's content.
+
+**`wire_search` only reads what this archive holds, which starts the day you
+first ran it.** Zero hits means "not in what we can search", never "nobody is
+talking about it", and the output says so on every reply.
+
+## Design
+
+[`docs/design.md`](docs/design.md) covers why the identity of an item is a pure
+function of its URL, why a failure is a value rather than an exception, why the
+full-text index needs a trigram tokenizer for Chinese to work at all, and what
+this server deliberately does not do.
+
+## Notes
+
+Only public endpoints are used: no credentials, no authentication bypass,
+no scraping behind a login. Conditional requests (`ETag`, `If-Modified-Since`)
+mean an unchanged feed is not re-downloaded. Intended for personal research —
+respect each source's terms of service.
+
+## Licence
+
+MIT. Built by [Levon Gabrielyan](https://github.com/levongabrielyan).

cablegram_mcp-0.1.0/README.md

@@ -0,0 +1,138 @@
+# cablegram-mcp
+
+Raw dispatches from tech, AI and Chinese/Russian sources — filtered by date,
+never ranked.
+
+A *cablegram* was the unedited message that arrived over the submarine cables,
+before an editor turned it into a story. This server is the cable: it brings the
+dispatches. Your model is the editor.
+
+**The point is the cable, not the news.** A launch discussed in Chinese or
+Russian today reaches English-language coverage days later, filtered through
+whoever decided it was worth translating — and often it never arrives at all.
+Nineteen sources in three languages, read directly, put a reader in California
+in the same week as a reader in Shanghai or Moscow.
+
+Headlines are never translated. Each dispatch carries its language, and the
+model reading it has more context for that than any translation step would.
+It also means the same story is kept in every language that carried it: OpenAI
+titles a post *"Pacing model development in an era of cyber-critical
+capabilities"* while a Russian channel titles the same URL *"OpenAI stopped RL
+for two weeks on its latest models"*. Both are stored against the same id, and
+either can be searched.
+
+A full day of all nineteen costs a few thousand tokens. Six hours of them,
+grouped by source with the cuts declared, is around 700.
+
+```
+CABLEGRAM v0.1 | 2026-08-30T09:09Z..2026-08-30T14:09Z | 11 items | 19/19 sources
+CUT   habr=2/4  hn=2/159  kr36=2/3   (newest kept)
+COLS  id hh:mm title    times UTC | body: wire_read(ids=[...])
+---
+
+## cls zh early,finance 1/1
+-- 08-30
+e60e27faa7fc 10:04 AI数据中心扩张“限制性因素”浮现 马斯克：SpaceX正铸造燃气轮机叶片
+
+## data_secrets ru telegram 1/1
+-- 08-30
+a50d137e3147 10:49 Агенты OpenAI одну за одной автономно создали три цивилизации
+
+## hn en community,searchable 2/159
+-- 08-30
+2929f114895f 14:06 METR and Redwood Offer Postmortem of the HuggingFace Hack (thezvi.wordpress.com)
+7901d3fb4e1c 14:04 Google removed the URLs. Only for the people who resell them (scraping.club)
+```
+
+*Five hours of nineteen sources, verbatim. `CUT` says what was left out and how
+much there was; `19/19` is how many answered.*
+
+
+## Status
+
+v0.1 — the nineteen sources work; the tool API may still move. All nineteen sources have an adapter and were verified
+against the live endpoints: eleven RSS feeds, Hacker News through its search
+index, a signed Chinese financial API, and six public Telegram channels.
+
+Two of them are worth knowing about before you rely on them:
+
+* **cls.cn is reverse-engineered.** An undocumented internal API with a signed
+  request. It holds 3.34 days at most and cannot page backwards, so a gap in
+  polling is permanent. `wire_sources` marks it `fragile`.
+* **Telegram is HTML with no contract.** The public preview view can change
+  without a version number to notice it by.
+
+Both are declared in the output rather than explained afterwards.
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+git clone https://github.com/levongabrielyan/cablegram-mcp
+cd cablegram-mcp
+uv sync
+```
+
+Register it with an MCP client — for Claude Code:
+
+```bash
+claude mcp add cablegram --scope user -- \
+  /path/to/cablegram-mcp/.venv/bin/python -m cablegram.cli serve
+```
+
+Then fill the archive, and keep filling it:
+
+```bash
+cablegram poll          # once, now
+cablegram sources       # what it knows about
+```
+
+Feeds expose a window of days, so put `cablegram poll` on a timer — an hour
+nobody polls is an hour no endpoint will serve again. A systemd user unit is in
+[`deploy/`](deploy/).
+
+## The four tools
+
+| Tool | Question |
+| --- | --- |
+| `wire_latest` | What did the sources publish in the last N hours? |
+| `wire_read` | Give me the stored text of these ids |
+| `wire_search` | When did this term start appearing? |
+| `wire_sources` | What exists, and what is currently broken? |
+
+All four are read-only and return plain text. The same information as JSON with
+indent costs roughly six times the tokens and truncates.
+
+## The local archive
+
+RSS feeds expose only their last few dozen entries; last week is unrecoverable.
+So everything fetched is stored in a SQLite file under your platform's data
+directory (`~/.local/share/cablegram/archive.db` on Linux; override with
+`CABLEGRAM_DB`).
+
+It is created on first run and grows by a few megabytes a year. Nothing is
+uploaded anywhere, and no seed database ships with this repository — the server
+fetches on your behalf and does not redistribute anyone's content.
+
+**`wire_search` only reads what this archive holds, which starts the day you
+first ran it.** Zero hits means "not in what we can search", never "nobody is
+talking about it", and the output says so on every reply.
+
+## Design
+
+[`docs/design.md`](docs/design.md) covers why the identity of an item is a pure
+function of its URL, why a failure is a value rather than an exception, why the
+full-text index needs a trigram tokenizer for Chinese to work at all, and what
+this server deliberately does not do.
+
+## Notes
+
+Only public endpoints are used: no credentials, no authentication bypass,
+no scraping behind a login. Conditional requests (`ETag`, `If-Modified-Since`)
+mean an unchanged feed is not re-downloaded. Intended for personal research —
+respect each source's terms of service.
+
+## Licence
+
+MIT. Built by [Levon Gabrielyan](https://github.com/levongabrielyan).

cablegram_mcp-0.1.0/deploy/README.md

@@ -0,0 +1,18 @@
+# Running the poller on a timer
+
+The archive is only worth what has been put in it, and feeds expose a window of
+days: an hour nobody polls is an hour no endpoint will serve again. So the
+poller belongs on a timer, independently of whether an MCP client is running.
+
+Copy both files into `~/.config/systemd/user/`, adjust the path in the service,
+and:
+
+    systemctl --user daemon-reload
+    systemctl --user enable --now cablegram-poll.timer
+    systemctl --user list-timers cablegram-poll.timer
+
+`cablegram poll` exits non-zero when every source failed, so a failure is
+visible to `systemctl --user status` rather than silent.
+
+Any scheduler works — this is just the one with no daemon to install. Hourly is
+comfortable for the RSS sources.

cablegram_mcp-0.1.0/deploy/cablegram-poll.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=cablegram: fetch every source once and archive it
+
+[Service]
+Type=oneshot
+# Adjust to where you cloned it. `uv run` is used rather than a bare
+# `cablegram` because the documented install (git clone + uv sync) leaves the
+# entry point inside the project's own .venv and never on PATH — copying a
+# %h/.local/bin path here earns a status=203/EXEC on the first run.
+WorkingDirectory=%h/cablegram-mcp
+ExecStart=/usr/bin/env uv run cablegram poll

cablegram_mcp-0.1.0/deploy/cablegram-poll.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Poll the cablegram sources hourly
+
+[Timer]
+OnCalendar=hourly
+Persistent=true
+RandomizedDelaySec=300
+
+[Install]
+WantedBy=timers.target

cablegram_mcp-0.1.0/docs/design.md

@@ -0,0 +1,134 @@
+# Design notes
+
+Why this server is shaped the way it is. The code says what it does; this says
+what it refused to do, and what went wrong on the way.
+
+## The one assumption everything follows from
+
+**A model reads this output. A person does not.**
+
+That single fact decides most of what follows. A human operator notices when a
+tool returns an empty list on a busy day, or when a summary reads oddly. Nobody
+is watching here, so a wrong answer that looks well-formed is never caught. The
+design is therefore biased, everywhere, towards making a failure *visible in the
+payload itself* rather than towards making the payload tidy.
+
+Concretely, the output states:
+
+| Marking | Without it |
+| --- | --- |
+| `DOWN cls=HTTP403` | An absent source cannot be known to exist; its silence reads as "nothing happened there" |
+| `CUT hn=25/57` | An undeclared cut is indistinguishable from a source with little to say |
+| `~a3f9c2e1` | A capture time presented as a publication time files the item under the wrong day |
+| `PENDING` | A source with no adapter reported as broken buries the one that is actually broken |
+| `body=description 240c` | Reporting *how much* of an article arrived, without guessing whether it is all of it |
+| `"0 hits" does NOT mean nobody is talking about it` | The single most likely false conclusion this server can cause |
+
+## Date-filtered, never ranked
+
+The server brings dispatches; the model is the editor. Ranking would mean
+deciding what matters, with far less context than the model has — and a ranked
+list cannot be un-ranked by the reader, while an unranked one can be sorted.
+
+Depth is a different matter: `detail="headlines"` trims how much of each item is
+returned, uniformly and on request. Trimming depth is not selecting.
+
+## Identity
+
+`id = sha1(normalise(url))[:12]`, a pure function of the URL: no clock, no
+network, no state. Two calls hours apart agree without the server remembering
+anything.
+
+Normalisation errs, everywhere, towards keeping URLs apart:
+
+* **Merging two articles is permanent.** `url_norm` is UNIQUE, so the second one
+  never enters the archive and nothing reports it.
+* **Splitting one article is a duplicate** — recoverable, though not harmless:
+  each split quietly lowers the cross-source count.
+
+Both are bad; only one cannot be undone. Hence a *denylist* of tracking
+parameters rather than an allowlist: an allowlist drops any key it has not heard
+of, so `?sid=1` and `?sid=2` became the same id and the second article was
+rejected in silence.
+
+Twelve hex digits, not eight. At eight, a 50% chance of collision arrives at
+77,000 items — about five months of these feeds — and the id is a PRIMARY KEY,
+so a collision is a real article silently refused.
+
+The archive records the recipe that produced its ids and refuses to open if it
+changed. Otherwise every stored id would stop matching, every item would be
+inserted again, and the archive would double while reporting nothing wrong.
+
+## The archive is the point
+
+Feeds expose a window of days and no history of their own. Everything else here
+can be rewritten in an afternoon; this file is the only part whose value depends
+on when it was started. It lives outside the project directory, under the
+platform's data directory and never under a cache directory — caches are
+declared deletable and cleaners act on that.
+
+`sighting` is a separate table because `item` can only name whichever source got
+there first. Without it the cross-source count reads 1 for everything, which
+looks like a story nobody else picked up rather than a missing feature. Each
+sighting keeps the headline that source used: one outlet writes 智谱 where
+another writes Zhipu for the same link, and that pairing is the only bridge
+between a Chinese story and an English query.
+
+Full-text search uses `tokenize='trigram'`. With SQLite's default tokenizer
+every Chinese query returns zero hits, silently — Chinese has no spaces, so a
+whole headline becomes one token. Terms shorter than three characters cannot use
+a trigram index at all, and the common Chinese company names are exactly two, so
+those fall back to a substring scan. The output says which engine answered,
+because their recall differs.
+
+## Failure handling
+
+* **A failure is a value, not an exception.** One source failing must not cost
+  the other eighteen, and the caller receives one result per source in the order
+  given — a source never disappears from the list because it failed.
+* **The deadline cancels only what is still in flight.** Cancelling the batch
+  turned one slow feed into eleven dead ones, which nothing downstream could
+  tell apart from a real outage.
+* **A 304 is a success.** The source answered and had nothing new. Counting it
+  as a failure turns a quiet week into a fake outage; it also must not overwrite
+  the last real result with a zero.
+* **A failed poll never touches `last_ok` or the stored validators.** `last_ok`
+  is how anyone notices a source has been mute for days, and wiping an ETag
+  re-downloads the whole feed for good, with no error to show for it.
+* **One entry, one transaction.** A single unparseable entry used to roll back
+  everything already written for that source.
+* **A feed that parses to zero entries has its own state.** That is what a feed
+  looks like the day it changes format, and as a plain success it is
+  indistinguishable from a source with no news.
+
+## Third-party input is hostile
+
+Feeds are fetched from servers nobody here controls.
+
+Entity expansion is bounded by measurement, not by inspecting declarations.
+Three earlier guards each looked for the *shape* of the last attack — nested
+declarations, a padded prologue, a comment hiding the DOCTYPE — and each left
+the property open; a flat bomb (one entity, no nesting, referenced seven hundred
+times) walked through all three. Fields are capped as a second line of defence,
+the one that reaches the database and the index.
+
+Responses are capped on bytes received rather than on `Content-Length`, which
+can lie.
+
+## Zero dependencies beyond the MCP SDK
+
+Nineteen fixed sources and eleven RSS feeds do not justify a parser dependency:
+a dependency earns its place when it encapsulates knowledge that shifts or that
+fails silently. The SDK ships an HTTP client, and the standard library parses
+XML and RFC-822 dates.
+
+## What this server does not do
+
+* It does not translate. Each dispatch carries its language, and the model
+  reading it has more context for that than any translation step would.
+* It does not rank, score or deduplicate across sources beyond counting.
+* It does not search the web. `wire_search` reads only what this archive holds,
+  which starts the day the server was first run.
+* It does not fetch article bodies. What a feed ships is what is stored.
+* Sources are fixed, not configurable. A configurable aggregator is a different
+  product; this one is tuned for one question.

cablegram_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "cablegram-mcp"
+version = "0.1.0"
+description = "Raw dispatches from 19 tech, AI and Chinese/Russian sources. Date-filtered only, never ranked."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Levon Gabrielyan" }]
+keywords = ["mcp", "model-context-protocol", "rss", "news", "ai", "tech-signals"]
+
+dependencies = [
+    "mcp>=2.1.1",
+]
+
+[project.scripts]
+cablegram = "cablegram.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/levongabrielyan/cablegram-mcp"
+Repository = "https://github.com/levongabrielyan/cablegram-mcp"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cablegram"]