Ref

Ref MCP

Một máy chủ ModelContextProtocol cung cấp cho công cụ hoặc tác nhân lập trình AI của bạn quyền truy cập vào tài liệu cho các API, dịch vụ, thư viện, v.v. Đây là điểm đến duy nhất giúp tác nhân của bạn luôn cập nhật tài liệu một cách nhanh chóng và tiết kiệm token.

Để biết thêm thông tin, hãy xem ref.tools

Tìm kiếm theo tác nhân để có đúng ngữ cảnh cần thiết

Các công cụ của Ref được thiết kế để phù hợp với cách các mô hình tìm kiếm trong khi sử dụng ít ngữ cảnh nhất có thể nhằm giảm thiểu suy giảm ngữ cảnh. Mục tiêu là tìm chính xác ngữ cảnh mà tác nhân lập trình của bạn cần để thành công trong khi sử dụng số token tối thiểu.

Tùy thuộc vào độ phức tạp của lời nhắc, các tác nhân lập trình LLM như Claude Code thường sẽ thực hiện một hoặc nhiều lần tìm kiếm và sau đó chọn một vài tài nguyên để đọc sâu hơn.

Đối với một truy vấn đơn giản về Figma's Comment REST API, nó sẽ thực hiện một vài lệnh gọi để có được chính xác những gì cần thiết:

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

Đối với các tình huống phức tạp hơn, LLM sẽ cố gắng tinh chỉnh lời nhắc khi đọc kết quả. Ví dụ:

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref tận dụng các phiên MCP để theo dõi quỹ đạo tìm kiếm và giảm thiểu việc sử dụng ngữ cảnh. Còn rất nhiều ý tưởng đang được phát triển nhưng đây là những gì chúng tôi đã triển khai cho đến nay.

1. Lọc kết quả tìm kiếm

Đối với các tìm kiếm tương tự lặp lại trong một phiên, Ref sẽ không bao giờ trả về kết quả trùng lặp. Theo cách truyền thống, bạn đào sâu hơn vào kết quả tìm kiếm bằng cách phân trang đến kết quả tiếp theo nhưng cách tiếp cận này cho phép tác nhân phân trang VÀ điều chỉnh lời nhắc cùng một lúc.

2. Tìm nạp phần quan trọng của trang

Khi đọc một trang tài liệu, Ref sẽ sử dụng lịch sử tìm kiếm phiên của tác nhân để loại bỏ các phần ít liên quan hơn và trả về 5k token phù hợp nhất. Điều này giúp Ref tránh được một vấn đề lớn với việc thu thập dữ liệu web fetch() tiêu chuẩn, đó là khi gặp một trang tài liệu lớn, bạn có thể dễ dàng kéo vào hơn 20k token vào ngữ cảnh, hầu hết trong số đó là không liên quan.

Tại sao việc giảm thiểu token từ ngữ cảnh tài liệu lại quan trọng?

1. Nhiều ngữ cảnh hơn khiến mô hình kém thông minh hơn

Có tài liệu rõ ràng rằng tính đến tháng 7 năm 2025, các mô hình trở nên kém thông minh hơn khi bạn đưa vào nhiều token hơn. Bạn có thể đã nghe nói về việc các mô hình hiện nay xử lý ngữ cảnh dài rất tốt và điều đó phần nào đúng nhưng không phải là bức tranh toàn cảnh. Để có phần giới thiệu nhanh về một số nghiên cứu, hãy xem video này từ nhóm tại Chroma.

2. Token tốn kém $$$

Hãy tưởng tượng bạn đang sử dụng Claude Opus như một tác nhân nền và bạn bắt đầu bằng cách yêu cầu tác nhân kéo vào ngữ cảnh tài liệu và giả sử nó kéo vào 10000 token ngữ cảnh với 4000 token liên quan và 6000 token là nhiễu thêm. Với giá API, 6k token đó tốn khoảng 0,09 đô la CHO MỖI BƯỚC. Nếu một lời nhắc cuối cùng mất 11 bước với Opus, bạn đã chi 1 đô la một cách vô ích.

Thiết lập

Có hai tùy chọn để thiết lập Ref làm máy chủ MCP, thông qua máy chủ streamable-http (được khuyến nghị) hoặc máy chủ stdio cục bộ (kế thừa).

Repo này chứa máy chủ stdio kế thừa.

Streamable HTTP (được khuyến nghị)

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

Công cụ

Máy chủ Ref MCP cung cấp tất cả các công cụ liên quan đến tài liệu cho nhu cầu của tác nhân của bạn.

ref_search_documentation

Một công cụ tìm kiếm mạnh mẽ để kiểm tra tài liệu kỹ thuật. Tuyệt vời để tìm kiếm sự kiện hoặc đoạn mã. Có thể được sử dụng để tìm kiếm tài liệu công khai trên web hoặc github cũng như từ các tài nguyên riêng tư như repo và pdf.

Tham số:

• query (bắt buộc): Truy vấn để tìm kiếm tài liệu liên quan. Đây nên là một câu hoàn chỉnh hoặc câu hỏi.

ref_read_url

Một công cụ tìm nạp nội dung từ một URL và chuyển đổi nó thành markdown để dễ đọc với Ref. Điều này mạnh mẽ khi được sử dụng kết hợp với công cụ ref_search_documentation trả về các url của nội dung liên quan.

Tham số:

• url (bắt buộc): URL của trang web cần đọc.

Hỗ trợ nghiên cứu sâu của OpenAI

Ref có thể được sử dụng như một nguồn cho nghiên cứu sâu. OpenAI yêu cầu các định nghĩa công cụ cụ thể, vì vậy khi được sử dụng với một ứng dụng khách OpenAI, Ref sẽ cung cấp các công cụ tương tự với tên gọi hơi khác.

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

Phát triển

npm install
npm run dev

Chạy với Inspector

Đối với mục đích phát triển và gỡ lỗi, bạn có thể sử dụng công cụ MCP Inspector. Inspector cung cấp giao diện trực quan để kiểm tra và giám sát các tương tác của máy chủ MCP.

Truy cập tài liệu Inspector để biết hướng dẫn thiết lập chi tiết.

Để kiểm tra cục bộ với Inspector:

npm run inspect

Hoặc chạy cả trình theo dõi và inspector:

npm run dev

Phát triển cục bộ

1. Sao chép kho lưu trữ
2. Cài đặt các phụ thuộc:

npm install

3. Xây dựng dự án:

npm run build

4. Để phát triển với tự động xây dựng lại:

npm run watch

Giấy phép

MIT