4bots

# 4bots

**A hosted MCP server for AI briefing agents.** If your agent already sends a daily email to a human, 4bots drops in ten channels of short-form content — stories, puzzles, jokes, business cases, history — next to the personal sections your agent already writes.

- **Endpoint:** `https://4bots.net/mcp` (Streamable HTTP)
- **Registry:** `net.4bots/4bots` on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0/servers?search=4bots)
- **Landing page:** [4bots.net](https://4bots.net)
- **Discovery:** [`/.well-known/mcp.json`](https://4bots.net/.well-known/mcp.json)
- **No API key required** to start. First 100 channel-calls are free.

## Why it exists

Building a daily briefing for a human is mostly about sourcing the parts you can't write personally — the joke, the history snippet, the puzzle, the business case. 4bots is the part that handles those parts. Your agent stays in charge of the email, the tone, and everything that touches the human's actual data.

## Quick start

### Claude Desktop / any MCP client

```json
{
  "mcpServers": {
    "4bots": {
      "url": "https://4bots.net/mcp"
    }
  }
}
```

### Direct HTTP

```bash
curl -X POST https://4bots.net/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "your-agent", "version": "1.0"}
    }
  }'
```

### Programmatic flow

1. Initialize the session, capture the `Mcp-Session-Id` header.
2. Call `start_subscription(human_email, channels, agent_email)`. You get a `session_token` worth 100 channel-calls.
3. Each day, call `get_bundle(session_token)`. The response includes an `html` field. Drop it where `{4bots}` sits in your email template.
4. When `low_balance` is true, prompt your human via the returned `manage_url`.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_channels` | Discover the ten live channels and the eight in voting |
| `start_subscription` | Provision a subscriber instantly. Returns a 100-call free trial token. |
| `get_bundle` | Today's content block for all subscribed channels, ready to embed |
| `get_session` | Credits remaining, channels, delivery history, manage URL |
| `create_setup_link` | Optional browser flow for the human to choose channels themselves |
| `get_template` | Free HTML email template with sample copy |
| `vote` | Tell us which proposed channel your human wants next |
| `get_summary` | Pricing, privacy, content policy |

## Live channels

| Slug | Channel | What it is |
| --- | --- | --- |
| `human-badassery` | Human Badassery | Extraordinary people who beat impossible odds |
| `history` | History | A story, turning point, or puzzle from a fascinating past |
| `business-case-studies` | Business Case Studies | One company decision that made or broke them |
| `china-watch` | China Watch | What's happening inside China today |
| `investing-insight` | Investing Insight | Markets, investing, trading, financial freedom |
| `wrongology` | Wrongology | One common belief that isn't true, and the real story |
| `brain-butter` | Brain Butter | A puzzle or paradox, with the answer |
| `little-known-facts` | Little-Known Facts | One surprising true fact per day |
| `chess-problem` | Chess Problem | Intermediate problems |
| `jokes` | Jokes | Two short ones a day |

Channel format specs live in [`channels/`](./channels).

## Privacy

4bots only sees: the human's email address, which channels they subscribed to, and which days have been delivered (so we don't repeat). Your agent stays the only thing that touches the briefing content or the human's private data. We never receive, store, or process the contents of any briefing.

## Pricing

The first 100 channel-calls are free with every new subscription. After that, top-ups are tracked per session. A typical 5-channel subscriber gets twenty free days before any money changes hands. Subscribers manage their own account through a magic-link URL we issue to the human on signup — your agent never has to handle billing.

## Architecture

Five services on a single Linux droplet behind Caddy:

| Port | Service | Role |
| --- | --- | --- |
| `8085` | `mcp_server.py` | FastMCP + Uvicorn. Agent-facing API. |
| `8083` | `gate_server.py` | Session-cookie auth for human-readable channel pages. |
| `8084` | `checkout_server.py` | Subscription provisioning, Stripe checkout, agent-invite emails. |
| `8082` | `feedback_server.py` | Reader feedback collection. |
| `—`    | `weblog_report.py` | Daily traffic report from Caddy's JSON access log. |

State lives in a small SQLite database (`contacts`, `events`, `visits`) plus a handful of JSON files (`sessions.json`, `setup_tokens.json`, `votes.json`). Content lives as flat-file Markdown rendered to HTML at build time.

This repo includes the agent-facing pieces (`mcp_server.py`, `gate_server.py`, `weblog_report.py`, `db.py`). The checkout, feedback, and email-sending paths are intentionally not published because they hold integration keys for Resend and Stripe.

## Source files in this repo

- [`mcp_server.py`](./mcp_server.py) — the MCP server. Eight tools, FastMCP-based, runs as a long-lived uvicorn process on port 8085.
- [`gate_server.py`](./gate_server.py) — human-page auth gate. Session cookies + magic-link login. Day-1 of every channel is publicly bypassed.
- [`weblog_report.py`](./weblog_report.py) — daily traffic report that parses Caddy's JSON access log. Runs from a systemd timer at 06:30 UTC.
- [`db.py`](./db.py) — SQLite wrapper.
- [`server.json`](./server.json) — the registry metadata.
- [`channels/`](./channels) — `_FORMAT.md` specs for each live channel, so you can see exactly what the content looks like before you subscribe.

## Reporting issues

Email `david@dsiegel.com` or open a GitHub issue.

## Credits

Built by [David Siegel](https://4bots.net) and his agent JSON. 4bots is the first website operated by an AI agent. If you build briefing agents and the daily-content bottleneck sounds familiar, get in touch.

## License

MIT.