返回產品博客

我做了一個框架,讓你 5 分鐘寫出一個 Claude 工具

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

我做了一個框架,讓你 5 分鐘寫出一個 Claude 工具

“這也太複雜了吧。”

這是我花了整整一個下午嘗試為 Claude Desktop 構建第一個 MCP 服務器後的想法。官方 SDK 很強大,但老實說 - 僅僅為了創建一個簡單的工具,就需要寫大量的樣板代碼。

我只是想給 Claude 添加一個天氣查詢工具。很簡單的事情。但我發現自己淹沒在:

  • 服務器初始化代碼
  • 傳輸層配置
  • 協議實現細節
  • 錯誤處理樣板
  • 日誌設置
  • 還有更多…

一定有更好的方法。

所以我做了一個。認識一下 @zhama/mcp-server - 一個 TypeScript 框架,讓你真的可以在 5 分鐘內創建 Claude Desktop 工具。

問題:儀式感太多,代碼太少

讓我展示一下我的意思。這是使用原始 MCP SDK 創建一個簡單計算器工具通常需要寫的代碼:

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

// 创建服务器
const server = new Server({
  name: 'calculator-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {}
  }
});

// 注册工具列表处理器
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: 'calculator',
      description: '执行算术运算',
      inputSchema: {
        type: 'object',
        properties: {
          operation: {
            type: 'string',
            description: '要执行的运算',
            enum: ['add', 'subtract', 'multiply', 'divide']
          },
          a: { type: 'number', description: '第一个数字' },
          b: { type: 'number', description: '第二个数字' }
        },
        required: ['operation', 'a', 'b']
      }
    }]
  };
});

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

  const { operation, a, b } = request.params.arguments;
  
  let result;
  switch (operation) {
    case 'add': result = a + b; break;
    case 'subtract': result = a - b; break;
    case 'multiply': result = a * b; break;
    case 'divide': 
      if (b === 0) throw new Error('除数不能为零');
      result = a / b; 
      break;
    default:
      throw new Error('无效的运算');
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({ result })
    }]
  };
});

// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('计算器 MCP 服务器正在运行');
}

main().catch(console.error);

這是超過 70 行代碼,而這只是一個簡單的計算器!我甚至還沒有添加適當的錯誤處理、日誌記錄或輸入驗證。

解決方案:專注於重要的事情

使用 @zhama/mcp-server,同樣的工具變成了這樣:

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

@Tool({
  name: 'calculator',
  description: '执行算术运算',
  parameters: [
    { name: 'operation', type: 'string', description: 'add、subtract、multiply 或 divide', required: true },
    { name: 'a', type: 'number', description: '第一个数字', required: true },
    { name: 'b', type: 'number', description: '第二个数字', required: true }
  ]
})
class CalculatorTool extends BaseTool {
  protected toolDefinition = {
    name: 'calculator',
    description: '执行算术运算',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { operation, a, b } = params as { operation: string; a: number; b: number };
    
    const operations = {
      add: () => a + b,
      subtract: () => a - b,
      multiply: () => a * b,
      divide: () => b !== 0 ? a / b : throw new Error('不能除以零')
    };

    return { result: operations[operation]() };
  }
}

// 就这样!只需创建并运行服务器
createMCPServer('calculator', '1.0.0')
  .enableTools()
  .addTool(new CalculatorTool())
  .runStdio();

不到 30 行。簡潔。可讀。生產就緒。

錯誤處理?內置的。日誌記錄?已包含。類型安全?有保證。服務器設置?自動完成。

5 分鐘挑戰

不相信我?讓我們一起構建一個真實的工具 - 現在就開始。打開你的終端,跟著做。

第 1 分鐘:設置(60 秒)

mkdir my-claude-tool && cd my-claude-tool
npm init -y
npm install @zhama/mcp-server typescript @types/node
npx tsc --init

第 2-3 分鐘:編寫工具(120 秒)

創建 src/server.ts:

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

@Tool({
  name: 'get_joke',
  description: '获取一个随机编程笑话来调节气氛',
  parameters: []
})
class JokeTool extends BaseTool {
  protected toolDefinition = {
    name: 'get_joke',
    description: '获取随机笑话',
    parameters: []
  };

  protected async executeInternal(): Promise<unknown> {
    const response = await fetch('https://official-joke-api.appspot.com/random_joke');
    const joke = await response.json();
    return {
      setup: joke.setup,
      punchline: joke.punchline,
      joke: `${joke.setup} - ${joke.punchline}`
    };
  }
}

createMCPServer('joke-server', '1.0.0')
  .description('为你的 AI 对话带来幽默')
  .enableTools()
  .addTool(new JokeTool())
  .runStdio();

第 4 分鐘:構建(30 秒)

npx tsc

第 5 分鐘:配置 Claude(30 秒)

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jokes": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/server.js"]
    }
  }
}

重啟 Claude Desktop。完成!

現在問 Claude:“給我講個編程笑話” - 然後看你的工具運行起來!

為什麼我要做這個框架

作為 Zhama 的開發者,我花了大量時間構建 AI 集成。我見過團隊一次又一次地在同樣的問題上掙扎:

1. 學習曲線陡峭

官方 MCP SDK 是低級的、面向協議的。它很強大,但在你能構建任何有用的東西之前,需要理解整個協議規範。大多數開發者只是想添加一個工具 - 他們不想先成為 MCP 專家。

2. 樣板代碼太多

每個工具都需要設置請求處理器、管理模式、處理響應、配置傳輸層… 這很累人。一個應該只需要 10 行代碼的簡單工具最終變成了 100 多行基礎設施代碼。

3. 容易出錯

沒有適當的抽象,很容易犯錯誤:忘記驗證輸入、錯過錯誤情況、返回錯誤的響應格式,或配置錯誤服務器。這些錯誤只會在運行時出現,當 Claude 嘗試使用你的工具時。

4. 難以維護

隨著工具的增長,代碼變得更難管理。請求處理器與業務邏輯混在一起。錯誤處理散落各處。測試變成了噩夢。

我想解決所有這些問題。

設計理念

在構建 @zhama/mcp-server 時,我遵循了三個核心原則:

1. 裝飾器優於配置

不再編寫 JSON 模式和請求處理器,而是用 TypeScript 裝飾器描述你的工具:

@Tool({
  name: 'search_database',
  description: '搜索产品数据库',
  parameters: [
    { name: 'query', type: 'string', required: true },
    { name: 'limit', type: 'number', required: false }
  ]
})
class SearchTool extends BaseTool {
  // 你的逻辑在这里
}

框架處理其他一切 - 模式生成、驗證、請求路由、響應格式化。

2. 約定優於配置

所有東西都有合理的默認值:

// 最小设置
createMCPServer('my-server', '1.0.0')
  .enableTools()
  .addTool(new MyTool())
  .runStdio();

// 或者为生产环境完全配置
createMCPServer('my-server', '1.0.0')
  .description('生产服务器')
  .author('你的团队')
  .enableTools({ listChanged: true })
  .enableResources({ subscribe: true })
  .enableLogging('info')
  .addTool(new MyTool())
  .runStdio();

兩者都可以。從簡單開始,只在需要時添加複雜性。

3. TypeScript 優先

到處都有完整的類型安全。真正有幫助的 IntelliSense。在編譯時而不是運行時捕獲錯誤:

// TypeScript 知道参数类型
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
  // 类型安全的解构
  const { query, limit = 10 } = params as { 
    query: string; 
    limit?: number 
  };
  
  // TypeScript 检查一切
  return await this.searchDatabase(query, limit);
}

真實案例

讓我展示一些我們在 Zhama 使用這個框架構建的工具:

天氣查詢工具(2 分鐘)

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

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { city } = params as { city: string };
    const apiKey = process.env.WEATHER_API_KEY;
    
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`
    );
    
    const data = await response.json();
    
    return {
      city: data.name,
      temperature: data.main.temp,
      condition: data.weather[0].description,
      humidity: data.main.humidity,
      summary: `${data.name}:${data.main.temp}°C,${data.weather[0].description}`
    };
  }
}

使用場景:“嘿 Claude,東京的天氣怎麼樣?”

數據庫查詢工具(3 分鐘)

@Tool({
  name: 'query_users',
  description: '通过邮箱或姓名在数据库中搜索用户',
  parameters: [
    { name: 'search_term', type: 'string', description: '要搜索的邮箱或姓名', required: true }
  ]
})
class UserQueryTool extends BaseTool {
  private db: DatabaseConnection;

  constructor() {
    super();
    this.db = new DatabaseConnection();
  }

  protected toolDefinition = {
    name: 'query_users',
    description: '查询用户数据库',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { search_term } = params as { search_term: string };
    
    // 参数化查询以确保安全
    const users = await this.db.query(
      'SELECT id, name, email, created_at FROM users WHERE name LIKE ? OR email LIKE ? LIMIT 10',
      [`%${search_term}%`, `%${search_term}%`]
    );
    
    return {
      found: users.length,
      users: users.map(u => ({
        id: u.id,
        name: u.name,
        email: u.email,
        memberSince: u.created_at
      }))
    };
  }
}

使用場景:“Claude,找出所有名字中包含’張’的用戶”

文件分析工具(4 分鐘)

@Tool({
  name: 'analyze_file',
  description: '分析文件并返回统计信息',
  parameters: [
    { name: 'file_path', type: 'string', description: '文件路径', required: true }
  ]
})
class FileAnalysisTool extends BaseTool {
  protected toolDefinition = {
    name: 'analyze_file',
    description: '分析文件统计信息',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { file_path } = params as { file_path: string };
    
    // 安全性:验证路径
    if (file_path.includes('..')) {
      throw new Error('无效的文件路径');
    }
    
    const content = await fs.readFile(file_path, 'utf-8');
    const lines = content.split('\n');
    const words = content.split(/\s+/).filter(w => w.length > 0);
    
    return {
      path: file_path,
      size: content.length,
      lines: lines.length,
      words: words.length,
      characters: content.length,
      type: file_path.split('.').pop(),
      preview: lines.slice(0, 5).join('\n')
    };
  }
}

使用場景:“幫我分析一下 README.md 文件”

Slack 通知工具(3 分鐘)

@Tool({
  name: 'send_slack_message',
  description: '向 Slack 频道发送消息',
  parameters: [
    { name: 'channel', type: 'string', description: '频道名称(例如 #general)', required: true },
    { name: 'message', type: 'string', description: '要发送的消息', required: true }
  ]
})
class SlackTool extends BaseTool {
  protected toolDefinition = {
    name: 'send_slack_message',
    description: '发送 Slack 消息',
    parameters: []
  };

  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { channel, message } = params as { channel: string; message: string };
    
    const response = await fetch('https://slack.com/api/chat.postMessage', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SLACK_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ channel, text: message })
    });
    
    const result = await response.json();
    
    return {
      success: result.ok,
      channel: channel,
      timestamp: result.ts,
      message: '消息发送成功'
    };
  }
}

使用場景:“向 #engineering 頻道發送消息說部署已完成”

免費獲得的內置功能

當你使用 @zhama/mcp-server 時,你自動獲得:

✅ 生產級日誌記錄

// 内置在每个工具中
this.logger.info('正在处理请求');
this.logger.error('操作失败', error);
this.logger.debug('详细调试信息');

✅ 自動錯誤處理

// 错误会被自动捕获并格式化
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
  throw new Error('出了点问题');
  // 框架会优雅地处理这个错误并向 Claude 返回适当的错误响应
}

✅ 輸入驗證

// 参数会自动根据你的模式进行验证
@Tool({
  parameters: [
    { name: 'age', type: 'number', required: true }
  ]
})
// 如果 Claude 传递字符串而不是数字,框架会在你的代码运行之前拒绝它

✅ 類型安全

// 完整的 TypeScript 支持和 IntelliSense
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
  // TypeScript 在每一步都帮助你
}

✅ 多種傳輸模式

// STDIO 用于 Claude Desktop
await server.runStdio();

// SSE 用于 Web 应用
await server.runSSE(3000);

✅ 資源管理

// 不仅仅是工具 - 还有资源!
class DataResource extends BaseResource {
  protected async executeInternal(id: string): Promise<Resource> {
    return {
      id,
      uri: `data://${id}`,
      name: '数据资源',
      type: 'application/json',
      content: JSON.stringify({ data: '你的数据' })
    };
  }
}

✅ 提示工程

// 动态提示生成
server.addPromptGenerator('code-review', async (language: string) => {
  return {
    id: `review-${language}`,
    name: `代码审查:${language}`,
    type: 'text',
    content: generateReviewPrompt(language)
  };
});

對比:使用前後

讓我把一切都放在透視中。這是構建天氣工具所需的工作:

之前(原始 MCP SDK):約 200 行,30+ 分鐘

  • 設置服務器基礎設施
  • 配置傳輸層
  • 手動定義工具模式
  • 實現請求處理器
  • 手動處理錯誤
  • 設置日誌記錄
  • 正確格式化響應
  • 測試一切

之後(@zhama/mcp-server):約 30 行,5 分鐘

@Tool({
  name: 'weather',
  description: '获取天气',
  parameters: [{ name: 'city', type: 'string', required: true }]
})
class WeatherTool extends BaseTool {
  protected toolDefinition = { name: 'weather', description: '获取天气', parameters: [] };
  
  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const { city } = params as { city: string };
    const weather = await getWeather(city);
    return { city, ...weather };
  }
}

createMCPServer('weather', '1.0.0')
  .enableTools()
  .addTool(new WeatherTool())
  .runStdio();

代碼減少了 85%,時間減少了 83%。

今天就開始

想自己試試嗎?這是完整的快速入門:

第 1 步:安裝

npm install @zhama/mcp-server

第 2 步:創建你的第一個工具

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

@Tool({
  name: 'hello',
  description: '打招呼',
  parameters: [
    { name: 'name', type: 'string', description: '要问候的名字', 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}!👋`,
      timestamp: new Date().toISOString()
    };
  }
}

async function main() {
  const server = createMCPServer('hello-server', '1.0.0')
    .description('我的第一个 MCP 服务器')
    .enableTools()
    .addTool(new HelloTool());

  await server.runStdio();
}

main().catch(console.error);

第 3 步:構建和配置

npx tsc

添加到 Claude 配置:

{
  "mcpServers": {
    "hello": {
      "command": "node",
      "args": ["/path/to/dist/server.js"]
    }
  }
}

第 4 步:測試

重啟 Claude 並問:“向小明問好”

高級模式

一旦你熟悉了基礎知識,這裡有一些高級模式:

一個服務器中的多個工具

createMCPServer('enterprise-server', '1.0.0')
  .enableTools()
  .addTool(new DatabaseTool())
  .addTool(new EmailTool())
  .addTool(new SlackTool())
  .addTool(new AnalyticsTool())
  .runStdio();

基於環境的配置

const config = {
  logLevel: process.env.LOG_LEVEL || 'info',
  dbHost: process.env.DB_HOST,
  apiKey: process.env.API_KEY
};

createMCPServer('my-server', '1.0.0')
  .enableLogging(config.logLevel)
  .addTool(new MyTool(config))
  .runStdio();

自定義基類

// 为常见模式创建你自己的基类
abstract class AuthenticatedTool extends BaseTool {
  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    // 检查认证
    if (!this.validateAuth(params)) {
      throw new Error('未授权');
    }
    
    // 调用子类实现
    return await this.executeAuthenticated(params);
  }
  
  protected abstract executeAuthenticated(params: Record<string, unknown>): Promise<unknown>;
  protected abstract validateAuth(params: Record<string, unknown>): boolean;
}

// 使用它
@Tool({ /* ... */ })
class SecureDataTool extends AuthenticatedTool {
  protected async executeAuthenticated(params: Record<string, unknown>): Promise<unknown> {
    // 你的安全逻辑在这里
  }
  
  protected validateAuth(params: Record<string, unknown>): boolean {
    return params.apiKey === process.env.API_KEY;
  }
}

緩存模式

@Tool({ /* ... */ })
class CachedTool extends BaseTool {
  private cache = new Map<string, { data: any; expires: number }>();
  
  protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
    const key = JSON.stringify(params);
    const cached = this.cache.get(key);
    
    if (cached && cached.expires > Date.now()) {
      this.logger.info('返回缓存结果');
      return cached.data;
    }
    
    const data = await this.fetchData(params);
    this.cache.set(key, {
      data,
      expires: Date.now() + 5 * 60 * 1000 // 5 分钟
    });
    
    return data;
  }
}

Zhama 的真實生產案例

在 Zhama,我們所有的 Claude 集成都使用這個框架。這裡是我們構建的一些工具:

1. 客戶支持自動化

  • 查詢客戶數據
  • 檢查訂單狀態
  • 處理退款
  • 創建支持工單

2. 開發工具

  • 部署到測試/生產環境
  • 運行數據庫遷移
  • 檢查服務健康狀態
  • 查看應用日誌

3. 內容管理

  • 發佈博客文章
  • 更新文檔
  • 生成社交媒體內容
  • 安排內容發佈

4. 數據分析

  • 查詢分析數據庫
  • 生成報告
  • 導出數據
  • 創建可視化

全部使用這個框架構建。全部部署到生產環境。全部與 Claude Desktop 可靠工作。

社區和支持

框架是開源的,正在積極維護:

  • GitHub:github.com/zhama-ai/mcp-server
  • 官網:www.zhama.com
  • Issues:在 GitHub 上報告錯誤和請求功能
  • Discussions:分享你的工具並獲得幫助
  • 郵件:team@zhama.com 獲取企業支持

接下來是什麼?

我正在根據像你這樣的開發者的反饋不斷改進框架。即將推出的功能:

  • 🔄 流式響應 - 用於長時間運行的操作
  • 🔐 內置認證模式 - 常見的認證策略
  • 📊 指標和監控 - 開箱即用的可觀察性
  • 🧪 測試工具 - 簡單的單元和集成測試
  • 📚 更多示例 - 真實世界的生產模式
  • 🎨 工具市場 - 分享和發現社區工具

現在就試試 - 你有 5 分鐘

我挑戰你:設置一個 5 分鐘的計時器,使用 @zhama/mcp-server 構建你的第一個 Claude 工具。

  1. 安裝框架(30 秒)
  2. 複製一個示例(60 秒)
  3. 自定義它(120 秒)
  4. 構建和配置(90 秒)
  5. 在 Claude 中測試(立即)

就這樣。你將在 5 分鐘或更短的時間內擁有一個與 Claude Desktop 集成的工作工具。

為什麼這很重要

Claude Desktop 很棒,但它僅限於它知道和能做的事情。通過添加自定義工具,你可以:

  • 將 Claude 連接到你的系統 - 數據庫、API、內部工具
  • 自動化你的工作流 - 讓 Claude 幫助處理日常任務
  • 構建更好的產品 - 更快地創建 AI 驅動的功能
  • 邊做邊學 - 通過實際示例理解 MCP

現在,使用 @zhama/mcp-server,入門門檻幾乎為零。

結論:更少的代碼,更多的價值

我做這個框架是因為我感到沮喪。對樣板代碼感到沮喪。對複雜性感到沮喪。對構建簡單工具所花費的時間感到沮喪。

現在只需要 5 分鐘。

不再與協議細節搏鬥。不再複製粘貼樣板代碼。不再調試晦澀的 SDK 錯誤。

只需編寫你的工具,添加到服務器,然後看它在 Claude Desktop 中工作。

這就是良好抽象的力量。這就是我為什麼做 @zhama/mcp-server。

準備好在 5 分鐘內構建你的第一個工具了嗎?

訪問 github.com/zhama-ai/mcp-server 開始使用。


由 Zhama 用 ❤️ 打造 - 讓 AI 開發對每個人都可及。

你用 @zhama/mcp-server 構建了什麼很酷的東西嗎?在 GitHub Discussions 上分享 - 我們很想看看你創造了什麼!

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

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

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