跳到內容
Oleaflyv0.4.12

連接

把 Claude Desktop、Claude Code、Cursor、Codex 或其他 MCP 用戶端連接到 Oleafly 的本機專案工具。

Oleafly 可以充當 MCP(Model Context Protocol)伺服器。Claude Desktop、Claude Code、Cursor、Codex 和 Grok CLI 這類 MCP 用戶端,可以讀取、編輯、搜尋和編譯 Oleafly 專案。你不需要在 Oleafly 中設定 AI 供應商金鑰,因為模型由用戶端提供。

如果你已經訂閱了 Claude(或類似服務),並且想讓那個聊天應用程式來驅動 Oleafly,而不必把 API 金鑰貼進 設定,就適合用這個方式。

雙向的 MCP一個方向是:你電腦上的 MCP 用戶端,例如 Claude Desktop、Cursor 或 Codex,使用 Bearer 權杖連接到 Oleafly 位於 127.0.0.1 的 MCP 伺服器。它可以讀取、編輯並編譯專案,哪些變更要等你核准,則由你的核准政策決定。另一個方向是:Oleafly 內建的助理使用你新增的 MCP 伺服器所提供的工具,可以是執行指令的本機伺服器,或是位於某個 URL 的遠端伺服器。你的 MCP 用戶端使用 Oleafly 的工具Oleafly 的助理使用其他 MCP 伺服器MCP 用戶端Claude Desktop,Cursor, CodexOleafly MCP僅限 127.0.0.1專案讀取、編輯、編譯Bearer 權杖核准助理內建於 Oleafly本機伺服器執行指令遠端伺服器連接到 URL雙向的 MCP一個方向是:你電腦上的 MCP 用戶端,例如 Claude Desktop、Cursor 或 Codex,使用 Bearer 權杖連接到 Oleafly 位於 127.0.0.1 的 MCP 伺服器。它可以讀取、編輯並編譯專案,哪些變更要等你核准,則由你的核准政策決定。另一個方向是:Oleafly 內建的助理使用你新增的 MCP 伺服器所提供的工具,可以是執行指令的本機伺服器,或是位於某個 URL 的遠端伺服器。你的 MCP 用戶端使用 OleaflyOleafly 的助理使用伺服器MCP 用戶端Claude Desktop, CursorOleafly MCP僅限 127.0.0.1專案讀取、編輯、編譯Bearer 權杖核准助理內建於 Oleafly本機伺服器執行指令遠端伺服器連接到 URL
你電腦上的 MCP 用戶端透過 127.0.0.1 與權杖使用 Oleafly 的專案工具。反過來,Oleafly 的助理可以使用你新增的 MCP 伺服器所提供的工具。
  1. 開啟 設定 → 整合 → Oleafly MCP。
  2. 開啟 啟用 MCP 伺服器。

伺服器只會在 Oleafly 程序開啟期間執行。它只在 127.0.0.1 上接聽,絕不會在你的區域網路上接聽。關閉專案視窗不會停止伺服器。關閉 MCP 或結束 Oleafly 才會。

Oleafly 偏好使用連接埠 5323(http://127.0.0.1:5323/mcp)。如果它無法使用,伺服器會自動綁定另一個空閒的本機連接埠,並儲存起來供下次啟動使用。設定中會顯示目前使用中的 URL。它的重新啟動按鈕會盡可能沿用目前的連接埠,否則選擇另一個空閒的連接埠。

設定中提供常見用戶端可複製貼上的片段。請複製即時的 URL,因為所選的連接埠可能與 5323 不同,然後把 <token> 換成設定中的 bearer 權杖(顯示/複製)。

終端機視窗
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

加入 claude_desktop_config.json(透過 mcp-remote 的 stdio 橋接,因為 Desktop 偏好 stdio):

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

每個版本都附帶 oleafly.mcpb,這是一個 Claude Desktop 擴充功能,因此不需要設定檔或權杖。從最新版本 (在新分頁開啟)下載,用 Claude Desktop 開啟即可安裝。

擴充功能會啟動應用程式內附的 oleafly 指令,並處理 Oleafly 目前開啟的專案,所以請讓 Oleafly 保持執行並開啟 MCP 伺服器。如果 Claude Desktop 找不到該指令,請在擴充功能的設定中手動選擇:macOS 上是 Oleafly.app/Contents/MacOS 中的 oleafly-cli,Windows 上是 %LOCALAPPDATA%\Oleafly 中的 oleafly-cli.exe。

MCP Registry 收錄的同一擴充功能名稱為 io.github.Oleafly/oleafly。

寫入 .cursor/mcp.json(或你的用戶端的 MCP 設定檔):

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

寫入 ~/.grok/config.toml:

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

請使用 Oleafly 設定中的 Codex CLI 片段,它提供連到執行中伺服器的 stdio 橋接。把這個項目加入你的 Codex 設定,並使用 Oleafly 顯示的即時 URL 和權杖:

~/.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"
]

這個橋接需要 Node.js 和 npx。變更用戶端的設定後,請重新啟動或重新連線。

Oleafly 資料旁的 mcp.json 檔案(設定中會顯示)保存了相同的 URL 和權杖,方便你用腳本進行設定。它只會在伺服器執行期間寫入(在 Unix 上權限為 0600),並在伺服器停止時刪除。請像對待其他本機機密一樣對待它。

大多數 MCP 工具的名稱和結構描述,都與應用程式內的助理共用。專案探索和路由工具則由桌面後端提供。

有可用的專案開啟在應用程式中時,工具會以它為目標。有連線的視窗時,請使用 list_projects 和 open_project 選擇另一個專案。

最後一個視窗關閉之後,後端仍會保持 read_file、list_files 和 search_project 可用。在核准政策允許時,原生的寫入、取代、建立和重新命名也仍然可用。這些工具只使用應用程式最後回報的專案,而且如果那個專案已不再有效,就會拒絕該呼叫。它們絕不會從專案庫中的其他專案去猜測。狀態、專案選擇、刪除、編譯、記錄、PDF 檢視、主題變更和圖片工具,都需要有連線的視窗。

工具功能
get_statusOleafly 版本、已開啟的專案、它的文件引擎、主要文件、上次編譯的狀態,以及上次編譯為何失敗或無法執行
list_projects專案,含 ID、名稱、引擎、種類、主要文件、時間戳記、顏色、預覽狀態和匯出記錄
open_project以 id 開啟專案,讓其他工具以它為目標
list_files專案檔案樹
project_map大綱、標籤、引用、巨集、輸入關係圖、未解析的參照
search_project在目前的專案中搜尋文字
工具功能
read_file讀取專案檔案
get_log上次的編譯記錄
get_pdf_text從編譯後的 PDF 擷取的文字
verify_pdf_pages從頁面影像或頁面文字檢查已算繪的 PDF 頁面有沒有版面問題

get_pdf_text 和 verify_pdf_pages 讀取的是 Oleafly 手上最後一份 PDF。上次編譯失敗或無法執行時,它們的結果會說明這份 PDF 已過時以及原因,因為它來自較早的編譯,或是失敗的編譯所留下的不完整檔案。上次編譯無法執行時,get_log 也會這樣說明,因為這時的記錄來自較早的編譯。

工具功能
write_file寫入或覆寫檔案
replace_in_file在檔案內尋找並取代
create_file建立檔案或資料夾
rename_file重新命名或移動路徑
delete_file刪除檔案或資料夾
set_main_doc設定編譯的進入點文件
工具功能
compile把專案編譯成 PDF
preview_figure單獨轉譯一張圖片,並傳回 PNG 影像
insert_figure把最後預覽的圖片插入文件
load_image從專案載入影像,供圖片工作使用

compile 會說明建置是否成功、列出它的錯誤、說明有沒有 PDF,並以記錄檔的最後一部分作結。完成的建置也會回報它的警告。當建置無法執行、沒有完成,或需要原始碼之外的東西(例如沒有安裝的 TeX 或不存在的 Typst 版本)時,結果會給出原因,並指出 Oleafly 在應用程式中提供給你的修正方式。這個工具會請用戶端告訴你,並且不要動你的原始碼。你停止的編譯會標示為已停止,讓用戶端不會把它當成程式碼的錯誤。Oleafly 自己的助理也會得到同樣的結果。

請先呼叫 get_status,了解專案是 LaTeX、Typst 還是 Markdown,再用那種格式寫原始碼。preview_figure 和 insert_figure 可用於 LaTeX 和 Typst 專案:

  • 在 LaTeX 中,圖片是在小型獨立文件中編譯的 TikZ 程式碼,而 insert_figure 會把它包進 figure 環境。
  • 在 Typst 中,圖片是 Typst 標記,例如 CeTZ 畫布或 fletcher 圖表,以專案的 Typst 版本轉譯。insert_figure 會把它包進 #figure,把標籤放在它後面,並把它的 #import 行移到它上方。
  • 在 Markdown 專案中,兩個工具都會傳回錯誤,而且不會更動任何東西。

load_image 在每個專案中都能使用。

工具功能
toggle_theme切換淺色/深色模式
工具功能
list_skills列出已安裝的技能,含它們的 ID、名稱、描述,以及是否已開啟
load_skill載入某個技能的完整指示和它的檔案清單
read_skill_file從技能的資料夾讀取參考資料或腳本

技能工具在連線後立刻就能使用,不需要開啟專案,也不需要 Oleafly 視窗。用戶端會看到每個有效的技能,包括在設定中關閉的技能:這些開關決定的是 Oleafly 自己的助理使用哪些技能,而不是用戶端可以讀取什麼。改為從資料夾讀取技能的代理程式,可以使用 設定 → AI 助理 → 技能 中的 與這台電腦上的其他代理程式共用技能。請參閱 技能。

當 設定 → 實驗功能 中的 筆記 開啟時,就會有這些工具,開啟方式請見開啟筆記。它們處理的是你的筆記,而不是開啟中的專案,而且需要已連接的視窗。

工具功能
list_knowledge_notes列出你的筆記,最新的在前,附有 ID、標題、標籤、連結的專案和簡短摘要。可依標籤或專案篩選
search_notes搜尋你的筆記,並回傳 ID、標題、標籤、連結和符合的片段
read_note_by_id以 Markdown 讀取一則筆記,包含它的 front matter
today_note讀取今天的每日筆記;如果它還不存在,則回傳它將會使用的標題
list_note_tasks列出你的筆記中的核取方塊任務,最新的筆記在前。可依筆記,以及未完成或已完成篩選
note_backlinks列出連結到某則筆記的筆記,並附上每個連結周圍的文字
append_to_note把 Markdown 加到某則筆記或今天的每日筆記的結尾
edit_note_section改寫筆記中某個標題底下的部分,或加到它的結尾
create_note建立一則筆記,包含標題、Markdown、標籤和連結的專案

append_to_note 和 edit_note_section 不會直接寫入筆記。在你於 Oleafly 中接受之前,它們的變更會在筆記中以建議的形式顯示。create_note 會等待你在 Oleafly 中核准,append_to_note 在必須先建立今天的每日筆記時也一樣。在 信任這個連線 下,建立筆記不會詢問。透過協作伺服器共用的筆記可以讀取,但無法用這種方式變更。唯讀 會移除這三個變更筆記的工具。

許多 MCP 用戶端在呼叫工具之前會先詢問。Oleafly 也會套用你在 設定 → 整合 → Oleafly MCP 中選擇的政策:

  • 每項變更都要確認 是預設值。有應用程式視窗連線時,寫入、重新命名和刪除都會顯示核准卡片。沒有視窗時,這些操作會被拒絕,因為沒有地方可以顯示卡片。
  • 自動核准編輯,刪除需確認 讓寫入和重新命名在後端執行。刪除仍需要有連線的視窗來確認。
  • 信任這個連線 讓後端的寫入和重新命名不經 Oleafly 提示就能執行。刪除仍然需要有連線的視窗。只有在你信任用戶端和它自己的核准控制時,才使用這個政策。

另有兩個開關提供支援:

  • 唯讀(獨立的開關)會把會變更內容的工具完全從 tools/list 中移除,所以不論上述政策為何,外部應用程式都只能讀取和編譯,絕不能修改檔案。
  • Bearer 權杖:256 位元的隨機值,存放在 ~/.oleafly/ 下經過驗證的加密本機儲存空間。重新產生它,就能讓舊的用戶端失效。一般的設定讀取絕不會洩漏權杖。只有執行中伺服器的連線控制項,才能在設定中顯示它。

以及兩項你不需要設定的不變條件:

  • 僅限 localhost:綁定位址是 127.0.0.1。帶有瀏覽器 Origin 標頭的請求會被拒絕,而且 Host 必須是 loopback。
  • 專案限制:後端的檔案工具接受相對於專案的路徑,並把規範化的路徑限制在應用程式所回報的專案內。工具呼叫不能提供另一個專案 ID,也不能讓後端選擇專案庫中的不同專案。

有視窗連線時,MCP 活動 分頁會記錄傳入的呼叫。最後一個視窗關閉之後,後端的呼叫可以繼續,但在視窗重新連線之前,不會有活動面板或核准卡片。

雲端聊天服務無法連到你機器上的 127.0.0.1。請改用 Claude Desktop(或 Claude Code、Cursor 等)。不要把 MCP 連接埠穿隧到公開的網際網路:那會讓任何拿到 URL 的人都能編輯和刪除你本機的專案檔案。

症狀可以試試
有些工具無法使用圖片預覽和其他只能用在 UI 的工具需要 Oleafly 視窗。請開啟應用程式和專案,然後重試 tools/list。
連接埠從 5323 改變了偏好的連接埠無法使用,所以 Oleafly 選了一個空閒的。請從設定複製即時的 URL。
HTTP 401權杖不相符(例如重新產生之後)。請把新的權杖複製到用戶端。
HTTP 403用戶端傳送了 Origin 標頭或非 loopback 的 Host。請使用原生的 MCP 用戶端,不要用瀏覽器分頁。
呼叫逾時每次工具呼叫最多會等 5 分鐘(300 秒),讓編譯完成或等你按下核准。請核准或拒絕待處理的卡片,或重試。編譯可能花更久,Quarto 或 Calepin 筆記本最久可達一小時。呼叫逾時之後,它仍會在 Oleafly 中繼續執行,而需要 Oleafly 視窗的工具會等它完成,所以請讓它先跑完再重試。
compile 傳回原因而不是錯誤建置無法執行,例如因為沒有安裝 TeX。請使用 Oleafly 在應用程式中提供的修正方式,例如安裝 TinyTeX,然後再編譯一次。
無法連線Oleafly 必須在執行中且已啟用 MCP。這個伺服器會在你結束時停止;要在應用程式關閉時使用專案工具,請改把用戶端連接到 oleafly mcp。
設定 → AI 助理 → MCP。新增伺服器、瀏覽註冊庫,或從其他工具匯入設定。
設定 → AI 助理 → MCP。新增伺服器、瀏覽註冊庫,或從其他工具匯入設定。 開啟完整螢幕截圖

要讓內建的助理擁有更多工具,請開啟 設定 → AI 助理 → MCP。

  • 瀏覽註冊庫,尋找伺服器並檢視它的設定方式。
  • 從其他工具匯入,選取現有的伺服器設定。匯入之前請檢視所選的項目。
  • 新增伺服器,自己輸入伺服器,然後驗證連線。

已連線的伺服器會把它們的工具提供給助理。你可以在同一頁檢視連線狀態,並啟用或停用伺服器。憑證和指令屬於各伺服器自己的設定;連接新的伺服器之前請先檢視。

alphaXiv 也是以 MCP 伺服器的形式連接,但你是在 設定 → 整合 → alphaXiv 用 API 金鑰設定,而不是在這裡。連接之後,它會以 alphaXiv 之名出現在這份清單中。步驟請見 連接研究來源。

新增伺服器 → 表單。選擇本機指令或遠端 URL,填寫連線欄位,然後使用新增並驗證。
新增伺服器 → 表單。選擇本機指令或遠端 URL,填寫連線欄位,然後使用新增並驗證。 開啟完整螢幕截圖

在 設定 → AI 助理 → MCP 下,選擇 新增伺服器。本機伺服器會透過 stdio 執行指令;遠端伺服器則連到 URL。JSON 表單使用 Oleafly 的伺服器格式:

本機伺服器設定
{
"name": "Research tools",
"enabled": true,
"transport": "stdio",
"command": "your-mcp-server",
"args": ["--stdio"],
"env": {}
}

請把指令和引數換成你所安裝的伺服器文件所記載的內容。環境變數的值屬於 env 物件。

遠端伺服器設定
{
"name": "Research service",
"enabled": true,
"transport": "remote",
"url": "https://your-server.example/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

請把範例的 URL 和權杖換成該服務的連線資訊。使用 驗證 來檢查連線,然後檢視伺服器提供的工具。從伺服器所在的列啟用或停用它。使用它的編輯動作變更設定,使用它的移除動作中斷連接。

選擇 從其他工具匯入,檢視找到的設定,並選取你想要的伺服器。匯入之前,請檢視執行檔路徑、環境變數、URL 和憑證。這只會匯入連線設定;不會替你安裝伺服器的執行檔。

  1. 在 Oleafly 中開啟一個小型的練習專案。
  2. 用從應用程式複製的片段連接外部用戶端。
  3. 請用戶端呼叫 get_status 並列出專案檔案。
  4. 請它讀取主要文件並建議修改標題。
  5. 核准寫入之前,先在 Oleafly 中檢視這個動作。
  6. 編譯並檢查 PDF。

要在 Oleafly 內使用已連接的外部工具,請先從該伺服器支援的簡單唯讀請求開始,並檢視聊天中產生的工具卡片。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。