MCP Resources 最佳實踐：從官方範例到實戰設計
MCP Resources 最佳實踐：從官方範例到實戰設計
深入剖析社群與官方生態中成熟的 Resource 設計模式，幫助你打造對 LLM 友善的資源架構。
成功的 Resource 設計共通點
觀察目前做得成功的 resource 用法，大多有幾個共通點：
| 設計原則 | 說明 |
|---|---|
| 資源樹結構 | 把重要上下文做成可瀏覽的資源樹（logs、設定檔、文件、repo 結構…） |
| Resource Templates | 善用 resource templates 讓 LLM 可以動態指定參數，例如 repo://{owner}/{name} |
| LLM 友善格式 | 資源內容盡量是「可直接餵模型」的格式（純文字、結構化 JSON），避免讓工具再包一層 |
官方 Reference Servers 的 Resource 設計
這幾個是 MCP 官方 example servers，基本都示範了「正統」的 resource 實作方式，適合直接學習 + 參考程式碼結構。
Everything Server
官方綜合範例，包含 tools / resources / prompts 三種。
特色：
- Resource 實作偏教學型
- 示範如何列出固定 URI、回傳文字或檔案內容
- 適合理解最基本的資源 listing / read / template 概念
Filesystem Server
透過 resources 暴露特定目錄下的檔案為可讀資源。
支援格式： file:///path/to/file.txt
做得好的地方：
- 有明確的 allowlist / root path，兼顧安全與可用性
- 資源 metadata（mimeType、描述）設計合理，讓 LLM 比較會選對檔案
Git / GitHub Server
用資源把 repo 的內容暴露給 LLM。
暴露的資源類型：
- Repo 檔案結構
- README 內容
- PR diff
設計 Pattern：
先 Resources 給 context，再 Tools 做 action
LLM 可以先用資源理解專案，再用 tools 做進一步操作。這個 pattern 非常值得學習。
第三方開源專案的成熟案例
在各種 MCP server 彙整清單與教學 repo 裡，有幾種 resource pattern 是用得比較成熟的：
1. Observability / DevOps 類
把 logs、metrics query 結果、dashboard 設定檔等暴露成 resources。
常見作法：
- 一組「最近 1 小時 / 24 小時」的固定資源 URI
- 一組帶參數的 resource template（例如指定服務名稱、時間範圍）
效果： LLM 可以先「閱讀」關鍵 context 再提出診斷建議。
2. 資料分析型 Server
例如 pandas-mcp-server，把可用的 dataset（CSV/Parquet 等）當作資源列出。
優點：
- 避免一開始就把所有資料都塞進工具呼叫
- 實現「資料目錄瀏覽 → 精準載入」的流程
3. API 封裝型 Server
例如 Zapier / OpenAPI 轉 MCP 類專案。
設計方式：
- 把「可用的 service / account / workspace 列表」做成資源
- 而不是直接做成 tool 參數
好處： LLM 可以先讀資源了解有哪些系統與權限，再選對 tool 和參數。
推薦學習資源
官方文檔
| 資源 | 說明 |
|---|---|
| MCP Resources 官方文檔 | 說明 resources / resource templates 概念、協定格式，並有簡單 server 實作範例 |
中文教學
| 資源 | 說明 |
|---|---|
| HackMD：三大核心機制 | 中文說明，把 resources 比喻成「原料倉庫」，示範如何根據任務自動推薦資源 URI |
實作範例
| 資源 | 說明 |
|---|---|
| FastMCP | 展示 @mcp.resource("data://example") decorator 寫法，以及動態啟用/停用資源時如何觸發 resources/list_changed 通知 |
| Composio 教學 | 用 Python decorator 示範各種回傳型別的資源，強調「資源不只是檔案，可以是動態計算後的內容」 |
彙整清單
awesome-mcp-serversModel Context Protocol Resources & Guides
實戰設計範例：Infra / DevOps MCP Server
以下是一個「Infra / DevOps 環境觀測 MCP server」的 resource 設計範例：
固定資源 (Static Resources)
infra://k8s/clusters # 列出可用 cluster 與基本描述（region、用途）
infra://vercel/projects # 列出專案清單與環境 URL
Resource Templates (動態資源)
infra://k8s/cluster/{name}/namespaces
infra://k8s/cluster/{name}/ns/{ns}/recent-events
設計理念
┌─────────────────────────────────────────────────────────┐
│ LLM 工作流程 │
├─────────────────────────────────────────────────────────┤
│ 1. 先用 Resources 看結構（瀏覽資源樹） │
│ ↓ │
│ 2. 再用 Tools 下更具體的操作（kubectl / API 呼叫） │
└─────────────────────────────────────────────────────────┘
這個 pattern 在 observability、git、filesystem 那些成熟案例裡都有影子。
Resource 訂閱機制 (Subscription)
在現在的生態裡，「有把 resources 訂閱做得完整」的專案其實還不多，但有幾個方向與 repo 算是比較成熟、值得參考的實作風格。
成熟的訂閱使用場景
1. 動態配置 / 清單變化 (listChanged)
像 Mastra 的 MCPServer 類別就有直接支援 resources.notifyUpdated()、prompts.notifyListChanged()，專門用在「長連線環境」推送更新，不靠 polling。
適合場景： 專案列表、環境列表、工作 queue 這種會常變的資源。
2. 檔案 / 程式碼變更訂閱
MCP 規格本身以檔案範例講得最清楚：
對 file:///project/src/main.rs 做 resources/subscribe
↓
變動時 server 主動發 notifications/resources/updated
很多 IDE / FS 類 server 都會直接照這個 pattern：底層用 file watcher / git diff，觸發時就推更新。
3. 串流資料 / 監控類 Server
把事件流透過 SSE 或類似機制推給 MCP client，避免 client 一直打工具查詢。
實務作法： Server 內部訂閱 log / Kafka / Pulsar topic，一有新事件就觸發 updated 通知。
訂閱相關教學與設計指南
| 資源 | 說明 |
|---|---|
| MCP Resources 規格（新版 spec） | 明確定義 subscribe: true、listChanged: true capability，並給出 JSON 範例 |
| Active Data / Subscriptions 教學 | 用圖解說明 client 呼叫 resources/subscribe → server 監聽底層變更 → 推 updated 的整個 event loop |
| Mastra MCPServer | 有把「notifyUpdated 只在長連線 server 才有效」這類實作細節講清楚 |
實作 Pattern（適合 Infra / DevOps）
Capabilities 宣告
{
"resources": {
"subscribe": true,
"listChanged": true
}
}讓 host 知道可以訂閱單一資源、也會收到清單變更。
訂閱表 + Watcher 架構
┌─────────────────────────────────────────────────────────────┐
│ Subscription Manager │
├─────────────────────────────────────────────────────────────┤
│ 維護 uri -> subscribers 的 map │
│ │
│ 當底層變化時： │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ file watcher │ │ │ │
│ │ DB change stream│ -> │ 查哪些 uri 有訂閱 │ -> 發 updated │
│ │ message queue │ │ │ │
│ └─────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
若你的系統本來就有 event bus，可以直接把這層 MCP adapter 做成 library。
listChanged 的用法
有新的 deployment / job / project 出現時：
觸發 notifications/resources/list_changed
↓
LLM 不用硬猜還有哪些資源，也不用一直 call resources/list
Repo 選擇建議
因為真正「把 subscription 做到 production 等級」的多半是商業產品或框架，不一定全開源，建議學習路徑：
| 步驟 | 資源 | 目的 |
|---|---|---|
| 1 | MCP 規格 + Active Data 教學 | 拿到正確協定與 flow |
| 2 | Mastra MCPServer | 學它怎麼處理長連線與通知 |
| 3 | Streaming / Observability / FS 類 server | 把事件觸發邏輯對照到 MCP subscription |
核心設計原則總結
[!TIP]
Resource 給 Context，Tool 做 Action讓 LLM 先透過 Resources 理解環境與可用選項，再透過 Tools 執行具體操作。
設計 Checklist
- [ ] 資源 URI 是否有清晰的命名規範？
- [ ] 是否善用 resource templates 支援動態參數？
- [ ] 資源內容是否為 LLM 友善格式（純文字 / JSON）？
- [ ] metadata（mimeType、description）是否足夠幫助 LLM 選擇正確資源？
- [ ] 是否遵循「先 Resources 後 Tools」的設計 pattern？
- ← Previous
MCP Prompts 深度解析：橋接人類意圖與 AI 上下文 - Next →
RPC (Remote Procedure Call) 就是 IPC 嗎？