Bỏ qua để đến nội dung
Oleaflyv0.4.12

Kết nối

Kết nối Claude Desktop, Claude Code, Cursor, Codex hoặc một MCP client khác với các công cụ dự án cục bộ của Oleafly.

Oleafly có thể hoạt động như một máy chủ MCP (Model Context Protocol). Các MCP client như Claude Desktop, Claude Code, Cursor, Codex và Grok CLI có thể đọc, chỉnh sửa, tìm kiếm và biên dịch một dự án Oleafly. Bạn không cần khóa nhà cung cấp AI trong Oleafly vì client cung cấp mô hình.

Đây là lựa chọn khi bạn đã có thuê bao Claude (hoặc tương tự) và muốn ứng dụng trò chuyện đó điều khiển Oleafly, mà không cần dán khóa API vào Settings.

MCP theo cả hai chiềuTheo một chiều, một ứng dụng khách MCP trên máy tính của bạn, như Claude Desktop, Cursor hoặc Codex, kết nối đến máy chủ MCP của Oleafly tại 127.0.0.1 bằng một token bearer. Nó có thể đọc, chỉnh sửa và biên dịch dự án, và chính sách phê duyệt của bạn quyết định thay đổi nào phải chờ bạn. Theo chiều ngược lại, trợ lý tích hợp của Oleafly dùng công cụ từ các máy chủ MCP bạn thêm vào: một máy chủ cục bộ chạy một lệnh, hoặc một máy chủ từ xa tại một URL.Ứng dụng khách MCP của bạn dùng công cụ của OleaflyTrợ lý của Oleafly dùng các máy chủ MCP khácỨng dụng khách MCPClaude Desktop,Cursor, CodexOleafly MCPChỉ 127.0.0.1Dự ánĐọc, chỉnh sửa, biên dịchToken bearerPhê duyệtTrợ lýTích hợp trong OleaflyMáy chủ cục bộChạy một lệnhMáy chủ từ xaKết nối đến một URLMCP theo cả hai chiềuTheo một chiều, một ứng dụng khách MCP trên máy tính của bạn, như Claude Desktop, Cursor hoặc Codex, kết nối đến máy chủ MCP của Oleafly tại 127.0.0.1 bằng một token bearer. Nó có thể đọc, chỉnh sửa và biên dịch dự án, và chính sách phê duyệt của bạn quyết định thay đổi nào phải chờ bạn. Theo chiều ngược lại, trợ lý tích hợp của Oleafly dùng công cụ từ các máy chủ MCP bạn thêm vào: một máy chủ cục bộ chạy một lệnh, hoặc một máy chủ từ xa tại một URL.Ứng dụng khách MCP của bạn dùng OleaflyTrợ lý của Oleafly dùng các máy chủỨng dụng khách MCPClaude Desktop, CursorOleafly MCPChỉ 127.0.0.1Dự ánĐọc, chỉnh sửa, biên dịchToken bearerPhê duyệtTrợ lýTích hợp trong OleaflyMáy chủ cục bộChạy một lệnhMáy chủ từ xaKết nối đến một URL
Một ứng dụng khách MCP trên máy tính của bạn truy cập công cụ dự án của Oleafly qua 127.0.0.1 và một token. Theo chiều ngược lại, trợ lý của Oleafly có thể dùng công cụ từ các máy chủ MCP bạn thêm vào.
  1. Mở Settings → Integrations → Oleafly MCP.
  2. Bật công tắc Enable MCP server.

Máy chủ chỉ chạy khi tiến trình Oleafly còn mở. Nó chỉ lắng nghe trên 127.0.0.1, không bao giờ trên mạng cục bộ của bạn. Đóng cửa sổ dự án không dừng máy chủ. Tắt MCP hoặc thoát Oleafly mới dừng được.

Oleafly ưu tiên cổng 5323 (http://127.0.0.1:5323/mcp). Nếu cổng này không khả dụng, máy chủ tự động gắn vào một cổng cục bộ còn trống khác và ghi nhớ nó cho lần khởi động tiếp theo. Settings hiển thị URL đang hoạt động. Nút khởi động lại của Settings dùng lại cổng hiện tại khi có thể hoặc chọn một cổng trống khác.

Settings hiển thị các đoạn mã chép-dán sẵn cho các client phổ biến. Hãy chép URL đang hoạt động vì cổng được chọn có thể khác 5323, sau đó thay <token> bằng bearer token từ Settings (Reveal / Copy).

Cửa sổ terminal
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

Thêm vào claude_desktop_config.json (cầu nối stdio qua mcp-remote, vì Desktop ưu tiên stdio):

{
"mcpServers": {
"oleafly": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]
}
}
}

Mỗi bản phát hành đều có oleafly.mcpb, một tiện ích mở rộng cho Claude Desktop, nên bạn không cần tệp cấu hình hay token. Tải tệp từ bản phát hành mới nhất (mở trong thẻ mới) rồi mở bằng Claude Desktop để cài đặt.

Tiện ích này khởi chạy lệnh oleafly đi kèm ứng dụng và làm việc trên dự án đang mở trong Oleafly, vì vậy hãy để Oleafly chạy và bật máy chủ MCP. Nếu Claude Desktop không tìm thấy lệnh, hãy chọn nó trong phần cài đặt của tiện ích: oleafly-cli trong Oleafly.app/Contents/MacOS trên macOS, hoặc oleafly-cli.exe trong %LOCALAPPDATA%\Oleafly trên Windows.

MCP Registry liệt kê cùng tiện ích này với tên io.github.Oleafly/oleafly.

Trong .cursor/mcp.json (hoặc cấu hình MCP của client bạn):

{
"mcpServers": {
"oleafly": {
"url": "http://127.0.0.1:5323/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}

Trong ~/.grok/config.toml:

[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }

Dùng đoạn mã Codex CLI trong cài đặt Oleafly, đoạn mã này cung cấp cầu nối stdio tới máy chủ đang chạy. Thêm mục vào cấu hình Codex của bạn và dùng URL cùng token đang hoạt động mà Oleafly hiển thị:

~/.codex/config.toml
[mcp_servers.oleafly]
command = "npx"
args = [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]

Cầu nối yêu cầu Node.js và npx. Hãy khởi động lại hoặc kết nối lại client sau khi thay đổi cấu hình của nó.

Tệp mcp.json nằm cạnh dữ liệu Oleafly của bạn (hiển thị trong Settings) chứa cùng URL và token nếu bạn muốn viết script cho việc cài đặt. Nó chỉ được ghi khi máy chủ đang chạy (chế độ 0600 trên Unix) và bị xóa khi máy chủ dừng. Hãy đối xử với nó như bất kỳ bí mật cục bộ nào khác.

Hầu hết các công cụ MCP dùng chung tên và schema với trợ lý trong ứng dụng. Các công cụ khám phá và định tuyến dự án do backend của ứng dụng desktop cung cấp.

Các công cụ nhắm vào dự án đang mở trong ứng dụng khi có dự án khả dụng. Khi một cửa sổ được kết nối, dùng list_projects và open_project để chọn dự án khác.

Sau khi cửa sổ cuối cùng đóng, backend vẫn giữ read_file, list_files và search_project khả dụng. Các thao tác ghi, thay thế, tạo và đổi tên gốc cũng vẫn khả dụng khi chính sách phê duyệt cho phép. Các công cụ này chỉ dùng dự án cuối cùng mà ứng dụng báo, và từ chối lời gọi nếu dự án đó không còn hợp lệ. Chúng không bao giờ đoán từ các dự án khác trong thư viện. Trạng thái, chọn dự án, xóa, biên dịch, nhật ký, kiểm tra PDF, đổi giao diện và các công cụ hình đòi hỏi một cửa sổ được kết nối.

Công cụCông dụng
get_statusPhiên bản Oleafly, dự án đang mở, công cụ tài liệu của nó, tài liệu chính, trạng thái biên dịch gần nhất, và lý do lần biên dịch gần nhất thất bại hoặc không chạy được
list_projectsCác dự án kèm ID, tên, engine, loại, tài liệu chính, dấu thời gian, màu, trạng thái xem trước và lịch sử xuất
open_projectMở một dự án theo id để các công cụ khác nhắm vào nó
list_filesCây tệp của dự án
project_mapDàn ý, nhãn, trích dẫn, macro, đồ thị input, tham chiếu chưa giải quyết
search_projectTìm văn bản trong dự án hiện tại
Công cụCông dụng
read_fileĐọc một tệp của dự án
get_logNhật ký biên dịch gần nhất
get_pdf_textVăn bản trích xuất từ PDF đã biên dịch
verify_pdf_pagesKiểm tra các trang PDF đã kết xuất để tìm lỗi bố cục, từ ảnh trang hoặc văn bản trang

get_pdf_text và verify_pdf_pages đọc PDF cuối cùng mà Oleafly có. Khi lần biên dịch gần nhất thất bại hoặc không chạy được, kết quả của chúng nói rằng PDF đã cũ và lý do, vì nó đến từ một lần biên dịch trước hoặc là bản dở dang từ lần biên dịch thất bại. get_log cũng nói như vậy khi lần biên dịch gần nhất không chạy được, vì khi đó nhật ký của nó là từ một lần biên dịch trước.

Công cụCông dụng
write_fileGhi hoặc ghi đè một tệp
replace_in_fileTìm và thay thế trong một tệp
create_fileTạo một tệp hoặc thư mục
rename_fileĐổi tên hoặc di chuyển một đường dẫn
delete_fileXóa một tệp hoặc thư mục
set_main_docĐặt tài liệu làm điểm vào biên dịch
Công cụCông dụng
compileBiên dịch dự án thành PDF
preview_figureKết xuất riêng một hình và trả về ảnh PNG
insert_figureChèn hình vừa xem trước gần nhất vào tài liệu
load_imageTải một ảnh từ dự án để làm việc với hình

compile cho biết bản dựng có chạy được không, liệt kê các lỗi của nó, cho biết có PDF hay không, và kết thúc bằng phần cuối của nhật ký. Một bản dựng đã hoàn tất cũng báo các cảnh báo của nó. Khi bản dựng không chạy được, không hoàn tất, hoặc cần thứ gì đó nằm ngoài mã nguồn, chẳng hạn một bản cài TeX hoặc một phiên bản Typst chưa có, kết quả nêu lý do và gọi tên cách khắc phục mà Oleafly đang đề xuất cho bạn trong ứng dụng. Công cụ yêu cầu client báo cho bạn biết và để nguyên mã nguồn của bạn. Một lần biên dịch bạn đã dừng được đánh dấu là đã dừng, để client không coi đó là lỗi trong mã. Trợ lý riêng của Oleafly nhận cùng kết quả đó.

Hãy gọi get_status trước để biết dự án là LaTeX, Typst hay Markdown, rồi viết mã nguồn theo định dạng đó. preview_figure và insert_figure hoạt động trong các dự án LaTeX và Typst:

  • Trong LaTeX, hình là mã TikZ được biên dịch trong một tài liệu standalone nhỏ, và insert_figure bọc nó trong môi trường figure.
  • Trong Typst, hình là markup Typst, chẳng hạn một canvas CeTZ hoặc sơ đồ fletcher, được kết xuất bằng phiên bản Typst của dự án. insert_figure bọc nó trong #figure, đặt nhãn ngay sau nó và chuyển các dòng #import của nó lên trên.
  • Trong dự án Markdown, cả hai công cụ đều trả về lỗi và không thay đổi gì.

load_image hoạt động trong mọi dự án.

Công cụCông dụng
toggle_themeChuyển đổi chế độ sáng / tối
Công cụCông dụng
list_skillsLiệt kê các kỹ năng đã cài đặt kèm ID, tên, mô tả và trạng thái bật/tắt
load_skillTải toàn bộ hướng dẫn của một kỹ năng cùng danh sách tệp của nó
read_skill_fileĐọc một tài liệu tham chiếu hoặc script từ thư mục của một kỹ năng

Các công cụ kỹ năng hoạt động ngay sau khi kết nối, mà không cần dự án nào mở và không cần cửa sổ Oleafly. Client thấy mọi kỹ năng hợp lệ, kể cả những kỹ năng đã tắt trong Settings: các công tắc quyết định kỹ năng nào mà chính trợ lý của Oleafly dùng, chứ không quyết định client được đọc gì. Các agent đọc kỹ năng từ thư mục thay vào đó có thể dùng Share skills with other agents on this computer trong Settings → AI Assistant → Skills. Xem Kỹ năng.

Các công cụ này có mặt khi Notes đang bật trong Settings → Experimentation, như Bật Notes mô tả. Chúng làm việc trên các ghi chú của bạn, không phải trên dự án đang mở, và cần một cửa sổ đã kết nối.

Công cụChức năng
list_knowledge_notesLiệt kê các ghi chú của bạn, mới nhất trước, kèm ID, tiêu đề, thẻ gắn nhãn, dự án được liên kết và tóm tắt ngắn. Lọc theo thẻ gắn nhãn hoặc dự án
search_notesTìm kiếm các ghi chú của bạn và trả về ID, tiêu đề, thẻ gắn nhãn, liên kết và các đoạn trích khớp
read_note_by_idĐọc một ghi chú dưới dạng Markdown kèm front matter của nó
today_noteĐọc ghi chú hằng ngày của hôm nay, hoặc tiêu đề mà nó sẽ có nếu chưa tồn tại
list_note_tasksLiệt kê các tác vụ dạng hộp kiểm trong các ghi chú của bạn, ghi chú mới nhất trước. Lọc theo ghi chú và theo còn mở hay đã xong
note_backlinksLiệt kê các ghi chú liên kết đến một ghi chú, kèm văn bản quanh mỗi liên kết
append_to_noteThêm Markdown vào cuối một ghi chú hoặc vào cuối ghi chú hằng ngày của hôm nay
edit_note_sectionViết lại phần của một ghi chú nằm dưới một tiêu đề, hoặc thêm vào cuối phần đó
create_noteTạo một ghi chú với tiêu đề, Markdown, thẻ gắn nhãn và một dự án được liên kết

append_to_note và edit_note_section không ghi vào ghi chú. Các thay đổi của chúng hiển thị trong ghi chú dưới dạng đề xuất cho đến khi bạn chấp nhận chúng trong Oleafly. create_note chờ bạn phê duyệt trong Oleafly, và append_to_note cũng vậy khi nó phải tạo ghi chú hằng ngày của hôm nay trước. Dưới Trust this connection, việc tạo một ghi chú không hỏi. Một ghi chú được chia sẻ qua một máy chủ cộng tác có thể được đọc nhưng không thể thay đổi theo cách này. Read-only gỡ ba công cụ thay đổi ghi chú.

Nhiều MCP client hỏi trước khi gọi một công cụ. Oleafly cũng áp dụng chính sách được chọn trong Settings → Integrations → Oleafly MCP:

  • Confirm every change là mặc định. Các thao tác ghi, đổi tên và xóa hiển thị một thẻ phê duyệt khi một cửa sổ ứng dụng được kết nối. Không có cửa sổ, các thao tác đó bị từ chối vì không có nơi nào hiển thị thẻ.
  • Auto-approve edits, confirm deletes cho phép các thao tác ghi và đổi tên chạy trong backend. Xóa vẫn cần một cửa sổ được kết nối để xác nhận.
  • Trust this connection cho phép các thao tác ghi và đổi tên trong backend chạy mà không cần nhắc từ Oleafly. Xóa vẫn đòi hỏi một cửa sổ được kết nối. Chỉ dùng chính sách này khi bạn tin tưởng client và các kiểm soát phê duyệt riêng của nó.

Hai công tắc nữa hỗ trợ cho việc này:

  • Read-only (công tắc riêng) loại bỏ hoàn toàn các công cụ thay đổi khỏi tools/list, nhờ đó một ứng dụng bên ngoài có thể đọc và biên dịch nhưng không bao giờ chỉnh sửa tệp, bất kể chính sách ở trên.
  • Bearer token: một giá trị ngẫu nhiên 256 bit được lưu trong bộ lưu trữ cục bộ mã hóa có xác thực dưới ~/.oleafly/. Hãy tạo lại nó để vô hiệu hóa các client cũ. Các lần đọc cấu hình chung không bao giờ tiết lộ token. Chỉ các điều khiển kết nối của máy chủ đang chạy mới có thể hiển thị nó trong Settings.

Và hai điều bất biến mà bạn không cấu hình:

  • Localhost only: địa chỉ gắn là 127.0.0.1. Các yêu cầu mang header Origin của trình duyệt bị từ chối, và Host phải là loopback.
  • Project confinement: các công cụ tệp của backend chấp nhận đường dẫn tương đối dự án và giới hạn đường dẫn chuẩn vào dự án mà ứng dụng báo. Một lời gọi công cụ không thể cung cấp ID dự án khác hoặc bắt backend chọn một dự án thư viện khác.

Khi một cửa sổ được kết nối, thẻ MCP activity ghi lại các lời gọi đến. Các lời gọi backend có thể tiếp tục sau khi cửa sổ cuối cùng đóng, nhưng sẽ không có bảng hoạt động hay thẻ phê duyệt cho đến khi một cửa sổ kết nối lại.

Tại sao claude.ai trong trình duyệt không thể kết nối

Phần tiêu đề “Tại sao claude.ai trong trình duyệt không thể kết nối”

Một dịch vụ trò chuyện trên đám mây không thể truy cập 127.0.0.1 trên máy của bạn. Hãy dùng Claude Desktop (hoặc Claude Code, Cursor, v.v.) thay thế. Đừng tạo đường hầm đưa cổng MCP ra internet công cộng: điều đó sẽ cho phép bất kỳ ai có URL chỉnh sửa và xóa các tệp dự án cục bộ của bạn.

Triệu chứngCách khắc phục
Một số công cụ không khả dụngXem trước hình và các công cụ chỉ có trên giao diện khác cần một cửa sổ Oleafly. Hãy mở ứng dụng và dự án, rồi thử lại tools/list.
Cổng khác 5323Cổng ưu tiên không khả dụng nên Oleafly đã chọn một cổng trống. Hãy chép URL đang hoạt động từ Settings.
HTTP 401Token không khớp (ví dụ sau khi Regenerate). Hãy chép token mới vào client.
HTTP 403Client đã gửi header Origin hoặc Host không phải loopback. Hãy dùng MCP client bản địa, không phải thẻ trình duyệt.
Lời gọi quá thời gian chờMỗi lời gọi công cụ chờ tối đa 5 phút (300 s) cho việc biên dịch hoặc cho bạn nhấn Approve. Hãy phê duyệt hoặc từ chối các thẻ đang chờ, hoặc thử lại. Một lần biên dịch có thể mất lâu hơn, tới một giờ với notebook Quarto hoặc Calepin. Nó vẫn tiếp tục chạy trong Oleafly sau khi lời gọi hết thời gian chờ, và các công cụ cần cửa sổ Oleafly sẽ chờ nó, nên hãy để nó hoàn tất trước khi thử lại.
compile trả về một lý do thay vì các lỗiBản dựng không chạy được, chẳng hạn vì chưa cài TeX. Hãy dùng cách khắc phục mà Oleafly đề xuất trong ứng dụng, như cài TinyTeX, rồi biên dịch lại.
Không thể kết nốiOleafly phải đang chạy với MCP được bật. Máy chủ này dừng khi bạn thoát; để dùng công cụ dự án khi ứng dụng đã đóng, hãy kết nối client với oleafly mcp.
Settings → AI Assistant → MCP. Thêm một máy chủ, duyệt registry, hoặc nhập cấu hình từ công cụ khác.
Settings → AI Assistant → MCP. Thêm một máy chủ, duyệt registry, hoặc nhập cấu hình từ công cụ khác. Mở ảnh chụp màn hình đầy đủ

Để cấp thêm công cụ cho trợ lý tích hợp sẵn, hãy mở Settings → AI Assistant → MCP.

  • Browse registry để tìm một máy chủ và xem lại cách thiết lập của nó.
  • Import from other tools để chọn các cấu hình máy chủ sẵn có. Hãy xem lại các mục đã chọn trước khi nhập.
  • Add server để tự nhập một máy chủ, sau đó xác thực kết nối.

Các máy chủ đã kết nối cung cấp công cụ của chúng cho trợ lý. Bạn có thể xem trạng thái kết nối và bật hoặc tắt máy chủ từ cùng một trang. Thông tin đăng nhập và lệnh thuộc về từng cấu hình máy chủ; hãy xem lại chúng trước khi kết nối máy chủ mới.

alphaXiv cũng kết nối như một máy chủ MCP, nhưng bạn thiết lập nó trong Settings → Integrations → alphaXiv bằng khóa API thay vì ở đây. Sau khi kết nối, nó xuất hiện trong danh sách này với tên alphaXiv. Kết nối nguồn nghiên cứu trình bày các bước.

Add server → Form. Chọn Local command hoặc Remote URL, điền các trường kết nối, rồi dùng Add và xác thực.
Add server → Form. Chọn Local command hoặc Remote URL, điền các trường kết nối, rồi dùng Add và xác thực. Mở ảnh chụp màn hình đầy đủ

Trong Settings → AI Assistant → MCP, chọn Add server. Máy chủ cục bộ chạy một lệnh qua stdio; máy chủ từ xa kết nối tới một URL. Biểu mẫu JSON dùng định dạng máy chủ của Oleafly:

Cấu hình máy chủ cục bộ
{
"name": "Research tools",
"enabled": true,
"transport": "stdio",
"command": "your-mcp-server",
"args": ["--stdio"],
"env": {}
}

Thay lệnh và đối số bằng những gì được ghi trong tài liệu của máy chủ bạn đã cài. Các giá trị biến môi trường nằm trong đối tượng env.

Cấu hình máy chủ từ xa
{
"name": "Research service",
"enabled": true,
"transport": "remote",
"url": "https://your-server.example/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

Thay URL và token mẫu bằng thông tin kết nối của dịch vụ. Dùng Validate để kiểm tra kết nối, rồi xem lại các công cụ mà máy chủ cung cấp. Bật hoặc tắt máy chủ từ hàng của nó. Dùng hành động sửa của nó để thay đổi cấu hình và hành động xóa để ngắt kết nối.

Chọn Import from other tools, kiểm tra các cấu hình được phát hiện, và chọn máy chủ bạn muốn. Hãy xem lại đường dẫn tệp thực thi, biến môi trường, URL và thông tin đăng nhập trước khi nhập. Tính năng này nhập các thiết lập kết nối; nó không cài tệp thực thi của máy chủ giúp bạn.

  1. Mở một dự án luyện tập nhỏ trong Oleafly.
  2. Kết nối client bên ngoài bằng đoạn mã đã chép từ ứng dụng.
  3. Yêu cầu client gọi get_status và liệt kê các tệp của dự án.
  4. Yêu cầu nó đọc tài liệu chính và gợi ý một thay đổi tiêu đề.
  5. Xem lại hành động trong Oleafly trước khi phê duyệt một thao tác ghi.
  6. Biên dịch và kiểm tra PDF.

Với một công cụ bên ngoài đã kết nối bên trong Oleafly, hãy bắt đầu bằng một yêu cầu chỉ đọc đơn giản mà máy chủ đó hỗ trợ và kiểm tra thẻ công cụ xuất hiện trong phần trò chuyện.

Xem trước hình ảnh

Không tải được câu trả lời AI

Hãy thử lại, hoặc tìm trong tài liệu.