datacore-a2a-mcp 0.1.0__tar.gz

datacore_a2a_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Đã điền token thật — không bao giờ commit.
+.mcp.json
+.env

datacore_a2a_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 3TIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datacore_a2a_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: datacore-a2a-mcp
+Version: 0.1.0
+Summary: MCP server cho các skill dữ liệu DataCore: chuẩn hoá địa chỉ Việt Nam và tra cứu doanh nghiệp
+Project-URL: Homepage, https://github.com/DataCore-VietNam/datacore-a2a-mcp
+Project-URL: Documentation, https://github.com/DataCore-VietNam/datacore-a2a-mcp#readme
+Project-URL: Privacy Policy, https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/PRIVACY.md
+Project-URL: Issues, https://github.com/DataCore-VietNam/datacore-a2a-mcp/issues
+Author-email: 3TIT <mcp-security@datacore.vn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,address,company-data,mcp,model-context-protocol,vietnam
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DataCore A2A — MCP server
+
+<!-- mcp-name: vn.datacore/datacore-a2a -->
+<!-- Marker dự phòng: registry tìm chuỗi con, nên hai dòng cùng tồn tại được.
+     Giữ đường lùi nếu xác minh tên miền không xong, khỏi phải phát hành
+     một version mới chỉ để sửa một dòng comment.
+     mcp-name: io.github.nambn3tit/datacore-a2a-mcp -->
+
+Cho phép một MCP client (Claude Code, Claude Desktop, VS Code, Cursor…) dùng
+các skill dữ liệu của DataCore như tool native: chuẩn hoá địa chỉ Việt Nam,
+kiểm tra địa chỉ, tra cứu doanh nghiệp, sinh embedding.
+
+```
+MCP client (stdio) ──► datacore-mcp ──HTTPS──► DataCore API
+```
+
+Zero dependency, Python 3.9+.
+
+## Cài đặt
+
+```bash
+pip install datacore-a2a-mcp
+```
+
+## Cần có trước
+
+Server này là **client**, không phải dịch vụ. Nó cần một endpoint DataCore và
+một mandate token để gọi — liên hệ 3TIT để được cấp. Không có hai thứ đó thì
+server khởi động rồi thoát ngay kèm thông báo thiếu biến nào.
+
+## Cấu hình
+
+| Biến | Bắt buộc | Ý nghĩa |
+|---|---|---|
+| `DATACORE_A2A_URL` | có | Base URL của endpoint DataCore được cấp cho bạn, ví dụ `https://api.example.com` |
+| `DATACORE_MANDATE` | có | AP2 mandate token do DataCore cấp — quyết định skill nào được gọi và hạn mức chi tiêu |
+| `DATACORE_SKILLS` | không | Danh sách skill id cách nhau bằng phẩy để giới hạn tool, hoặc `*` để lấy hết. Bỏ trống dùng mặc định |
+| `DATACORE_TIMEOUT` | không | Timeout mỗi request (giây), mặc định `30` |
+
+Dùng đúng URL DataCore cấp kèm mandate. Một endpoint khác sẽ không nhận mandate
+của bạn và trả `401`.
+
+### Claude Code / Claude Desktop
+
+Thêm vào `.mcp.json` (project) hoặc config của Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "datacore-a2a": {
+      "command": "datacore-mcp",
+      "env": {
+        "DATACORE_A2A_URL": "https://api.example.com",
+        "DATACORE_MANDATE": "<mandate-token>"
+      }
+    }
+  }
+}
+```
+
+## Tool
+
+Tool list được **sinh từ endpoint**, không hardcode ở đây — nên khi DataCore
+thêm skill, restart server là thấy tool mới.
+
+Mặc định expose 4 skill đã nối backend thật:
+
+| Tool | Skill id | Việc nó làm |
+|---|---|---|
+| `address_normalize` | `address.normalize` | Chuẩn hoá địa chỉ Việt Nam thành tỉnh / huyện / xã |
+| `address_validate` | `address.validate` | Kiểm tra một địa chỉ có tồn tại theo dữ liệu hành chính |
+| `company_search` | `company.search` | Tra cứu doanh nghiệp theo tên hoặc mã số thuế |
+| `company_embeddings` | `company.embeddings` | Sinh vector embedding cho văn bản |
+
+Mọi tool là **read-only** (`readOnlyHint: true`): không ghi, không xoá, không
+tạo gì. Gọi lại cùng input cho cùng kết quả.
+
+Ba skill khác của DataCore (`company.graph`, `company.financial-sankey`,
+`company.news`) **cố ý không được expose**: chúng đang trả dữ liệu
+mock/deterministic. Muốn thấy chúng để thử thì đặt `DATACORE_SKILLS="*"`, và
+đừng tin kết quả.
+
+## Ví dụ
+
+Ba prompt dưới đây chạy qua ba tool khác nhau:
+
+1. **Chuẩn hoá địa chỉ** — "Chuẩn hoá địa chỉ này thành tỉnh/huyện/xã: So 1 Ly
+   Thai To, Hoan Kiem, Ha Noi"
+2. **Tra cứu doanh nghiệp** — "Tìm thông tin doanh nghiệp có mã số thuế
+   0100109106 và cho tôi biết trạng thái hoạt động"
+3. **Embedding** — "Sinh embedding cho đoạn mô tả ngành nghề này rồi cho biết
+   vector có bao nhiêu chiều: bán buôn thiết bị điện tử"
+
+## Mô hình bảo mật
+
+Server này mang mandate token **nguyên dạng** ở header `X-AP2-Mandate` để phía
+DataCore verify, và không tự khai bất kỳ header authorization nào khác. Một
+client không được là nơi tự cấp quyền cho chính nó — nó chỉ chuyển tiếp thứ nó
+được cấp, còn mọi quyết định cho phép hay từ chối đều nằm ở phía DataCore.
+
+Mandate là **bearer credential**: ai giữ nó cũng gọi được đúng những skill trong
+đó, tới hết hạn mức, cho tới khi hết hạn. Giữ nó như giữ mật khẩu — đừng commit
+`.mcp.json` đã điền token, và nếu client của bạn hỗ trợ, đọc nó từ trình quản lý
+secret thay vì để inline.
+
+**Package này** không bao giờ ghi token ra log, kể cả một phần; nội dung `text`
+bạn gửi cũng không. Đó là cam kết cho tiến trình chạy trên máy bạn — phía dịch
+vụ là chuyện khác, và [PRIVACY.md](PRIVACY.md) nói thẳng nó lưu những gì.
+
+## Xử lý sự cố
+
+Log đi ra **stderr**, prefix `[datacore-mcp]`. stdout là kênh JSON-RPC.
+
+| Triệu chứng | Nguyên nhân thường gặp |
+|---|---|
+| Server thoát ngay, `THIẾU biến môi trường bắt buộc` | Chưa set `DATACORE_A2A_URL` hoặc `DATACORE_MANDATE` |
+| `401` mọi request | Mandate hết hạn, hoặc `DATACORE_A2A_URL` không phải endpoint đã cấp kèm mandate đó |
+| `402` | Đã dùng hết spend cap của mandate |
+| `403` | Skill nằm ngoài allowlist của mandate — xin mandate có skill đó |
+| `502` | Backend của skill đó phía DataCore không phản hồi |
+| Không thấy tool nào | `DATACORE_SKILLS` lọc hết, hoặc endpoint chưa đăng ký skill nào |
+
+## Báo lỗi bảo mật
+
+`mcp-security@datacore.vn`. Đừng mở issue công khai cho lỗi bảo mật.
+
+Nghi mandate của mình bị lộ thì **báo ngay** — đừng đợi tới lúc nó hết hạn.
+Chúng tôi cần biết để xử lý phía dịch vụ.
+
+## Quyền riêng tư
+
+Xem [PRIVACY.md](PRIVACY.md). Ngắn gọn: package này chạy trên máy bạn, không lưu
+gì, không gửi đi đâu ngoài endpoint DataCore bạn tự cấu hình, và không bao giờ
+ghi mandate token vào log.
+
+## License
+
+MIT — xem [LICENSE](LICENSE).

datacore_a2a_mcp-0.1.0/PRIVACY.md

@@ -0,0 +1,93 @@
+# Privacy Policy — datacore-a2a-mcp
+
+Áp dụng cho package `datacore-a2a-mcp` (MCP server). Cập nhật 2026-08-24.
+
+## Package này là gì, về mặt dữ liệu
+
+`datacore-a2a-mcp` là một **client chạy trên máy bạn**. Nó không phải dịch vụ do
+chúng tôi vận hành, không nhận dữ liệu về phía chúng tôi, và không có backend
+riêng. Nó là một tiến trình cục bộ dịch giữa MCP client của bạn (Claude Code,
+Claude Desktop, VS Code…) và endpoint DataCore mà **bạn** cấu hình.
+
+## Dữ liệu nó xử lý
+
+| Dữ liệu | Từ đâu | Đi đâu |
+|---|---|---|
+| Nội dung `text` bạn (hoặc agent) đưa vào tool | MCP client | Gửi tới endpoint DataCore ở `DATACORE_A2A_URL` qua HTTPS |
+| Skill id được gọi | Tên tool | Cùng request trên |
+| Mandate token | `DATACORE_MANDATE` | Header `X-AP2-Mandate` của cùng request trên |
+| Kết quả trả về | Endpoint DataCore | Trả lại MCP client |
+
+Không có đích đến nào khác. Package **zero dependency** nên không có thư viện
+bên thứ ba nào chạm vào dữ liệu, và không có telemetry, analytics, hay
+crash-reporting nào.
+
+## Nó lưu gì
+
+**Không lưu gì cả.** Không file, không cache, không database, không state giữa
+các lần chạy. Mọi thứ nằm trong bộ nhớ tiến trình và mất khi tiến trình dừng.
+
+## Nó ghi log gì
+
+Log đi ra **stderr**, nơi MCP client của bạn quyết định giữ hay bỏ:
+
+- Lúc khởi động: base URL, timeout, danh sách skill được bật
+- Lúc discovery: số tool tìm được và skill id của chúng
+- Khi tool lỗi: câu lỗi đã được dịch, gồm mã HTTP và message của server
+
+**Mandate token không bao giờ được ghi log, kể cả một phần của nó** — đây là
+token cấp quyền chi tiêu, và stderr của MCP server thường được client ghi ra
+file. Nội dung `text` bạn gửi cũng không được ghi log.
+
+## Dữ liệu gửi tới DataCore thì sao
+
+Mục trên nói về package — thứ chạy trên máy bạn. Mục này nói về **dịch vụ** ở
+đầu kia `DATACORE_A2A_URL`. Hai thứ khác nhau, và cam kết của package không phủ
+lên dịch vụ được, nên phần này viết riêng.
+
+### Dịch vụ nhận gì
+
+Mỗi lần gọi tool, dịch vụ nhận: nội dung `text` bạn gửi, skill id, mandate của
+bạn (mandate id, client id, danh sách skill được phép, hạn mức chi tiêu, hạn sử
+dụng), cùng những thứ mọi request HTTP đều mang — địa chỉ IP nguồn và header.
+
+### `text` của bạn đi tới đâu
+
+Gateway verify chữ ký mandate → orchestrator kiểm skill có nằm trong mandate
+không và hạn mức còn không → chuyển cho worker agent của skill đó → worker gọi
+API dữ liệu tương ứng: dữ liệu địa giới hành chính, dữ liệu doanh nghiệp, hoặc
+mô hình embedding.
+
+Các API dữ liệu đó là hệ thống riêng, không cùng một hệ thống với gateway. Nên
+**nội dung `text` của bạn có rời khỏi phạm vi chúng tôi để tới bên cung cấp dữ
+liệu** — đó là cách duy nhất để có câu trả lời cho truy vấn của bạn. Bên cung
+cấp dữ liệu có chính sách riêng của họ.
+
+### Dịch vụ lưu gì
+
+| Thứ được lưu | Nội dung | Sống bao lâu |
+|---|---|---|
+| Bộ đếm chi tiêu | Một con số cho mỗi mandate. Không có nội dung truy vấn | Tự xoá đúng lúc mandate hết hạn |
+| Bản ghi tính phí | mandate id, client id, worker, skill id, số tiền, thời điểm. Không có nội dung truy vấn | Theo hệ thống tính phí |
+| Log request ở gateway | **Body request — tức `text` của bạn — body response, header, query string, IP nguồn** | Theo chính sách log của hệ thống |
+
+Dòng thứ ba là dòng đáng đọc kỹ: gateway ghi log ở mức đầy đủ, nên **truy vấn
+và kết quả của bạn được lưu lại ở phía dịch vụ, không chỉ đi ngang qua**. Nếu
+định gửi dữ liệu nhạy cảm qua tool này, hãy tính trên giả định đó. Package
+không hứa thay cho phần này được — nó chỉ hứa được rằng bản thân nó không lưu
+và không ghi gì (mục trên).
+
+### Dùng để làm gì
+
+Phục vụ chính request đó, cộng với vận hành và tính phí: đối soát khi có sự cố,
+đếm chi tiêu theo mandate, xuất hoá đơn. Không bán cho ai, và không dùng nội
+dung truy vấn của bạn để huấn luyện mô hình.
+
+### Yêu cầu xoá, hoặc khiếu nại
+
+`mcp-security@datacore.vn`. Nói rõ mandate id hoặc client id để chúng tôi tìm
+đúng bản ghi — chúng tôi không tra được theo nội dung truy vấn.
+
+## Liên hệ
+
+Vấn đề bảo mật hoặc quyền riêng tư: `mcp-security@datacore.vn`

datacore_a2a_mcp-0.1.0/README.md

@@ -0,0 +1,138 @@
+# DataCore A2A — MCP server
+
+<!-- mcp-name: vn.datacore/datacore-a2a -->
+<!-- Marker dự phòng: registry tìm chuỗi con, nên hai dòng cùng tồn tại được.
+     Giữ đường lùi nếu xác minh tên miền không xong, khỏi phải phát hành
+     một version mới chỉ để sửa một dòng comment.
+     mcp-name: io.github.nambn3tit/datacore-a2a-mcp -->
+
+Cho phép một MCP client (Claude Code, Claude Desktop, VS Code, Cursor…) dùng
+các skill dữ liệu của DataCore như tool native: chuẩn hoá địa chỉ Việt Nam,
+kiểm tra địa chỉ, tra cứu doanh nghiệp, sinh embedding.
+
+```
+MCP client (stdio) ──► datacore-mcp ──HTTPS──► DataCore API
+```
+
+Zero dependency, Python 3.9+.
+
+## Cài đặt
+
+```bash
+pip install datacore-a2a-mcp
+```
+
+## Cần có trước
+
+Server này là **client**, không phải dịch vụ. Nó cần một endpoint DataCore và
+một mandate token để gọi — liên hệ 3TIT để được cấp. Không có hai thứ đó thì
+server khởi động rồi thoát ngay kèm thông báo thiếu biến nào.
+
+## Cấu hình
+
+| Biến | Bắt buộc | Ý nghĩa |
+|---|---|---|
+| `DATACORE_A2A_URL` | có | Base URL của endpoint DataCore được cấp cho bạn, ví dụ `https://api.example.com` |
+| `DATACORE_MANDATE` | có | AP2 mandate token do DataCore cấp — quyết định skill nào được gọi và hạn mức chi tiêu |
+| `DATACORE_SKILLS` | không | Danh sách skill id cách nhau bằng phẩy để giới hạn tool, hoặc `*` để lấy hết. Bỏ trống dùng mặc định |
+| `DATACORE_TIMEOUT` | không | Timeout mỗi request (giây), mặc định `30` |
+
+Dùng đúng URL DataCore cấp kèm mandate. Một endpoint khác sẽ không nhận mandate
+của bạn và trả `401`.
+
+### Claude Code / Claude Desktop
+
+Thêm vào `.mcp.json` (project) hoặc config của Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "datacore-a2a": {
+      "command": "datacore-mcp",
+      "env": {
+        "DATACORE_A2A_URL": "https://api.example.com",
+        "DATACORE_MANDATE": "<mandate-token>"
+      }
+    }
+  }
+}
+```
+
+## Tool
+
+Tool list được **sinh từ endpoint**, không hardcode ở đây — nên khi DataCore
+thêm skill, restart server là thấy tool mới.
+
+Mặc định expose 4 skill đã nối backend thật:
+
+| Tool | Skill id | Việc nó làm |
+|---|---|---|
+| `address_normalize` | `address.normalize` | Chuẩn hoá địa chỉ Việt Nam thành tỉnh / huyện / xã |
+| `address_validate` | `address.validate` | Kiểm tra một địa chỉ có tồn tại theo dữ liệu hành chính |
+| `company_search` | `company.search` | Tra cứu doanh nghiệp theo tên hoặc mã số thuế |
+| `company_embeddings` | `company.embeddings` | Sinh vector embedding cho văn bản |
+
+Mọi tool là **read-only** (`readOnlyHint: true`): không ghi, không xoá, không
+tạo gì. Gọi lại cùng input cho cùng kết quả.
+
+Ba skill khác của DataCore (`company.graph`, `company.financial-sankey`,
+`company.news`) **cố ý không được expose**: chúng đang trả dữ liệu
+mock/deterministic. Muốn thấy chúng để thử thì đặt `DATACORE_SKILLS="*"`, và
+đừng tin kết quả.
+
+## Ví dụ
+
+Ba prompt dưới đây chạy qua ba tool khác nhau:
+
+1. **Chuẩn hoá địa chỉ** — "Chuẩn hoá địa chỉ này thành tỉnh/huyện/xã: So 1 Ly
+   Thai To, Hoan Kiem, Ha Noi"
+2. **Tra cứu doanh nghiệp** — "Tìm thông tin doanh nghiệp có mã số thuế
+   0100109106 và cho tôi biết trạng thái hoạt động"
+3. **Embedding** — "Sinh embedding cho đoạn mô tả ngành nghề này rồi cho biết
+   vector có bao nhiêu chiều: bán buôn thiết bị điện tử"
+
+## Mô hình bảo mật
+
+Server này mang mandate token **nguyên dạng** ở header `X-AP2-Mandate` để phía
+DataCore verify, và không tự khai bất kỳ header authorization nào khác. Một
+client không được là nơi tự cấp quyền cho chính nó — nó chỉ chuyển tiếp thứ nó
+được cấp, còn mọi quyết định cho phép hay từ chối đều nằm ở phía DataCore.
+
+Mandate là **bearer credential**: ai giữ nó cũng gọi được đúng những skill trong
+đó, tới hết hạn mức, cho tới khi hết hạn. Giữ nó như giữ mật khẩu — đừng commit
+`.mcp.json` đã điền token, và nếu client của bạn hỗ trợ, đọc nó từ trình quản lý
+secret thay vì để inline.
+
+**Package này** không bao giờ ghi token ra log, kể cả một phần; nội dung `text`
+bạn gửi cũng không. Đó là cam kết cho tiến trình chạy trên máy bạn — phía dịch
+vụ là chuyện khác, và [PRIVACY.md](PRIVACY.md) nói thẳng nó lưu những gì.
+
+## Xử lý sự cố
+
+Log đi ra **stderr**, prefix `[datacore-mcp]`. stdout là kênh JSON-RPC.
+
+| Triệu chứng | Nguyên nhân thường gặp |
+|---|---|
+| Server thoát ngay, `THIẾU biến môi trường bắt buộc` | Chưa set `DATACORE_A2A_URL` hoặc `DATACORE_MANDATE` |
+| `401` mọi request | Mandate hết hạn, hoặc `DATACORE_A2A_URL` không phải endpoint đã cấp kèm mandate đó |
+| `402` | Đã dùng hết spend cap của mandate |
+| `403` | Skill nằm ngoài allowlist của mandate — xin mandate có skill đó |
+| `502` | Backend của skill đó phía DataCore không phản hồi |
+| Không thấy tool nào | `DATACORE_SKILLS` lọc hết, hoặc endpoint chưa đăng ký skill nào |
+
+## Báo lỗi bảo mật
+
+`mcp-security@datacore.vn`. Đừng mở issue công khai cho lỗi bảo mật.
+
+Nghi mandate của mình bị lộ thì **báo ngay** — đừng đợi tới lúc nó hết hạn.
+Chúng tôi cần biết để xử lý phía dịch vụ.
+
+## Quyền riêng tư
+
+Xem [PRIVACY.md](PRIVACY.md). Ngắn gọn: package này chạy trên máy bạn, không lưu
+gì, không gửi đi đâu ngoài endpoint DataCore bạn tự cấu hình, và không bao giờ
+ghi mandate token vào log.
+
+## License
+
+MIT — xem [LICENSE](LICENSE).

datacore_a2a_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# Tên xác nhận còn trống 2026-08-24 (pypi.org/pypi/datacore-a2a-mcp/json → 404).
+# Tên trên PyPI là vĩnh viễn, không đổi được sau khi đã upload.
+name = "datacore-a2a-mcp"
+dynamic = ["version"]
+description = "MCP server cho các skill dữ liệu DataCore: chuẩn hoá địa chỉ Việt Nam và tra cứu doanh nghiệp"
+readme = "README.md"
+requires-python = ">=3.9"
+
+# Cố ý rỗng. Zero dependency là tính năng, không phải thiếu sót: MCP stdio chỉ
+# là JSON-RPC 2.0 phân cách bằng newline, nên `pip install` không kéo theo gì
+# và cũng không có dependency nào để bị CVE.
+dependencies = []
+
+keywords = ["mcp", "model-context-protocol", "a2a", "vietnam", "address", "company-data"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+
+# MIT: package này là một wrapper mỏng không chứa business logic, nên điều khoản
+# patent của Apache-2.0 không mua thêm gì đáng kể, và MIT thì ngắn, quen mắt,
+# không làm ai phải đọc kỹ trước khi cài. Đổi sang Apache-2.0 nếu muốn có
+# patent grant tường minh — chỉ cần thay file LICENSE và dòng dưới.
+#
+# Dạng SPDX string này cần hatchling >= 1.27 (PEP 639). Build lỗi ở chỗ này thì
+# đổi về: license = { file = "LICENSE" } và thêm lại classifier
+# "License :: OSI Approved :: MIT License".
+license = "MIT"
+license-files = ["LICENSE"]
+
+[[project.authors]]
+name = "3TIT"
+# ⚠️ Hộp thư này phải tồn tại thật trước khi publish — PyPI và registry đều hiện
+# nó ra, và đây là đường người ta báo lỗi bảo mật. Alias vào đâu cũng được.
+email = "mcp-security@datacore.vn"
+
+[project.scripts]
+datacore-mcp = "datacore_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/DataCore-VietNam/datacore-a2a-mcp"
+Documentation = "https://github.com/DataCore-VietNam/datacore-a2a-mcp#readme"
+# PRIVACY.md trong repo, không phải một trang riêng — đủ cho Anthropic và không
+# thêm một chỗ nữa để quên cập nhật. Phần nói về package đã đầy đủ; phần nói về
+# dịch vụ DataCore còn một khối TODO phải điền trước khi submit Anthropic.
+"Privacy Policy" = "https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/PRIVACY.md"
+Issues = "https://github.com/DataCore-VietNam/datacore-a2a-mcp/issues"
+
+[tool.hatch.version]
+path = "src/datacore_mcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/datacore_mcp"]
+
+[tool.hatch.build.targets.sdist]
+# sdist mà PyPI phát ra chứa đúng những gì liệt kê ở đây. Giữ danh sách hẹp:
+# mọi file lọt vào đây là file công khai.
+#
+# PRIVACY.md có trong danh sách vì người chỉ tải sdist vẫn phải đọc được nó.
+# Runbook phát hành cố ý không nằm trong repo này — nó là tài liệu nội bộ, không
+# phải tài liệu cho người dùng package.
+include = ["src/datacore_mcp", "README.md", "PRIVACY.md", "pyproject.toml"]

datacore_a2a_mcp-0.1.0/src/datacore_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server cho các skill dữ liệu của DataCore A2A."""
+
+__version__ = "0.1.0"

datacore_a2a_mcp-0.1.0/src/datacore_mcp/server.py

@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+"""
+MCP server cho DataCore: mỗi skill dữ liệu thành một MCP tool.
+
+    MCP client (stdio) ──► server này ──HTTPS──► DataCore API
+
+Mandate token được mang **nguyên dạng** ở header ``X-AP2-Mandate`` để phía
+DataCore verify. Server này không bao giờ tự khai bất kỳ header authorization
+nào khác: một client không được là nơi tự cấp quyền cho chính nó, nên nó chỉ
+chuyển tiếp thứ nó được cấp.
+
+Tool list sinh **từ endpoint** chứ không hardcode ở đây, nên DataCore thêm
+skill là client thấy tool mới sau khi restart server này.
+
+Zero dependency, Python 3.9+. MCP stdio chỉ là JSON-RPC 2.0 phân cách bằng
+newline nên không cần SDK — và quan trọng hơn, người cài không phải kéo theo
+cây dependency nào.
+"""
+
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+import uuid
+
+try:
+    from . import __version__
+except ImportError:  # chạy trực tiếp file này, ngoài package
+    __version__ = "0.0.0+local"
+
+
+# ------------------------------------------------------------------ cấu hình
+
+#: Skill được expose ra tool. Cố ý là danh sách trắng tường minh chứ không
+#: phải "mọi thứ endpoint trả về": ``company.graph``,
+#: ``company.financial-sankey`` và ``company.news`` hiện trả dữ liệu
+#: demo/deterministic, nên đưa chúng ra ngoài là mô tả dữ liệu giả như dữ liệu
+#: thật — lý do bị registry từ chối phổ biến nhất. Chuyển sang đây khi từng
+#: skill có dữ liệu thật.
+DEFAULT_SKILLS = (
+    "address.normalize",
+    "address.validate",
+    "company.search",
+    "company.embeddings",
+)
+
+PROTOCOL_FALLBACK = "2025-06-18"
+
+# Tên tool MCP không nhận dấu chấm, mà skill id thì có ("address.normalize").
+# Đổi sang '_' và giữ map ngược lại — cái gửi lên phải là id thật.
+_TOOL_NAME_SAFE = re.compile(r"[^a-zA-Z0-9_-]")
+
+_skill_by_tool_name = {}
+
+
+def log(msg):
+    """stderr, không phải stdout — stdout là kênh JSON-RPC, ghi gì vào đó là hỏng protocol."""
+    print(f"[datacore-mcp] {msg}", file=sys.stderr, flush=True)
+
+
+def _require(name, what, example):
+    """
+    Env bắt buộc, không có default. Bản trước default ``A2A_BASE_URL`` về một
+    IP LAN của người viết; ai cài cũng gặp timeout mà không hiểu vì sao. Thiếu
+    cấu hình là lỗi không tự phục hồi được, nên fail ngay và nói rõ thiếu gì.
+    """
+    value = os.environ.get(name, "").strip()
+    if not value:
+        log(f"THIẾU biến môi trường bắt buộc {name} ({what}).")
+        log(f"  ví dụ: {name}={example}")
+        log("  xem README để biết cách lấy mandate và URL endpoint.")
+        sys.exit(2)
+    return value
+
+
+def load_config():
+    base_url = _require(
+        "DATACORE_A2A_URL",
+        "base URL của endpoint DataCore",
+        "https://api.example.com",
+    ).rstrip("/")
+    mandate = _require(
+        "DATACORE_MANDATE",
+        "AP2 mandate token do DataCore cấp",
+        "<jws-token>",
+    )
+
+    raw_skills = os.environ.get("DATACORE_SKILLS", "").strip()
+    if raw_skills == "*":
+        skills = None  # None = không lọc, lấy hết những gì endpoint trả về
+    elif raw_skills:
+        skills = tuple(s.strip() for s in raw_skills.split(",") if s.strip())
+    else:
+        skills = DEFAULT_SKILLS
+
+    timeout = float(os.environ.get("DATACORE_TIMEOUT", "30"))
+    return base_url, mandate, skills, timeout
+
+
+BASE_URL, MANDATE, SKILL_FILTER, TIMEOUT = "", "", DEFAULT_SKILLS, 30.0
+
+
+# ------------------------------------------------------------------ HTTP
+
+
+class A2AError(Exception):
+    """DataCore trả về HTTP lỗi. ``status`` là mã, ``detail`` là body."""
+
+    def __init__(self, status, detail):
+        super().__init__(f"HTTP {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+#: Mã status DataCore trả về, dịch sang câu người đọc hiểu được thay vì để
+#: client tự đoán ý nghĩa của một con số như 402.
+_STATUS_HINT = {
+    400: "request không hợp lệ, hoặc skill chưa được đăng ký",
+    401: (
+        "mandate thiếu hoặc không hợp lệ. Kiểm tra DATACORE_MANDATE còn hạn, và "
+        "kiểm tra DATACORE_A2A_URL đúng là endpoint DataCore đã được cấp"
+    ),
+    402: "vượt spend cap của mandate — cần mandate mới hoặc cap cao hơn",
+    403: "skill nằm ngoài allowlist của mandate",
+    404: "không tìm thấy route — kiểm tra lại DATACORE_A2A_URL",
+    502: "backend của skill này không phản hồi",
+    503: "dịch vụ tạm thời không khả dụng",
+}
+
+
+def _error_detail(exc):
+    """
+    Lấy field ``error`` trong body lỗi. Body có thể không phải JSON (một proxy
+    chen vào và trả HTML chẳng hạn), nên phải chịu được cả trường hợp đó thay
+    vì ném tiếp một lỗi parse che mất lỗi gốc.
+    """
+    try:
+        body = exc.read().decode("utf-8", "replace")
+    except Exception:
+        return exc.reason or "không có chi tiết"
+    try:
+        parsed = json.loads(body)
+    except ValueError:
+        return (body[:300] or exc.reason or "không có chi tiết").strip()
+    if isinstance(parsed, dict):
+        return parsed.get("error") or parsed.get("message") or json.dumps(parsed)[:300]
+    return body[:300]
+
+
+def http_json(path, payload=None):
+    """
+    Một chỗ duy nhất gắn ``X-AP2-Mandate``. Token đi cả trên discovery lẫn
+    invoke, vì cả hai đều là request được authorize — discovery không mang
+    mandate cũng bị từ chối 401.
+    """
+    data = json.dumps(payload).encode() if payload is not None else None
+    headers = {"Accept": "application/json", "X-AP2-Mandate": MANDATE}
+    if data is not None:
+        headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(
+        f"{BASE_URL}{path}",
+        data=data,
+        headers=headers,
+        method="POST" if data is not None else "GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        raise A2AError(e.code, _error_detail(e)) from None
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"không kết nối được tới {BASE_URL}: {e.reason}") from None
+
+
+# ------------------------------------------------------------------ discovery
+
+
+def tool_name_for(skill_id):
+    return _TOOL_NAME_SAFE.sub("_", skill_id)
+
+
+def discover_tools():
+    """
+    Sinh tool list từ endpoint discovery.
+
+    Endpoint trả kèm vài field mô tả hạ tầng phía DataCore; chúng bị bỏ đi có
+    chủ ý. Địa chỉ nội bộ và thông điệp lỗi hạ tầng không có việc gì phải đi
+    tới máy người dùng, và càng không thuộc về một tool description mà model
+    sẽ đọc.
+    """
+    entries = http_json("/orchestrate/skills")
+    if not isinstance(entries, list):
+        raise RuntimeError(f"/orchestrate/skills trả về {type(entries).__name__}, cần một list")
+
+    _skill_by_tool_name.clear()
+    tools = []
+    skipped = []
+
+    for entry in entries:
+        skill_id = (entry or {}).get("id")
+        if not skill_id:
+            continue
+        if SKILL_FILTER is not None and skill_id not in SKILL_FILTER:
+            skipped.append(skill_id)
+            continue
+
+        name = tool_name_for(skill_id)
+        _skill_by_tool_name[name] = skill_id
+
+        # `name` của endpoint là mô tả ngắn của chính skill; nó là title hiển
+        # thị tốt hơn skill id. Rơi về id khi endpoint không trả được mô tả.
+        title = entry.get("name") or skill_id
+        description = entry.get("description") or f"DataCore skill {skill_id}"
+        examples = entry.get("examples") or []
+        if examples:
+            description += "\n\nVí dụ input: " + "; ".join(str(e) for e in examples[:3])
+        if entry.get("available") is False:
+            description += (
+                "\n\n(Agent giữ skill này đang không phản hồi. Skill id vẫn đúng "
+                "và gọi được khi agent trở lại.)"
+            )
+
+        tools.append({
+            "name": name,
+            "title": title,
+            "description": description,
+            # Bốn hint đều là sự thật về skill, không phải khai cho đủ: mọi
+            # skill hiện tại là tra cứu thuần, không ghi gì, gọi lại cùng input
+            # cho cùng kết quả, và dữ liệu đến từ backend ngoài process này.
+            "annotations": {
+                "title": title,
+                "readOnlyHint": True,
+                "destructiveHint": False,
+                "idempotentHint": True,
+                "openWorldHint": True,
+            },
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "text": {
+                        "type": "string",
+                        "description": "Input dạng free-text gửi cho skill.",
+                    }
+                },
+                "required": ["text"],
+                "additionalProperties": False,
+            },
+        })
+
+    log(f"{len(tools)} tool từ {BASE_URL}: {sorted(_skill_by_tool_name.values())}")
+    if skipped:
+        log(f"bỏ qua {len(skipped)} skill ngoài DATACORE_SKILLS: {sorted(skipped)}")
+    return tools
+
+
+def call_skill(skill_id, text):
+    """Gọi một skill và trả về payload thô mà DataCore trả lại."""
+    body = http_json("/orchestrate", {"skill": skill_id, "text": text})
+
+    payload = (body or {}).get("payload")
+    state = (body or {}).get("state")
+    if not payload:
+        raise RuntimeError(f"DataCore trả state={state} nhưng không có payload")
+    return payload
+
+
+# ------------------------------------------------------------------ MCP
+
+
+def _tool_error(exc):
+    """Câu lỗi cho Claude đọc: mã status → nguyên nhân, kèm chi tiết của server."""
+    if isinstance(exc, A2AError):
+        hint = _STATUS_HINT.get(exc.status, "lỗi từ DataCore")
+        return f"{hint} (HTTP {exc.status}): {exc.detail}"
+    return str(exc)
+
+
+def handle(method, params):
+    """
+    Trả về ``(result, error)``. Chỉ implement những method client thực sự gọi
+    — initialize / tools/list / tools/call — cộng ping. Method khác trả -32601.
+    """
+    if method == "initialize":
+        requested = params.get("protocolVersion")
+        return {
+            # Echo lại version client xin nếu là string: server không dùng gì
+            # đặc thù theo version, nên khớp client là lựa chọn an toàn nhất.
+            "protocolVersion": requested if isinstance(requested, str) else PROTOCOL_FALLBACK,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "datacore-a2a", "version": __version__},
+        }, None
+
+    if method == "ping":
+        return {}, None
+
+    if method == "tools/list":
+        try:
+            return {"tools": discover_tools()}, None
+        except Exception as e:
+            # Không với tới endpoint được là lỗi cấu hình, không phải lỗi
+            # protocol — trả error để client hiện lý do thật.
+            return None, {"code": -32603, "message": f"Discovery thất bại: {_tool_error(e)}"}
+
+    if method == "tools/call":
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        text = args.get("text")
+
+        if not _skill_by_tool_name:
+            try:
+                discover_tools()
+            except Exception as e:
+                return None, {"code": -32603, "message": f"Discovery thất bại: {_tool_error(e)}"}
+
+        skill_id = _skill_by_tool_name.get(name)
+        if not skill_id:
+            return None, {"code": -32602, "message": f"Tool không tồn tại: {name}"}
+        if not isinstance(text, str) or not text.strip():
+            return None, {"code": -32602, "message": "Thiếu tham số 'text'"}
+
+        try:
+            return {"content": [{"type": "text", "text": call_skill(skill_id, text)}]}, None
+        except Exception as e:
+            # isError=true để Claude thấy tool thất bại và tự điều chỉnh, thay
+            # vì tưởng chuỗi lỗi là kết quả hợp lệ.
+            message = _tool_error(e)
+            log(f"tool {name} lỗi: {message}")
+            return {"content": [{"type": "text", "text": message}], "isError": True}, None
+
+    return None, {"code": -32601, "message": f"Method không hỗ trợ: {method}"}
+
+
+def serve():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as e:
+            log(f"bỏ qua dòng không phải JSON: {e}")
+            continue
+
+        req_id = request.get("id")
+        method = request.get("method")
+
+        # Notification (không có id) — theo spec KHÔNG được trả lời.
+        # notifications/initialized rơi vào đây.
+        if req_id is None:
+            log(f"notification: {method}")
+            continue
+
+        try:
+            result, error = handle(method, request.get("params") or {})
+        except Exception as e:
+            result, error = None, {"code": -32603, "message": f"Lỗi nội bộ: {e}"}
+
+        response = {"jsonrpc": "2.0", "id": req_id}
+        if error:
+            response["error"] = error
+        else:
+            response["result"] = result
+
+        sys.stdout.write(json.dumps(response) + "\n")
+        sys.stdout.flush()
+
+
+def main():
+    global BASE_URL, MANDATE, SKILL_FILTER, TIMEOUT
+    BASE_URL, MANDATE, SKILL_FILTER, TIMEOUT = load_config()
+
+    # Không log MANDATE, kể cả một phần của nó: đây là token cấp quyền chi
+    # tiêu, và stderr của MCP server thường được client ghi ra file log.
+    scope = "tất cả skill của endpoint" if SKILL_FILTER is None else ", ".join(SKILL_FILTER)
+    log(f"start v{__version__} | base={BASE_URL} | timeout={TIMEOUT}s | skill={scope}")
+
+    try:
+        serve()
+    except (KeyboardInterrupt, BrokenPipeError):
+        pass
+
+
+if __name__ == "__main__":
+    main()