Factory Droid + Scrapeless: Thêm một Máy chủ MCP từ xa

TL;DR:

• droid mcp add kết nối Scrapeless trong một lệnh. Sử dụng --type http, một tiêu đề x-api-token và --no-oauth; mục nhập được lưu vào ~/.factory/mcp.json.
• Viết khóa dưới dạng ${SCRAPELESS_API_KEY}, với dấu ngoặc. Droid mở rộng hình thức đó và đặt tên biến khi nó chưa được thiết lập, nhưng nó gửi một $SCRAPELESS_API_KEY trống như văn bản nguyên thủy.
• Một dự án .factory/mcp.json có thể mang theo tham chiếu một cách an toàn. Khóa ở lại trong môi trường của từng nhà phát triển, và máy chủ liệt kê như connected [project].
• droid mcp list phân tách bốn vấn đề khác nhau. connected, needs authentication, failed: Failed to connect to MCP server và một lỗi biến chưa được thiết lập đều chỉ ra một cách sửa chữa khác nhau.
• connected chứng minh rằng tiêu đề đã đến nơi, không phải rằng khóa hoạt động. Một khóa giả cũng được liệt kê là kết nối, vì vậy hãy xác nhận bằng một công cụ gọi.
• Một công cụ gọi không giao diện cần --auto high, vì vậy hãy xác định phạm vi cho nó. droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' cho phép cuộc gọi thực hiện chỉ với một công cụ đó và không gì khác.
• Lấy một khóa trên kế hoạch miễn phí của Scrapeless và thêm máy chủ chỉ trong vài phút.

Factory Droid lập kế hoạch và chỉnh sửa mã từ terminal của bạn, và droid exec chạy cùng một tác nhân không có giao diện trong các tập lệnh và CI. Không chế độ nào có thể nhìn vào một trang web chỉ bằng chính nó. Một máy chủ MCP cung cấp cho Droid các công cụ mà nó gọi trong một nhiệm vụ, và máy chủ Scrapeless MCP được lưu trữ cung cấp việc lấy trang, một trình duyệt đám mây và tìm kiếm.

Thiết lập chỉ là một lệnh. Những gì quyết định xem nó có giữ vững hay không là cách khóa tiếp cận tiêu đề, tệp cấu hình mà mục nhập sống trong và droid mcp list thực sự đang báo cáo điều gì.

Những Gì Droid Có Thể Gọi Khi Scrapeless Được Thêm Vào

Máy chủ Scrapeless cung cấp 25 công cụ. scrape_markdown, scrape_html và scrape_screenshot trả về một trang trong một cuộc gọi. Mười sáu browser_* công cụ, từ browser_create đến browser_close, thực hiện một phiên trình duyệt đám mây từng bước. crawl_start, crawl_result và crawl_cancel quản lý việc thu thập dữ liệu. google_search và google_trends trả về dữ liệu tìm kiếm và xu hướng, và ai_scraper lưu giữ câu trả lời từ các trợ lý AI như ChatGPT và Perplexity.

Kiến trúc MCP phân tách khách hàng gọi công cụ khỏi máy chủ cung cấp chúng, đó là lý do tại sao Droid chỉ cần một URL và một tiêu đề để sử dụng một máy chủ được lưu trữ ở nơi khác.

Điều Kiện Tiên Quyết

• Factory Droid CLI. Hướng dẫn này sử dụng các phiên bản 0.213.0 và 0.220.0.
• Một tài khoản Factory đã đăng nhập, hoặc FACTORY_API_KEY đã được thiết lập, cho bước mà mô hình chạy một lời nhắc.
• Một khóa API Scrapeless từ bảng điều khiển Scrapeless.

Bước 1: Thêm Máy Chủ

droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth

--type http chọn giao thức HTTP có thể stream; loại mặc định là stdio, mà sẽ coi URL như một lệnh để khởi động. --no-oauth tắt luồng OAuth mà Droid sẽ cung cấp cho một máy chủ từ xa được xác thực bằng tiêu đề.

Added HTTP MCP server scrapeless with URL: https://api.scrapeless.com/mcp

Mục nhập được viết vào ~/.factory/mcp.json:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "YOUR_SCRAPELESS_API_KEY"
      },
      "oauth": false,
      "disabled": false,
      "type": "http"
    }
  }
}

"oauth": false là những gì --no-oauth đã thêm vào. "disabled": false giữ cho máy chủ hoạt động.

Bước 2: Đặt Một Tham Chiếu Biến Trong Tiêu Đề

Lệnh ở trên để lại một khóa nguyên thủy trong tệp. Thay thế nó bằng ${SCRAPELESS_API_KEY} để tệp giữ một tên và shell của bạn giữ giá trị. Các dấu ngoặc là quan trọng: Droid mở rộng hình thức dấu ngoặc của mở rộng tham số POSIX và truyền một $SCRAPELESS_API_KEY trống qua không thay đổi.

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "${SCRAPELESS_API_KEY}"
      },
      "oauth": false,
      "disabled": false,
      "type": "http"
    }
  }
}

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
droid mcp list

Configured MCP servers:
  scrapeless  http  connected  [user]

Khi biến chưa được thiết lập trong shell đó, Droid sẽ đặt tên cho nó thay vì thất bại mơ hồ:

  scrapeless  http  failed: MCP server credential references an unset environment variable "SCRAPELESS_API_KEY"  [user]

Bỏ qua dấu ngoặc và cảnh báo đó sẽ không bao giờ xuất hiện. Droid gửi văn bản nguyên thủy $SCRAPELESS_API_KEY, máy chủ vẫn được liệt kê là connected, và vấn đề chỉ hiện ra trong cuộc gọi công cụ đầu tiên.

Bước 3: Chia Sẻ Máy Chủ Qua Một Dự Án mcp.json

Droid cũng đọc .factory/mcp.json từ một dự án, vì vậy máy chủ có thể sống trong kho lưu trữ cho mọi người sao chép nó. Một khóa nguyên thủy trong tệp đó sẽ được cam kết cùng với nó, và thông tin xác thực mã cứng là một điểm yếu phần mềm được phân loại vì lý do đó. Tham chiếu có dấu ngoặc thì an toàn để cam kết vì mỗi nhà phát triển cung cấp một khóa từ môi trường của họ. Lưu cùng một JSON như .factory/mcp.json trong gốc kho lưu trữ:

  scrapeless  http  connected  [project]

Nhãn trong dấu ngoặc là phạm vi mà Droid đã tải mục nhập từ, đây là cách nhanh nhất để xác nhận rằng tệp dự án là tệp đang có hiệu lực. Nếu không có biến, mục nhập dự án báo cáo cùng một lỗi biến chưa được thiết lập, gán nhãn [project].
Thiết lập điều này bây giờ? Kế hoạch Scrapeless miễn phí bao gồm kết nối và các lệnh gọi công cụ đầu tiên của bạn.

Bước 4: Đọc những gì danh sách báo cáo của droid mcp

Các hàng Bearer xuất hiện nhiều nhất vì gần như mọi ví dụ MCP đều xác thực theo cách đó. Scrapeless trả lời một yêu cầu mà không có x-api-token với một phản hồi 401 Unauthorized, và với OAuth bật, Droid đọc đó như một yêu cầu đăng nhập:

  scrapeless  http  needs authentication  [user]
Some servers need authentication. Start droid and run /mcp to authenticate.

Chạy /mcp không giải quyết được, vì điểm cuối Scrapeless không có luồng OAuth để hoàn tất. Thay vào đó, hãy thay đổi tiêu đề.

Trạng thái có thể gây hiểu lầm là connected. Bắt tay Scrapeless chấp nhận bất kỳ giá trị x-api-token không trống, vì vậy một khóa bị gõ sai hoặc thu hồi có thể hiển thị giống như một khóa tốt.

Bước 5: Chạy Droid chỉ với các công cụ Scrapeless

droid exec chạy một lời nhắc không giao diện, và nó bắt đầu ở chế độ chỉ đọc. Một cuộc gọi đến một công cụ MCP vượt quá chế độ đó: trong Droid 0.220.0, vòng chạy dừng lại với "quyền truy cập không đủ để tiếp tục", và --auto medium vẫn trả lời "Chạy lại với --auto high". Cờ --only-tools chấp nhận các bộ chọn MCP, vì vậy kết hợp mức độ tự chủ cao hơn với một bộ chọn cho phép một công cụ:

droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' "Use the scrapeless MCP server's scrape_markdown tool on https://example.com and reply with the first heading of the page, quoted exactly."

Droid trả lời:

The first heading of the page is:

"Example Domain"

Thêm --list-tools vào cùng một bộ chọn cho thấy một vòng chạy đó có thể đạt tới đâu. Droid định danh các công cụ MCP <server>___<tool>, và scrapeless___scrape_markdown là công cụ duy nhất được đánh dấu là cho phép, và 24 công cụ Scrapeless khác và các công cụ tệp và shell tích hợp của Droid đều bị đánh dấu là bị chặn. 'MCP:scrapeless' cho phép tất cả 25 công cụ Scrapeless thay vào đó, và --add-tools và --remove-tools chấp nhận cùng các bộ chọn đó.

Nội dung trang trong kết quả là xác nhận. Với một khóa kém, cuộc gọi cùng vẫn trả về HTTP 200, và văn bản kết quả bắt đầu bằng Failed to fetch data; Scrapeless không đánh dấu điều đó là một lỗi MCP, vì vậy hãy đọc văn bản thay vì trạng thái.

Để biết thêm về máy chủ, thông báo Scrapeless MCP server bao gồm những gì nó tiết lộ và hướng dẫn tích hợp MCP của chúng tôi so sánh cách các đại lý truy cập vào trình duyệt. Tài liệu Browser MCP có tham chiếu cấu hình, trang Scraping API mô tả các nhân vật đứng sau các công cụ, và bảng giá liệt kê chi phí của một cuộc gọi.

Kết luận

Thêm Scrapeless vào Droid chỉ là một lệnh. Giữ cho thiết lập đáng tin cậy phụ thuộc vào những gì droid mcp list có thể và không thể thấy: tham chiếu ${SCRAPELESS_API_KEY} được bao bọc cho phép Droid định danh một biến thiếu, --no-oauth chuyển một lỗi tiêu đề thành một thất bại thay vì một yêu cầu đăng nhập, và chỉ một lệnh gọi công cụ, không phải trạng thái connected, chứng minh khóa hoạt động.

Đặt tham chiếu bao bọc trong một dự án .factory/mcp.json và toàn bộ nhóm nhận được máy chủ mà không ai phải cam kết một khóa.

Sẵn sàng để cho Droid xem trực tiếp web? Bắt đầu với kế hoạch Scrapeless miễn phí và thêm máy chủ.

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

Q: Làm thế nào để tôi thêm một máy chủ MCP từ xa với một khóa API vào Factory Droid?

Chạy droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth. Mục nhập đi vào ~/.factory/mcp.json, nơi bạn có thể thay thế khóa tường minh bằng ${SCRAPELESS_API_KEY}.

Q: Droid có mở rộng các biến môi trường trong các tiêu đề MCP không?

Có, ở dạng được bao bọc. ${SCRAPELESS_API_KEY} được thay thế bằng giá trị của biến, và một biến chưa thiết lập tạo ra một trạng thái thất bại mà xác định nó. Một $SCRAPELESS_API_KEY trần được gửi dưới dạng văn bản literal.
Q: Tại sao danh sách droid mcp lại cần xác thực?

Máy chủ trả về mã 401 khi OAuth được bật, vì vậy Droid cung cấp một tùy chọn đăng nhập. Đối với Scrapeless, điều này gần như luôn có nghĩa là một tiêu đề Authorization: Bearer. Sử dụng x-api-token và thêm --no-oauth; việc chạy /mcp không thể sửa chữa sự không khớp của tiêu đề.

Q: Sự khác biệt giữa ~/.factory/mcp.json và .factory/mcp.json là gì?

~/.factory/mcp.json là cấu hình người dùng của bạn và áp dụng cho mọi dự án. .factory/mcp.json trong một kho lưu trữ áp dụng cho dự án đó, xuất hiện dưới dạng [project] trong droid mcp list, và có thể được cam kết miễn là khóa đó là một tham chiếu ${SCRAPELESS_API_KEY}.

Q: Liên kết có nghĩa là khóa Scrapeless của tôi hợp lệ?

Không. Bắt tay Scrapeless chấp nhận bất kỳ giá trị x-api-token không rỗng nào, vì vậy một khóa sai cũng được liệt kê là connected. Một công cụ gọi trả về nội dung trang là bằng chứng; một khóa xấu trả về văn bản bắt đầu bằng Failed to fetch data.

Q: Làm thế nào để tôi giới hạn một lần chạy exec droid chỉ với các công cụ Scrapeless?

Truyền --only-tools 'MCP:scrapeless' cho mỗi công cụ Scrapeless, hoặc 'MCP:scrapeless/scrape_markdown' cho một cái, cùng với --auto high, mà một cuộc gọi công cụ MCP cần. --add-tools và --remove-tools sử dụng cùng một bộ chọn.

Q: Làm thế nào để tôi xóa máy chủ Scrapeless khỏi Droid?

Chạy droid mcp remove scrapeless. Lệnh này xóa mục khỏi tệp cấu hình định nghĩa nó.