MCP Server

MCP (Model Context Protocol) Server là một giao thức mở cho phép các AI assistant (như Claude) kết nối trực tiếp với các hệ thống dữ liệu bên ngoài thông qua một giao diện chuẩn hoá. MCP Server đóng vai trò trung gian giữa Claude và API hóa đơn đầu vào, giúp Claude có thể truy vấn dữ liệu hóa đơn một cách tự nhiên trong hội thoại.

---

Kiến trúc tổng quan

Claude Desktop / MCP Client
  → (stdio transport)
→ MCP Server (Python / FastMCP)
  → (HTTP / JSON-RPC V2)
→ Input Invoice API
  → (dữ liệu hóa đơn)
→ trả về Claude

---

Công nghệ sử dụng

Thành phần	Công nghệ	Mô tả
MCP Server	Python 3.12 + FastMCP	Xử lý MCP protocol qua stdio
HTTP Client	httpx (async)	Gọi Input Invoice API
Container	Docker + Docker Compose	Đóng gói và triển khai
Cấu hình	python-dotenv	Quản lý biến môi trường

---

Danh sách MCP Tools

Tool	Mô tả	Tham số chính
list_invoices	Tìm kiếm danh sách hóa đơn với bộ lọc tuỳ chỉnh	domain, limit, offset, order
get_invoice_detail	Lấy chi tiết một hóa đơn theo invoiceNo	invoice_no (bắt buộc)
search_invoices_by_seller	Tìm hóa đơn theo MST người bán	seller_tax_code (bắt buộc), limit, offset
search_invoices_by_buyer	Tìm hóa đơn theo MST người mua	buyer_tax_code (bắt buộc), limit, offset
search_invoices_by_date_range	Tìm hóa đơn theo khoảng ngày phát hành	date_from, date_to, invoice_type, invoice_status, limit, offset

---

Yêu cầu hệ thống

Yêu cầu	Phiên bản tối thiểu
Python	3.12+
Docker	24.0+
Docker Compose	2.20+
Claude Desktop	Phiên bản mới nhất

mẹo

Bạn cũng có thể chạy MCP Server trực tiếp bằng Python mà không cần Docker. Xem hướng dẫn trong trang Kết nối.