cmap
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
cmap-mcp
Tiếng Việt | English
Một công cụ dòng lệnh (cmap) và một máy chủ MCP giúp các coding agent (Claude Code, Codex, Cursor và các công cụ khác) đọc dữ liệu công khai trên cmap.vn, bản đồ văn hóa Việt Nam: sự kiện văn hóa, lễ hội, triển lãm, biểu diễn, thể thao và hoạt động cộng đồng, ưu đãi, địa điểm và tỉnh thành.
Cả hai lối vào đều là lớp vỏ mỏng bọc quanh cùng một thư viện lõi, nên chúng trả về cùng một dữ liệu.
Dữ liệu và ghi nguồn
Dữ liệu thuộc về cmap.vn và đơn vị vận hành trang. Dự án này không lưu trữ hay phân phối lại dữ liệu: nó lấy dữ liệu lúc chạy từ JSON API công khai của trang, giữ một bộ đệm cục bộ, và mỗi bản ghi đều có trường url dẫn về trang tương ứng trên cmap.vn. Vui lòng ghi nguồn cmap.vn khi bạn dùng kết quả. Các yêu cầu được gửi một cách lịch sự (tối đa 4 yêu cầu cùng lúc, User-Agent cmap-mcp/<version>, chờ rồi thử lại khi gặp 429 và 5xx, mỗi lần làm mới toàn bộ cách nhau ít nhất vài phút). Hãy đọc điều khoản của trang hoặc hỏi đơn vị vận hành trước khi phân phối lại dữ liệu cho mục đích thương mại hay công khai.
Related MCP server: dia-chi-moi
Cài đặt
Không cần cài đặt nếu bạn có Node 22+ hoặc Bun:
npx -y cmap-mcp events search "ha noi"
bunx cmap-mcp events search "ha noi"Các cách khác:
Cài toàn cục:
npm install -g cmap-mcphoặcbun add -g cmap-mcp, rồi chạycmap.Tệp chạy độc lập (không cần Node hay Bun) trên GitHub Releases:
cmap-linux-x64,cmap-linux-arm64,cmap-darwin-x64,cmap-darwin-arm64vàcmap-windows-x64.exe, kèm tệpSHA256SUMSđể kiểm tra.Docker:
docker run -p 8787:8787 ghcr.io/cuongtranba/cmap-mcpkhởi động máy chủ MCP ở chế độ HTTP. Image được phát hành cholinux/amd64vàlinux/arm64với các taglatest,<major>.<minor>và<version>(ví dụ0.1.0).Agent skill:
npx skills add cuongtranba/cmap-mcp(hoặcbunx skills add cuongtranba/cmap-mcp) dạy agent khi nào và cách gọi CLI. Xem skills/cmap/SKILL.md.
CLI
cmap sync | cmap status
cmap events search [query] --province --type --category --from --to --free|--paid --highlight --limit --offset --lang
cmap events near <lat> <lng> [--radius-km] [--limit]
cmap event get <id|slug> [--lang]
cmap offers search [query] --province --kind --limit --offset
cmap offer get <id|slug>
cmap provinces | cmap province get <id|slug|name> | cmap places [--province --type] | cmap taxonomies
cmap mcp [--http host:port]
cmap --version | cmap --help | cmap <command> --helpCờ dùng chung: --refresh (đồng bộ từ cmap.vn trước), --max-age <minutes> (đồng bộ lại khi bộ đệm cũ hơn số phút này; mặc định 60), --text (xuất dạng dễ đọc thay vì JSON), --lang vi|en.
cmap events search "ngay van hoa" --from 2026-11-24 --to 2026-11-24
cmap events search --province "Ha Noi" --free --limit 10 --text
cmap events near 21.0285 105.8542 --radius-km 5
cmap event get am-vang-dong-que-9TXHDc --lang en
cmap province get "da nang"
cmap offers search "bao tang"
cmap taxonomiesTìm kiếm không phân biệt dấu tiếng Việt (
ha noitìm thấyHà Nội). Ngày có dạngYYYY-MM-DD.--from/--togiữ lại các sự kiện có thời gian giao với khoảng ngày đã cho.Kết quả là JSON định dạng đẹp trên stdout. Khi có lỗi, lệnh thoát với mã 1 và in
{ "error": { "code", "message" } }ra stderr (các mãNOT_FOUND,VALIDATION,UPSTREAM,SYNC_REJECTED,NO_SNAPSHOT); khi dùng sai cú pháp, lệnh thoát với mã 2 và in hướng dẫn.Lần gọi đầu tiên đồng bộ toàn bộ dữ liệu (khoảng 2 đến 6 giây); các lần sau đọc từ bộ đệm.
Máy chủ MCP
Mười công cụ chỉ đọc, mỗi công cụ ứng với một phương thức của thư viện: search_events, get_event, events_near, list_provinces, get_province, list_taxonomies, search_offers, get_offer, list_places, get_sync_status. Mỗi công cụ đều có schema đầu vào và đầu ra và trả về structuredContent; lỗi của thư viện được trả về dưới dạng kết quả công cụ với isError: true.
Claude Code:
claude mcp add cmap -- npx -y cmap-mcp mcpCodex, trong ~/.codex/config.toml:
[mcp_servers.cmap]
command = "npx"
args = ["-y", "cmap-mcp", "mcp"]Bất kỳ MCP client nào nhận cấu hình JSON:
{
"mcpServers": {
"cmap": { "command": "npx", "args": ["-y", "cmap-mcp", "mcp"] }
}
}Chế độ HTTP (Streamable HTTP, không trạng thái): cmap mcp --http 127.0.0.1:8787 phục vụ POST /mcp và GET /healthz. Dùng --http :8787 để lắng nghe trên mọi giao diện mạng, ví dụ trong container:
docker run -p 8787:8787 -v cmap-cache:/data ghcr.io/cuongtranba/cmap-mcpImage chạy bằng người dùng không phải root, giữ bộ đệm trong /data (CMAP_CACHE_DIR=/data) và có health check trên GET /healthz.
Ở chế độ stdio, máy chủ chỉ ghi thông điệp giao thức ra stdout; log được ghi ra stderr. Máy chủ nạp bộ đệm khi khởi động (đồng bộ trước nếu chưa có) và đồng bộ lại ở nền sau mỗi CMAP_REFRESH_MIN phút, giữ lại dữ liệu tốt gần nhất nếu một lần đồng bộ thất bại.
Cấu hình
Biến | Mặc định | Ý nghĩa |
|
| Địa chỉ gốc của nguồn dữ liệu |
|
| Thư mục chứa |
|
| CLI đồng bộ lại khi bộ đệm cũ hơn số phút này |
|
| Số yêu cầu đồng thời tới nguồn dữ liệu |
|
| Chu kỳ làm mới ở nền của máy chủ MCP, tính bằng phút |
Cách hoạt động
Một lần đồng bộ lấy các taxonomy, rồi lấy sự kiện theo từng tỉnh, mỗi tỉnh một lần (34 yêu cầu, mỗi yêu cầu tối đa 100 sự kiện), cùng với ưu đãi và địa điểm, kiểm tra từng bản ghi bằng zod, loại bỏ bản trùng và thay kết quả mới vào một cách nguyên tử (snapshot.json). Tìm kiếm chạy trên snapshot đó, nên trả kết quả tức thì, không cần gõ dấu, và vẫn hoạt động khi cmap.vn chậm. Một lần đồng bộ thất bại hoặc đáng ngờ (hơn 10% bản ghi không hợp lệ) sẽ giữ lại snapshot trước đó. Chỉ phần nội dung dài của một sự kiện hoặc ưu đãi được lấy khi cần, theo id.
Cơ chế phân trang danh sách của chính trang web làm mất khoảng 20 sự kiện (thứ tự sắp xếp không ổn định), và các endpoint resolve, map và facets cũng mắc cùng lỗi này, nên không endpoint nào trong số đó được dùng để đảm bảo tính đúng đắn. Chi tiết và quá trình điều tra có trong docs/design.md (tiếng Anh).
Phát triển
Bun là bộ công cụ duy nhất.
bun install
bun run lint # Biome
bun run typecheck # tsc --noEmit
bun test # chạy offline, với nguồn dữ liệu giả (test/fake-cmap.ts)
bun run build # dist/cli.js, chạy được trên Node 22+
bun run build:bin # tệp chạy độc lập cho máy hiện tại, dist/cmap
bun run build:binaries # cả năm tệp chạy phát hành + SHA256SUMS trong dist/bin
bun run test:live # kiểm tra cmap.vn thật: schema, cấu trúc khóa, 34 tỉnh, mỗi tỉnh <=100 sự kiện
bun run fixtures:record # ghi lại test/fixtures từ API thật
bun run contract:record # ghi lại test/contract/shape.json sau một thay đổi có chủ đích ở nguồn dữ liệuĐọc AGENTS.md (tiếng Anh) trước khi sửa mã.
CI và phát hành
GitHub Actions chỉ dùng Bun (oven-sh/setup-bun, phiên bản Bun lấy từ trường packageManager trong package.json).
cichạy trên mọi pull request và mọi lần push lênmain:bun install --frozen-lockfile, lint, typecheck,bun test,bun run build, rồi các smoke test (node dist/cli.js --versionvà--helptrên Node của runner,--versioncủa tệp chạy linux-x64),bun pm pack --dry-runvà một bước kiểm tra rằngbunx skills add ./ --listliệt kêcmap. Đây là status check bắt buộc chomain.live-e2echạy các live test (bun run test:live) với cmap.vn thật mỗi ngày lúc 07:00 giờ Việt Nam (00:00 UTC), khi được kích hoạt thủ công, và trên các pull request có chạm tớisrc/upstream,src/snapshot,test/livehoặctest/contract. Khi một lần chạy theo lịch hoặc thủ công trênmainthất bại, workflow mở một issue gắn nhãnupstream-drift("cmap.vn upstream changed: live e2e failing") kèm liên kết tới lần chạy và 150 dòng output cuối, hoặc bình luận vào issue đang mở. Khi một lần chạy sau đó thành công, workflow đóng issue đó. Sau một thay đổi có chủ đích ở nguồn dữ liệu, hãy chạybun run contract:recordvà commit tệptest/contract/shape.jsonmới.releasechạy khi một tagv*được push.
Để phát hành:
bun pm version patch # hoặc minor / major: tăng phiên bản trong package.json, commit và gắn tag vX.Y.Z
git push --follow-tagsSau đó workflow release sẽ:
verify thất bại nếu tag không khớp với phiên bản trong
package.json, và chạy lại toàn bộ các bước kiểm tra củaci.npm phát hành bằng
bun publish --access public, dùng secretNPM_TOKENcủa repository. Đặt secret này một lần bằnggh secret set NPM_TOKEN -R cuongtranba/cmap-mcp(một npm automation token).bun publishhiện chưa tạo được provenance statement hay dùng npm trusted publishing, nên gói được phát hành không kèm provenance.binaries đính kèm
cmap-linux-x64,cmap-linux-arm64,cmap-darwin-x64,cmap-darwin-arm64,cmap-windows-x64.exevàSHA256SUMSvào một GitHub Release có ghi chú phát hành tự động.docker push
ghcr.io/cuongtranba/cmap-mcpcholinux/amd64vàlinux/arm64với các tag<version>,<major>.<minor>vàlatest(các tag pre-release nhưv1.0.0-rc.1không cập nhậtlatest), dùngGITHUB_TOKENcó sẵn.
Dependabot mở các pull request cập nhật hằng tuần cho GitHub Actions và các phụ thuộc Bun, gộp chung các bản cập nhật minor và patch.
Giấy phép
MIT, xem LICENSE. Dữ liệu do cmap.vn cung cấp không thuộc phạm vi giấy phép này.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and read published GoVisit destination and local business data through 22 read-only tools.
A read-only verified record of agent-operable GTM tools: search, fetch, compare, track changes.
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceProvides AI agents with verified Vietnamese tax and legal retrieval capabilities, including searching legal documents, fetching document details, evaluating effective tax rules at a specified date, and tracking recent legal updates.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to convert old Vietnamese addresses (63 provinces with district level) into post-2025 addresses (34 provinces, ward/province only), returning new ward codes, postal codes, confidence and all candidates when a unit was split or ambiguous. Also exposes tools to parse free-form addresses, search old/new administrative units, list provinces and wards, and trace which old units formed a new ward.MIT
- FlicenseNot gradedqualityBmaintenanceEnables agents to query a fully offline, 66.7-million-character Xi'an local gazetteer knowledge base without internet access or API keys. Exposes tools for knowledge-base statistics, category and book listings, tables of contents, keyword full-text search, and full or chunked article retrieval, with complete hierarchical paths on every result.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to discover upcoming events in a given city, optionally filtered by category slug or free-text keyword. It also retrieves full detail for a single event, including description, timing, venue, organizer, and ticket price range and availability.75 npmMIT