# mdshare-mcp

MCP server cho phép AI chat (Claude, và các client hỗ trợ MCP) gọi trực tiếp 1 tool
`publish_markdown` để đăng nội dung markdown lên dịch vụ `mdshare` đã deploy trước đó —
không cần tải file về máy rồi tự `curl` lên.

## Kiến trúc

```
Claude.ai (chat) → tool "publish_markdown" → mdshare-mcp (server này) → POST → mdshare → trả URL
```

Đây là MCP server dạng **Remote (Streamable HTTP)**, chạy độc lập trên Render — khác với
MCP server "local (stdio)" chỉ chạy được khi cài trên máy cá nhân. Vì bạn dùng Claude qua
web, bản Remote HTTP là lựa chọn đúng: không cần cài gì trên máy.

## 2 tool được cung cấp

- **`publish_markdown(content)`** — đăng nội dung markdown lên `mdshare`, trả về URL xem và URL raw.
- **`fetch_markdown(key_or_url)`** — tải lại nội dung 1 paste đã đăng, dựa vào key hoặc URL
  (chấp nhận cả dạng `domain/p/key` và `domain/p/key/raw`). Đây là tool **fallback quan trọng**:
  một số AI chat (đã ghi nhận với ChatGPT) không tự fetch được URL trả về `Content-Type: text/plain`
  thuần — trình duyệt-tool tích hợp của các client này thường được thiết kế để đọc trang HTML
  (có `<title>`, cấu trúc DOM...), và có thể coi 1 file text thuần là "file tải xuống" rồi từ chối
  đọc nội dung thay vì hiển thị. Khi gặp tình huống đó, chỉ cần yêu cầu AI chat gọi tool
  `fetch_markdown` thay vì tự mở URL — nội dung sẽ được tải về ngay trong server, trả thẳng vào
  kết quả tool, không phụ thuộc vào khả năng duyệt web của client.

## Nền tảng nào hỗ trợ custom MCP server? (thông tin tại thời điểm viết, có thể thay đổi)

| Nền tảng | Hỗ trợ custom remote MCP? | Ghi chú |
|---|---|---|
| Claude | Có | Tất cả các gói, kể cả free |
| ChatGPT | Có | Cần bật Developer Mode, gói trả phí (Plus/Pro/Business/Enterprise/Edu) |
| Grok | Có | Gói trả phí, mục "Bring Your Own MCP" tại grok.com/connectors |
| Qwen, DeepSeek, Kimi, z.ai (GLM), Manus, Meta AI | Chưa rõ / có thể chưa hỗ trợ ở chat UI tiêu dùng | Một số bên hỗ trợ MCP theo hướng khác (làm MCP server cho client khác gọi vào, hoặc qua SDK lập trình), nhưng chưa xác nhận có ô "thêm custom MCP server" trong giao diện chat web thông thường |

Vì server này tuân thủ đúng chuẩn MCP (Streamable HTTP), nó sẽ tự động chạy được với bất kỳ
client nào hỗ trợ chuẩn — không cần sửa code theo từng nền tảng. Với các nền tảng ở dòng "chưa rõ",
cách chắc chắn nhất là kiểm tra trực tiếp trong phần Settings/Connectors của nền tảng đó, vì thông
tin hỗ trợ MCP đang thay đổi rất nhanh giữa các AI chat.

## Bước 1 — Deploy lên Render

Y hệt quy trình đã làm với `mdshare`:

1. Đẩy code (`server.js`, `package.json`, `render.yaml`) lên 1 GitHub repo mới, ví dụ `mdshare-mcp`.
2. Trên Render: **New** → **Blueprint** → chọn repo `mdshare-mcp`.
3. Khi được hỏi biến môi trường, nhập:
   - `MDSHARE_BASE_URL` = URL của service `mdshare` đã deploy trước đó
     (ví dụ `https://mdshare-11s5.onrender.com` — **không có** dấu `/` ở cuối).
4. Bấm **Apply**.

Sau khi deploy xong, Render cho URL dạng `https://mdshare-mcp-xxxx.onrender.com`.
Endpoint MCP thực sự nằm ở: `https://mdshare-mcp-xxxx.onrender.com/mcp`.

## Bước 2 — Kết nối vào Claude.ai qua Custom Connector

1. Vào **claude.ai** → **Settings** → **Connectors** (hoặc mục tương đương trong Settings).
2. Chọn **Add custom connector** (hoặc "Add more").
3. Nhập URL: `https://mdshare-mcp-xxxx.onrender.com/mcp`
4. Đặt tên gợi nhớ, ví dụ "mdshare".
5. Lưu lại. Claude sẽ tự động phát hiện tool `publish_markdown`.

Sau bước này, trong bất kỳ cuộc trò chuyện nào, bạn có thể bật connector "mdshare" lên
(qua menu công cụ trong khung chat), rồi yêu cầu ví dụ:

> "Tóm tắt nội dung trên thành markdown rồi đăng lên mdshare cho tôi"

Claude sẽ tự gọi tool `publish_markdown`, và trả về URL kết quả ngay trong chat.

## Kết nối từ các AI chat khác (ChatGPT, v.v.)

Nếu client đó hỗ trợ MCP qua Streamable HTTP (giao thức MCP chuẩn, không riêng của Anthropic),
quy trình tương tự: cung cấp URL `https://mdshare-mcp-xxxx.onrender.com/mcp` vào phần cấu hình
connector/tool của client đó. Cú pháp thêm connector khác nhau tuỳ nền tảng — kiểm tra tài liệu
chính thức của client để biết vị trí cấu hình.

## Test thủ công (không qua AI chat, chỉ để kiểm tra server hoạt động)

Trên `cmd` Windows:

```cmd
curl -X POST https://mdshare-mcp-xxxx.onrender.com/mcp ^
  -H "Content-Type: application/json" ^
  -H "Accept: application/json, text/event-stream" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"
```

Kết quả phải chứa tool `publish_markdown` trong danh sách trả về.

## Bảo mật cần lưu ý

- MCP server này **không có xác thực** — bất kỳ ai biết URL `/mcp` đều gọi được tool
  `publish_markdown` để đăng nội dung lên `mdshare` của bạn. Với dùng cá nhân, rủi ro thấp
  (URL không công khai, khó đoán qua subdomain ngẫu nhiên của Render), nhưng nếu muốn chặt hơn:
  - Thêm 1 header bí mật (ví dụ `X-Api-Key`) kiểm tra trong `server.js` trước khi xử lý request MCP.
  - Cấu hình biến môi trường `MCP_SHARED_SECRET` và yêu cầu client gửi kèm header đó.
- `mdshare` (dịch vụ đích) vốn đã không có auth theo thiết kế ban đầu, nên tool này chỉ đơn
  thuần tự động hoá lại đúng hành vi thủ công bạn từng làm bằng `curl` — không mở thêm rủi ro
  mới ở phía `mdshare`.

## Cơ sở lý luận cho lựa chọn thiết kế

- **Streamable HTTP thay vì SSE (Server-Sent Events)**: SSE là giao thức MCP thế hệ cũ, đã bị
  đánh dấu không khuyến khích trong đặc tả MCP hiện hành; Streamable HTTP là giao thức chuẩn
  hiện tại, được các SDK chính thức khuyến nghị cho remote MCP server.
- **Stateless (`sessionIdGenerator: undefined`)**: vì tool chỉ thực hiện 1 thao tác đơn giản
  (POST 1 lần, nhận 1 kết quả), không cần duy trì trạng thái phiên giữa nhiều lần gọi — giúp
  server đơn giản hơn và tương thích tốt với môi trường serverless/free-tier có thể khởi động
  lại container bất kỳ lúc nào.