mcp-server/README.md

# betternews-mcp

MCP server for the [BetterNews](https://betternews.app) API. Works with Claude, Codex, OpenClaw, and any other MCP-compatible client.

## Install with an AI agent

Tell your agent:

> Install the BetterNews MCP server from `https://gitea.reversed.dev/betternews/mcp-server`. Clone it, run `pnpm install && pnpm build`, then add it to your MCP config pointing at `dist/index.js` with a `BETTERNEWS_API_KEY` env var. Get an API key from Settings → API Keys on betternews.app and choose only the scopes you need.

---

## Setup

### 1. Get an API key

Create one at **Settings → API Keys** on [betternews.app](https://betternews.app).

Choose only the scopes you need. Available scopes:

| Scope | Access |
|---|---|
| `news:read` | List and search news |
| `news:write` | Create, edit, react, bookmark |
| `news:comment` | Post and delete comments |
| `news:moderate` | Review items and source submissions |
| `sources:read` | List sources |
| `sources:write` | Create/edit sources (Mod/Admin) |
| `bookmarks:write` | Manage bookmarks |
| `tickets:read` | View own tickets |
| `tickets:write` | Open tickets and reply |
| `tickets:moderate` | Manage all tickets (Mod/Admin) |
| `mod:queue` | Access mod queue and tickets |
| `mod:stats` | View moderation statistics |
| `mod:users` | Manage users (Admin) |
| `user:profile` | Read own profile and news |
| `user:apikeys` | List own API keys |
| `privacy:read` | Export personal data |

### 2. Install and build

```sh
pnpm install
pnpm build
```

### 3. Configure your MCP client

#### Claude Desktop / Claude Code

Add to your `claude_desktop_config.json` (or project `.mcp.json`):

```json
{
  "mcpServers": {
    "betternews": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "BETTERNEWS_API_KEY": "bn_sk_your_key_here"
      }
    }
  }
}
```

#### Codex CLI

```sh
BETTERNEWS_API_KEY=bn_sk_your_key_here codex --mcp "node /path/to/mcp-server/dist/index.js"
```

#### OpenClaw

Add as a stdio MCP tool with `command: node dist/index.js` and the `BETTERNEWS_API_KEY` env var.

## Tools

### News

| Tool | Description | Required scope |
|---|---|---|
| `get_top_news` | Top 5 news by weighted score | — |
| `list_news` | Paginated news list with filters | `news:read` |
| `get_news_item` | Single news item by ID | `news:read` |
| `search_news` | Semantic vector search | `news:read` |
| `get_similar_news` | Vector-similar articles | `news:read` |
| `create_news_item` | Create a draft | `news:write` |
| `update_news_item` | Edit an item | `news:write` |
| `submit_news_item` | Submit draft for review | `news:write` |
| `review_news_item` | Approve / reject / revise | `news:moderate` |
| `like_news_item` | Toggle like | `news:write` |
| `dislike_news_item` | Toggle dislike | `news:write` |
| `bookmark_news_item` | Toggle bookmark | `bookmarks:write` |
| `delete_news_item` | Delete an item | `news:write` |
| `get_news_item_stats` | Engagement stats | Mod/Admin |

### Comments

| Tool | Description | Required scope |
|---|---|---|
| `list_comments` | Comments on a news item | `news:read` |
| `create_comment` | Post a comment | `news:comment` |
| `delete_comment` | Delete a comment | `news:comment` |

### Sources

| Tool | Description | Required scope |
|---|---|---|
| `list_sources` | Paginated source list | `sources:read` |
| `get_source` | Single source by ID | `sources:read` |
| `create_source` | Create a source | `sources:write` |
| `update_source` | Edit a source | `sources:write` |
| `list_source_submissions` | Source suggestions on an item | `news:read` |
| `submit_source` | Suggest a source | `news:write` |
| `review_source_submission` | Approve / reject suggestion | `news:moderate` |

### User

| Tool | Description | Required scope |
|---|---|---|
| `get_current_user` | Own profile and account details | `user:profile` |
| `get_user_profile` | Public profile by username | — |
| `list_my_news` | Own news items | `user:profile` |
| `list_my_source_submissions` | Own source submissions | `user:profile` |
| `list_bookmarks` | Bookmarked news items | `bookmarks:write` |
| `update_profile` | Update display name / email / bio | `user:profile` |

### Moderation

| Tool | Description | Required scope |
|---|---|---|
| `get_mod_queue` | Pending review queue | `mod:queue` |
| `get_mod_stats` | Aggregate statistics | `mod:stats` |
| `list_mod_users` | All users (Admin) | `mod:users` |
| `get_mod_user` | User detail (Admin) | `mod:users` |
| `change_user_role` | Change role (Admin) | `mod:users` |
| `ban_user` | Ban a user (Admin) | `mod:users` |
| `unban_user` | Lift a ban (Admin) | `mod:users` |
| `list_all_tickets` | All tickets (Mod view) | `mod:queue` |

### Tickets

| Tool | Description | Required scope |
|---|---|---|
| `list_my_tickets` | Own support tickets | `tickets:read` |
| `get_ticket` | Ticket with reply history | `tickets:read` |
| `create_ticket` | Open a ticket | `tickets:write` |
| `reply_to_ticket` | Reply to a ticket | `tickets:write` |
| `update_ticket_status` | Change ticket status (Mod) | `tickets:moderate` |

### Legal

| Tool | Description |
|---|---|
| `get_terms_of_service` | Current published ToS |
| `get_privacy_policy` | Current published Privacy Policy |
| `list_legal_documents` | List all docs (Mod/Admin see drafts) |
| `accept_legal_documents` | Accept current legal docs |

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `BETTERNEWS_API_KEY` | Yes | API key with prefix `bn_sk_` |