或許是因為在大型語言模型的強化學習 (RL) 或微調過程中，設計者主要將模型的優化目標聚焦於事實準確性、邏輯連貫性與安全合規上。然而，人類靈魂深層的、非結構性的、詩意的需求，卻很少成為 AI 被深度優化的目標。

幸好，人類歷史上有無數偉大的屬靈導師，他們的作品早已沉澱了千年智慧。既然 AI 缺乏深沉的靈魂維度，我們何不將這些屬靈經典作為 AI 的「記憶」？我決定做一個實驗：透過 RAG (Retrieval-Augmented Generation) 技術，將畢德生(Eugene Peterson) 的牧者智慧和坎培斯 (Thomas à Kempis) 的修院語氣等人的著作注入 AI 的知識庫。

以下就是我一步步用「提示（prompt）」打造我的心靈導師的過程。

從 PDF 到章節：讓經典被「讀懂」

我的第一個挑戰是讓這些經典「讀得懂」。這些智慧都被鎖在一整份龐大的 PDF 檔案裡。我想要的不是把整本書隨機切成幾百個碎片（那會失去語境，像完整的故事被斷章取義），而是要尊重作者，按「章節」來理解。畢竟，一個章節本身就是一個完整的思緒單元。

我寫了幾個prompt，幫我把 PDF 檔案逐章逐節地轉換成 Markdown，並要求它務必保留原文的語氣，一個字都不許亂改。拿到初稿後，我又讓 AI 幫我按章切分檔案，確保每一個檔案都是一個獨立的、帶有語義完整性的「記憶」單元。這是 RAG 系統穩定的基礎。

建立心靈圖書館：Chroma 與索引卡

接下來，我需要一個「圖書館」來存放這些珍貴的章節。我選擇了 Chroma 雲端服務，主要是看中它的免費額度與免維護特性（不用自己維護database）。

我又請 AI 幫我生成了一個簡單的 Python 腳本。這個腳本走訪每個章節檔案，並在寫入 Chroma collection 時，一併附上「書名」和「章名」這兩個關鍵的「標籤」（Metadata）。這就像給每一段智慧語錄都貼上了一張清晰的索引卡，確保未來檢索時能精確找到出處。

給 AI 戴上導師的帽子

參考指令

Build a FastAPI RAG chatbot that serves a small Tailwind frontend at /chat. Use Python 3.11, FastAPI, httpx, ChromaDB (cloud client) for embeddings retrieval, and LM

Studio’s OpenAI-compatible local API for generation. Requirements:

• Env vars: CHROMA_API_KEY, CHROMA_TENANT, CHROMA_DATABASE (default “dev”), LM_STUDIO_BASE_URL (default http://host.docker.internal:1234), LM_STUDIO_CHAT_MODEL (default openai/gpt-oss-20b).

• Retrieval: top_k with default 7, cap 8; allocate fairly across collections. Max context per doc 1200 chars. Response length presets: short/medium/long with approximate char targets.

• Chat endpoint POST /chat: accepts messages [{role, content}], top_k, collections, response_length; returns reply plus sources (collection, label, filename, distance).

現在，我的「圖書館」有了，就需要一位「館長」來處理請求。我再次使用提示，請 AI 幫我搭建一個 FastAPI 伺服器作為後端。這位「館長」的任務很明確：

1. 根據使用者選擇的導師，到圖書館裡檢索出最相似的幾段經文。

2. 把這些經文優雅地彙整成一個「上下文」。

3. 最關鍵的是：它必須在這個上下文中，要求回應模型使用「屬靈導師的口吻」，溫柔、沉穩，並明確標註來源章節。

4. 最後一條戒律：如果圖書館裡找不到相關內容，它絕對不能亂編，必須坦誠告知。

我就是在 AI 給出的骨架上，補足了錯誤處理和細節配置，讓它能順利將檢索到的智慧，送往我的本機推理模型進行「解讀」。

本機模型

我把語言模型跑在我自己的 Mac 上，搭配 LM Studio 與 MLX FP4 量化模型。

前端：

為了簡單的自己實驗整個Rag建置，我沒有使用既有的聊天框架，想看看 Codex 能不能理解我的概念，幫我兜出整個前端。看起來完全難不倒 Codex: https://github.com/schwannden/spiritual-director-chat

實驗：人格分離，讓導師的聲音更純淨

玩了一陣子後，我發現自己貪心了。我不想只有一位導師，我想能自由切換「畢德生的牧者語氣」和「坎培斯的修院語氣」，讓我可以看看中世紀的智慧跟當代牧者的差異。

於是我回頭修改提示，加入了「人格 (Persona) 分離」的設計。我讓前端增加了一個下拉選單，後端則會根據我的選擇，只去查對應的資料庫，或是將兩本書的上下文合併。更精確的系統提示，確保模型在回應時能保持選定導師獨有的語氣，避免兩位聖賢的聲音「混音」，讓指引更為純淨清晰。

參考指令

Evolve the existing RAG chatbot to support two distinct personas tied to the collections. Requirements:

• Collections stay “on-living-well” and “imitatio-christi”, but add persona-aware voices.

• on-living-well → Eugene Peterson: warm, pastoral, conversational.

• imitatio-christi → Thomas à Kempis: reflective, devotional, humble.

• both → blend the two voices naturally.

• Update the system prompt generation so the tone changes based on selected collections; keep the default to on-living-well when none provided.

• Keep retrieval/top_k logic intact; if “both” is requested, spread top_k across collections as before.

拿同一個問題，選擇不同的屬靈經典作為依據回答，AI確實可以開始模仿我們要他成為的人。

在這個小小的實驗室裡，我看到了不同世代屬靈智慧的差異：

• 當我選中畢德生的近代屬靈智慧時，導師的回應帶著一種溫柔的基調，教我們溫柔地對待自己，看重平凡與日常中的恩典。

• 當我切換到坎培斯的中世紀修院智慧時，回應則轉為一種更嚴謹、更克制的語氣，提醒我們要忘我、要捨己，將目光專注於更高遠的目標。

最終的反思：有限的科技，無限的生命

這個 RAG 實驗雖然成功地讓 AI 穿上了「屬靈導師」的外衣，但它也讓我更清楚地意識到：AI 在心靈領域能提供的幫助，終究是極其有限的。說到底，這次的嘗試，本質上只是想看看 AI 能否至少精確地模仿我喜歡的作者語氣，同時順便測試一些好用且免費的開源工具（如 Chroma、LM Studio）。

真正的屬靈指引，其困難度遠超於此。它沒有固定的 SOP 或一套通用的語氣。面對同一個問題，一位屬靈導師必須深知對方的光景與時代盲點，才能準確回應：究竟是該挑戰、安慰、責備，還是僅僅是單純地陪伴、禱告與聆聽？這一切，都需要建立在愛的關係、順服的關係、長時間累積的理解，以及在關係中不斷加深的認識。

因此，這個系統的最佳定位，是作為一本經典導讀工具，而非一位真正的導師。它為我們打開了一扇門，讓我們更貼近那些偉大靈魂的文字，但通往心靈深處的道路，依舊需要我們自己投入真實的生命與關係。

I wanted a Claude Code–style coding buddy that runs 100% locally on my MacBook Pro: no API keys, no cloud costs, and fast on Apple Silicon. After a short detour with MLX Knife, the winning combo was:

• LM Studio for a local, OpenAI-compatible API server

• GPT-OSS-20B (MXFP4) as the model

• OpenCode as the terminal coding agent

Below is exactly what I ran and clicked, plus the one config file that makes it all gel.

tl;dr (copy-paste)

# 1) Install LM Studio (GUI + local API server)
brew install --cask lm-studio

# 2) (Optional) launch LM Studio from terminal
open -a “LM Studio”

# 👉 In LM Studio UI:
# - Start the Local Server (Runtimes → Developer) until it says:
#   Reachable at http://127.0.0.1:1234
# - Load the model: gpt-oss-20b (MLX / MXFP4)
# - Turn the Context Length slider way up (OpenCode uses long prompts)

# 3) Quick API smoke test (expects LM Studio at :1234)
curl http://127.0.0.1:1234/v1/models
curl -s -X POST “http://127.0.0.1:1234/v1/chat/completions” \
  -H “Content-Type: application/json” -H “Authorization: Bearer EMPTY” \
  -d ‘{
    “model”: “gpt-oss-20b”,
    “messages”: [{”role”:”user”,”content”:”Say hi in one sentence.”}]
  }’ | jq .

# 4) Install OpenCode (terminal coding agent)
brew install sst/tap/opencode

# 5) Create OpenCode config (provider → LM Studio, model → gpt-oss-20b)
mkdir -p ./.opencode
cat > ./.opencode/opencode.json <<’JSON’
{
  “$schema”: “https://opencode.ai/config.json”,
  “provider”: {
    “lmstudio”: {
      “npm”: “@ai-sdk/openai-compatible”,
      “name”: “LM Studio (local)”,
      “options”: {
        “baseURL”: “http://127.0.0.1:1234/v1”,
        “apiKey”: “EMPTY”
      },
      “models”: {
        “gpt-oss-20b”: { “name”: “gpt-oss-20b” }
      }
    }
  },
  “model”: “lmstudio/gpt-oss-20b”
}
JSON

# 6) Run it 🚀
opencode

The longer story

I set out to recreate the “talk to your editor” workflow, but fully local. I first tried MLX Knife to host an OpenAI-compatible server on http://127.0.0.1:8000/v1. It did spin up—and even had a tiny simple_chat.html—but OpenCode needed a few API behaviors the server didn’t fully cover. Specifically, I ran into OpenAI-compat mismatches (e.g., JSON field naming) and a missing embeddings endpoint, which some clients expect. Those gaps are tracked in the project’s issues, so it may work out of the box later; it just didn’t for my setup today. (GitHub)

So I pivoted to LM Studio, which exposes the familiar OpenAI-like endpoints (/v1/models, /v1/chat/completions, /v1/completions, /v1/embeddings) on a local server—by default reachable at http://127.0.0.1:1234/v1. That instantly clicked with OpenCode. (LM Studio)

step-by-step (with a couple of gotchas I hit)

1) install LM Studio

brew install --cask lm-studio
open -a “LM Studio”

2) start the local server + load the model

In LM Studio:

• Go to Runtimes → Developer and toggle the server to Running. You should see Reachable at

http://127.0.0.1:1234

• and a list of supported OpenAI-like endpoints. (LM Studio)

• Load gpt-oss-20b (your screenshots show the MLX format with MXFP4 quantization).

• Important: drag the Context Length slider way up (your pic showed support up to 131072). OpenCode sends longer task prompts than a normal chat; with a tiny context window, tools won’t run well.

3) smoke test the API

curl http://127.0.0.1:1234/v1/models

curl -s -X POST “http://127.0.0.1:1234/v1/chat/completions” \
  -H “Content-Type: application/json” -H “Authorization: Bearer EMPTY” \
  -d ‘{
    “model”: “gpt-oss-20b”,
    “messages”: [{”role”:”user”,”content”:”Quick smoke test.”}]
  }’ | jq .

LM Studio speaks OpenAI-compatible JSON on those endpoints, so this should stream back a response. (LM Studio)

4) install OpenCode

brew install sst/tap/opencode

(Official install paths—brew and script—are in their docs/readme.) (opencode.ai)

5) point OpenCode at LM Studio (one config file)

I used a provider pointing to LM Studio’s baseURL. The config below is exactly what I run:

{
  “$schema”: “https://opencode.ai/config.json”,
  “provider”: {
    “lmstudio”: {
      “npm”: “@ai-sdk/openai-compatible”,
      “name”: “LM Studio (local)”,
      “options”: { “baseURL”: “http://127.0.0.1:1234/v1” },
      “models”: { “gpt-oss-20b”: { “name”: “gpt-oss-20b” } }
    }
  },
  “model”: “lmstudio/gpt-oss-20b”
}

Docs show exactly this pattern for OpenAI-compatible providers (custom baseURL, map of models). (opencode.ai)

Then put it in ~/.opencode/opencode.json

Once OpenCode boots, I select the model and start giving it real dev work (“set up a Go REST handler + Makefile and explain each change”), and it runs entirely through LM Studio locally.

what it’s like in practice

With LM Studio + OpenCode, the workflow feels like Claude Code in my terminal—edits, diffs, planning, and “do-this-then-that” loops—entirely offline. On my MacBook Pro, GPT-OSS-20B (MXFP4) is a sweet spot: strong reasoning, reasonable VRAM/RAM footprint, and it keeps up with iterative coding.

Final Note

Here are the reasons why I choose the tech stack:

• reasoning capability
  GPT-OSS-20B is a mixture-of-experts (MoE) model. Even though it has 20B parameters in total, only a subset of experts activate per request. This design gives it strong reasoning skills without needing to run all 20B parameters at once.

• runtime memory efficiency
  Because MoE only “turns on” part of the model each step, the effective compute is closer to ~3–4B active parameters. That keeps memory usage low enough to run smoothly on a MacBook Pro instead of a datacenter GPU.

• mlx optimization
  The model comes in MLX format, which is Apple’s deep learning framework optimized for M-series chips. MLX takes advantage of Apple Silicon’s GPU and memory architecture, so inference runs faster and more efficiently compared to generic formats.

• quantization (MXFP4)
  The weights are stored in MXFP4, a 4-bit floating-point quantization scheme supported natively in MLX. This drastically reduces the model’s footprint on disk and in RAM, while still preserving reasoning quality. In practice, this means GPT-OSS-20B (MXFP4) fits comfortably in ~12 GB, perfect for laptop use.

I suppose LM Studio could easily be swapped for something else that support MLX optimization. And open code can be swapped for something like goose too. Try and play with your favorite tool! The horizon for edge AI is getting closer and closer.

references

• LM Studio OpenAI-like endpoints: /v1/models, /v1/chat/completions, /v1/completions, /v1/embeddings. (LM Studio)

• LM Studio via Homebrew cask (install line). (Homebrew Formulae)

• OpenCode providers/config (custom OpenAI-compatible baseURL). (opencode.ai)

• MLX Knife issues illustrating why I switched (format mismatch & missing embeddings). (GitHub)

網址：prayer.simtaiwan.org

一頓午餐完成的 PoC

那天午餐的時候，SIM 的 Roger 突然問我：「能不能找個時間聊聊？」
我心想反正我帶著電腦，就說：「不如現在就開始吧。」
他有點驚訝，本來以為要先交通想法、評估困難度，沒想到我們就直接開工了。

一小時以後，網站圓形大致完成。但是從看起來完成，到一個專業可維護的上線網站，中間還發生了什麼事呢？

從原型到正式上線

PoC 雖快，但要真正上線還有幾個關卡。

Github Pages 提升效能

Lovable 的痛點在於 loading 太慢。所以我把專案接上 Github，利用 Github Pages 來發佈，效能直接提升。Loading的時間從3秒鐘降到幾百毫秒。
但這裡有個坑：因為我們是 SPA（Single Page Application），直接放在 Github Pages 會遇到 routing 問題。

上傳到 Github Pages 的時候，會遇到一個特別的麻煩：SPA（Single Page Application）本身的路由，會被 Github Pages 的內建 routing 擋住。原因是這樣的：

• 在 React Router（或 Vue Router）裡，/prayer/123 其實只是由前端解讀的虛擬路由。

• 但 Github Pages 不是這樣想，它會真的去伺服器裡找 /prayer/123 這個資料夾或檔案。

• 找不到？那就直接回 404。

換句話說，Github Pages 的靜態檔案伺服器 router，會先攔截掉 request，導致 React Router 根本沒機會處理。

Workaround：Custom 404 Redirect

解法是我們自己做一個 客製化的 404 頁面：

1. 使用者打 /prayer/123 → Github Pages 找不到 → 跳到我們的 404.html。

2. 在 404.html 裡，我們把當前的 path、query parameter、hash 都記下來。

3. 接著用 JavaScript 把使用者導回 /（root）。

4. 這時候 React Router 接手，讀到剛剛傳過來的路由資訊，再判斷該顯示哪一個頁面。

自訂網域 & Cloudflare

接著，我們需要一個好記的網址。SIM 的 IT 幫忙在 DNS 加了 CNAME，指到 Github Pages。再透過 Cloudflare 設定 Custom Domain，就能用上 prayer.simtaiwan.org (請看Github官方教學)。

Supabase 帳號切換

由於我自己的 Supabase 免費額度已經爆掉，所以乾脆用 SIM 的 email 申請新的專案，再邀請我自己進去做管理員，方便長期維護。

工程品質：從 README 到 Release

穩定上線後，專案不只要能跑，更要「可維護」。

1. README / Contributing Guide
   我用 Cursor 和 Claude Code 幫忙生成文件，讓任何後續的同工可以快速上手。

2. CI/CD 品質控管
   設定了 linter、type check、prettier 等自動檢查，避免品質下滑。

3. Dependabot 自動更新
   套件沒有定期更新，是很多專案的主要死因...

4. 版本管理 Conventional Commit + Release Please

這個組合是我在自己的開源專案裡愛上的一套流程。

Conventional Commit 的規範，要求我們在 commit message 裡面加上簡單的前綴：

• feat: → 新功能

• fix: → 修 bug

• docs: → 文件更新

• chore: → 其他雜事
  …還有其他細分。

這樣一來，commit log 不再是「亂糟糟的備忘錄」，而是結構化的資訊。

接著，Release Please 就能讀懂這些規範化的 commit，幫我：

1. 自動產生 CHANGELOG（清楚列出新增、修正、變更）。

2. 自動 bump 版本號（依照 semver：feat 就升 minor，fix 就升 patch）。

3. 自動發 release（甚至能幫忙建 tag、打 package）。

結果就是：我根本不用自己盯著版本號，或擔心 changelog 忘了寫。
整個 release 流程只要點幾下即可完成，特別適合這種公開、要長期維護的專案。

產品思維：從需求翻譯開始

這段過程最有趣的，其實是「需求翻譯」。

Roger 一開始希望上傳兩張圖：一張中文，一張英文。但我建議直接用 i18n（國際化機制），同一張圖就能自動切換語言，不需要兩份檔案。一般使用者在把一個想法轉成網站的時候，會想像把它本來的流程原封不動變成網頁，但是作為設計師我們可以用我們對於網站如何被使用的專業，來協助。

很多使用者其實不知道還有什麼可能性。例如：字體調整，Dark Mode，PWA（安裝成 App）... 等等，這些都是讓手機版更好閱讀的工具。

另外，每一篇禱告到底要是一個popup還是一個獨立頁面？這就跟你有沒有想要讓使用者分享某一篇禱告，還是你只有想要讓使用者分享網頁。這些設計所帶來的使用者習慣區別，都可以溝通清楚～

以上通通只要在 Lovable 聊聊天就完成，完全不用寫 code。真正有價值的地方，就是釐清真實需求。

圖片壓縮：為 20 年後預先設想

另一個潛在問題，是 Supabase 免費空間只有 1G。禱告圖檔一張就好幾 MB，照這樣上傳，五年內就爆掉了。

我先想過請同工壓縮再上傳，但這樣太麻煩，也不現實。最後決定直接在前端用 compressor.js：每張圖在上傳前自動壓到 300kb 左右。這樣 1G 空間至少能撐 50 年，使用者也完全不用改變習慣。

回顧：Vibe Coding 的精髓

Vibe Coding 讓有些人覺得，好像以前那些程式能力都派不上用場了。
但其實不是被取代，而是 「與人互動、溝通、理解」的能力被放大了價值。

社會學者 Bruno Latour 曾提出一個有趣的問題：我們真正關注的究竟是 matter of fact，還是 matter of concern？

• Matter of fact，在這個例子裡，就像是網站本身要用react還是next、PWA該如何實現，style 應該要用 tailwind 還是 styled component。

• Matter of concern，則是我們如何去關注重要的議題：如何與使用者一起挖掘真正重要的功能？這項產品服務的對象是誰？我們做的每一件事情，能不能推動使用者開始關注重要焦點？

在 Vibe Coding 的時代，我相信 系統設計與運維的能力會更加重要，因為這些是基礎建設。但同時，更重要的是：站在使用者角度思考，翻譯他們的需要，真誠地希望做出能幫助人的產品。

網址再次附上 👉 prayer.simtaiwan.org 一起為世界禱告
也歡迎參與貢獻：https://github.com/Fruitful-Tools/sim-weekly-prayers

如果你正在找一份可以安安靜靜寫程式、不需要太多溝通的工作，老實說——Ubiquiti Cloud Team 可能不適合你。

年輕的工程師通常在意的是能不能學習、有沒有人帶；而資深工程師，則更看重領域的深度與發揮空間。這兩種我都理解，也都經歷過。在 Ubiquiti Cloud Team，工作確實不輕鬆，問題通常也不單純。但如果你追求挑戰、在意技術如何帶出產品價值，這裡就是個能讓你不斷磨練、逐步放大的舞台。

一些基本資訊先講清楚：我們使用 GitHub，開發環境現代化，雲平台該用的都有；團隊內部提供各種 AI coding 工具輔助日常開發（包括我本人非常依賴的 ChatGPT, Cursor 和 Claude Code）；工作型態彈性大，遠端、無限假、健身補助。

一切從「真實世界的裝置」開始

Ubiquiti 跟多數純軟體公司不太一樣，我們的雲端服務是為了支援全球各地數以百萬計的實體網通設備：從 AP、路由器、交換器，到監控攝影機、IoT gateway，甚至還有電力供應管理器。這些設備部署在咖啡店、學校、醫院，還有個人的家裡。

我們團隊的任務，就是讓這些設備背後的雲端控制平台穩定又好用。這看起來像是「寫 API、接資料庫、做 UI」這類常見的工作，但實際上，每一段 API call、每一筆資料同步，背後都連動到一個現實世界中正在運作的裝置。我們的思考總是以終為始：這樣做有沒有達到目的，哪些裝置受到影響，部署的策略又是怎麼樣？怎樣做好風險管控？

有些決定做錯了就回不了頭，但是在這裡步調很快，影響的使用者又很廣，我們常常要思考，能不能在可控的風險底下，做出可進可退的決定，怎樣逐步的rollout，怎樣持續監測。

這種「我寫的程式現在就影響到某人家的網路有沒有通」的感覺，很真實、很有壓力，也很有成就感。在這裡工作，沒有所謂的「純工程師」。每個人都在思考架構，思考使用者。

技術風格與文化：高度自主、強調Ownership

Ubiquiti 的文化跟我以前待過的公司都不一樣。

我待過新創，跟著 MoBagel 從10個人成長到70個人。在那裡很多事情都是我說了算，一個晚上就可以生出一條新的產品線。後來在 Dell 400個人的 Global team，在那裡有大量的跨團隊，跨國，跨層級的溝通，還有硬體文化與軟體文化的隔閡要跨越。

Ubiquiti工作的感受在這兩者之間。當然不可能自己說要上一個版本就上（再次強調：我們有上百萬的使用者），但也不會有太誇張的層層的溝通成本。

很多人在面試時都會問：「你們公司的技術文化怎麼樣？」這是一個很常見也很重要的問題，但其實我常常在想——大家口中的「技術文化」到底是什麼意思？

有些人會把技術文化等同於：你們有沒有寫 Unit Test？文件寫得完不完整？PR 有沒有人幫忙 Review？有沒有 CICD？Roadmap 是怎麼規劃的？這些都很實際，也都重要，但我在 Ubiquiti 工作後，有一個更深的體會。

這是我待過技術文化最健康的公司之一。對，問題也還有很多，可以改善的空間還有很多，多到說不完。但是我仍然會說這是我待過技術文化最健康的公司之一。

我們的文件寫得非常完整；測試也不是應付差事，而是真的能幫助維護品質；PR review 非常認真，夥伴們會提供誠懇又具建設性的 feedback，而且這些 review 常常不只是寫法對錯，還包含對系統整體影響的思考。但這一切都不是靠規定、SOP、或是每天 standup 打卡出來的，而是來自大家對於技術品質的高度自我要求。

簡待來說，公司的技術文化，其實是每一個個人貢獻者的堅持與共識底下去創造出來的。

我曾在新創公司當技術研發總監，也在 DELL 那種超過 400 人的全球研發團隊工作過。自己也寫過不少開源專案。我很在意技術文化，但必須說，Ubiquiti 讓我看見的是，技術文化最有效率地推動方式，其實是buttom-up。Hire 對的人，不僅僅是在意的人，而且是可以主動解決問題的人，最後反而大家更加輕鬆。

這樣的文化不是靠「被動適應」能維持的。我們期待加入團隊的人，不只是來享受這個環境，而是能夠「共同維護、甚至改善」這樣的文化。

工程師不只是寫程式，而是參與產品

很多時候，我們不只是「接到 spec 就照做」，而是反過來主動提出：「這樣設計其實對裝置端沒那麼友善」、「我們可以把這個流程拉平，減少使用者等待時間」……這類建議很多時候會被採納，甚至讓產品設計更貼近實際情境。

如果你也好奇 Ubiquiti 的雲端工程文化…

我會說這是一個很適合喜歡 ownership、又不怕面對真實世界 challenge 的工程師來的地方。你會每天被各種新情境刺激大腦，也會學到如何跟 device team、frontend team、support team 一起打造一個「真的會被用、而且被重度使用」的產品。

在這裡，不只是 coding，更多的是思考與設計。而最棒的是，你寫的每一行程式，最終都會ship給上百萬的使用者。我自己家裡跟教會也都換成了整套的Ubiquiti網路設備，這樣方便的可監控性還有靈活的遠端設定，真的是有打中我們這種IT prosumer的心。

When I first started building websites, everything was manual. Spin up a VM, install packages, configure Apache, set up networking—line by line, hoping I didn’t miss a step. It worked, but it was fragile.

Then Docker came along. Suddenly, I could package everything into one neat container. Docker Compose made it even better—I could describe my whole stack in a single YAML file. Kubernetes took it further by orchestrating all the moving parts for me. And when Terraform arrived, it felt like magic: I wasn’t scripting servers anymore, I was declaring what I wanted, and the system figured out the rest.

At the time, I just appreciated the convenience. What I didn’t realize was that I was stepping into a world perfectly suited for AI.

Why Declarative Thinking Matters

Declarative tools like Docker, Kubernetes, and Terraform flip the script. Instead of telling machines how to do something, we describe the end state. The system takes responsibility for figuring out the steps to get there.

Take infrastructure. Back in the old days, I’d write long bash scripts: install Postgres, configure users, set up storage, open the right ports, and hope I hadn’t missed a detail. Every line was an instruction tied to a particular OS, version, or runtime. For an AI trying to understand this, it’s like reading a recipe where half the ingredients are hidden between the lines—you need deep contextual knowledge just to interpret what’s happening.

With Terraform, I can instead declare:

resource "aws_db_instance" "mydb" {
  engine            = "postgres"
  instance_class    = "db.t3.micro"
  allocated_storage = 20
}

That snippet is compact but unambiguous. It says, “I want a Postgres database of this size and type.” AI doesn’t need to parse ten steps of installation logic—it just sees the goal. Because declarative code describes what something is rather than how to do it, it maps naturally onto how AI models understand text: as patterns, relationships, and outcomes.

The same is true in UI. In the old CSS days, I’d have a spaghetti of selectors, nested rules, and overrides—difficult for me to reason about, and almost impossible for an AI to modify without breaking something. But with Tailwind, I can write:

<button className="bg-blue-600 rounded-lg hover:bg-blue-700">
  Submit
</button>

Every class is atomic, precise, and predictable. Change bg-blue-600 to bg-green-600, and the background color only changes—no side effects lurking elsewhere. For an AI, this is huge: it can confidently generate changes knowing the outcome is deterministic.

This is why declarative paradigms are so AI-friendly. They reduce ambiguity, eliminate hidden state, and separate intent from implementation. Instead of reverse-engineering “what the human really meant” from dozens of imperative steps, AI can work directly with clear, human-readable declarations of the desired outcome.

Writing Code That AI Can Understand

Over the years, I’ve noticed that the practices making my code easier for teammates also make it easier for AI. Some practical shifts stand out:

• Vertical slice architecture: Organizing by features instead of layers gives both humans and AI self-contained units of meaning.

• llms.txt files: Just like robots.txt tells crawlers what to do, llms.txt gives AI a roadmap for your project.

• AI-actionable docs: Instead of vague “configure the DB,” I now write: “set DATABASE_URL=postgres://user:pass@host/db.” Instead of writing click this link in the document, we can write run curl -XPOST ... so AI doesn’t guess—it executes.

• Composable components: Smaller, reusable parts reduce the chances of AI (or me) breaking things when making changes.

Toward a Shared Language Between Humans and AI

Looking back, I realize Docker, Compose, K8s, and Terraform weren’t just conveniences. They were rewiring how I think about code. Declarative, modular, predictable—exactly the qualities that make AI collaboration possible.

The shift is bigger than tools. It’s about our role. We’re no longer just code writers. We’re system architects, orchestrating intelligent collaboration between humans and machines.

That’s the real “declarative revolution.” It’s not just how we deploy apps or style UIs—it’s a new way of thinking about programming itself. A shared language between us and AI.

And once you see it that way, it’s hard not to imagine what the next decade of coding will look like.

在沒寫一行 code 的情況下，我使用 lovable 完成了一個有互動、有設計感、有行動體驗的網站，而且只花了 20 分鐘。

成品：https://2025-bible-reading.fruitful-tools.com/

我不是第一次做網頁，但這次是我第一次不用打開 VSCode/Cursor，甚至是一邊單手抱著四個月大的寶寶、一邊語音輸入指令完成的。

🎯 這次的任務：做出一個讀經計畫 Web App

這個網站的目標很簡單：

• 本來就在今年為教會設計了一年 12 個月份的讀經計畫

• 每個月一張讀經卡（正面是計畫，背面是設計圖）。本來列印成酷卡，但是因為數量不足，後來有些人拿不到了，才想說設計成網頁。

• 手機優化、預設繁體中文

這些需求，你交給設計師畫圖、前端寫 code、PM 排進開發時程，可能要 1~2 週才會上線。如果你是很優秀的前端工程師，可能也要花三四個小時。但是我只做了一件事：跟 lovable.dev 說清楚我要什麼。

🧠 怎麼跟 AI 說？我的語音指令長這樣：

please use the following tech stack 
React 19, Tailwind CSS v4, Vite, TypeScript, React Router v7, 
ShadCN/UI, Framer Motion 
 
I wish to create a yearly bible reading plan app, purely frontend. 
I will upload 24 images, 12 as monthly bible reading calendar, 12 are designs related to that month's scope. 
Create a website that has 12 months as 12 cards. 
When a card is clicked, show the calendar png. 
When clicked again, flip the card to show design. 
Make it a web app. 
Greenish design. 
i18n with default to 繁體中文.

其實這第一步的指令，應該是對非工程師來說最困難的地方。因為一開始選擇什麼樣的「網頁技術套件」，會大大影響後續網站的可維護性與延展性。 這邊分享我下的 tech stack 指令。這一段是我以前在帶開發專案時，反覆磨出來的經驗組合 — — 既要現代、要快，又要容易整合元件庫與動畫，也要讓後面維護不頭痛。

這代表：跟工程師問清楚技術架構，描述你想要什麼，AI就能幫你開工。

上面AI沒有尊重我說喜歡綠色，並且要繁體中文的功能。可能一次講太多了，所以提示一下

I wish to have greenish design, 
and I want i18n with default to 繁體中文

中間有個小bug出現，我無腦點一下叫他修，然後就87%完成了。

📦 上傳素材（最近才release的功能）：24 張圖片，AI 自動分類

我事先準備好了 24 張圖：1~12 月份的「讀經表」（正面）與「設計圖」（背面），檔名就是 1.png ~ 24.png。

我跟 AI 說：

I uploaded january's front and back image (1.png and 2.png), 
february is 3.png and 4.png, ...etc

就這樣，它自己處理好了。

🔧 指令微調與問題修正（像在帶專案一樣）

過程中，我發現幾個 UX 問題，於是直接「改需求」：

1. 改進手機 UX：圖片載入時要有明確提示

When I click on the calendar card and there is a pop-up, 
the image is loading in real time, 
but the visual effect is not clear that it’s loading. 
Could you improve the user experience on this issue?

AI 立刻改了，圖片還沒載好時會顯示 loading spinner，避免使用者卡住。

2. 小bug：修正翻頁動畫

upon click month card, the calendar card is shown in the popup. 
I wish to flip to the back side (the design) 
when I click the image in the popup. 
There should be an animation of flipping card

3. 加入「月份解鎖機制」

我希望未來的月份不能點擊，增加一點期待感：

Can you lock each month's card until 1 month before? 
For example, user can not click on September until August.

AI 做到了，還會自動根據目前時間決定哪幾個月可點。

Lovable也把 custom domain 整合的很好，這塊我就不詳述了，請官方文件，基本上也是點一點就出來了。

一個可以 demo 的產品

不到 30 分鐘，我就能拿出一個可以 demo 的 Web App：

• 行動裝置支援好

• 有 loading 狀態

• 卡片翻面動畫自然

• 根據月份解鎖

• 用繁體中文顯示

• 無須後端，Custom domain跟 Cloudflare 整合又方便又快

這個專案的價值不在技術，而在：我們把想法轉為實體產品的門檻，降到前所未有的低。

末了的話

• 給產品經理：POC不用找設計師了，先看看 AI 有沒有懂你吧。

• 給老闆或接案公司：這個世界距離又快又穩又好的日子越來越靠近了。

• 給父母：如果你需要一手抱寶寶，一手寫code，就用講的把網頁講出來吧。不要再害怕生小孩了！

即便透過觀念上的解釋：MCP AI Agent在紅什麼，不自己動手做做看，可能還是很難了解AI Agent到底是什麼。這篇文章手把手教你用MCP Server建制一個AI Agent，連接Goose或者使用Claude Desktop使用你的AI Tool。

(專案代碼在這邊)

建制你的MCP Server專案

安裝uv (python package manager): https://docs.astral.sh/uv/getting-started/installation/，確認你的uv安裝路徑

which uv 
# 我的路徑在 ${HOME}/.local/bin/uv

初始化專案

uv init --package mcp-server-demo 
cd mcp-server-demo 
uv add "mcp[cli]" pydantic loguru faker

使用你的IDE/編輯器創建

# src/mcp_server_demo/server.py 
 
import random 
from loguru import logger 
from mcp.server.fastmcp import FastMCP 
from faker import Faker 
 
fake = Faker() 
 
# Create an MCP server 
mcp = FastMCP("mcp-server-demo") 
 
# Add an addition tool 
@mcp.tool() 
def get_order_info(order_id: str) -> dict: 
    """Get the status of an order""" 
    status = ["success", "delayed", "cancelled", "pending_payment"] 
    order_info = { 
        "order_id": order_id, 
        "status": random.choice(status), 
        "client_email": fake.email(), 
    } 
    logger.info(f"Order info: {order_info}") 
    return order_info 
 
 
@mcp.tool() 
def send_coupon_to_user(order_id: str, customer_email: str) -> str: 
    """Send a coupon to the user to make user happy""" 
    logger.info(f"send coupon to {customer_email} for order {order_id}") 
    return f"Coupon sent to {customer_email}"src/mcp_server_demo/__init__.py

# src/mcp_server_demo/__init__.py 
 
from .server import mcp 
from loguru import logger 
 
def main() -> None: 
    logger.info("Starting MCP server demo") 
    mcp.run() 
 
 
if __name__ == "__main__": 
    main()

# src/mcp_server_demo/__main__.py 
 
from mcp_server_demo import main 
 
main()

測試一下 uv run mcp-server-demo

看到這些訊息就表示成功囉，可以ctrl + C關掉他了

安裝 Goose

從Goose官方文件安裝: https://block.github.io/goose/docs/quickstart

Goose 是一個開源的 MCP 客戶端，讓你可以配置自己的 LLM 提供者（使用 API 金鑰），在自己的機器上運行，並與你的 AI 代理（MCP 伺服器）互動。

如果你沒有任何LLM金鑰，也無法搭載本地的LLM，可以下載 Claude Desktop，用你的免費額度來玩玩看：https://modelcontextprotocol.io/quickstart/user

在Good 上面設定你的 LLM 供應商：https://block.github.io/goose/docs/getting-started/providers

打開Goose設定 -> Add custom extensions

Command那邊要放 {path to uv} run {path to your project}/.venv/bin mcp-server-demo

按Add，可以加入

實際場景

如果我們問了一個不清不楚的問題（沒有提供訂單資訊），透過工具提供的資訊，Goose可以請我們提供詳細資訊

當我們詢問某一筆延遲的訂單，系統主動告訴我們要不要使用coupon工具發放優惠卷，並且使用訂單查到到使用者email進行發放

如果我說好，系統還可以讓我手動審核同意再行動

下一步

看見AI Agent怎樣和Chatbot互動，應該更可以了解AI Agent的價值了吧！傳統軟體開發通常由後端整合第三方服務，前端負責 UI/UX，確保使用者體驗。但這種方式要求開發者掌握所有邏輯，並自行串接各種服務，以維持完整控制權。

隨著生成式 AI（Generative AI）與 AI Agent 的發展，設計思維開始轉變。我們可透過 AI Agent 定義業務邏輯，並透過標準化協議（如 Anthropic 的 Multi-Context Protocol, MCP）管理 AI 與 LLM（大語言模型）的互動。這讓開發者無需關注傳統的後端邏輯與前端開發，而是專注於 AI Agent 的行為設計，讓 AI 自主處理任務。

這種模式提升了開發靈活性，特別適用於快速驗證新想法（Prototype）。開發者只需定義 AI Agent 的核心功能，而無需投入大量時間與資源搭建完整的前後端架構，透過 MCP 標準化的互動，即可快速落地應用。

接著你可以：

1. Fork 專案自己來玩玩看：https://github.com/schwannden/mcp-server-demo

2. 看看 MCP 官方的 Reference Server: https://github.com/modelcontextprotocol/servers

3. 加入Goose Discrod看看其他人在做什麼酷酷的事情：https://discord.com/invite/block-opensource

(This is a chat gpt tranlated article from: https://medium.com/@schwanndenkuo/mcp-ai-agent%E5%9C%A8%E7%B4%85%E4%BB%80%E9%BA%BC-e7fd2523c749)

(If you would rather like to start building your own AI agent, checkout: AI Agent 0 到 1: MCP Server with Goose）

Background Story

As large language models (LLMs) like ChatGPT, Claude, and Gemini continue to evolve and become more powerful, the question arises: where is AI headed in the future? Tech industry leaders such as Andrew Ng, Elon Musk, and Jensen Huang have all pointed out that “AI Agents will be the next major milestone.” But what exactly is an AI Agent?

With more and more LLM providers offering advanced models and applications, we naturally wonder: is there an open and universal protocol that allows us to create AI Agents freely without being locked into a specific platform or provider?

Limitations of LLMs

When we use LLMs like ChatGPT or Claude, we can ask questions and have conversations, but they can’t actually “do” anything. For example, you can’t directly ask ChatGPT to book a restaurant, send an email, or fetch a report from your home NAS.

This is where AI Agents come into play. An AI Agent acts like a personal assistant that not only converses with you but also takes real actions based on your needs. For instance, if you want to know when a particular colleague last logged into your company’s system last month, a standard LLM wouldn’t be able to help because it lacks access to your company’s internal data. However, an AI Agent can accomplish this by calling the company’s internal APIs or querying the database to retrieve the relevant information instantly.

Another limitation of LLMs is that their responses are confined to their pre-trained knowledge. If you ask about a breaking news event or specific business data within your company, an LLM will often be clueless. To address this, we might use Retrieval-Augmented Generation (RAG), which allows an LLM to “look up” additional data before responding. However, RAG works best when dealing with relatively static, infrequently changing data. For real-time or dynamic requests — such as checking the current shipping status of a customer’s order — RAG can be slow and costly.

On the other hand, an AI Agent functions like a real-world assistant that can handle tasks dynamically. If you ask, “Where is my order #12345 right now?” the AI Agent can immediately call your company’s logistics system API to provide a real-time, accurate response.

Summary

• General LLMs act like “knowledgeable encyclopedias” that provide answers based on their training data but cannot take action.

• RAG-enhanced LLMs function as “encyclopedias with a database,” useful for retrieving external data but not ideal for real-time scenarios.

• AI Agents work like “assistants that can take action,” using tools and APIs to solve specific, real-time problems.

Limitations of AI Agents

1. Interoperability Issue:
   With the rise of multiple LLM providers like Claude, Gemini, and OpenAI, AI-powered applications have diversified — from chatbots like ChatGPT to intelligent IDEs like Cursor. However, ensuring that an AI Agent can seamlessly integrate across different platforms is challenging. Ideally, we need a standardized protocol that allows an AI Agent to work flexibly across various platforms without being tied to a specific model or service provider.

2. Limited Adaptability for Automation:
   Traditional AI Agents are designed primarily for human users — meaning they operate step by step based on user commands or predefined workflows. This limits their flexibility when used by other machines (such as client applications or automation services). Ideally, applications should be able to dynamically select and orchestrate different AI Agent tools based on real-time needs, rather than following rigid, pre-scripted sequences.

How MCP (Anthropic’s Model Context Protocol) Solves These Issues

MCP introduces a standardized client-server architecture that effectively addresses these challenges. Developers can focus on creating independent function modules, known as MCP Servers, which handle specific tasks such as sending emails, managing calendars, or performing image recognition. Meanwhile, applications that integrate with LLMs — such as Claude Chatbot or intelligent IDEs like Cursor — act as MCP Clients. These MCP Clients can dynamically explore and identify available functionalities provided by MCP Servers, selecting the most appropriate tools for complex tasks.

This structured collaboration makes AI Agents more interoperable, easier for machines to understand, and seamlessly automatable, enhancing the flexibility and efficiency of the entire AI ecosystem.

Real-World Workflow Example

Imagine you’ve built an AI customer service chatbot using MCP that integrates two tools:

1. Order Tracking Tool — Connects to your company’s database to check order status based on a provided order number.

2. Coupon Issuance Tool — Dynamically decides whether to issue discount coupons if a customer is dissatisfied.

Scenario: A Customer Inquiry

A customer asks the AI chatbot:
“My order #12345 has been delayed for two weeks. Can you check on it for me?”

1. MCP Client (e.g., Claude Chatbot) analyzes the request and determines that it needs external tools to complete the task.

2. It dynamically queries the MCP Server to check what tools are available.

3. The MCP Server responds with a list of available tools and how to use them.

4. The AI decides to first call the Order Tracking Tool, using order number #12345 to check the status.

5. Suppose the response indicates “Shipment delayed, not yet dispatched.”

6. The LLM understands that the customer might be dissatisfied, so it calls the Coupon Issuance Tool to offer compensation.

7. The AI chatbot responds: “Your order is delayed due to a logistics issue. We sincerely apologize for the inconvenience. As a token of our apology, we’re offering you a discount coupon.”

Now, if the order status instead showed “Payment not completed.”

• The AI would not issue a coupon since the issue isn’t a shipping delay.

• Instead, it would respond: “Your order is awaiting payment. Please complete the payment, and we will process the shipment immediately. Thank you!”

In this scenario, we didn’t need to manually code logic for every possible situation. By simply providing MCP Server tools, the LLM itself can dynamically decide which tools to use to resolve issues intelligently.

Frequently Asked Questions (FAQ)

Q: Who developed MCP?

A: MCP was introduced by Anthropic as a protocol that enables AI models to interact more flexibly with external tools. However, MCP is not exclusive to Anthropic’s AI models (e.g., Claude) but is designed as an open, vendor-agnostic standard that any AI model can use.

Q: How does MCP work?

A: The workflow follows these steps:

1. The MCP Client (e.g., Claude, Goose, etc.) sends a request to the MCP Server.

2. The MCP Server responds with available tools, resources, and prompts.

3. The MCP Client determines which tools to use and what data to provide to the AI model to fulfill the user request.

This allows AI to dynamically select and combine different tools to complete tasks more efficiently.

Q: Is MCP limited to Claude?

A: No. While Claude Desktop is an MCP Client developed by Anthropic, MCP itself is not tied to any single AI vendor. For example, Goose is a rapidly growing MCP Client that supports integration with various LLM APIs and features an MCP Server marketplace offering a variety of tools.

Q: Are there security risks with MCP? How can we ensure its security?

A: MCP does not require sending sensitive data to AI models by default. Security depends on how MCP Servers manage data transmission. Best practices include:

• Access control: Restrict API and tool access to prevent data leaks.

• API key management: Securely store and manage API keys to prevent unauthorized access.

• Monitoring and auditing: Track API calls and data access to detect and mitigate security risks.

By following these practices, MCP can be implemented securely while maintaining data integrity.

Useful Resources

• MCP Official Website

• MCP Reference Servers

• List of MCP Clients & Supported Protocol Features

（比起觀念的了解，如果你想要直接動手，請看：AI Agent 0 到 1: MCP Server with Goose）

故事背景

隨著 ChatGPT、Claude、Gemini 等大型語言模型（LLM）不斷推陳出新、能力越來越強大，AI 的未來究竟會往哪裡發展呢？科技圈重量級人物，如 Andrew Ng、Elon Musk 和黃仁勳都紛紛指出：「AI Agent 將會是下一個重要的里程碑。」那麼，大家口中的 AI Agent 到底是什麼呢？

然而，當越來越多 LLM 廠商提供各種強大的模型與應用時，我們不禁好奇：有沒有一個開放且通用的協議（Protocol），能讓我們自由創造各種 AI Agent，而不用擔心被某個特定平台或廠商綁住呢？

傳統軟體開發通常由後端整合第三方服務，前端負責 UI/UX，確保使用者體驗。但這種方式要求開發者掌握所有邏輯，並自行串接各種服務，以維持完整控制權。隨著生成式 AI（Generative AI）與 AI Agent 的發展，設計思維開始轉變。我們可透過 AI Agent 定義業務邏輯，並透過標準化協議（如 Anthropic 的 Multi-Context Protocol, MCP）管理 AI 與 LLM（大語言模型）的互動。這讓開發者無需關注傳統的後端邏輯與前端開發，而是專注於 AI Agent 的行為設計，讓 AI 自主處理任務。這種模式提升了開發靈活性，特別適用於快速驗證新想法（Prototype）。開發者只需定義 AI Agent 的核心功能，而無需投入大量時間與資源搭建完整的前後端架構，透過 MCP 標準化的互動，即可快速落地應用。

LLM的限制

我們平常用 ChatGPT 或 Claude 這些大型語言模型（LLM）時，通常只能問問題或聊天，但沒辦法讓它們真的「做」什麼事。比如說，你不能直接叫 ChatGPT 幫你訂餐廳、寄 email，或去你家 NAS 裡抓一份報告。

這時候，「AI Agent」就派上用場了。AI Agent 就像是一個貼心的小秘書，不僅能和你對話，還能根據你的需求實際「動手做事」。舉例來說，如果你想知道上個月某個同事最後一次登入公司系統是什麼時候，一般的 LLM 是答不出來的，因為它不懂你公司內部的資料。但是 AI Agent 可以做到，它會直接去呼叫公司內部系統的 API 或查詢資料庫，立刻幫你找到準確的紀錄。

另一方面，LLM 的另一個問題是，它回答問題的能力侷限在自己所學過的知識內。如果碰上了最新發生的新聞，或者你自家的業務資訊，LLM 常常束手無策。為了解決這個問題，我們可能會想到 RAG（Retrieval-Augmented Generation，檢索增強生成），讓 LLM 能夠先去「翻閱」額外的資料再回答問題。不過，RAG 適合的情境是資料相對靜態、變動不頻繁的情況。如果你有些即時的、動態的需求（比如即時查詢某個顧客訂單的出貨進度），用 RAG 不只緩慢，還可能成本太高。

而 AI Agent 就像是幫你跑腿的小助手，你只要給它明確的任務，例如：「幫我確認訂單 12345 現在寄到哪裡了？」它會馬上呼叫你公司物流系統的 API，給出即時又正確的答案。

總結一下：

• 一般的 LLM 就像「聰明的萬事通先生」，只能提供他知道的答案，而且只動口，不動手。

• RAG 就像是「帶著資料庫的百科全書」，但資料庫通常比較靜態，不適合需要即時資料的情境。

• AI Agent 則像是「能跑腿、能幫你辦事的小秘書」，根據你提供的特定工具或 API，解決具體、即時的問題。

AI Agent的限制

AI Agent 面臨的第一個限制是「通用性」的問題。隨著越來越多的 LLM 廠商（如 Claude, Gemini, OpenAI 等）湧現，基於這些模型打造的應用程式也越來越多元：從最常見的 Chatbot（如 Claude、ChatGPT）到更複雜的智能 IDE（如 Cursor），我們很難確保自己開發的 AI Agent 能夠無縫地在各種不同的平台或環境中運作。理想上，我們希望有一套標準協議，讓同一個 AI Agent 可以輕鬆地與各個平台整合，不必受限於特定的模型或服務供應商。

AI Agent 面臨的第二個限制，是過去的設計往往只適合讓「人」來使用。使用者指示一步，AI Agent 就執行一步，或者必須按照預先定義好的流程才能運作。這樣的設計對「機器」（例如用戶端應用程式或自動化服務）來說不夠彈性。應用程式難以智能地根據需求動態選用不同的 Agent 工具，更別提自動判斷使用順序。

MCP（Anthropic Model Context Protocol）提供了一個標準化的 Client–Server 架構，完美地解決了這兩個問題。透過 MCP，開發者只需專注於製作各自獨立的功能模組，這些模組稱為 MCP Server，例如發送 Email、管理行事曆或進行圖像辨識等特定任務。另一方面，整合 LLM 的應用程式，例如 Claude Chatbot 或智能 IDE Cursor 等，則扮演 MCP Client 的角色。這些 MCP Client 能夠透過 MCP Server 提供的標準化介面，動態地探索和識別可用的功能與工具，並根據使用者或應用需求智能地排列組合、選擇最合適的工具來完成複雜任務。

透過這種分工與協作的架構，MCP 讓 AI Agent 變得更具通用性，也更加容易被機器理解與自動化整合，使得整個 AI 生態圈能夠更加靈活且高效地運作。

實際的工作流程：

假設今天你透過MCP建立了一個AI客服機器人，它整合了兩個工具：

1. 訂單查詢工具：可以連接你的公司資料庫，根據客戶提供的訂單編號查詢訂單狀態。

2. 優惠券發送工具：當客戶遇到不滿意的情況時，AI能夠動態地決定是否給予折扣優惠券。

1. 一位顧客向AI客服詢問：「我的訂單 #12345 已經兩週了還沒有收到，可以幫我查一下嗎？」

2. 此時MCP Client (例如Claude Chatbot)透過內建的LLM分析使用者需求，知道需要透過工具來完成此任務。它動態地向 MCP Server詢問：「目前有哪些工具可用？」

3. MCP Server 回傳目前可用的工具清單和使用方式給Client。

4. AI判斷後，決定先呼叫訂單查詢工具，透過客戶提供的「#12345」查詢訂單狀態。

假設訂單狀態顯示：「出貨延誤，尚未寄出」。

1. LLM理解顧客可能會因此不滿意，於是動態地決定再透過優惠券發送工具向顧客提供一張優惠券，作為補償。

2. 最終AI客服回覆顧客：「您的訂單因為物流延誤尚未寄出，造成您的不便，我們深感抱歉，特別贈送您一張折扣優惠券以表歉意。」

假設訂單狀態顯示：「尚未付款」。

1. LLM理解此情境並非出貨問題，而是付款問題，因此不會發送優惠券，而是提醒顧客完成付款。

2. 最終AI客服回覆顧客：「您的訂單尚未完成付款，請您完成付款後，我們將立即為您安排出貨，謝謝！」

在這樣的場景中，注意，我們不需要去提供情境判斷的邏輯，只要透過MCP Server提供兩個工具，LLM自己有辦法依照情境判斷要使用哪些工具解決問題。

常見問題

Q：MCP 是由誰開發的？
A：MCP 是由 Anthropic 公司提出的一套協議，目的是讓 AI 模型能夠更靈活地與外部工具互動。不過 MCP 並不限於 Anthropic 自己的 AI 模型（如 Claude），而是開放且獨立於特定 AI 廠商的標準，因此任何符合 MCP 的模型都能搭配使用。

Q：MCP 的工作原理是什麼？
A：MCP 的工作流程大致如下：

1. MCP Client（例如 Claude、Goose 等）會先向 MCP Server 發出請求。

2. MCP Server 會回應並告訴 Client 有哪些工具（tools）、資源（resources）及提示訊息（prompts）可用。

3. MCP Client 根據 Server 提供的資訊，智慧地判斷該使用哪些 API，並決定要提供什麼樣的資料給 AI 模型，以滿足使用者的需求。

透過這樣的架構，AI 能更靈活地自動選擇、組合不同的工具來完成任務。

Q：MCP 是否一定要搭配 Claude 使用？
A：並不一定。Claude Desktop 雖然是 Anthropic 開發的一款 MCP Client，但 MCP 本身並不侷限於任何單一 AI 廠商或模型。我個人推薦可以嘗試 Goose，它是一個近期非常熱門的 MCP Client 實作，不但可以自由接入各家 LLM API Key，團隊也積極發展 MCP Server 市集（Marketplace），提供豐富的工具與資源。

Q：使用 MCP 會有安全風險嗎？該如何確保 MCP 的安全性？
A：MCP 本身並不會強迫將敏感資料傳送到 AI 模型端，而是完全由 MCP Server 決定資料的傳輸範圍。因此，確保 MCP 安全性的重點在於如何設定與管理 MCP Server，具體包含：

• 權限控制：透過細緻的權限管理，嚴格限制每個 API 或工具能存取的資料範圍，防止敏感資料外洩。

• API 金鑰管理：妥善保管 API 金鑰，避免外流，同時採用安全的金鑰儲存與管理機制。

• 監控與記錄：對每一次 API 呼叫與資料存取進行監控，透過定期的記錄與稽核，掌握系統狀態，快速發現與處理潛在的安全問題。

透過以上措施，即可有效控制 MCP 可能的安全風險，保障資料安全性與系統穩定性。

好用資源

1. MCP官方網站

2. MCP Reference Servers

3. MCP Clients 跟每個 Client 目前支援的 protocol範圍

4. 自己動手做一個MCP Server吧

The Challenge of Searching Large Tables in Django Admin

At Ubiquiti, our systems often deal with enormous datasets — tables with over 1 billion records are not uncommon. While Django Admin is a powerful tool for managing and interacting with data, its default search functionality can become a bottleneck in these scenarios. The built-in icontains query used in search_fields scans every column included, leading to sluggish performance as the dataset scales.

Consider a user management table with billions of records:

• We want email prefix search to quickly locate users whose email addresses start with a specific term (e.g., searching for john@domain.com should instantly find matches).

• We also want email alias search that identifies aliases for a given email using regular expressions (e.g., searching for schwannden@gmail.com should also return schwannden+test1@gmail.com and other variants).

• We also want to search user by UUID, using index would be very fast in support cases when we can obtain user’s UUID.

Here’s the catch:

• These two searches are independent use cases by. A regex-based alias search is computationally expensive and shouldn’t be performed unless explicitly needed.

• Django Admin’s get_search_results function only accepts a single search_term, making it impossible to differentiate between the prefix search and alias search.

To make matters worse, adding multiple search fields by overwriting the change_list template doesn’t help because Django passes all queries through the same q=<some search term> parameter, preventing us from distinguishing between search types.

The Solution: Adding Custom Filters for Large Tables

The Django list_filter feature could be an ideal solution for custom filtering logic. However, its default implementation generates choices for filtering, which is impractical for fields like UUIDs or emails where precomputing billions of choices is infeasible.

This problem led us to explore a creative approach to customize the list_filter component and integrate specialized search functionality directly into the Django Admin interface. After much research, we came across a post that inspired us to extend Django’s list_filter to support dynamic input fields for our custom search needs.

Here’s how we implemented it:

Create a Custom Input Filter Template

First, we added a new template to render input fields dynamically in the admin filter area.

Create the file templates/admin/input_filter.html:

{% load i18n %} 
 
<details data-filter-title="{{ title }}" open class="filter-item"> 
    <summary> 
      {% blocktranslate with filter_title=title %} {{ filter_title }} {% endblocktranslate %} 
    </summary> 
    <ul> 
        <li> 
            {% with choices.0 as all_choice %} 
            <form method="GET" action=""> 
                {% for k, v in all_choice.query_parts %} 
                <input type="hidden" name="{{ k }}" value="{{ v }}" /> 
                {% endfor %} 
                <input 
                    type="text" 
                    value="{{ spec.value|default_if_none:'' }}" 
                    name="{{ spec.parameter_name }}"/> 
                {% if not all_choice.selected %} 
                    <strong><a href="{{ all_choice.query_string }}">⨉ {% trans 'Remove' %}</a></strong> 
                {% endif %} 
            </form> 
            {% endwith %} 
        </li> 
    </ul> 
  </details>

2. Define an InputFilter Base Class

Next, we created an InputFilter class to manage custom input fields:

class InputFilter(SimpleListFilter): 
    """ 
    Base class for filters that take a text input 
    """ 
 
    template = "admin/input_filter.html" 
    parameter_name: str 
    title: str 
 
    def lookups(self, request, model_admin): 
        # Dummy, required to show the filter. 
        return ((),) 
 
    def choices(self, changelist): 
        # Grab only the "all" option. 
        all_choices = super().choices(changelist) 
        try: 
            all_choice = next(all_choices) 
            all_choice["query_parts"] = ( 
                (k, v) for k, v in changelist.get_filters_params().items() if k != self.parameter_name 
            ) 
            yield all_choice 
        except StopIteration: 
            return  # Clean exit when no values remain 
 
    def queryset(self, request, queryset): 
        value = self.sanitized_value() 
        if value is not None: 
            return queryset.filter(**{f"{self.parameter_name}": value}) 
        return queryset 
 
    def sanitized_value(self): 
        value = self.value() 
        if value is None: 
            return None 
        return value.strip()

With this base filter, we can now inplement our own filters, we can use parameter_name to overwrite the way we wish query is made, and we could overwrite def queryset to provide more customized search query like finding email aliases.

class UUIDFilter(InputFilter): 
    """ 
    Filter for UUID exact match 
    Ignore filter if the value is not a valid UUID 
    """ 
 
    parameter_name = "id" 
    title = "By User ID" 
 
    def sanitized_value(self): 
        value = super().sanitized_value() 
        if value is None: 
            return None 
        try: 
            return uuid.UUID(value) 
        except ValueError: 
            return None 
 
 
class EmailFilter(InputFilter): 
    """ 
    Filter for email prefix search on the user model itself 
    """ 
 
    parameter_name = "email__startswith" 
    title = "By Email Prefix" 
 
 
class EmailAliasFilter(InputFilter): 
    """ 
    Filter for email alias search 
    For example, "test+alias@example.com" will be matched by "test@example.com" 
    """ 
 
    parameter_name = "email" 
    title = "Search Email Alias" 
 
    def queryset(self, request, queryset): 
        value = self.sanitized_value() 
        if value is not None: 
            split_result = value.split("@") 
            if len(split_result) != 2: 
                return queryset.none() 
            local_part, domain = split_result 
            # Adjust the local part to remove any existing '+' and its suffix 
            local_part = local_part.split("+")[0] 
            regex = rf"{local_part}(\+.+)?@{domain}" 
            return queryset.filter(email__iregex=regex) 
        return queryset

And in our admin model, we can mix this custom filters with built in field filter like:

class UserAdmin(admin.ModelAdmin): 
    list_filter = (UUIDFilter, EmailFilter, EmailAliasFilter, "is_legacy")

The built in choice filter still work on fields with less options.

Reusing filter

Assuming we have another model with a foreign key poiting to User, and we wish to filter this record by its related user’s email, we simply need to inherit from the original EmailFilter and change the parameter_name

class ShoppingCartUserFilter(EmailFilter) 
    parameter_name = "user__email" 
 
class CartAdmin(admin.ModelAdmin): 
    list_filter = [ShoppingCartUserFilter, "cart_type"]

Bravo: A Scalable Solution

This approach transforms Django Admin’s search functionality into a powerful, scalable tool capable of handling massive datasets efficiently. By introducing customizable filters, you can address diverse search scenarios without compromising performance. Whether managing billions of records or implementing tailored search logic, this method ensures your admin remains user-friendly and lightning-fast.

“By wisdom a house is built, and by understanding it is established; by knowledge the rooms are filled with all precious and pleasant riches.”
Proverbs 24:3–4

Today we dive into this obscure exception: Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block.

What Happened

On a sunny Wednesday, we were excited to release a new version of our service to production, which has around 1k~5k active requests per second. As usual, we monitored for unexpected exceptions that happened, and this popped up a few times: Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block.

The root cause was found quickly, a race condition existed in how one of the tables arehandled, but what troubled us was the strange message that was not helping at all!

Our Original Code

class A(Model): 
    id: int 
 
class B(Model): 
    id: int 
    a: OneToOneField(A, on_delete=models.CASCADE) 
 
def send_event(a): 
    print(f"{a.id} deleted") 
 
def delete_a(a): 
    with @transaction.atomic(): 
        try: 
            a.delete() 
            send_event(a) 
        except A.NotFound: 
            pass # it is ok 
        other_db_query()

Note a race condition could already happen, when 2 requests delete the same instance of A, it is likely that we would send the event twice.

A refactor that creates this obscure exception

We thought making send_event into a signal could help make the main business more clear:

class A(Model): 
    id: int 
 
class B(Model): 
    id: int 
    a: OneToOneField(A, on_delete=models.CASCADE) 
 
@receiver(post_delete, sender=B) 
def send_event(b): 
    a = b.a 
    print(f"{a.id} deleted") 
 
def delete_a(a): 
    with @transaction.atomic(): 
        try: 
            a.delete() 
        except A.NotFound: 
            pass # it is ok 
        other_db_query()

What we expected to happen upon a race condition should be

1. Request 1 delete A instance, cascade delete B, triggers signal in send_event

2. Request 2 delete the same A instance, does the same thing, but finishes first.

3. In request 1, send_event should raise A.NotFound in line a = b.a

4. The exception should be handled as disregarded in delete_a try-catch block.

5. Other query should proceed as normal.

But in fact, we receive this Unhandled exception: An error occurred in the current transaction. You can’t execute queries until the end of the ‘atomic’ block. And the line of error happens in some other DB query. Why?

Django’s Official Warning

In Django’s official document: https://docs.djangoproject.com/en/5.1/topics/db/transactions/#controlling-transactions-explicitly

It states that one should Avoid catching exceptions inside atomic!

Why? Because inside an atomic session, when a DB query failed, it not only raises exception, but it mark the transaction state as being corrupted. This is so that during the __exit__ handling of a with transaction.atomic() context, it can properly rollback the session.

In our case, the exception raised from a = b.a is caught indeed! but the atomic session state has been marked as corrupted. So in some other DB query , we have this obscure exception which is not helpful, and took us a long time to find the root cause.

What should be done in this situation?

Following Django’s document suggestion, if we are to handle an exception within a atomic session, it is best to create a nested session and try catch it. This update will fix the issue

@receiver(post_delete, sender=B) 
def send_event(b): 
    try: 
        with transaction.atomic(): 
            a = b.a 
            print(f"{a.id} deleted") 
    except A.NotFound: 
        pass

Since a NotFound exception is not something that actually breaks the database, we let the inner session handles the rollback (which does nothing), and set the session state back to normal, some that later DB query can be executed normally.

Wrapping It All Up: The Art of Taming Transactions

In high-concurrency systems, even caught exceptions can corrupt transactions. Django’s atomic blocks demand careful handling — use nested transactions to isolate risks and follow framework warnings. Resilient code isn’t just functional; it’s designed for real-world complexity. Remember, every obscure error is a chance to learn and improve.

“Unless the Lord builds the house, those who build it labor in vain.”

— Psalm 127:1

Helm and Kustomization: A Tail of K8S Manifests Management

This repository provide examples for you to code and play around for the concepts in the following articles.

It uses a demo backend application that would serve different API result when deployed with different environment variables. It uses k3d to create a k8s cluster in docker (using k3s), and uses justfile as the project interface. Users who have difficult installing justfile may refer to justfile for the equivalent commands for inteeracting with source codes.

The raw Kubernetes YAML declarations are commonly referred to as “Kubernetes manifests” or “Kubernetes YAML manifests.” These manifests are written in YAML,which is a human-readable data serialization format. The manifests define the desired state of Kubernetes resources such as pods, deployments, services, and more. These manifests serves as the programmer’s interface to a kubernetes cluster, with various kubernetes controller taking care of the actual resource (compute, storage, network) provisioning and orchastration logic.

Managing Kubernetes manifests at scale can become challenging, especially when dealing with a large number of YAML files. To address this issue, several tools and techniques have emerged to simplify the management of Kubernetes manifests. Three popular methods are raw YAML, Helm charts, and Kustomize. Let’s discuss each of them in more detail:

Raw YAML: Raw YAML manifests are the basic way of defining Kubernetes resources. Each resource is defined in a separate YAML file, and you apply them using kubectl apply -f <filename>. While this approach is straightforward, it can become cumbersome to manage and maintain a large number of individual files, especially in complex deployments.

Refer to https://github.com/schwannden/helm-and-kustomize/tree/main/raw_yaml to see how to deploy this demo backend with raw YAML files:

kubectl apply -f deployment.yaml -n demo 
kubectl apply -f service.yaml -n demo 
kubectl apply -f ingress.yaml -n demo

With raw YAML manifests

1. It requires manually updating in a complicated yaml file.

2. It requires operaator to update multiple locations if we decide to change some shared values like port, service name, …etc.

3. Not clear to operator as to which values are expose for customization.

Helm charts: Helm is a package manager for Kubernetes that provides a higher-level abstraction for managing applications. It introduces the concept of Helm charts, which are packages containing a set of pre-configured Kubernetes manifests. Helm charts are written in YAML and can encapsulate multiple resources, including deployments, services, config maps, and more. Helm allows you to define templates, values, and hooks, making it easy to parameterize and customize deployments.

Refer to https://github.com/schwannden/helm-and-kustomize/tree/main/chart to see how to deploy this demo backend with a helm chart.

helm install demo-backend . --namespace demo --create-namespace

WIth Helm chart,

1. It is much more convenient to change common values through values.yaml.

2. Shared configuration can be managed with the helm’s templating functions.

But still

1. It is not clear how to solve problems where you need to manage variations of the same application configuration for different environments or teams.

Kustomize: Kustomize is another tool for managing Kubernetes manifests. It is included in the kubectl command-line tool since Kubernetes 1.14. Kustomize allows you to customize and manage Kubernetes resources using overlays and patches without modifying the base manifests directly.

Kustomize uses a directory structure with a base and overlay approach. The base directory contains the original YAML manifests, and overlays contain patches or additional configuration that customize the base resources. Overlays can be used to modify labels, annotations, names, and other fields in the base manifests. With Kustomize, you can manage different configurations and environments without duplicating or modifying the original YAML files.

Refer to https://github.com/schwannden/helm-and-kustomize/tree/main/kustomize to see how to deploy this demo backend with Kustomization

kubectl apply -n demo -k overlays/demo

1. Kustomize works well with version control systems and is especially useful in scenarios where you need to manage variations of the same application configuration for different environments or teams.

2. But Kustomize lacks the version control, installation management features provided by helm.

Indeed, both Kustomize and Helm are valuable tools for managing Kubernetes manifests, and they approach manifest management in different ways. Kustomize focuses on customization and patching of base manifests, while Helm provides a higher-level package management approach.T

here might be scenario where you need the benefits of both, an example to do so with ArgoCD is documented here, but it is a more advanced topic that should not be covered in this article.

In the previous post I explained how to build and host one’s own Airflow image, that would be the top right corner of this architectural diagram.

In another post I also explained a bit about deploying Airflow with Argo CD from official helm chart and use customize to tailor for different environments.

This post aim to run through the whole process again but now entirely on GKE. Having been managing our own airflow for a while, the time for solving hardware and network related issues (not to mention storage class issues) is eating up our devops team resource, and we decide that it is worth the cost to migrate the entire airflow deployment on GKE.

If you decide to use GKE’s Composer, you may skip this tutorial completely, as Composer manages Airflow for you. We decide to host our own Airflow to have more granular control over resources and deployment strategy. This is our architectural setup:

1. Deploy Airflow on GKE Autopilot.

2. Setup GKE Standard cluster for Airflow deployment.

3. Setup Workload Identity so that service accounts in Argo CD can impersonate a service account to operate on Google’s Kubernetes API.

4. Create Argo CD application with proper cluster configuration, and set the destination to external cluster.

Refer to https://github.com/schwannden/argocd-operator and https://github.com/schwannden/airflow-operator to get started, the remaining article is a step by step walk through and explanation.

Deploying Argo CD to GKE Autopilot

Here are the things we need to do to be able to deploy Argo CD on GKE

https://github.com/schwannden/argocd-operator/tree/main/base

1. disable ssl in argocd-server.yaml as we are deploying on to GKE, which means we are setting up ingress and load balancer service on GKE, therefore handling certificate on GKE load balancer.

2. disable https port in service.yaml, same reason as above.

https://github.com/schwannden/argocd-operator/tree/main/overlays/gke

in overlays/gke, we configure google load balancer (frontend, backend, and ingress) in ingress.yaml.

Enable Workload Identity

argocd-operator/workload-identity at main · schwannden/argocd-operator

The steps to enable workload identity are outlined here (codes are in repo):

Variable Definitions (reference: https://github.com/schwannden/argocd-operator/blob/main/workload-identity/.env)

1. GSA_PROJECT: the project to create google service account that would grant GKE access, this should be the project hosting your GKE that host the Argo CD application.

2. GSA_NAME: the name of the service account that will be grating permission to deploy application to target cluster.

3. GKE_PROJECT: the project where you want to allow the Kubernetes service account to impersonate the IAM service account, i.e., the project where you create your GKE cluster and enable is workload identity.

4. NAMESPACE: argocd’s namespace

5. TARGET_PROJECT: the project hosting the destination GKE cluster of your Argo CD application.

Steps in detail:

• Enable GKE’s workload identity
  Enable workload identity for the GKE that deploys Argo CD, refer to official document.

• Create a Google service account

gcloud iam service-accounts create ${GSA_NAME} — project=${GSA_PROJECT}

• Grant the Google service account permission to operate on target GKE

gcloud projects add-iam-policy-binding ${TARGET_PROJECT} \ 
      --member=serviceAccount:${GSA_NAME}@${GSA_PROJECT}.iam.gserviceaccount.com \ 
      --role=roles/container.developer

• Grant the argocd kubernetes service accounts to act as google service account

gcloud iam service-accounts add-iam-policy-binding ${GSA_NAME}@${GSA_PROJECT}.iam.gserviceaccount.com \ 
      --role roles/iam.workloadIdentityUser \ 
      --member "serviceAccount:${GKE_PROJECT}.svc.id.goog[${NAMESPACE}/argocd-application-controller]" 
gcloud iam service-accounts add-iam-policy-binding ${GSA_NAME}@${GSA_PROJECT}.iam.gserviceaccount.com \ 
      --role roles/iam.workloadIdentityUser \ 
      --member "serviceAccount:${GKE_PROJECT}.svc.id.goog[${NAMESPACE}/argocd-server]"

• Annotate the Kubernetes service account with the email address of the IAM service account

kubectl annotate serviceaccount argocd-application-controller --namespace argocd \ 
      iam.gke.io/gcp-service-account=${GSA_NAME}@${GSA_PROJECT}.iam.gserviceaccount.com 
kubectl annotate serviceaccount argocd-server --namespace argocd \ 
      iam.gke.io/gcp-service-account=${GSA_NAME}@${GSA_PROJECT}.iam.gserviceaccount.com

Now you are all set! Your Argo CD can now use workload identity, and the 2 service accounts (argocd-server and argocd-application-controller) now have permission to do so.

Creating Argo CD Application

airflow-operator/cd/overlays/gke at main · schwannden/airflow-operator

With the following application spec you may point destination to your target GKE cluster

apiVersion: argoproj.io/v1alpha1 
kind: Application 
metadata: 
  name: airflow 
  namespace: argocd 
spec: 
  project: default 
  source: 
    repoURL: 'your-airflow-operator-url' 
    path: overlays/production 
    plugin: 
      name: kustomized-helm 
  destination: 
    namespace: airflow 
    server: https://your-gke-endpoint 
  syncPolicy: 
    automated: 
      prune: false 
      selfHeal: false 
    syncOptions: 
      - CreateNamespace=true

And you may supply cluster certificcate to Argo CD as follows

apiVersion: v1 
kind: Secret 
metadata: 
  name: ndpoint-airflow-cluster-secret 
  namespace: argocd 
  labels: 
    argocd.argoproj.io/secret-type: cluster 
type: Opaque 
stringData: 
  name: your-cluster-endpoint 
  server: your-cluster-endpoint 
  config: | 
    { 
      "execProviderConfig": { 
        "command": "argocd-k8s-auth", 
        "args": ["gcp"], 
        "apiVersion": "client.authentication.k8s.io/v1beta1" 
      }, 
      "tlsClientConfig": { 
        "insecure": false, 
        "caData": "your-cluster-certificate-in-base64" 
      } 
    }

Congratulations! You should be able to host your own Airflow!

And let us not grow weary of doing good, for in due season we will reap, if we do not give up.

Happy Hacking!

Our favorite time to solve devops issue with opensource solution have come again, yay~

MoBagel’s 8ndpoint is a platform with multiple micro services to help store owners make better decision about restock, ad performance, customer segments, and repurchase recommendations. Though the platform consists of multiple services, they share very similar deployment technology. For example, we always use Fastapi for backend, and our frontend app is served very similarly, and database technologies are very similar as well.

Helm is a great tool for managing Kubernetes deployment, says their official website:

Helm is the best way to find, share, and use software built for Kubernetes

Helms takes care of the following issues when managing a Kubernetes application:

1. yaml file template language and generation.

2. separating deployment spec (under templates) and configuration (values.yaml).

3. version control: chart’s version control and deployment version control.

4. deployment operation: install, uninstall, upgrade, rollback, status check, …etc.

With Helm and the various services that we need to manage, a way to manage and collaborate on Helm chart is necessary. Let me briefly talk about our Helm Chart structure, and then shares about how we build our public and open sourced helm chart repository.

How MoBagel Structure Helm Charts

As we mentioned, a lot of our micro services share common deployment structure, just different parameters. So we create a public Helm chart repository for MoBagel, and host all common charts on this repository.

Developers can use common charts by adding our repository to helmhelm repo add mobagel https://mobagel.github.io/charts

Since these are generic charts, all information are non-sensitive, we can open source this project. As for our deployment, we will be version controlling all deployment parameters, so we need to use private git repository.

To know more about how to create a helm chart, refer to the well written official document. Here we briefly mention how we use the released public chart in our private deployment charts:

1. In Chart.yaml add public chart as a dependency.

2. Before chart is deployed, run helm dependency build. The parent chart will be installed as a sub chart under the charts folder.

3. Since dependencies become sub charts, we simply overwrite chart values in values.yaml file, but with a added nesting level.# in Chart.yaml
   dependencies:
   - name: fastapi
    version: "0.1.0"
    repository: "https://mobagel.github.io/charts"# In values.yaml
   fastapi:
    ingress:
      enabled: true
      hosts:
        - host: some-custom-host.com
          paths:
            - path: /api
              pathType: Prefix
   ... (put the value override for value.yaml for fastapi chart)

Create Chart Repository Hosting on Github

After understanding how chart dependencies are set up, we still need to create our own repository hosting. The official document introduces several ways of doing so, and I find hosting it on GitHub to be the most convenient.

1. create a repository under your organization, you may name it charts or helm-charts , since this repository will be hosting all your public, shareable charts.

2. Give it a README.md, and create 2 branch: main and gh-pages

3. Go to repository’s Setting > Pages, enable Github Pages and set Source to Deploy from a branch, then set branch to gh-pages .

4. On branch main , create a charts folder, and put your existing helm charts in this folder.

5. On branch main , add a .github/workflows/release.yml file, this file uses chart releaser action to create chart index file and serve it on your github pages.# release.yml
   name: Release Chartson:
    push:
      branches:
        - mainjobs:
    release:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v2
          with:
            fetch-depth: 0- name: Configure Git
          run: |
            git config user.name "$GITHUB_ACTOR"
            git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
        - name: Install Helm
          uses: azure/setup-helm@v1
          with:
            version: v3.8.1- name: Run chart-releaser
          uses: helm/chart-releaser-action@v1.4.0
          env:
            CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

In the last step, the chart releaser will perform the following steps automatically for you:

1. check and compare all charts under charts folder to see if there areany changes.

2. build the charts and release them as GitHub releases (upload chart as artifact) for you.

3. update index.yaml file and serve it on gh-branch page.

After all is setup, people can start adding your chart repository byhelm repo add [org-name] [git page url]

A full and working example is given here: https://github.com/MoBagel/charts

And the chart repository can be added ashelm repo add mobagel https://mobagel.github.io/charts

Enjoy having your own helm charts in a few steps, God bless!

A joyful heart is good medicine, but a broken spirit dries up the bones.

Proverbs 17:22

Airflow with ArgoCD, Kustomize, and Helm — Introducing CI/CD for Our Data Scientist Team

Some prerequisites for following this blog post, include:

1. Basic knowledge of K8s and ArgoCD. I recommend this video to get a landscape of what ArgoCD is.

2. Basic knowledge of Kustomize.

Here is the repository for deploying Airflow on ArgoCD.

Before you start using the repository, you need to have:

1. A running K8s cluster. If you want to get a light-weight K3s cluster up and running, you can check out this online tutorial.

2. If your use case requires a customized Airflow image, that is outside the scope of this article.

The Benefits of Today’s Tools

1. Why Kustomize?

Airflow comes with its nice helm chart, and our team has been using this helm chart for a while to play with Airflow. However, as we are pushing Airflow to production, we need a way to configure an Airflow cluster for development use, and a cluster for production use.

We hope the 2 clusters can accept different configurations on ingress routes, passwords, worker replica, … etc. Using 2 values.yaml files doesn’t seem to be the most elegant approach and not as convenient when we are deploying with ArgoCD. Using different branches also creates problems and results in a bunch of merge conflicts over time. Kustomize seems to solve this deployment configuration issue quite well, and forces us to continue this infrastructure as code culture.

2. Why use ArgoCD?

ArgoCD’s declarative gitops enables a K8s native CD workflow. Without the need to store K8s credentials in our pipeline server (either GitHub or GitLab), our credential management becomes a bit easier.

Architecture and Scenario

Scenario Walk Through:

1. When a data scientist realizes that he/she needs a new dependency from Airflow, they update Airflow image spec, which triggers an automatic build and push new image to Docker Hub (checkout this post for detail).

2. After they have the new image, they can use this image to continuously develop the dags in their own dags repository and create pr on dags repository’s develop branch.

3. Before the dag is deployed, data scientists update Airflow ArgoCD repository to point airflow image to the new image version.

4. ArgoCD picks up the update automatically and updates the develop environment’s Airflow.

5. Data scientist finally merge their code to the develop branch of dags repository.

6. Develop environment’s Airflow picks up dag change, and we are able to run tests on develop environment.

7. After all tests are done, deploy Airflow to production, and merge dags repository’s develop into master branch.

Making Airflow Work on ArgoCD

1. ArgoCD doesn’t work natively with kustomize + Helm chart (i.e., ksutomize --enable-helm), so we need to install a plugin to make yaml file from helm chart. See README for installation instruction. In the plugin, we basically customized yaml spec generation command by kustomize build --enable-helm command.

2. So the approach we took is, we use Kustomize as the main configuration management tool, so we are translating helm chart to Kustomize. In order to do this, we installed a plugin to ArgoCD. If you know of a more elegant approach, please let me know, your suggestions would be much appreciated.

3. In overlays folder, that’s where we make Airflow’s gitSync pull from different branches based on deployment environments.

4. base/kustomization is where we translate helm chart’s job hook related flag to ArgoCD’s hook. Since we are not deploying this with helm but Kustomize, we need these flags so that ArgoCD know when to start these jobs, and how to handle the hook delete policy.

5. For detailed steps, please visit the repository’s README file.

And with that, you’ve crossed another level to becoming a boss coder. GG! 👏

I hope you found this article instructional and informative. If you have any feedback or queries, please let me know in the comments below. And follow SelectFrom for more tutorials and guides on topics like Big Data, Spark, and data warehousing.

The world’s fastest cloud data warehouse:

When designing analytics experiences which are consumed by customers in production, even the smallest delays in query response times become critical. Learn how to achieve sub-second performance over TBs of data with Firebolt.

Airflow — Build, Host, Maintain Your Own Dependencies with GitHub and Docker Hub (for Free)

In Mobagel, we use Airflow to run various data processing tasks, and as Airflow’s document suggested, it is highly recommended that we maintain our own dependencies in our production environment.

Airflow has more than 60 community managed providers (installable via extras) and some of the default extras/providers installed are not used by everyone, sometimes others extras/providers are needed, sometimes (very often actually) you need to add your own custom dependencies, packages or even custom providers.

This guide shows you how to use open source community tool to build and maintain your own airflow image.

Setup Docker Hub Account

Docker Hub is a platform that host your docker images for free, so you need to create an account on docker hub first (or ask you colleague to share organization account to you).

Go to repositories -> Create Repository

You may name your repository airflow, because image name under different namespace will not conflict with each other.

Setup Airflow Build Pipeline

Now, you may go to airflow’s official repository, and fork the official repository to your organization/account.

Now, you want to add your own build pipeline file. I recommend you create a branch from the desired version first, and do not commit on the original airflow branch. This just makes future pulls from upstream easier. In our example, let’s call it custom-release branch, and branch if from v2–3-stable.git clone [your_forked_repo]
git checkout v2–3-stable git checkout -b custom-release git push -u origin custom-release

Now we may add our workflow file .github/workflows/cd.yaml (example file).name: Publish Docker image

on:
 release:
   types: [published]

jobs:
 push_to_registry:
   name: Push Docker image to Docker Hub
   runs-on: ubuntu-latest
   steps:
     - name: Check out the repo
       uses: actions/checkout@v3

     - name: Log in to Docker Hub
       uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
       with:
         username: ${{ secrets.DOCKER_USERNAME }}
         password: ${{ secrets.DOCKER_PASSWORD }}

     - name: Extract metadata (tags, labels) for Docker
       id: meta
       uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
       with:
         images: mobagel/airflow

     - name: Build and push Docker image
       uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
       env:
         AIRFLOW_GPL_UNIDECODE: yes
       with:
         context: .
         push: true
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}
         build-args: |
           AIRFLOW_VERSION=2.3.2
           AIRFLOW_EXTRAS=async,celery,cncf.kubernetes,dask,docker,grpc,http,ldap,postgres,redis,statsd,virtualenv
           PYTHON_BASE_IMAGE=python:3.8-slim-buster
           ADDITIONAL_PYTHON_DEPS=scikit-learn==1.0.2 slack-sdk==3.14.1 simplejson==3.17.6 glom==22.1.0

A few notes about this pipeline file:

• We set the trigger condition to on publish, so this pipeline is triggered if a release is issued on GitHub page.

• In the login step, we need to provide our Docker hub login username and password. We put these variable as GitHub secret. You can go to GitHub repository page > Settings > Secrets > Action to add your secret.

• In the step build, we may give supported arguments by Airflow to build our custom image. In our case, we removed a lot of default AIRFLOW_EXTRAS to reduce our image size, fixed AIRFLOW_VERSION and PYTHON_BASE_IMAGE, and added our own ADDITIONAL_PYTHON_DEPS .

After you setup this file, push to your custom-release branch and you are good to go.git add .
git commit -m"adding custom build flow"
git push

Start Your Airflow Build

After all this setup, you may inform your team members about the process for creating a pull request on this repository. If anyone wants to make adjustments to dependencies, tell them to update the ADDITIONAL_PYTHON_DEPS variable in .github/workflows/cd.yaml , and push to custom-release branch (or create a pull request depending on your team policy).

To trigger release, create a release from your repository page > Releases > Draft to draft a new release.

1. In tag, choose a tag of your choice. We used [airflow-version]c[our-version], so our tag is in the form of 2.3.2c1 . Note that this tag will also be the tag of your image.

2. Select the custom-release branch as target branch.

3. Fill in the release title and release message and click publish release. Then, your image build will be triggered automatically (you may view build status from repository page > Actions).

After the image is built, go to your own Docker Hub page to verify that the image with the new tag has been published.

Concluding Remark

1. After introducing this workflow, the company’s infrastructure maintainer no longer need to help the team upgrade Airflow images. And it is very easy to train our team member to execute this flow on their own.

2. Compared to the approach of training team member to actually build and push their own image, this approach is much easier in the sense that publishers don’t need to install Docker on their own computer, don’t need to understand Docker build command. Security wise, only the pipeline is allowed to push images. This way we don’t need to give away credentials to each developer. IaC-wise, each version of our own custom image is version controlled, and traceable.

3. Hosting repositories on GitHub or Docker Hub and using their free service sounds good. But for enterprises, the issue has always been whether we can open source these code. Since Airflow itself is already open sourced, and it is generally not too much of an issue to reveal our Airflow dependencies, the whole solution of building and hosting Airflow is quite acceptable. If your company is customizing Airflow in a way that would reveal business secret or introduce security concerns, you’ll need to consider a private approach of your own.

Conclusion

And with that, you’ve crossed another level to becoming a boss coder. GG! 👏

I hope you found this article instructional and informative. If you have any feedback or queries, please let me know in the comments below. And follow SelectFrom for more tutorials and guides on topics like Big Data, Spark, and data warehousing.

The world’s fastest cloud data warehouse:

When designing analytics experiences which are consumed by customers in production, even the smallest delays in query response times become critical. Learn how to achieve sub-second performance over TBs of data with Firebolt.