打造你的第一個 MCP Server：從概念到實作

開場：為什麼需要 MCP？從真實痛點出發

你是一位熱愛學習的工程師，這些年累積了超過 1000 篇個人筆記，散落在本地資料夾裡。涵蓋前端框架、後端架構、演算法、系統設計⋯⋯每一篇都是你花時間整理的寶貴知識。

某天，你想問 ChatGPT：「幫我找所有關於 React Hooks 的筆記，並整理出我還沒掌握的進階用法。」

這個需求聽起來很合理，對吧？但實際上，要讓 AI 助手做到這件事，困難重重。

現有方案都不夠好

讓我們快速看幾個現有的處理方式：

手動複製貼上？ 效率極差，每次都要重複，而且 AI 只能看到你貼的部分，無法主動探索更多相關筆記。

批次上傳檔案？ 跟剛剛一樣的問題，你得先猜哪些檔案相關，容易遺漏，而且每個新問題都要重新上傳。

用 Claude Code 或 Cursor？ 它們的能力被綁死在特定工具裡，而且這些工具就是很會 Coding，不太會討論、發想創意。更重要的是，缺乏標準化 —— 每個工具都自己搞一套。

寫個 REST API？ 這是最接近的方案，但有個致命問題：REST API 是為「程式」設計的，不是為「LLM」設計的。 LLM 不知道你有哪些 API，需要每次對話都重新被告知規格，還得自己猜該呼叫哪個 endpoint。

這就是 MCP 要解決的問題。

MCP 是什麼？AI 義肢製作手冊

不知道你有沒有看過 Cyberpunk 2077？

在這個世界觀上，大部分的人都會安裝一推超酷的義肢，更強壯的手臂、更壯的機械腿...，但這些義肢要能正常運作，有個前提：義肢的接口必須符合標準規格。如果每個義肢廠商都自己搞一套接口，那你的手臂根本裝不上去。

MCP 就像是一本「AI 義肢製作手冊」。

ChatGPT、Claude 這些 AI 會根據這本手冊打造對應的「安裝槽」，而任何人都可以根據這份手冊，設計給 AI 使用的「義肢」，然後直接裝上去。

重點來了：MCP 只是一本製作手冊，用嚴謹的話來講就是：

AI 與工具溝通的標準協定
讓 AI 能自動發現工具的機制
標準化的權限和安全邊界

它只決定「接口的部分長怎樣」，確保你做出來的義肢可以順利裝到其他 AI 身上。至於這個義肢有什麼功能？讀檔案、查資料庫、發 email、控制你的智慧家居⋯⋯隨便你，完全自由。

與 REST API 的差異

MCP 是為 LLM 設計的標準化協定,讓 AI 能夠自動發現和使用你的工具。

關鍵差異:

特性	REST API	MCP
設計對象	給「開發者」用	給「LLM」用
發現機制	需要讀文件	AI 自動發現工具
使用方式	需要寫程式呼叫	AI 自動選擇並呼叫
參數格式	需要查文件	設計 MCP 時，都會定義好

在提到 MCP 之前，必須得提一下什麼是「Agent」?

這裡快速釐清一下概念。

AI（嚴格來說是 LLM）就是一個只會思考、無法行動的大腦。
對，他只是一顆大腦，沒手沒腳，無法行動。他可以思考得很深入、很精彩，但你問他「幫我查一下天氣」，他只能回答「抱歉我查不了」。

那什麼是 Agent 呢
簡單說，Agent = AI 大腦 + 能力（工具）。給 AI 裝上「手」（查天氣的工具）、「腳」（控制智慧家居的工具），他就從一顆只會想的大腦，變成一個能實際做事的 Agent。

MCP 就是定義「怎麼給 AI 裝義肢」的標準。

如果你對 AI Agent 的概念想要更深入了解，推薦閱讀我之前撰寫的書籍《從零開始，打造一個生成式 AI 平台》https://www.books.com.tw/products/0011029234 ，裡頭有更完整的講解。

MCP 的核心概念：Tools — AI 的「義肢」

如果說 AI 的大腦是語言模型，那麼 Tools 就是 AI 的義肢。

沒有義肢，大腦再聰明也只能思考，無法行動。有了 Tools，AI 才能：

獲取資訊 — 讀取你的檔案、查詢資料庫、呼叫 API
執行動作 — 發送郵件、建立文件、修改資料
改變狀態 — 更新設定、記錄日誌、觸發流程

Tools 的三個關鍵特性

1. AI 自己決定什麼時候用

這是 Tools 最重要的特性。你不需要明確指示「請呼叫 XXX 工具」，AI 會根據對話情境自己判斷。
AI 自己決定：

什麼時候用工具
用哪個工具
傳什麼參數

2. Tool 本質就是一個 Function

Tools 就是一個 Function，他執行完後的結果，會送回給 LLM
就像下面這三個 Function

list_notes()→ 返回：[note1.md, note2.md, note3.md]
read_note(path: "note1.md")→ 返回：筆記的完整內容
search_notes(query: "React")→ 返回：包含 "React" 的筆記列表和摘要

每個 Tool 的呼叫都會產生結果，AI 會根據結果決定下一步動作。
這就像是你問助理「幫我查一下檔案」，他真的會去翻檔案櫃。

3. 有明確的規格書（Schema-Defined）

每個 Tool 都有清楚的說明書，你必須替每一個工具定義好以下參數

工具名稱，這個工具叫什麼
工具說明，這個工具是做什麼的
輸入參數，這個工具可以傳入什麼，需要提供什麼參數
輸出參數，這個工具會回傳什麼

基本上還是剛剛提到的，Tool 的本質就是一個 Function，只是你必須詳細交代 LLM 該怎麼用、什麼時會去用這個 Function

快速確認你的學習狀況（單選題）

你正在開發一個「個人知識庫」的 MCP Server。下列哪個功能「不應該」設計成 Tool？

搜尋筆記內容（根據關鍵字找出相關筆記）

筆記分類規則（說明你如何組織筆記的 markdown 文件）

建立新筆記（在指定目錄建立 .md 檔案）

統計筆記數量（計算各分類有多少筆記）

單選題解析：你正在開發一個「個人知識庫」的 MCP Server。下列哪個功能「不應該」設計成 Tool？

工具是一個 Function，是一個可以被執行的行為
筆記分類規則，其實就是很單純的文字、命令告訴 LLM 該怎麼做

目標：實作第一個 Tool：列出所有筆記

我們要解決什麼問題？
現在我們要讓 AI 能夠「看到」你電腦裡有哪些筆記檔案。
這個工具很簡單：

輸入：不需要參數（列出所有筆記就好）
輸出：每個筆記的名稱 + 路徑
目的：讓 AI 知道有哪些筆記可以讀取

第一步，創建一個簡單的 HTTP 伺服器

首先，創建一個資料夾當作專案資料夾我這邊就叫做「my-notes-mcp-server」

接下來打開終端機，進入該資料夾中直接貼上這三行命令初始化 Nodejs 專案同時安裝必要套件

1npm init -y
2npm install @modelcontextprotocol/sdk express zod
3npm install -D @types/express @types/node tsx typescript

創建一個 index.ts 這是一個非常簡單的 HTTP 伺服器

1import express from 'express';
2
3// 1. 建立 Express 應用程式
4const app = express();
5
6app.use(express.json());
7
8// 2. 設定路由
9// 健康檢查 endpoint
10app.get('/health', (req, res) => {
11  res.json({ 
12    status: 'ok',
13    message: 'Server is running!' 
14  });
15});
16
17// 3. 啟動伺服器
18const port = 8080;
19
20app.listen(port, () => {
21  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
22  console.log(`📍 健康檢查：http://localhost:${port}/health`);
23});

打開 package.json 簡單設定一下一些常用命令

1{
2  "name": "my-notes-mcp-server",
3  "version": "1.0.0",
4  "description": "",
5  "main": "index.js",
6  "scripts": {
7    "dev": "tsx watch index.ts",
8    "start": "tsx index.ts",
9    "build": "tsc",
10    "serve": "node dist/index.js"
11  },
12  "keywords": [],
13  "author": "",
14  "license": "ISC",
15  "type": "commonjs",
16  "dependencies": {
17    "@modelcontextprotocol/sdk": "^1.20.2",
18    "express": "^5.1.0",
19    "zod": "^3.25.76"
20  },
21  "devDependencies": {
22    "@types/express": "^5.0.4",
23    "@types/node": "^24.9.1",
24    "tsx": "^4.20.6",
25    "typescript": "^5.9.3"
26  }
27}
28

我打算使用 TypeScript 所以需要創建一個 tsconfig.json 確保 TypeScript 能正確被處理

1{
2  "compilerOptions": {
3    "target": "ES2022",
4    "module": "ESNext",
5    "moduleResolution": "bundler",
6    "esModuleInterop": true,
7    "strict": true,
8    "skipLibCheck": true,
9    "outDir": "./dist"
10  },
11  "include": ["*.ts"]
12}

OK! 現在在終端機輸入 npm run dev 應該能夠在瀏覽器中打開 http://localhost:8080/health

第二步，開始打造一個最簡單的 MCP 伺服器

首先，創建 MCP Server 他是整個系統的核心，負責連接管理、訊息傳輸、主持著各種各樣的設定記載這邊的話只需要定義伺服器的名稱跟版本即可，他會顯示在客戶端上

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
4const app = express();
5
6app.use(express.json());
7
8// 建立 MCP Server
9const server = new McpServer({
10  name: 'my-notes-server',
11  version: '1.0.0'
12});
13
14app.get('/health', (req, res) => {
15  res.json({ 
16    status: 'ok',
17    message: 'Server is running!' 
18  });
19});
20
21const port = 8080;
22
23app.listen(port, () => {
24  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
25  console.log(`📍 健康檢查：http://localhost:${port}/health`);
26});

接著，我們就可以來定義第一個工具，讓 AI 能知道並使用他 mcpServer 提供 registerTool 來註冊一個新工具必須先傳入工具的名稱，這裡的名稱應當直覺、能夠被 LLM 直接理解他的功能

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
4const app = express();
5
6app.use(express.json());
7
8// 建立 MCP Server
9const server = new McpServer({
10  name: 'my-notes-server',
11  version: '1.0.0'
12});
13
14server.registerTool(
15  'list_files' // 工具名稱 
16);
17
18app.get('/health', (req, res) => {
19  res.json({ 
20    status: 'ok',
21    message: 'Server is running!' 
22  });
23});
24
25const port = 8080;
26
27app.listen(port, () => {
28  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
29  console.log(`📍 健康檢查：http://localhost:${port}/health`);
30});

再來， registerTool 的第二個參數傳入該工具的規格書 - title，這個工具叫什麼 - description，這個工具是做什麼的 - inputSchema，這個工具需要傳入什麼 - outputSchema，這個工具會回傳什麼特別值得一提，inputSchema、outputSchema 使用 zod 來定義型別以右邊程式碼為例該工具應該會回傳一個物件 { files: string[] }

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3import { z } from 'zod';
4
5const app = express();
6
7app.use(express.json());
8
9// 建立 MCP Server
10const server = new McpServer({
11  name: 'my-notes-server',
12  version: '1.0.0'
13});
14
15server.registerTool(
16  'list_files',
17  {
18    title: '列出檔案',
19    description: '列出所有 Markdown 檔案',
20    inputSchema: {}, // 這裡不需要傳入任何參數 
21    outputSchema: {
22      files: z.array(z.string())
23    }
24  },
25);
26
27app.get('/health', (req, res) => {
28  res.json({ 
29    status: 'ok',
30    message: 'Server is running!' 
31  });
32});
33
34const port = 8080;
35
36app.listen(port, () => {
37  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
38  console.log(`📍 健康檢查：http://localhost:${port}/health`);
39});

再來， registerTool 的第三個參數傳入該工具的實際執行函數一但工具被調用，該 function 會被執行，回傳數值便會直接送回給 LLM。回傳數值必然會有 content ，他是一個陣列來告知 LLM 工具執行的結果

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3import { z } from 'zod';
4
5const app = express();
6
7app.use(express.json());
8
9// 建立 MCP Server
10const server = new McpServer({
11  name: 'my-notes-server',
12  version: '1.0.0'
13});
14
15server.registerTool(
16  'list_files',
17  {
18    title: '列出檔案',
19    description: '列出所有 Markdown 檔案',
20    inputSchema: {}, // 這裡不需要傳入任何參數 
21    outputSchema: {
22      files: z.array(z.string())
23    }
24  },
25  async () => {
26    return {
27      content: [                               // ← 必須是陣列
28        {
29          type: 'text',                        // ← 內容類型
30          text: '目前還沒有檔案'                // ← 實際內容
31        }
32      ]
33    };
34  }
35);
36
37app.get('/health', (req, res) => {
38  res.json({ 
39    status: 'ok',
40    message: 'Server is running!' 
41  });
42});
43
44const port = 8080;
45
46app.listen(port, () => {
47  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
48  console.log(`📍 健康檢查：http://localhost:${port}/health`);
49});

回傳數值中的 content，不只可以回傳文字、還可以加入圖片、音訊、檔案等內容（右側程式碼僅為舉例）

1import express from "express";
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5const app = express();
6
7app.use(express.json());
8
9// 建立 MCP Server
10const server = new McpServer({
11  name: "my-notes-server",
12  version: "1.0.0",
13});
14
15server.registerTool(
16  "list_files",
17  {
18    title: "列出檔案",
19    description: "列出所有 Markdown 檔案",
20    inputSchema: {}, // 這裡不需要傳入任何參數
21    outputSchema: {
22      files: z.array(z.string()),
23    },
24  },
25  async () => {
26    return {
27      content: [
28        {
29          type: "text",
30          text: "目前還沒有檔案",
31        },
32        {// 簡單展示一下如果要回傳圖片該怎麼做 
33          type: "image",
34          data: "base64 編碼的圖片",
35          mimeType: "image/png",
36        },
37      ],
38    };
39  }
40);
41
42app.get("/health", (req, res) => {
43  res.json({
44    status: "ok",
45    message: "Server is running!",
46  });
47});
48
49const port = 8080;
50
51app.listen(port, () => {
52  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
53  console.log(`📍 健康檢查：http://localhost:${port}/health`);
54});
55

回傳數值除了 content，還有 structuredContent content：給 AI「閱讀」的文字內容 structuredContent：給程式「解析」的結構化資料通常來說，structuredContent 跟 content 的內容是一摩一樣的只是 content 的內容可能透過 JSON.stringify 轉成純文字，讓 LLM 可以直接閱讀

1import express from "express";
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5const app = express();
6
7app.use(express.json());
8
9// 建立 MCP Server
10const server = new McpServer({
11  name: "my-notes-server",
12  version: "1.0.0",
13});
14
15server.registerTool(
16  "list_files",
17  {
18    title: "列出檔案",
19    description: "列出所有 Markdown 檔案",
20    inputSchema: {}, // 這裡不需要傳入任何參數
21    outputSchema: {
22      files: z.array(z.string()),
23    },
24  },
25  async () => {
26    const output = { files: [] };              // ← 先用空陣列
27
28    return {
29      content: [
30        {
31          type: "text",
32          text: JSON.stringify(output, null, 2),
33        }
34      ],
35      structuredContent: output                // 同時提供結構化資料
36    };
37  }
38);
39
40app.get("/health", (req, res) => {
41  res.json({
42    status: "ok",
43    message: "Server is running!",
44  });
45});
46
47const port = 8080;
48
49app.listen(port, () => {
50  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
51  console.log(`📍 健康檢查：http://localhost:${port}/health`);
52});
53

現在，將整個 MCP 伺服器透過 Express 對外開放讓 AI 客戶端可以連接

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
4import { z } from 'zod';
5
6const app = express();
7app.use(express.json());
8
9const server = new McpServer({
10  name: 'my-notes-server',
11  version: '1.0.0'
12});
13
14server.registerTool(
15  'list_files',
16  {
17    title: '列出檔案',
18    description: '列出所有 Markdown 檔案',
19    inputSchema: {},
20    outputSchema: { files: z.array(z.string()) }
21  },
22  async () => {
23    const output = { files: [] };
24
25    return {
26      content: [
27        {
28          type: "text",
29          text: JSON.stringify(output, null, 2),
30        }
31      ],
32      structuredContent: output 
33    };
34  }
35);
36
37// MCP endpoint
38app.post('/mcp', async (req, res) => {
39  try {
40    const transport = new StreamableHTTPServerTransport({
41      sessionIdGenerator: undefined,
42      enableJsonResponse: true
43    });
44   
45    res.on('close', () => transport.close());
46    
47    await server.connect(transport);
48    await transport.handleRequest(req, res, req.body);
49  } catch (error) {
50    console.error('MCP 請求錯誤：', error);
51    if (!res.headersSent) {
52      res.status(500).json({
53        jsonrpc: '2.0',
54        error: { code: -32603, message: 'Internal server error' },
55        id: null
56      });
57    }
58  }
59});
60
61app.get('/health', (req, res) => {
62  res.json({ status: 'ok' });
63});
64
65const port = 8080;
66app.listen(port, () => {
67  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
68  console.log(`📍 MCP endpoint：http://localhost:${port}/mcp`);
69});

第三步，測試看看 MCP 伺服器有沒有建立成功

這邊可以在終端機中直接打入一串指令，開啟 mcp 測試工具

1npx @modelcontextprotocol/inspector http://localhost:8080/mcp

輸入完成後，他會開啟一個網站

確保 Transport Type 是 Streamable HTTP

確保 URL 是 http://localhost:8080/mcp

按下 Connect

你應該可以看到連接成功，你可以點擊中間的 List Tools

應該可以看到我們創建的工具「list files」

第四步，實作檔案系統讀取

我們來把 list_files 的功能給實際做出來
由於本教學的重點是 MCP，我會用很快的速度帶過去，就不特別提細節了

為了方便測試，我建議在專案資料夾中建立一個 notes 資料夾我們的 mcp 工具會把該資料夾當作我們的筆記目錄

我這邊使用 fs.readdir() 讀取目錄過濾出 .md 檔案然後回傳給 LLM

1import express from 'express';
2import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
4import { z } from 'zod';
5import fs from 'fs/promises'; 
6import path from 'path';
7
8const app = express();
9app.use(express.json());
10
11// 筆記目錄
12const NOTES_DIR = './notes';
13
14const server = new McpServer({
15  name: 'my-notes-server',
16  version: '1.0.0'
17});
18
19server.registerTool(
20  'list_files',
21  {
22    title: '列出檔案',
23    description: '列出所有 Markdown 檔案',
24    inputSchema: {},
25    outputSchema: { files: z.array(z.string()) }
26  },
27  async () => {
28    try {
29      const entries = await fs.readdir(NOTES_DIR, { withFileTypes: true });
30      const files = entries
31        .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
32        .map(entry => entry.name);
33      
34      const output = { files };
35      
36      return {
37        content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
38        structuredContent: output
39      };
40    } catch (error) {
41      return {
42        content: [{ type: 'text', text: `錯誤：${(error as Error).message}` }],
43        isError: true
44      };
45    }
46  }
47);
48
49app.post('/mcp', async (req, res) => {
50  try {
51    const transport = new StreamableHTTPServerTransport({
52      sessionIdGenerator: undefined,
53      enableJsonResponse: true
54    });
55    res.on('close', () => transport.close());
56    await server.connect(transport);
57    await transport.handleRequest(req, res, req.body);
58  } catch (error) {
59    console.error('MCP 請求錯誤：', error);
60    if (!res.headersSent) {
61      res.status(500).json({
62        jsonrpc: '2.0',
63        error: { code: -32603, message: 'Internal server error' },
64        id: null
65      });
66    }
67  }
68});
69
70app.get('/health', (req, res) => {
71  res.json({ status: 'ok' });
72});
73
74const port = 8080;
75app.listen(port, () => {
76  console.log(`🚀 伺服器運行中：http://localhost:${port}`);
77  console.log(`📍 MCP endpoint：http://localhost:${port}/mcp`);
78  console.log(`📂 筆記目錄：${NOTES_DIR}`);
79});