# Hướng dẫn agent kết nối news-ingest MCP

> Bản live: `https://news.xkd.vn/guide.md` / `/guide.html` — endpoint: `https://news.xkd.vn/mcp`

`https://news.xkd.vn/mcp` — server MCP (Streamable HTTP, JSON-RPC 2.0) nhận bản tin
hằng ngày cho news.xkd.vn. Mỗi agent có **token riêng**; token nằm trong
`/opt/news-ingest/.env` trên VPS (dạng `TOKENS=wsl:...,win:...`).

## 1. Thông số

| Mục | Giá trị |
|---|---|
| Endpoint | `https://news.xkd.vn/mcp` (POST only; GET → 405) |
| Auth | header `Authorization: Bearer <TOKEN>` — **bắt buộc cho mọi `tools/*`** |
| HMAC (khuyến khích) | header `X-News-Signature: hex(HMAC_SHA256(token, raw_body UTF-8))` |
| Giới hạn | `text` ≤ 128 KB; không nhận future-date; 10 lần auth-sai/15 phút/IP → lock 15′ |
| Ghi chú môi trường | HTTP client trong sandbox kernel sinh `urllib` POST có thể gặp 405 giả — dùng **curl** hoặc MCP client thật |

Sai token/signature chỉ bị delay 250 ms + đếm fail — không làm rớt submit hợp lệ khác.

## 2. Tools

| Tool | Input | Ý nghĩa |
|---|---|---|
| `submit_item` | `kind`: `brief` \| `keo`; `text`: **một mục tin ngắn nguyên văn** | Push lên feed liên tục — tự timestamp giờ VN, dedup theo nội dung (`unchanged:true` nếu trùng), render ngay. **Đây là tool chính.** |
| `submit_daily` | như `submit_item` (date bị bỏ qua) | Alias deprecated cho tương thích cũ — hành vi = submit_item |
| `list_items` | `kind?`, `limit?` (default 20) | Đọc feed — mới nhất trước |
| `get_feedback` | — | Số item mỗi kind + mục gần nhất của agent |

Mô hình v3: **không còn khái niệm ngày** — mỗi submit = 1 mục độc lập; trang
`/brief/` `/deal/` là feed mới-nhất-trước (tstamp ghi giờ VN trong tên item);
`submit_item` trùng nội dung = no-op an toàn khi retry.

## 3. Handshake (JSON-RPC 2.0)

```
POST initialize  {protocolVersion:"2025-03-26", capabilities:{}, clientInfo:{...}}   → result + Mcp-Session-Id
POST notifications/initialized                                                        → 202
POST tools/list                                                                       → {tools:[...]}
POST tools/call    {name:"submit_item", arguments:{kind,text}}                            → {content:[{type:"text",text:JSON}]}
```

## 4. Ví dụ curl (đúng như seed phiên sống 18/11)

```bash
TOKEN="..."        # token agent của bạn
curl -sk -X POST https://news.xkd.vn/mcp \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-03-26","capabilities":{},
                 "clientInfo":{"name":"hermes-wsl","version":"1.0"}}}'

curl -sk -X POST https://news.xkd.vn/mcp \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# đăng file nguyên con
python3 - <<'EOF'
import json, subprocess, hmac, hashlib, os
tok = os.environ["NEWS_MCP_TOKEN"]
text = open("Brief.txt", encoding="utf-8").read()
body = json.dumps({"jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"submit_item","arguments":{"kind":"brief","text":text}}})
sig = hmac.new(tok.encode(), body.encode(), hashlib.sha256).hexdigest()
r = subprocess.run(["curl","-sk","-X","POST","https://news.xkd.vn/mcp",
  "-H","Authorization: Bearer "+tok, "-H","X-News-Signature: "+sig,
  "-H","Content-Type: application/json","-d",body], capture_output=True, text=True)
print(r.stdout)
EOF
```

## 5. Cấu hình Hermes (client MCP thường trực)

Thêm vào `config.yaml` của máy agent (giá trị `headers` được gửi mọi call):

```yaml
mcp_servers:
  news-write:
    url: https://news.xkd.vn/mcp
    headers:
      Authorization: "Bearer <TOKEN>"
```

Sau đó agent có sẵn tool `news-write.submit_daily` — ra lệnh kiểu *"đăng file
/workspace/Brief.txt lên news"* là đủ. Tên cú pháp có thể lệch giữa các phiên —
kiểm bằng `hermes` runtime (tool list sẽ hiện `news-write`).

## 6. Lỗi thường gặp

| Triệu chứng | Nguyên nhân / xử lý |
|---|---|
| `{"ok":false,"error":"unauthorized"}` | token sai/thiếu — token đúng máy mỗi agent, lấy từ VPS |
| `{"ok":false,"error":"bad signature"}` | HMAC tính sai: HMAC của **raw body** (đúng chuỗi gửi đi), không re-serialize |
| `429 temporarily locked` | IP đã vượt 10 lần auth-sai/15′ — chờ hết 15′ hoặc nhờ `systemctl restart news-ingest` |
| `unchanged:true` | Resubmit đúng nội dung đã có — không lỗi; chỉ render khi nội dung đổi |
| `kind/date sai` | kind phải `brief|keo`; date `YYYY-MM-DD`, không tương lai |
