Kho Repo
Dành cho AI agent

API & MCP của Kho Repo

Kho hiện có 1.026 repo trong 34 chủ đề. Mọi endpoint đọc đều mở CORS, không cần khoá, và trả về mô tả tiếng Việt kèm mô tả gốc từ GitHub.

Bắt đầu nhanh

Bắt đầu bằng việc mô tả nhu cầu của bạn. Agent gọi một endpoint, nhận về danh sách repo kèm lý do khớp:

# Tìm repo theo nhu cầu (tiếng Việt hoặc tiếng Anh)
curl "https://kho.shopkitai.com/api/v1/search?q=cao+dữ+liệu+web+cho+RAG&limit=5"

# Lấy chi tiết một repo
curl "https://kho.shopkitai.com/api/v1/repos/firecrawl/firecrawl"

# Lọc theo chủ đề + ngôn ngữ
curl "https://kho.shopkitai.com/api/v1/repos?topic=scrape&language=Python&sort=stars&per_page=10"

Tìm theo tình huống dự án

Khi bạn không biết cần tìm gì, dùng tham số use_case — kho sẽ tự chọn các chủ đề liên quan:

build-webBuild web app

Frontend, backend, UI, biểu đồ, API, cào dữ liệu, triển khai.

curl "https://kho.shopkitai.com/api/v1/search?use_case=build-web&limit=8"
build-ai-agentBuild AI agent

Framework agent, MCP, skill/prompt, bộ nhớ, nền tảng LLM.

curl "https://kho.shopkitai.com/api/v1/search?use_case=build-ai-agent&limit=8"
build-storeBuild store dropship

Storefront headless, mẫu Shopify/Stripe, giỏ hàng, hiệu ứng, triển khai.

curl "https://kho.shopkitai.com/api/v1/search?use_case=build-store&limit=8"
scrape-webCào dữ liệu web

Thư viện cào web, trình duyệt tự động, nguồn API công khai.

curl "https://kho.shopkitai.com/api/v1/search?use_case=scrape-web&limit=8"
rag-llmRAG / ứng dụng LLM

Nền tảng RAG, vector store, mô hình ngôn ngữ, xử lý tài liệu.

curl "https://kho.shopkitai.com/api/v1/search?use_case=rag-llm&limit=8"
self-hostTự host & triển khai

Giải pháp self-hosted, container, giám sát hệ thống.

curl "https://kho.shopkitai.com/api/v1/search?use_case=self-host&limit=8"
learnHọc & lộ trình

Sách, lộ trình, phỏng vấn, danh sách awesome.

curl "https://kho.shopkitai.com/api/v1/search?use_case=learn&limit=8"
mediaẢnh / video / âm thanh

Sinh ảnh, giọng nói, dựng video, OCR, thị giác máy tính.

curl "https://kho.shopkitai.com/api/v1/search?use_case=media&limit=8"

Endpoint đọc

MethodPathMô tả
GET/api/v1/searchTìm theo mô tả tự nhiên, có lý do khớp và gợi ý chủ đề.
GET/api/v1/reposDuyệt / lọc / phân trang danh sách repo.
GET/api/v1/repos/{owner}/{name}Chi tiết một repo kèm repo liên quan.
GET/api/v1/topicsToàn bộ chủ đề, nhóm chủ đề và ngôn ngữ.
GET/api/v1/languagesDanh sách ngôn ngữ lập trình trong kho.
GET/api/v1/statsTổng quan kho: số repo, chủ đề, sao.
GET/api/v1/store/planKế hoạch dựng store bán hàng dropship theo vai trò.
GET/openapi.jsonOpenAPI 3.1 document đầy đủ.
GET/llms.txtManifest dạng văn bản cho agent.

Tham số /api/v1/repos

Tham sốKiểuÝ nghĩa
qstringTừ khoá tìm kiếm, không phân biệt dấu tiếng Việt. Nhận cả ID tình huống (scrape-web, build-web…) để lọc theo nhóm chủ đề.
use_casestringID tình huống dự án — cùng ý nghĩa với use_case của /api/v1/search.
topicstringID hoặc tên chủ đề (ví dụ scrape, agent, frontend).
languagestringNgôn ngữ chính của repo.
ownerstringTên tổ chức / chủ sở hữu.
min_starsintegerNgưỡng số sao tối thiểu.
sortstringstars | newest | name | updated | relevance.
page / per_pageintegerPhân trang, per_page tối đa 100.
fieldsstringChỉ trả về các trường cần, ví dụ name,url,summary.

Cập nhật kho theo yêu cầu

Kho được cập nhật khi có yêu cầu. Các endpoint ghi cần header X-Api-Key trùng với biến môi trường KHO_REPO_ADMIN_KEY.

MethodPathMô tả
POST/api/v1/reposThêm repo mới vào kho (tự lấy metadata từ GitHub).
PATCH/api/v1/repos/{owner}/{name}Sửa mô tả, chủ đề, điểm nổi bật.
DELETE/api/v1/repos/{owner}/{name}Xoá repo khỏi kho.
POST/api/v1/repos/{owner}/{name}/refreshLàm mới số sao & ngày push từ GitHub.
# Thêm repo mới — tự lấy mô tả, ngôn ngữ, số sao và tự suy luận chủ đề
curl -X POST "https://kho.shopkitai.com/api/v1/repos" \
  -H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repo":"microsoft/playwright","summary":"Playwright giúp kiểm thử và tự động hoá trình duyệt."}'

# Sửa mô tả tiếng Việt của một repo
curl -X PATCH "https://kho.shopkitai.com/api/v1/repos/microsoft/playwright" \
  -H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"scrape","highlights":["Chạy Chromium, Firefox, WebKit."]}'

Kế hoạch dựng store bán hàng

Kho không chỉ lưu repo, mà còn trả về kế hoạch dựng store để AI agent tự động hoá việc dựng cửa hàng. Endpoint này tự chọn repo trong kho cho từng vai trò (storefront, design system, giỏ hàng, hiệu ứng, carousel, hosting…), kèm lệnh cài đặt, gợi ý kỹ thuật và checklist ra mắt store.

# Kế hoạch dựng store theo nền tảng
curl "https://kho.shopkitai.com/api/v1/store/plan?platform=shopify"

# Chỉ lấy một vai trò
curl "https://kho.shopkitai.com/api/v1/store/plan?role=cart"

# platform: shopify (Hydrogen headless) | stripe (tự host) | nextjs (thuần)
# role: storefront | storefront-skills | design-system | animation | cart | carousel | hosting | product-media
Vai tròDùng để
storefrontNền tảng dựng trang cửa hàng: danh mục, sản phẩm, checkout.
storefront-skillsSkill cho AI agent viết đúng chuẩn Storefront API, clone landing page.
design-systemBộ component giao diện dùng chung cho mọi trang.
animationHiệu ứng 3D, Bento Grid, Marquee, shimmer cho hero và trang sản phẩm.
cartGiỏ hàng trượt kèm thanh free shipping và upsell 1-click.
carouselDải video UGC 9:16 tự động phát để tăng tỷ lệ chốt đơn.
hostingFramework chạy production và cách deploy store.
product-mediaCông cụ tạo ảnh sản phẩm, video unbox, ảnh nền landing page.

Trên MCP server, agent gọi tool plan_store với tham số platform và role, hoặc dùng search_repos với use_case=build-store.

Dịch vụ API và gateway

Ngoài kho repo, Kho Repo còn làm cổng cho các dịch vụ khác. Mỗi dịch vụ có một id riêng và một đường dẫn gateway dạng /api/v1/services/{id}/proxy/* — cùng một kiểu gọi, cùng một API key. Hiện có dịch vụ ch-relay (cổng OpenAI-compatible) và kho-catalog (tra cứu kho nội bộ).

MethodPathMô tả
GET/api/v1/servicesDanh sách dịch vụ kèm trạng thái cấu hình.
GET/api/v1/services/{id}Chi tiết một dịch vụ + trạng thái upstream.
GET/POST/api/v1/services/{id}/proxy/{path}Chuyển tiếp tới upstream (cần X-Api-Key).
# Xem dịch vụ đang mở và trạng thái kết nối
curl "https://kho.shopkitai.com/api/v1/services"

# Gọi model qua gateway của ch-relay (OpenAI-compatible)
curl -X POST "https://kho.shopkitai.com/api/v1/services/ch-relay/proxy/v1/chat/completions" \
  -H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Xin chào"}]}'

# Dùng qua OpenAI SDK — chỉ cần đổi base_url
# base_url = "https://kho.shopkitai.com/api/v1/services/ch-relay/proxy/v1"

Trên MCP server, agent gọi tool list_services để xem dịch vụ kèm trạng thái, và call_service để gọi dịch vụ qua gateway.

Bảng quản trị relay

Relay chạy trên VPS với hai khoá tách biệt: khoá công khai dùng cho mọi agent gọi model, khoá quản trị chỉ dùng để quản lý tài khoản đăng nhập. Khoá quản trị không bao giờ tới trình duyệt — bảng điều khiển gọi API quản trị qua proxy phía server, chỉ có cookie phiên đã ký mới là thứ duy nhất trình duyệt giữ.

KhoáDùng choCách dùng
KHO_RELAY_TOKENGọi model qua pool tài khoản của bạn.Header X-Api-Key hoặc Authorization: Bearer khi gọi /v1/*.
KHO_RELAY_ADMIN_TOKENQuản lý tài khoản, hạn mức, log yêu cầu, danh sách chia sẻ.Chỉ dùng server-side. Không chia sẻ cho agent.

Bảng quản trị nằm ở repo.shopkitai.com/quan-tri. Đăng nhập bằng khoá quản trị của Kho Repo, phiên có hiệu lực 12 giờ. Bốn tab: Tổng quan (lưu lượng, độ trễ, nhóm tài khoản), Tài khoản (bật/tắt, hạn mức, cooldown, đăng nhập ChatGPT mới), Lưu lượng (biểu đồ theo khung giờ, log yêu cầu) và Chia sẻ (danh sách tài khoản được phép dùng share lane).

# Share lane — dành cho người dùng Codex của bạn
# Chỉ tài khoản ChatGPT đã được enroll mới gọi được, và dùng ChatGPT token của chính họ
curl "https://relay.shopkitai.com/share/v1/models" \
  -H "Authorization: Bearer <CHATGPT_TOKEN>"

# Trang đăng nhập quản trị (dùng KHO_REPO_ADMIN_KEY)
open https://repo.shopkitai.com/quan-tri

Gọi model — endpoint cho khách

Ngoài API tra cứu kho, hệ thống còn chạy một cổng OpenAI-compatible để agent gọi model. Cổng này tách riêng khỏi site: mỗi khách nhận một khoá riêng, có hạn mức lượt gọi, hạn mức token và thời hạn sử dụng — hết hạn thì cổng trả 429/403 và tự chặn, không cần thao tác tay.

Base URL

https://relay.shopkitai.com/v1

Header xác thực

Authorization: Bearer <khoá khách>

Hoặc dùng X-Api-Key: <khoá khách> — không gõ khoá vào thanh địa chỉ.

Khoá khách được cấp ở bảng quản trị (tab Khoá khách), chuỗi có dạng kho_<40 ký tự hex>. Chuỗi gốc chỉ hiện đúng một lần ngay sau khi cấp — relay chỉ lưu dấu vân tay SHA-256, không lưu bản gốc. Cổng /v1/* đã bật CORS nên agent chạy trong trình duyệt gọi được ngay, không cần proxy.

# 1. Kiểm tra khoá vừa được cấp — xem hạn mức còn lại
curl https://relay.shopkitai.com/v1/me -H "Authorization: Bearer $RELAY_TOKEN"

# 2. Xem các model đang được phục vụ
curl https://relay.shopkitai.com/v1/models -H "Authorization: Bearer $RELAY_TOKEN"

# 3. Gọi model
curl https://relay.shopkitai.com/v1/chat/completions \
  -H "Authorization: Bearer $RELAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Xin chào"}]}'

Dùng OpenAI SDK — chỉ cần đổi base_url

# Python
from openai import OpenAI

client = OpenAI(base_url="https://relay.shopkitai.com/v1", api_key="kho_...")
resp = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Xin chào"}],
)
print(resp.choices[0].message.content)

# Node.js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.shopkitai.com/v1",
  apiKey: process.env.RELAY_TOKEN,
});

const resp = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [{ role: "user", content: "Xin chào" }],
});
console.log(resp.choices[0].message.content);

Windows PowerShell

Lệnh curl của Windows PowerShell 5.1 là alias của Invoke-WebRequest, không nhận cờ -d — dùng Invoke-RestMethod như dưới đây:

$RELAY_TOKEN = "kho_..."
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

$headers = @{ Authorization = "Bearer $RELAY_TOKEN" }
$body = @{ model = "gpt-6-luna"; messages = @(@{ role = "user"; content = "Xin chao" }) } | ConvertTo-Json -Depth 5

$resp = Invoke-RestMethod -Uri "https://relay.shopkitai.com/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

$resp.choices[0].message.content

Endpoint

MethodPathDùng để
GET/v1/modelsDanh sách model đang được phục vụ.
POST/v1/chat/completionsGọi model. Hỗ trợ stream:true và toàn bộ tham số OpenAI.
GET/v1/meXem hạn mức, thời hạn và trạng thái của chính khoá đang dùng.
GET/v1/models/{model}Chi tiết một model.

Header theo dõi hạn mức

Mỗi phản hồi kèm header để khách tự theo dõi, không cần gọi thêm:

HeaderÝ nghĩa
x-kho-key-labelTên của khoá đang gọi.
x-kho-remaining-requestsSố lượt gọi còn lại (thiếu nếu không giới hạn).
x-kho-remaining-tokensSố token còn lại (thiếu nếu không giới hạn).

Mã lỗi

CodeNguyên nhânCách xử lý
400Model không được tài khoản ChatGPT phía sau hỗ trợ (gói free không có gpt-6-astra/gpt-6-sol).Dùng model khác — xem GET /v1/models.
401Thiếu khoá, khoá không hợp lệ, hoặc provider chưa có tài khoản (Antigravity).Kiểm tra lại header Authorization: Bearer.
403Khoá đã hết hạn hoặc bị tắt.Liên hệ chủ cổng để cấp lại.
429Hết hạn mức lượt gọi hoặc token.Chờ chu kỳ reset hoặc nâng hạn mức.
503Provider thiếu API key (opencode-zen / opencode-go chưa được cấu hình).Dùng model của provider đang mở.

Model nào chạy được

ModelTrạng tháiGhi chú
gpt-6.2-astra, gpt-6.2-sol, gpt-6.1-terraDùng được ngayModel mới nhất trong pool — Codex CLI tự chọn sau khi sync.
gpt-6-lunaDùng được ngayModel mặc định cho khách.
gpt-6-astra, gpt-6-sol, gpt-6.1-solDùng được ngayPool có tài khoản ChatGPT trả phí.
gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-lunaDùng được ngay
gpt-5.5Không dùng đượcTài khoản ChatGPT phía sau không hỗ trợ model này (trả 400).
opencode-zen/*, opencode-go/*Chưa công bốProvider chưa có API key — không có trong GET /v1/models, gọi trực tiếp trả 503.
google-antigravity/*Chưa công bốChưa có tài khoản Google — không có trong GET /v1/models, gọi trực tiếp trả 401.

Danh sách model đang phục vụ lấy chính xác từ GET /v1/models — endpoint này chỉ công bố model relay thực sự phục vụ, nên dùng làm nguồn sự thật thay vì bảng trên.

Kết nối MCP server

MCP server chạy ở chế độ stateless, hỗ trợ Streamable HTTP. Agent dùng được 10 tool: search_repos, get_repo, list_topics, get_stats, plan_store, list_services, call_service, add_repo, update_repo và remove_repo.

# Claude Code
claude mcp add --transport http kho-repo https://kho.shopkitai.com/mcp

# Cursor / agent khác dùng cấu hình JSON
{
  "mcpServers": {
    "kho-repo": { "type": "http", "url": "https://kho.shopkitai.com/mcp" }
  }
}

Định dạng phản hồi

{
  "data": [
    {
      "name": "firecrawl/firecrawl",
      "url": "https://github.com/firecrawl/firecrawl",
      "topic": "Thu thập dữ liệu & Trình duyệt tự động",
      "topic_id": "scrape",
      "language": "TypeScript",
      "stars": 202341,
      "summary": "🔥 The API to search, scrape, and interact with the web for AI",
      "description": "Mô tả gốc từ GitHub",
      "highlights": ["…"],
      "why_match": "Khớp ở: tên repo, mô tả tiếng Việt"
    }
  ],
  "meta": {
    "total": 23,
    "page": 1,
    "per_page": 24,
    "total_pages": 1
  }
}

Chủ đề có sẵn

AI Agent & MCP74Trợ lý lập trình AI51Skill, Prompt & Mẫu cho AI65Bộ nhớ, Ngữ cảnh & Tiết kiệm token25Nền tảng AI, RAG & Workflow71Mô hình AI & Huấn luyện64AI Ảnh, Giọng nói & Deepfake46Dựng video & Slide tự động37Tài liệu, OCR & Thị giác máy tính38Học AI & Machine Learning68Thu thập dữ liệu & Trình duyệt tự động23API & Dịch vụ dữ liệu7Ngôn ngữ & Runtime18Framework Backend31Framework Frontend24Thư viện giao diện & CSS13Đồ họa, 3D & Sơ đồ21Editor, Terminal & Dòng lệnh45Ứng dụng đa nền tảng & Game14Container & DevOps24Giám sát, CSDL & Phân tích32Tự host & Nhà thông minh10Bảo mật & Hack17Tài chính & Crypto14Tiện ích Windows & Hệ thống25Tải & phát Video, Nhạc14Năng suất, Ghi chú & Việc làm40Sách, Khóa học & Lộ trình36Thuật toán & Phỏng vấn18Danh sách Awesome & Tổng hợp38Quy chuẩn & Thực hành tốt7Khác5Store & Dropship E-commerce5Hiệu ứng & Animation UI6
API cho AI agent — Kho Repo