Agent MCP guide

Bản thô: /guide.md — endpoint: https://news.xkd.vn/mcp

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