# 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 |