[Apero · Khung năng lực AI 07/2026] md2link

📋 Apero AI Submission · Asset 2 — Bản mô tả

Giá trị · Vấn đề giải quyết

Tại sao cần md2link?

Chia sẻ markdown / HTML / JSON tưởng đơn giản nhưng các option hiện tại đều thiếu: Gist không render đẹp, Notion đóng, Pastebin không có MCP cho AI agent. md2link ghép tất cả vào 1 URL.

❌ Vấn đề đang gặp

Gist / Pastebin không có preview đẹp cho markdown, HTML, JSON
Notion / Confluence phải login, không share nhanh cho khách
Không có tool nào cho AI agent tạo & quản lý doc share tự động
Muốn share HTML thì phải tự host, lo XSS, lo domain
JSON API response dài — không có viewer collapsible tiện lợi

✅ md2link giải quyết

1 URL preview đủ 3 format — GFM · iframe sandbox · JSON tree
Không cần đăng ký để tạo doc, chỉ cần login khi muốn quản lý
MCP server — Claude / Cursor tạo, đọc, sửa doc qua chat
Sandbox HTML an toàn (Turnstile + rate limit + JWT edit token)
JSON collapsible viewer client-side — copy path, expand nhánh

Ai được lợi

👨‍💻 Developer

Share code review, log, JSON API response, HTML report. Không tốn thời gian setup hosting.

📊 PM / BA

Share spec markdown có preview đẹp, có comment inline, không cần cấp quyền Confluence.

🤖 AI Engineer

Cho Claude / Cursor tạo doc share tự động qua MCP — pipeline agent tự publish output.

💡

Giá trị đo được: giảm thời gian chuẩn bị bản share từ ~10 phút (host + convert + set permission) xuống ~10 giây (paste + save + copy URL). Với 5-10 lần share/tuần → tiết kiệm 1-2 giờ/người/tuần.

5 nhóm tính năng

Đủ dùng cho cá nhân, đủ chuyên nghiệp cho AI agent

Một stack, năm sản phẩm nhỏ ghép lại: share markdown chuẩn GFM, share HTML sandbox an toàn, share JSON dạng collapsible tree, MCP server cho AI, và folder collection có edit token riêng.

📝

Share Markdown

CodeMirror 6 + live preview, GFM, Shiki syntax highlight, KaTeX, inline comment, version history 20 snapshot.

GFMShikiKaTeX

🌐

Share HTML Preview

Render trong iframe sandbox allow-scripts — script chạy được nhưng không thoát sang origin của md2link.

Import-onlySandboxed

🧬

Share JSON Preview

Collapsible tree viewer client-side. Perfect cho share API response, config, debug output.

Import-onlyInteractive

🤖

MCP Tools

11 tool cho Claude Desktop / Cursor / VS Code. AI agent tạo, đọc, sửa, xoá doc và folder qua REST API v1.

npm: md2link-mcpx-api-key

📁

Folder Management

Nhóm doc vào folder, share cả collection. Mỗi folder có visibility, password, edit token riêng.

FlatOrderedPassword

🛡️

An toàn & Chống bot

Cloudflare Turnstile, Upstash rate limit sliding-window, JWT unlock token, bcrypt password.

TurnstileUpstash

Cách vận hành

Kiến trúc end-to-end

Toàn bộ pipeline chạy trên edge của Vercel, dùng serverless Postgres (Neon) và Redis (Upstash). Không có server dài hạn — mọi request tự scale.

👤 User / AI Agent

Browser · Claude · Cursor · curl

→

⚡ Vercel Edge

Middleware · Turnstile · Rate limit

→

🧠 Next.js 15 API

App Router · Server Actions · REST v1

🐘 Neon Postgres

Docs · Folders · Comments · Versions

↔

🔴 Upstash Redis

Rate limit sliding-window

↔

🛡️ Cloudflare Turnstile

Anti-bot cho create/comment/import

Luồng tạo doc (Human)

Truy cập md2link.com → editor mở luôn
Chọn format (MD / HTML / JSON) → viết / paste content
Chọn visibility (public / unlisted / password) + expiresAt tùy chọn
Save → Turnstile verify → API validate → lưu Postgres
Nhận URL /d/{id} + edit token JWT

Luồng qua AI Agent (MCP)

User chat với Claude: "Tạo doc markdown chứa X"
Claude gọi MCP tool create_doc qua stdio
md2link-mcp package gọi POST /api/v1/docs với x-api-key
API verify key → check rate limit → insert Postgres
Trả về shareUrl → Claude paste cho user

🔐

Bảo mật lớp deep: API key chỉ qua header (không URL, không log). HTML render trong iframe sandbox không kèm allow-same-origin. Password doc hash bằng bcrypt. Edit token là JWT ngắn hạn — leaked URL không kèm token thì read-only.

1Share Markdown

Định dạng mặc định. Full editor + preview + comment + version.

Editor sẵn sàng

Luồng tạo

Mở md2link.com — editor mở luôn, không cần login
Viết markdown; preview render real-time bên phải
Chọn visibility: public / unlisted / password
(Tuỳ chọn) đặt expiresAt cho doc tự hết hạn
Save → nhận URL /d/{id}

Đi kèm miễn phí

Inline comment (anchor theo block ID)
Version history: 20 snapshot gần nhất, diff + restore
Auto OG image cho mỗi doc
URL import: paste link bài viết → convert markdown (Readability + Turndown)

URL patterns

URL	Trả về
`/d/{id}`	Reader page đầy đủ
`/d/{id}.md`	Raw markdown
`/d/{id}/edit?t=…`	Editor (cần token)
`/d/{id}/unlock`	Password gate

Ví dụ URL

GEThttps://md2link.com/d/abc12345.md

→ Content-Type: text/markdown

2Share HTML Preview

Import-only. Không có editor. Render trong iframe cách ly.

Import-only

Tạo qua API

curl -X POST https://md2link.com/api/v1/docs \
  -H "x-api-key: cm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"format":"html","content":"<h1>Hi</h1>","visibility":"unlisted"}'

🛡️

Sandbox: iframe dùng sandbox="allow-scripts" không kèm allow-same-origin. Script chạy được nhưng bị cô lập khỏi context md2link — chống XSS escape triệt để.

URL patterns

URL	Trả về
`/d/{id}`	Reader (iframe sandbox)
`/d/{id}.html`	Raw HTML, `text/html`
`/d/{id}.md`	406 Not Acceptable
`/d/{id}.json`	406 Not Acceptable

Use case

Share snapshot 1 trang web (đã Readability)
Share HTML report generated từ tool khác
Chèn iframe kết quả vào doc khác

3Share JSON Preview

Collapsible tree viewer. Perfect cho API response, config, debug output.

Import-only

Tạo

curl -X POST https://md2link.com/api/v1/docs \
  -H "x-api-key: cm_live_..." \
  -d '{"format":"json","content":"{\"user\":\"alice\"}","visibility":"unlisted"}'

URL patterns

URL	Trả về
`/d/{id}`	JSON tree viewer
`/d/{id}.json`	Raw JSON
`/d/{id}.html`, `.md`	406 Not Acceptable

Preview trong reader

▾ object {2}
"user": "alice"
▾ "roles": array [2]
0: "admin"
1: "editor"

💡

Viewer là client component. Expand / collapse từng nhánh, copy path bằng click, tiết kiệm màn hình khi JSON to.

4MCP Tools cho AI Agent

Package: md2link-mcp trên npm. Chạy 1 dòng, không cần build.

11 tools · Ready

Cấu hình Claude Desktop

{
  "mcpServers": {
    "md2link": {
      "command": "npx",
      "args": ["-y", "md2link-mcp"],
      "env": { "MD2LINK_API_KEY": "cm_live_..." }
    }
  }
}

Lấy API key: /settings/account/api-keys. Restart client — 11 tool xuất hiện trong picker.

Trỏ local dev

MD2LINK_BASE_URL=http://localhost:3000 \
MD2LINK_API_KEY=cm_live_... \
npx -y md2link-mcp

11 tools

whoamiVerify key + user info

create_docTạo doc mọi format

list_docsFilter + cursor pagination

get_docĐọc kèm content

update_docPartial update

delete_docXoá vĩnh viễn

create_folderTạo collection

list_foldersPagination

get_folderKèm doc con

update_folderPartial update

delete_folderDoc con thành orphan

🔒

API key chỉ truyền qua header x-api-key — không qua URL, không log. TLS mặc định. MCP không đọc filesystem — chỉ gọi REST API v1.

5Folder Management

Nhóm doc — share cả collection. Có visibility và edit token riêng.

Share cả folder

Đặc điểm

Flat structure (không nested folder)
Doc trong folder có folderPosition để giữ thứ tự
Folder dùng chung visibilityEnum (public / unlisted / password)
Doc giữ visibility riêng — folder không override
Slug nanoid 12 ký tự cho URL an toàn
Edit token JWT riêng — chỉ ai có ?t=… mới sửa được

URL patterns

URL	Trả về
`/f/{id}`	Folder reader (list doc)
`/f/{id}/edit?t=…`	Folder editor
`/f/{id}/unlock`	Password gate

API examples

POST/api/v1/folders

→ Tạo folder

PATCH/api/v1/docs/{docId}

→ Move doc: { folderId }

GET/api/v1/docs?folderId={fid}

→ List doc trong folder

DEL/api/v1/folders/{id}

→ Xoá folder, doc con thành orphan

⚠️

Xoá folder không xoá doc con — chủ ý để tránh mất data ngoài ý muốn. Doc con giữ nguyên nhưng folderId = null.

📋 Apero AI Submission · Asset 3

Source code

Repository & Quyền truy cập

Repo private trên GitHub — chứa toàn bộ source code web app (Next.js) và MCP server (Node.js/TypeScript). Đã cấp quyền cho tài khoản đánh giá của L&D và Hội đồng.

⌨

KOHuyn/md2link

github.com/KOHuyn/md2link · private

Mở repo →

✅ Đã share quyền truy cập cho aihub@apero.vn (Read/Collaborator). L&D Team và Hội đồng đánh giá vào repo qua invitation. Nếu cần cấp thêm cho ai, ping trực tiếp author.

Nội dung repo

apps/web — Next.js 15 app router, reader/editor/settings, REST API v1
packages/mcp — md2link-mcp npm package, 11 tools
packages/db — Drizzle schema, migration, seed
docs/ — Kiến trúc, ADR, API spec
README.md — Getting started, deployment

Chạy local

git clone git@github.com:KOHuyn/md2link.git
cd md2link && pnpm install
cp .env.example .env.local  # set Neon + Upstash keys
pnpm db:push && pnpm dev  # → http://localhost:3000

Stack

Chuẩn production, cost thấp, deploy tức thì

Next.js 15 App Router + Neon Postgres serverless + Upstash Redis + Cloudflare Turnstile + Vercel edge. Tất cả có free tier — 1 developer chạy dài dài không tốn tiền.

▲

Next.js 15

App Router, ISR, server actions, ImageResponse cho OG.

🐘

Neon Postgres

Serverless. Drizzle ORM, migrations version-controlled.

⚡

Upstash Redis

Rate limit sliding-window trên mọi write endpoint.

🛡️

Cloudflare Turnstile

Anti-bot cho create, comment, import — miễn phí.

✍️

CodeMirror 6

Editor markdown split-pane, Shiki highlight.

🚀

Vercel

Auto-deploy on push, edge middleware cho URL rewrite.

md2link — Share markdown, HTML, JSON
qua một link duy nhất.

Xem md2link chạy thực tế trong 2 phút

Tại sao cần md2link?

❌ Vấn đề đang gặp

✅ md2link giải quyết

Đủ dùng cho cá nhân, đủ chuyên nghiệp cho AI agent

Share Markdown

Share HTML Preview

Share JSON Preview

MCP Tools

Folder Management

An toàn & Chống bot

Kiến trúc end-to-end

Repository & Quyền truy cập

Chuẩn production, cost thấp, deploy tức thì

Next.js 15

Neon Postgres

Upstash Redis

Cloudflare Turnstile

CodeMirror 6

Vercel