MCP Tools 開發指南
本專案的 MCP Tools 位於 pai-bot/src/mcp/tools/。
架構模式
Service Layer (ts-results) MCP Tool Layer
┌─────────────────────┐ ┌──────────────────────┐
│ Result<T, Error> │ --> │ { content, isError } │
└─────────────────────┘ └──────────────────────┘Service Layer
使用 ts-results 回傳 Result<T, Error>：
import { Err, Ok, type Result } from "ts-results";
export async function getData(): Promise<Result<Data, Error>> {
try {
const data = await api.fetch();
return Ok(data);
} catch (error) {
return Err(error instanceof Error ? error : new Error(String(error)));
}
}MCP Tool Layer
1. 註冊工具
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
export function registerMyTools(server: McpServer): void {
server.registerTool(
"tool_name", // 命名：category_action
{
title: "Tool Title",
description: "工具描述（中文）",
inputSchema: {
param: z.string().describe("參數說明"),
optional: z.number().optional().describe("可選參數"),
},
},
async ({ param, optional = 5 }) => {
// 實作
}
);
}2. 處理 Result
async ({ query }) => {
const result = await service.getData(query);
if (result.err) {
return {
content: [{ type: "text", text: `錯誤: ${result.val.message}` }],
isError: true,
};
}
return {
content: [{ type: "text", text: JSON.stringify(result.val, null, 2) }],
};
}3. 無 Result 的 Service（使用 try-catch）
async ({ query }) => {
try {
const data = await legacyService.fetch(query);
return {
content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
};
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
return {
content: [{ type: "text", text: `錯誤: ${message}` }],
isError: true,
};
}
}命名規範
| 類別 | 格式 | 範例 |
|---|---|---|
| 工具名稱 | category_action | google_calendar_list, memory_search |
| 函數名稱 | registerXxxTools | registerGoogleTools |
錯誤訊息格式
`${Category} 錯誤: ${error.message}`
// 範例: "Google Calendar 錯誤: Invalid credentials"註冊入口
在 pai-bot/src/mcp/index.ts 註冊：
import { registerMyTools } from "./tools/my-tools";
export function createMcpServer(): McpServer {
const server = new McpServer({ name: "pai-bot", version: "1.0.0" });
registerMyTools(server);
return server;
}Checklist
- Service 使用
Result<T, Error> - Tool 處理
result.err並回傳isError: true - 使用 Zod schema 定義參數
- 錯誤訊息包含分類前綴
- 在
index.ts註冊