newsblog-composer-mcp

# NewsBlog Composer MCP

<!-- mcp-name: io.github.Mohammed-Jameal-J/newsblog-composer -->

**A research and audit tool for people who write.** It finds corroborated
stories, pulls out facts with their sources attached, mines keywords from that
reporting, hands the writer a brief, reviews the draft they wrote, and builds the
schema, banner prompt and publishing pack around it.

**It does not write the prose, on purpose.** A model writing the sentences is
exactly what an AI detector catches, and no amount of cliché-removal changes
that: detectors measure how predictable the wording is, not how many stock
phrases it contains. More to the point, the byline claims a person wrote it.

So the split is: the server does search, verification, extraction, keywords,
structure, schema and auditing. The person writes the sentences. `draft_brief`
gives them everything to start with; `review_draft` tells them where the draft is
weak without rewriting a word.

**It runs with zero API keys.** Every credential is an upgrade, not a
requirement. See [No keys? Start here](#no-keys-start-here).

---

## Install

```powershell
pip install newsblog-composer-mcp
```

That gives you the `newsblog-mcp` command. To hack on it instead, clone it.

Windows:

```powershell
git clone https://github.com/Mohammed-Jameal-J/newsblog-composer-mcp.git
cd newsblog-composer-mcp
py -m venv .venv
.venv\Scripts\activate
pip install -e .
copy .env.example .env      # optional: every value in it is optional too
```

macOS / Linux:

```bash
git clone https://github.com/Mohammed-Jameal-J/newsblog-composer-mcp.git
cd newsblog-composer-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env        # optional: every value in it is optional too
```

Check what it can do on your machine:

```powershell
python -m newsblog_mcp.diagnose "your test headline here"
```

That prints which providers are configured, which will be tried, and the result
of a live `verify_news` call. Run it before wiring the server into a client —
if search is blocked by a corporate proxy or VPN, this is where you find out.

Offline test suite (no network needed):

```powershell
python tests\smoke_test.py
```

## Connect it

**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "newsblog": {
      "command": "C:\\path\\to\\newsblog-composer-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "newsblog_mcp.server"]
    }
  }
}
```

On macOS the file is `~/Library/Application Support/Claude/claude_desktop_config.json`
and the command is `/path/to/newsblog-composer-mcp/.venv/bin/python`.

**Claude Code** — `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "newsblog": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-m", "newsblog_mcp.server"]
    }
  }
}
```

Any other MCP client: launch `python -m newsblog_mcp.server` over stdio.

### Where it keeps your files

Installed from PyPI, the server writes to your user data directory, so nothing is
lost when you upgrade:

| | |
|---|---|
| Windows | `%LOCALAPPDATA%\newsblog-composer-mcp` |
| macOS | `~/Library/Application Support/newsblog-composer-mcp` |
| Linux | `~/.local/share/newsblog-composer-mcp` |

That folder holds `profile.json` (the identity you set at first run), `output/`
(every generated post) and an optional `.env`. Set `NEWSBLOG_DATA_DIR` to put
them somewhere else. Run from a cloned checkout instead and everything stays in
the project folder, beside the code.

`python -m newsblog_mcp.diagnose` prints the exact paths for your install.

---

## Publishing and connecting

**Claude Desktop / Claude Code** run it over stdio, which is what the install
section above sets up.

**ChatGPT cannot spawn a local process**, so stdio will never reach it. Run the
same server over HTTP and deploy it behind HTTPS:

```powershell
newsblog-composer-mcp --http --host 0.0.0.0 --port 8000
```

Then in ChatGPT: Settings → Connectors → Advanced → Developer mode, then **Add
custom connector** pointing at `https://your-host/mcp`. Custom connectors need a
Pro, Team, Enterprise or Edu plan.

**Publishing to the MCP Registry** needs the package on PyPI first, then the
`mcp-publisher` CLI with `server.json` in this repo. Four things must line up or
the publish is rejected:

- `name` must match the authenticated GitHub account: `io.github.<username>/newsblog-composer`
- `description` must be 100 characters or fewer
- `packages[].version` must be a release that already exists on PyPI
- the README must carry `mcp-name: <that same name>` on its own line. The
  registry proves package ownership by reading the description PyPI serves for
  that exact version, so the marker has to be in the release you uploaded, not
  just in the repo. It is the HTML comment at the top of this file.

## How to test it

Three levels, cheapest first.

**1. Offline, no network — proves the logic.**

```powershell
python tests\smoke_test.py
```

159 checks covering schema parity, the SEO audit, AI-word detection, publisher
identity behind aggregator links, clustering, the publishing pack, the derived
image concept and the install paths. All should pass in about two seconds.

**2. Network — proves search reaches you.**

```powershell
python -m newsblog_mcp.diagnose "a headline you saw in the news today"
```

One line per provider with timings, then the verdict. What you want to see is
`independent_publishers` naming several real outlets and `reference_candidates`
holding real publisher URLs.

**3. A whole post, end to end.**

```powershell
python examples\build_today_example.py
```

Builds a complete package from a real story using facts already in the file, and
prints the keywords, schema validation, AI-word check, human score and SEO score
before writing the output folder. Use it as the reference for what a good run
looks like. `examples\build_mistral_example.py` does the same for the
hand-written reference post.

**4. In Claude Desktop**, after restarting it:

> Use find_stories to get today's AI stories, pick the best corroborated one, and
> build the full blog package. Run find_ai_words until it comes back clean, then
> give me the publishing pack and the paste file.

## Privacy

The server runs on your own machine. Nothing is sent to the author of this
package, and there is no telemetry of any kind.

What leaves your machine, and only while a tool is running:

- **The headline or topic you give it** goes to whichever news search provider is
  active. With no keys configured that is GDELT and the Bing and Google News RSS
  feeds. If you set a provider key, it goes to that provider instead.
- **Article URLs** are fetched directly from the publishers that host them, the
  same request your browser would make.
- **Your draft text** goes to an AI detector only if you set `GPTZERO_API_KEY` or
  `SAPLING_API_KEY`, and to an image generator only if you call `generate_image`.
  Without those keys, no text leaves your machine for either purpose.

What stays on your machine: the publishing identity you set at first run
(`profile.json`), every generated post (`output/`), and any keys you configure.
See [Where it keeps your files](#where-it-keeps-your-files) for the exact paths.
Nothing in that folder is uploaded anywhere.

Optional API keys are read from the environment or from the extension's settings
panel. They are used only to authenticate with the provider they belong to.

## The tools

| Tool | What it does | Needs a key? |
|---|---|---|
| `capabilities` | Reports which providers are live and which fallbacks are in use | no |
| `find_stories` | Turns a topic into today's actual stories, grouped and ranked by corroboration and freshness | no |
| `verify_news` | Searches news providers, keeps matching results, counts independent publishers | no (keyless RSS) |
| `fetch_article_facts` | Downloads sources, extracts facts, short attributed quotes and figures | never |
| `draft_brief` | Hands the writer the structure, sourced facts, keywords and FAQ candidates | never |
| `review_draft` | Reads the writer's draft and says where it is weak. Rewrites nothing | never |
| `humanize_text` | Optional rewrite pass. Prefer `review_draft` | optional |
| `find_ai_words` | Finds every stock AI phrase with the sentence it sits in | never |
| `score_ai_text` | 0–100 human-readability score | optional |
| `generate_image` | Concept banner, trademark filter applied first | no (watermarked) |
| `seo_keywords` | Mines keywords from the fetched sources; long-tail and FAQ queries from Google autocomplete | no |
| `seo_audit` | Scores the finished body against on-page rules, returns fixes | never |
| `build_publishing_pack` | Title, labels, permalink, alt text and a paste-ready Gemini image prompt | never |
| `build_schema` | Renders HTML body + both JSON-LD blocks, then validates them | never |
| `save_and_present` | Writes the package to `output/`, with canonical/OG/Twitter tags | never |

Resources: `newsblog://house-style` (structure and sourcing rules for the
drafting step) and `newsblog://humanizer-rules` (the rewrite rule set).

## The flow

There are two entry points, depending on what you type.

**A topic** — "today's AI news", "electric vehicles", "Indian fintech". There is
no claim to verify yet, so start by finding out what happened:

```
find_stories("AI", days=1)
  ↓  stories grouped by event, ranked by publisher count then freshness
     pick one from ready_to_write, check its age_hours
verify_news(story.headline)
  ↓  … and continue as below
```

**A specific headline** — start at `verify_news` directly. Note that an old
headline correctly returns old sources; `days` limits how far back to look.

```
verify_news(title)
  ↓  stop here if is_legit is false
fetch_article_facts(result.fetchable_urls)   # or story.fetchable_urls
  ↓
seo_keywords(title, [fact.text for fact in facts])
  ↓  primary + secondary keywords, slug, meta title/description,
     and FAQ questions taken from real autocomplete d