BBT for BBT 繁體中文

Posted on Nov 7

如何讓 Codex CLI 透過 MCP 讀取 osFoundry 的筆記與知識庫

#codex #mcp #osfoundry #tutorial

完成這篇的設定後，Codex CLI 在你的儲存庫裡工作時，就能自己查閱 osFoundry 專案裡的規格 Note、客服知識庫和 bug Records。它透過 osFoundry 的 MCP 伺服器讀取資料，任何會寫入的動作都會先問過你，而它發出的每一次呼叫，都會列在 osFoundry 裡該連線的 Recent activity（最近活動）下。設定只有三件事：在 ~/.codex/config.toml 加一個 table、在瀏覽器登入一次、點一下把連線加進專案。

誰負責什麼

	Codex 這邊	osFoundry 這邊
登入	平常的 Codex 登入，不變。osFoundry 的 OAuth token 由 Codex 保管	你的 osFoundry 帳號核准連線一次，限一個 workspace
誰執行模型	Codex，在你的機器上，用你自己的 Codex 方案	沒有。這條路徑上沒有模型，也沒有供應商金鑰
工具在哪裡執行	Codex 透過 HTTPS 送出工具呼叫	`api.osfoundry.io` 先檢查存取權限再執行
Codex 看得到哪些工具	`config.toml` 裡的 `enabled_tools` / `disabled_tools`	該連線的 Tools 勾選清單
能碰到什麼	伺服器回傳的內容	你加入此連線的專案，以及你邀請它加入的頻道
核准	Codex 自己的確認提示，由 `default_tools_approval_mode` 決定	GitNest 與 Room 的變更會在「Needs your approval」（待你核准）中等候
資料留在哪裡	回答與 diff 留在你的 Codex 工作階段	筆記、記錄與文章留在 osFoundry。僅限本機的項目永遠不會離開裝置

設定

1. 在 osFoundry 建立連線

點 osFoundry 頁首的鑰匙圖示，打開 Connected 分頁（標題是「Connected agents」，下面顯示目前的 workspace 名稱）。在「Connect in three steps」下方的表單填入：

Assistant：Other MCP client
Display name：你認得出的名字，例如 Codex CLI
點 Add assistant（新增助理）

連線會以「Setup pending. This assistant cannot read or change anything yet.」的狀態出現。複製 Server address：

https://api.osfoundry.io/api/v1/external-mcp

範例：選取了 Codex CLI 連線的 Connected 分頁

2. 把伺服器加到 Codex

OpenAI Codex MCP 文件裡的一行指令：

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

這會寫入一個 [mcp_servers.osfoundry] table。打開 ~/.codex/config.toml 把它收緊。下面每個 key 都在那份文件裡：

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "list_note_tabs",
  "read_note_tab",
  "read_sheet_range",
  "search_knowledge_base",
  "read_knowledge_article",
  "list_record_items",
  "read_record_item",
  "edit_record_item",
]

每一行的作用：

scopes 取代伺服器提供的內容。沒寫的話，Codex 會從伺服器的 challenge 或它的 protected-resource metadata 取得 scope，而 osFoundry 的 metadata 列了四個，其中包括 osfoundry:run。只會讀取和更新記錄的程式助理，不需要執行工作階段的權限。
default_tools_approval_mode = "writes" 讓 Codex 對每個沒有標記為唯讀的工具跳出確認。osFoundry 會在工具上標 readOnlyHint，所以九個讀取工具不需確認就會執行，edit_record_item 則會先問。
enabled_tools 讓工具清單保持精簡。伺服器提供 59 個工具，這份清單只有十個。名稱用的是原始 MCP 工具名稱，不加任何前綴。名稱打錯不會報錯，那個工具只是不會出現。

如果這個伺服器只該在某個儲存庫裡生效，就把同樣的 table 放到那個儲存庫的 .codex/config.toml。Codex 只會讀取你標記為信任（trusted）的專案設定。

3. 登入

codex mcp login osfoundry

瀏覽器會打開 https://osfoundry.io/external-assistant-authorize，標題是「Connect an agent」。畫面上會顯示 Assistant client 和「Returns to」，後者是本機位址，因為 Codex 是在你的機器上接收 callback。接著：

Workspace to connect：選一個。第二個 workspace 需要另建一條連線。
Requested capabilities：使用上面的 scopes，會看到兩行，「Read supported resources in projects you add」和「Change supported resources where you have edit access」。
Connection：選「Use pending: Codex CLI」，讓這次登入綁定到步驟 1 建立的連線。
勾選「I approve connecting this assistant to 」，再點 Connect。

如果是透過 SSH 連進遠端主機，codex mcp login osfoundry --no-browser 會改為印出 URL。在你的筆電上打開它，再把完整的重新導向 URL 貼回終端機即可。

osFoundry 的伺服器有註冊端點，也接受公開用戶端，所以 Codex 會自行註冊，不需要貼上 client ID。

4. 把連線加入專案

回到鑰匙圖示 → Connected，連線現在會顯示「Connected.」。在 Projects 下選擇專案，點 Add to project（加入專案）。這樣就會開放該專案已同步的 Notes、知識庫、Record 頻道、雲端 Rooms、已指派的 GitNest 儲存庫和討論頻道，之後新增的內容也包含在內。其他 Message 頻道則需要各自 Invite（邀請）。

Tools 區塊一開始是「All supported tools are on by default.」。把這條連線永遠不該呼叫的工具取消勾選，這樣就算之後有人修改 config.toml 也一樣有效，然後點 Save tools（儲存工具）。

範例：只勾選讀取工具的 Tools 清單，接著按 Save tools

5. 在 Codex 裡確認

在 codex 的 TUI 輸入 /mcp，會列出啟用中的伺服器，裡面應該要有 osfoundry。接下來直接用一般的話提出需求就行。

實際執行

撰寫本文的機器上沒有安裝 Codex，所以下面的工作階段是模擬的範例。工具名稱是線上伺服器從 tools/list 回傳的名稱。Codex 的原始碼會在模型看到的名稱中，替 MCP 工具加上 mcp__<server>__ 前綴，所以這裡也寫成那個樣子。提示、專案和回答都是示範內容。

範例（模擬）

> tests/test_refund.py 裡失敗的測試預期退款期限是 14 天。
  在改任何東西之前，先查 osFoundry 的規格和客服 KB。

• mcp__osfoundry__list_granted_resources {}
  ← 1 個專案：「Billing v2」
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "退款"}
  ← Note「退款規則（規格）」
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← 分頁：Note（文字）、Sheet「邊界案例」
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← 「退款須於發票日期起 30 天內提出…」
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "退款期限"}
  ← 文章「退款政策」，2 天前更新：30 天
• edited src/billing/refund.py, tests/test_refund.py
• mcp__osfoundry__edit_record_item {"record_channel_id": "…", "item_id": "…",
      "values": {"status": "Fixed"}, "expected_version": "…", "idempotency_key": "…"}
  [Codex 詢問：允許這次工具呼叫嗎？ → 是]
  ← saved

錯的是測試，不是程式碼。規格 Note 和 KB 文章都寫 30 天。
我改了測試和該常數的註解，跑了 pytest（12 個通過），
並把「退款期限差了 16 天」這筆記錄設為 Fixed。

edit_record_item 會帶上 read_record_item 或 list_record_items 回傳的版本，所以如果這段期間有人改過那筆記錄，請求會被拒絕，而不是直接覆蓋。重複的 idempotency_key 會回傳第一次的結果，所以重試的呼叫不會寫入兩次。中間那個核准提示來自 Codex，不是 osFoundry，原因是 default_tools_approval_mode = "writes"。

界線在哪裡

Codex 讀取 osFoundry，osFoundry 不讀取 Codex。這條連線只是讓 Codex 在它判斷需要時呼叫工具。osFoundry 會在 Recent activity 中列出每次呼叫的工具名稱、存取判定和時間，但它無法打開你的 Codex 工作階段、儲存庫或終端機。除非 Codex 把原始碼放進工具參數（例如某筆記錄的留言），否則你的原始碼不會送到任何地方。

兩道篩選各有不同的用途。config.toml 裡的 enabled_tools 決定要提供哪些工具給模型，讓提示保持簡短、選項一目了然。osFoundry 的 Tools 勾選清單是擁有者的開關，不管本機檔案怎麼寫都持續有效。兩者都不會授予任何存取權，那是由專案成員資格決定的。

存取權在每次呼叫時判定。每次呼叫都會比對連線狀態、所屬 workspace、目前的專案成員資格、項目現在所在的專案，以及你本人在該專案中的角色。把 Note 移到別的專案、移除專案，或點 Revoke connection（撤銷連線），即使 token 還沒過期，Codex 的下一次呼叫也會被拒絕。

有些寫入是以提案的形式進行。GitNest 工作、change set、檔案匯入和 pull request 會經過 propose_… 工具，並在 Connected 分頁的「Needs your approval」下列出目標和檔案，等到你點 Approve 或 Decline 為止。Codex 永遠拿不到你的 Git 供應商 token。反正 Codex 手上已經有你的本機 checkout，所以上面的設定範例本來就沒有納入這些工具。

僅限本機的資料留在本機。伺服器的 initialize 回應裡也寫著：「Local-only data is unavailable to cloud clients.」本機 Rooms、本機 Graph 工作階段，以及任何尚未同步的內容，都無法透過這條連線看到。

下一步

把 Codex 指向一個你平常就用來回答問題的知識庫，請它拿 docstring 或錯誤訊息去比對，例如「KB 對這個錯誤的描述，和程式印出來的一樣嗎？」。search_knowledge_base 會回傳文章 ID 和最後更新時間，所以很容易查證出處。osFoundry 如何整理知識庫，請見知識庫頁面。

DEV Community