返回產品博客

為什麼現有的 MCP SDK 不夠用?開發者的視角

本文發佈於 2024年11月18日。產品當前能力參見產品能力。

為什麼現有的 MCP SDK 不夠用?開發者的視角

讓我先聲明一點:官方的模型上下文協議 SDK 非常優秀。它設計良好,精確遵循規範,並讓你完全控制協議。Anthropic 團隊在創建一個堅實的 MCP 開發基礎方面做得非常出色。

但問題是:技術上正確並不意味著對開發者友好。

在 Zhama 為生產環境構建了數十個 MCP 服務器之後,我發現了當前 SDK 的六個根本問題,這些問題使它不適合真實世界的快速開發。這不是為了批評而批評 - 這是對我們為什麼構建 @zhama/mcp-server 的誠實分析,以及為什麼你可能也需要它。

核心問題:協議優先 vs 開發者優先的設計

官方 MCP SDK 是協議優先的。它旨在讓你直接訪問模型上下文協議的原語:請求、響應、處理器、傳輸層。如果你要:

  • 為 MCP 構建基礎設施
  • 創建自己的抽象層
  • 實現自定義協議擴展
  • 調試協議級問題

這很好。

但如果你要:

  • 快速構建業務工具
  • 專注於應用邏輯
  • 維護多個工具
  • 讓新開發者快速上手
  • 在緊迫的期限下工作

這就很糟糕。

讓我準確展示我的意思。

問題 #1:學習曲線太陡峭

你需要學習什麼(官方 SDK)

在你可以構建一個簡單的計算器工具之前,你需要理解:

  1. 服務器初始化和配置

    const server = new Server({
      name: 'my-server',
      version: '1.0.0'
    }, {
      capabilities: {
        tools: {},
        resources: {},
        prompts: {}
      }
    });
  2. 請求模式類型

    import {
      CallToolRequestSchema,
      ListToolsRequestSchema,
      ListResourcesRequestSchema,
      ReadResourceRequestSchema
    } from '@modelcontextprotocol/sdk/types.js';
  3. 請求處理器註冊

    server.setRequestHandler(ListToolsRequestSchema, async () => {
      // 返回工具定义
    });
    
    server.setRequestHandler(CallToolRequestSchema, async (request) => {
      // 执行工具逻辑
    });
  4. 用於輸入驗證的 JSON Schema

    inputSchema: {
      type: 'object',
      properties: {
        param1: { type: 'string' },
        param2: { type: 'number' }
      },
      required: ['param1', 'param2']
    }
  5. 響應格式化

    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result)
      }]
    };
  6. 傳輸層設置

    const transport = new StdioServerTransport();
    await server.connect(transport);

這至少是 6 個不同的概念,僅僅是為了構建一個 “Hello World” 工具。

你需要學習什麼(@zhama/mcp-server)

import { createMCPServer, BaseTool, Tool } from '@zhama/mcp-server';

@Tool({
  name: 'hello',
  description: '打招呼',
  parameters: [
    { name: 'name', type: 'string', required: true }
  ]
})
class HelloTool extends BaseTool {
  protected toolDefinition = {
    name: 'hello',
    description: '打招呼',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { name } = params as { name: string };
    return { greeting: `你好,${name}!` };
  }
}

createMCPServer('hello-server', '1.0.0')
  .enableTools()
  .addTool(new HelloTool())
  .runStdio();

兩個概念:裝飾器和執行方法。其他一切都自動處理。

影響

使用官方 SDK,你的第一個工具需要 2-4 小時(包括學習時間)。使用 @zhama/mcp-server,只需要 5-10 分鐘。

這不是一個小差異 - 這是第一天生產力提高 24 倍。

問題 #2:樣板代碼爆炸

讓我們用兩種方法構建相同的功能,並計算代碼行數。

任務:創建天氣工具

官方 SDK 實現:156 行

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool as MCPTool
} from '@modelcontextprotocol/sdk/types.js';

// 服务器设置
const server = new Server({
  name: 'weather-server',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

// 工具定义
const weatherToolDefinition: MCPTool = {
  name: 'get_weather',
  description: '获取城市的当前天气',
  inputSchema: {
    type: 'object',
    properties: {
      city: {
        type: 'string',
        description: '城市名称'
      },
      units: {
        type: 'string',
        description: '温度单位',
        enum: ['celsius', 'fahrenheit'],
        default: 'celsius'
      }
    },
    required: ['city']
  }
};

// 列出工具处理器
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [weatherToolDefinition]
  };
});

// 执行工具处理器
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== 'get_weather') {
    throw new Error(`未知工具:${request.params.name}`);
  }

  const { city, units = 'celsius' } = request.params.arguments as {
    city: string;
    units?: string;
  };

  try {
    // 输入验证
    if (!city || typeof city !== 'string') {
      throw new Error('城市必须是非空字符串');
    }

    if (units && !['celsius', 'fahrenheit'].includes(units)) {
      throw new Error('单位必须是 celsius 或 fahrenheit');
    }

    // 获取天气数据
    const apiKey = process.env.WEATHER_API_KEY;
    if (!apiKey) {
      throw new Error('WEATHER_API_KEY 未配置');
    }

    const tempUnit = units === 'fahrenheit' ? 'imperial' : 'metric';
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&appid=${apiKey}&units=${tempUnit}`
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`未找到城市:${city}`);
      }
      throw new Error(`天气 API 错误:${response.status}`);
    }

    const data = await response.json();

    // 格式化结果
    const result = {
      city: data.name,
      country: data.sys.country,
      temperature: data.main.temp,
      feels_like: data.main.feels_like,
      condition: data.weather[0].main,
      description: data.weather[0].description,
      humidity: data.main.humidity,
      wind_speed: data.wind.speed,
      units: units
    };

    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  } catch (error) {
    // 错误处理
    const errorMessage = error instanceof Error ? error.message : '未知错误';
    console.error('天气工具错误:', errorMessage);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: errorMessage
        })
      }],
      isError: true
    };
  }
});

// 服务器启动
async function main() {
  try {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error('天气 MCP 服务器运行在 stdio');
  } catch (error) {
    console.error('启动服务器失败:', error);
    process.exit(1);
  }
}

main();

@zhama/mcp-server 實現:47 行

import { createMCPServer, BaseTool, Tool } from '@zhama/mcp-server';
import fetch from 'node-fetch';

@Tool({
  name: 'get_weather',
  description: '获取城市的当前天气',
  parameters: [
    { 
      name: 'city', 
      type: 'string', 
      description: '城市名称', 
      required: true 
    },
    { 
      name: 'units', 
      type: 'string', 
      description: 'celsius 或 fahrenheit', 
      required: false 
    }
  ]
})
class WeatherTool extends BaseTool {
  protected toolDefinition = {
    name: 'get_weather',
    description: '获取天气信息',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { city, units = 'celsius' } = params as { 
      city: string; 
      units?: string 
    };

    const apiKey = process.env.WEATHER_API_KEY;
    if (!apiKey) throw new Error('WEATHER_API_KEY 未配置');

    const tempUnit = units === 'fahrenheit' ? 'imperial' : 'metric';
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&appid=${apiKey}&units=${tempUnit}`
    );

    if (!response.ok) {
      if (response.status === 404) throw new Error(`未找到城市:${city}`);
      throw new Error(`天气 API 错误:${response.status}`);
    }

    const data = await response.json();

    return {
      city: data.name,
      country: data.sys.country,
      temperature: data.main.temp,
      feels_like: data.main.feels_like,
      condition: data.weather[0].main,
      description: data.weather[0].description,
      humidity: data.main.humidity,
      wind_speed: data.wind.speed,
      units
    };
  }
}

createMCPServer('weather-server', '1.0.0')
  .enableTools()
  .enableLogging('info')
  .addTool(new WeatherTool())
  .runStdio();

結果:代碼減少 70% - 而且 @zhama/mcp-server 版本更易讀。

樣板代碼稅

使用官方 SDK 構建的每個工具都需要:

  • 服務器配置:約 10 行
  • 模式定義:約 15-30 行
  • 處理器註冊:約 5 行
  • 請求路由:約 5-10 行
  • 響應格式化:約 5-10 行
  • 錯誤處理:約 10-20 行
  • 傳輸層設置:約 5 行

每個工具有 55-90 行樣板代碼。

使用 @zhama/mcp-server:**0 行樣板代碼。**只需編寫業務邏輯。

問題 #3:錯誤處理是你的問題

官方 SDK 完全將錯誤處理留給你。這意味著:

你必須處理

  1. 輸入驗證錯誤

    if (!params.email || typeof params.email !== 'string') {
      throw new Error('无效的邮箱参数');
    }
  2. 業務邏輯錯誤

    try {
      const result = await performOperation();
    } catch (error) {
      // 这里应该返回什么?
    }
  3. 響應格式化

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ error: error.message })
      }],
      isError: true  // 别忘了这个!
    };
  4. 日誌記錄

    console.error('工具失败:', error);  // 希望这就够了

真實成本

在生產環境中,我們發現使用官方 SDK 時,錯誤處理代碼經常超過業務邏輯代碼。一個典型的工具看起來像:

  • 業務邏輯:30 行
  • 錯誤處理:50 行
  • 樣板代碼:40 行

只有 25% 的代碼是實際功能。

使用 @zhama/mcp-server

protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
  // 只需编写你的逻辑
  // 错误自动捕获
  // 日志自动记录
  // 响应自动格式化
  
  const result = await performOperation(params);
  return result;  // 就这样!
}

80-90% 的代碼是實際功能。

問題 #4:沒有開發者體驗功能

官方 SDK 提供零開發者體驗優化:

缺失的功能

  1. 沒有 TypeScript 裝飾器 - 手動模式定義
  2. 沒有自動驗證 - 你要驗證每個參數
  3. 沒有日誌系統 - 自己實現或使用 console.log
  4. 沒有測試工具 - 自己想辦法 mock
  5. 沒有開發模式 - 沒有熱重載或自動重啟
  6. 沒有調試工具 - Console.error 是你的朋友
  7. 沒有類型推斷 - 手動轉換所有內容
  8. 沒有文檔生成 - 全部手寫

示例:添加工具參數

官方 SDK:需要更新 4 個地方

// 1. 更新模式
const toolDef = {
  inputSchema: {
    properties: {
      existingParam: { type: 'string' },
      newParam: { type: 'number' }  // 在这里添加
    },
    required: ['existingParam', 'newParam']  // 还有这里
  }
};

// 2. 更新类型定义
type ToolParams = {
  existingParam: string;
  newParam: number;  // 在这里添加
};

// 3. 更新验证
if (typeof params.newParam !== 'number') {  // 在这里添加
  throw new Error('newParam 必须是数字');
}

// 4. 更新逻辑
const { existingParam, newParam } = params;  // 在这里使用

@zhama/mcp-server:只需更新 1 個地方

@Tool({
  parameters: [
    { name: 'existingParam', type: 'string', required: true },
    { name: 'newParam', type: 'number', required: true }  // 只需在这里添加
  ]
})
class MyTool extends BaseTool {
  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { existingParam, newParam } = params as { 
      existingParam: string; 
      newParam: number 
    };
    // 立即使用 - 验证是自动的
  }
}

問題 #5:維護變成噩夢

隨著 MCP 服務器的增長,官方 SDK 的問題會複合:

場景:一個服務器中有 10 個工具

官方 SDK 結構

// server.ts - 800+ 行

// 工具定义(150 行)
const tool1Def = { /* ... */ };
const tool2Def = { /* ... */ };
// ... 还有 8 个

// 列表处理器(50 行)
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [tool1Def, tool2Def, /* ... */]
  };
});

// 执行处理器(600+ 行)
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case 'tool1':
      // 60 行逻辑 + 错误处理
      break;
    case 'tool2':
      // 60 行逻辑 + 错误处理
      break;
    // ... 还有 8 个 case
  }
});

問題:

  • 單個 800 行的文件
  • 工具無法獨立測試
  • 共享狀態導致 bug
  • 每個 PR 都有合併衝突
  • 無法跨服務器重用工具

@zhama/mcp-server 結構

// tools/tool1.ts (30 行)
@Tool({ /* ... */ })
export class Tool1 extends BaseTool { /* ... */ }

// tools/tool2.ts (30 行)
@Tool({ /* ... */ })
export class Tool2 extends BaseTool { /* ... */ }

// ... 还有 8 个工具文件

// server.ts (15 行)
import { Tool1, Tool2, /* ... */ } from './tools';

createMCPServer('my-server', '1.0.0')
  .enableTools()
  .addTool(new Tool1())
  .addTool(new Tool2())
  // ... 还有 8 个
  .runStdio();

好處:

  • 模塊化、有組織的代碼庫
  • 每個工具可獨立測試
  • 沒有共享狀態問題
  • 乾淨的 git 歷史
  • 工具是可重用的包

問題 #6:忽略生產環境考慮

官方 SDK 設計上是最小化的。它不包括生產必需品:

缺少什麼

  1. 結構化日誌

    • 沒有日誌級別
    • 沒有日誌格式化
    • 沒有日誌聚合支持
    • 只有 console.error()
  2. 指標和監控

    • 沒有性能跟蹤
    • 沒有錯誤率監控
    • 沒有使用統計
    • 沒有健康檢查
  3. 配置管理

    • 沒有基於環境的配置
    • 沒有密鑰管理
    • 沒有配置驗證
    • 所有東西都要手動設置
  4. 優雅關閉

    • 沒有清理鉤子
    • 沒有連接排空
    • 手動信號處理
  5. 速率限制

    • 沒有內置速率限制
    • 沒有請求節流
    • 沒有配額管理
  6. 緩存

    • 沒有緩存層
    • 沒有響應記憶化
    • 自己構建

生產環境現實檢查

在 Zhama,我們運行每天處理數千個請求的 MCP 服務器。這是我們需要的:

// 我们想要的
createMCPServer('production-server', '1.0.0')
  .enableLogging('info')  // 结构化日志
  .enableMetrics()  // 性能跟踪
  .enableRateLimit({ maxRequests: 100, windowMs: 60000 })
  .enableCaching({ ttl: 300 })
  .enableHealthCheck('/health')
  .onShutdown(async () => {
    // 清理
  })
  .addTool(new MyTool())
  .runStdio();

官方 SDK 提供:以上都沒有。

@zhama/mcp-server 提供:內置日誌,其餘可擴展。

真實世界影響:案例研究

讓我分享我們在 Zhama 的實際數據:

項目:客戶支持自動化

**目標:**為 Claude 構建 15 個工具來幫助客戶支持

使用官方 SDK(我們的第一次嘗試)

  • **開發時間:**6 周
  • **編寫代碼:**約 4,500 行
  • **編寫測試:**約 1,200 行
  • **第一個月的 bug:**23 個
  • **新開發者入職時間:**3 天
  • **業務邏輯行數:**約 1,200 行(27%)
  • **樣板代碼行數:**約 3,300 行(73%)

使用 @zhama/mcp-server(遷移後)

  • **遷移時間:**1 周
  • **遷移後代碼:**約 1,800 行(減少 60%)
  • **編寫測試:**約 600 行
  • **第一個月的 bug:**4 個
  • **新開發者入職時間:**4 小時
  • **業務邏輯行數:**約 1,400 行(78%)
  • **樣板代碼行數:**約 400 行(22%)

ROI

  • 入職速度提高 5 倍
  • bug 減少 6 倍
  • 代碼維護量減少 60%
  • 添加新工具速度提高 3 倍

這就是我們為什麼構建 @zhama/mcp-server。

解決方案:框架,而非庫

根本問題是 MCP SDK 是一個庫(低級原語),而大多數開發者需要的是一個框架(高級抽象)。

有什麼區別?

庫(官方 SDK):

  • 你調用它
  • 你控制流程
  • 你編寫所有粘合代碼
  • 最大靈活性
  • 最小生產力

框架(@zhama/mcp-server):

  • 它調用你
  • 它控制流程
  • 它提供粘合代碼
  • 優化生產力
  • 在重要的地方仍然靈活

框架優勢

// 库方法:你做所有事情
const server = createServer();
server.on('request', (req) => {
  if (req.type === 'listTools') {
    return handleListTools();
  } else if (req.type === 'callTool') {
    return handleCallTool(req);
  }
});

// 框架方法:你提供业务逻辑
@Tool({ name: 'my-tool', /* ... */ })
class MyTool extends BaseTool {
  async executeInternal(params) {
    // 只需你的逻辑
  }
}

從官方 SDK 遷移

如果你已經在使用官方 SDK,遷移很簡單:

步驟 1:安裝框架

npm install @zhama/mcp-server

步驟 2:轉換工具

之前:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'my-tool') {
    const result = await doSomething(request.params.arguments);
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }]
    };
  }
});

之後:

@Tool({ name: 'my-tool', /* ... */ })
class MyTool extends BaseTool {
  protected async executeInternal(params: Record<string, unknown>) {
    return await doSomething(params);
  }
}

步驟 3:更新服務器

之前:

const server = new Server(/* ... */);
server.setRequestHandler(/* ... */);
const transport = new StdioServerTransport();
await server.connect(transport);

之後:

createMCPServer('my-server', '1.0.0')
  .enableTools()
  .addTool(new MyTool())
  .runStdio();

遷移時間

  • **1-3 個工具:**30 分鐘
  • **4-10 個工具:**2-3 小時
  • **11-20 個工具:**1 天
  • **20+ 個工具:**2-3 天

加上:新工具的生產力立即提升。

何時使用哪個

使用官方 SDK 當:

✅ 你在構建 MCP 基礎設施
✅ 你需要協議級控制
✅ 你在實現自定義擴展
✅ 你有非常特定的需求
✅ 你在構建自己的框架

使用 @zhama/mcp-server 當:

✅ 你在構建業務工具(99% 的情況)
✅ 你想快速交付
✅ 你重視開發者體驗
✅ 你在構建生產服務
✅ 你有一個開發團隊
✅ 你想要可維護的代碼

未來:為每個人提供更好的工具

我們在 Zhama 的目標不是取代官方 SDK - 而是在它之上構建。@zhama/mcp-server 在底層使用官方 SDK,添加了缺失的開發者體驗層。

接下來是什麼

我們正在積極開發:

  • 測試工具 - 簡單的單元和集成測試
  • 開發模式 - 熱重載和更好的調試
  • 指標集成 - Prometheus、DataDog 等
  • 速率限制 - 內置請求節流
  • 緩存層 - 智能響應緩存
  • 工具市場 - 分享和發現工具
  • 文檔生成器 - 自動生成工具文檔

結論:選擇你自己的冒險

模型上下文協議是革命性的。官方 SDK 是可靠的。但它是為協議實現者設計的,而不是應用程序開發者。

如果你在構建:

  • 概念驗證:官方 SDK 可以
  • 生產工具:使用 @zhama/mcp-server
  • 團隊項目:絕對使用 @zhama/mcp-server
  • 企業集成:使用 @zhama/mcp-server

底線

官方 SDK:

  • 天氣工具 156 行
  • 第一個工具 6 小時
  • 73% 樣板代碼
  • 手動錯誤處理
  • 沒有 DX 功能
  • 難以維護

@zhama/mcp-server:

  • 天氣工具 47 行(減少 70%)
  • 第一個工具 15 分鐘(快 24 倍)
  • 22% 樣板代碼
  • 自動錯誤處理
  • 內置 DX 功能
  • 易於維護

選擇是顯而易見的。

今天就試試

準備好擺脫樣板地獄了嗎?5 分鐘開始:

npm install @zhama/mcp-server

訪問:

  • GitHub:github.com/zhama-ai/mcp-server
  • 官網:www.zhama.com
  • 文檔:完整示例和指南

由 Zhama 用 ❤️ 打造 - 因為開發者應該擁有更好的工具。

對這個分析有想法?加入 GitHub 的討論或通過 team@zhama.com 聯繫我們

16 個開箱即用的 Tego 模板技能:IT 運維 + 跨境電商,一上線就能跑

Tego OS v3.0.0 一次性補齊了 16 個 Tego 系列模板技能,覆蓋 IT 運維與跨境電商兩條最高頻的產業鏈路。每個技能都附帶可執行 bash 腳本,不是「提示詞模板」,而是真正能跑——本文系統介紹這 16 個技能、對應業務流程,以及與 per_user / 模板治理 / BusinessMonitor 是怎麼聯動的。

微信交流群二維碼 微信公眾號二維碼