Máy chủ MCP cho bộ nhớ agent: kết nối Claude Code với HotKV

Máy chủ MCP là cách đơn giản nhất để trao cho một trợ lý AI bộ nhớ kéo dài hơn một cuộc chat. Claude Code, Cursor và các client tương tự mất ngữ cảnh của cuộc chat khi nó kết thúc. Trao cho chúng quyền truy cập cơ sở dữ liệu thô để khắc phục điều đó là rủi ro. hotkv-mcp là máy chủ MCP mã nguồn mở của chúng tôi cho HotKV. Nó trao cho trợ lý một bộ công cụ cố định cho ghi chú, lịch sử hội thoại, nhật ký sự kiện, mẫu prompt và tìm kiếm tài liệu. Nó không cung cấp gì khác.

Tóm lại. hotkv-mcp là một máy chủ MCP theo Apache-2.0 kết nối Claude Code, Cursor, VS Code hoặc agent của riêng bạn với một máy chủ HotKV qua 28 công cụ cố định. Không có công cụ nào chạy một lệnh tùy ý, nên trợ lý không thể xóa sạch dữ liệu hay thay đổi cấu hình. Chế độ chỉ đọc loại bỏ mọi công cụ ghi, và một namespace giới hạn agent trong một tiền tố khóa. Cài đặt bằng pip install hotkv-mcp hoặc chạy bằng uvx.

Model Context Protocol là gì

Model Context Protocol, hay MCP, là một chuẩn mở để kết nối các ứng dụng AI với hệ thống bên ngoài như nguồn dữ liệu, công cụ và quy trình. Phần giới thiệu của dự án so sánh nó với một cổng USB-C cho ứng dụng AI. Theo thuật ngữ MCP, ứng dụng là client, và mỗi hệ thống nó kết nối tới được cung cấp bởi một máy chủ.

Với bộ nhớ, điều đó nghĩa là trợ lý gọi một công cụ có tên, như công cụ lưu một ghi chú. Máy chủ quyết định công cụ đó được phép làm gì. Mô hình không bao giờ có kết nối cơ sở dữ liệu của riêng mình.

Máy chủ MCP của HotKV cung cấp những gì

Máy chủ bọc bộ nhớ agent, sổ đăng ký prompt và tìm kiếm tài liệu của HotKV trong 28 công cụ. Mỗi công cụ khai báo trong các chú thích MCP của nó rằng nó chỉ đọc, ghi hay xóa. Khi đó client có thể yêu cầu phê duyệt trước các công cụ phá hủy.

Các công cụ bộ nhớ ánh xạ vào các kho được mô tả trong bộ nhớ agent AI, cụ thể là lịch sử hội thoại, ghi chú làm việc và nhật ký sự kiện. Việc gợi nhớ ngữ nghĩa bằng embedding không được cung cấp. rag_search xếp hạng theo độ liên quan từ khóa, nên không cần embedding.

Các công cụ khóa, hash và list hoạt động với bất kỳ máy chủ HotKV nào. Các công cụ bộ nhớ, prompt và tìm kiếm tài liệu dùng các engine AI của HotKV, cần một giấy phép bao gồm chúng. Nếu không có, các công cụ đó trả về thông báo rằng máy chủ không được cấp phép cho tính năng này. Các công cụ khóa vẫn hoạt động. Các instance HotKV Cloud Performance và Scale bao gồm các engine AI, như trang AI mô tả.

Cài đặt và kết nối

Máy chủ cần Python 3.10 trở lên. Nó được viết dựa trên máy chủ HotKV 0.3.0 và gói hotkv-client chính thức, và phiên bản 1.0.0 có trên PyPI. Cài đặt bằng pip, hoặc chạy mà không cần cài bằng uv.

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

Thêm nó bằng một lệnh. Dấu -- tách các tùy chọn của chính Claude Code khỏi lệnh khởi động máy chủ, như tài liệu MCP của Claude Code mô tả.

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor và Claude Desktop

Các client đọc tệp mcpServers nhận cùng máy chủ dưới dạng một mục JSON. Hãy giữ mật khẩu trong biến môi trường HOTKV_URL hoặc kho bí mật của client. Một dòng lệnh hiển thị cho những người dùng khác của máy. Dùng hotkvs:// cho kết nối TLS.

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

Kiểm tra nó có hoạt động không

Chạy claude mcp list để xác nhận máy chủ đã được đăng ký. Sau đó yêu cầu trợ lý gọi công cụ server_info. Nó trả về phiên bản HotKV và mức dùng bộ nhớ, cộng thêm số khóa khi không đặt namespace. Nó cũng báo cáo máy chủ có ở chế độ chỉ đọc không và bị giới hạn trong namespace nào. Điều đó xác nhận các biện pháp bảo vệ của bạn đã có hiệu lực.

Giữ agent trong các giới hạn an toàn

Một mô hình có thể gọi công cụ cũng có thể bị dụ dỗ dùng sai chúng, nên các giới hạn quan trọng hơn các tính năng.

Không có lệnh tùy ý

Không có công cụ nào chạy một lệnh thô. Trợ lý không thể xóa sạch cơ sở dữ liệu hay thay đổi cấu hình của máy chủ, vì không công cụ nào trong 28 công cụ làm những việc đó. Nó có thể đọc bất kỳ khóa nào các công cụ chạm tới, đó là lý do namespace bên dưới quan trọng.

Chế độ chỉ đọc

--read-only loại bỏ mọi công cụ ghi, gồm set, delete, hash_set, list_push, các công cụ bộ nhớ thêm hoặc xóa, prompt_save, rag_create và rag_ingest. Agent thậm chí không thấy chúng. Hãy dùng nó cho các trợ lý cần tham khảo bộ nhớ nhưng không bao giờ thay đổi nó.

Namespace và giới hạn kích thước

--namespace PREFIX lưu mọi thứ dưới tiền tố đó. Agent không bao giờ thấy tiền tố và không thể chạm tới các tên khác. Hãy cho mỗi agent một tiền tố không phải phần đầu của tiền tố khác. Dùng agent-a và agent-b, đừng dùng agent và agent:b, nếu không tiền tố ngắn hơn có thể chạm tới các tên của tiền tố dài hơn.

Kết quả cũng có giới hạn. --max-value-bytes cắt các giá trị dài và gắn cờ chúng là bị cắt, với mặc định 65,536 byte. --max-items giới hạn số khóa, mục list hoặc kết quả mà một lần gọi trả về, mặc định là 200. Vì vậy một giá trị khổng lồ đơn lẻ không thể làm ngập ngữ cảnh của mô hình. Việc đọc cả một hash không bị giới hạn số mục, nên hãy giữ các hash lớn ngoài namespace của agent.

Transport HTTP không có đăng nhập

Transport stdio mặc định được client khởi động như một tiến trình con. Để dùng chung, bạn có thể chạy hotkv-mcp --transport streamable-http, lắng nghe trên 127.0.0.1:8000 tại /mcp. Nó không xác thực người gọi. Hãy giữ nó trên localhost hoặc đặt sau một reverse proxy có xác thực, và cho nó một namespace riêng.

Chọn thiết lập cho một nhóm

Các cờ phù hợp phụ thuộc vào mục đích của từng agent. Mọi tùy chọn bên dưới là một cờ dòng lệnh. --read-only và --namespace cũng có biến môi trường, HOTKV_MCP_READ_ONLY và HOTKV_MCP_NAMESPACE.

Hãy bắt đầu từ hàng hạn chế nhất đủ làm được việc. Mở rộng quyền truy cập sau này thì dễ, còn thu hồi những gì agent đã ghi thì khó.

Phiên đầu tiên, từng bước

Một bản thử ngắn cho thấy các biện pháp bảo vệ làm gì trước khi bạn tin tưởng máy chủ với các ghi chú thật. Hãy dùng một namespace dùng một lần và một máy chủ HotKV cục bộ có giấy phép cho các engine AI, vì các công cụ bộ nhớ không hoạt động nếu thiếu giấy phép đó.

1. Kết nối với một namespace. Chạy claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Kiểm tra các giới hạn. Yêu cầu trợ lý gọi server_info và báo cáo namespace cùng việc máy chủ có chỉ đọc không. Nó nên nói trial và không chỉ đọc.
3. Lưu một ghi chú. Yêu cầu nó nhớ rằng site staging nằm ở một địa chỉ nhất định, dưới một ghi chú đặt tên theo site. Trợ lý gọi memory_set_note, và phiên được tạo ở lần dùng đầu tiên.
4. Đọc lại trong một cuộc chat mới. Bắt đầu một cuộc hội thoại mới và hỏi có những ghi chú nào cho phiên đó. Nó gọi memory_list_notes và memory_get_note, và ghi chú vẫn còn đó.
5. Ghi nhật ký một quyết định. Yêu cầu nó ghi một quyết định vào nhật ký sự kiện. Nó gọi memory_log_event, và memory_query_events đưa nó trở lại sau đó.
6. Gỡ quyền ghi của nó. Xóa mục cũ, kết nối lại với --read-only và lặp lại bước 4. Việc đọc vẫn hoạt động, và các công cụ ghi không còn được cung cấp.

Nếu bước 6 hoạt động như mô tả, bạn đã thấy hai cơ chế kiểm soát quan trọng nhất, namespace và chế độ chỉ đọc.

Hãy coi bất cứ thứ gì trợ lý lưu là văn bản không đáng tin khi nó được đọc lại, như bài về bộ nhớ giải thích trong phần coi văn bản đã lưu là không đáng tin. Ghi chú được viết từ các trang web có thể mang theo chỉ dẫn.

Khắc phục sự cố

• "This HotKV server is not licensed for that feature." Các công cụ bộ nhớ, prompt và tìm kiếm tài liệu cần một giấy phép HotKV bao gồm các engine AI. Các công cụ khóa, hash và list vẫn hoạt động mà không cần giấy phép.
• Kết nối thất bại. Kiểm tra scheme của URL. hotkv://, hotkvs:// (TLS), redis:// và rediss:// đều hoạt động, và mật khẩu được đặt trong URL dưới dạng hotkv://:password@host:6379.
• Một giá trị trả về bị cắt. Kết quả được gắn cờ là bị cắt khi vượt --max-value-bytes. Hãy nâng giới hạn hoặc lưu các giá trị nhỏ hơn.
• Thiếu một công cụ ghi. Tìm --read-only trong các đối số của máy chủ hoặc HOTKV_MCP_READ_ONLY trong môi trường của nó.
• Trợ lý không tìm thấy một tên nó đã lưu trước đó. Kiểm tra rằng nó đã dùng cùng tên phiên hoặc agent, và máy chủ chạy với cùng namespace như trước.
• Không tìm thấy uvx. Cài đặt uv, hoặc cài gói bằng pip và khởi động hotkv-mcp trực tiếp.

Câu hỏi thường gặp