“中國版 Muse”來了:TeGo 讓雲端 Agent 在企業上崗
Muse 讓雲端 Agent 走到臺前。TeGo 把數字分身帶進中國企業的真實工作:接任務、用工具、交結果,也讓關鍵操作回到人的判斷中。
本文發佈於 2024年11月18日。產品當前能力參見產品能力。
讓我先聲明一點:官方的模型上下文協議 SDK 非常優秀。它設計良好,精確遵循規範,並讓你完全控制協議。Anthropic 團隊在創建一個堅實的 MCP 開發基礎方面做得非常出色。
但問題是:技術上正確並不意味著對開發者友好。
在 Zhama 為生產環境構建了數十個 MCP 服務器之後,我發現了當前 SDK 的六個根本問題,這些問題使它不適合真實世界的快速開發。這不是為了批評而批評 - 這是對我們為什麼構建 @zhama/mcp-server 的誠實分析,以及為什麼你可能也需要它。
官方 MCP SDK 是協議優先的。它旨在讓你直接訪問模型上下文協議的原語:請求、響應、處理器、傳輸層。如果你要:
這很好。
但如果你要:
這就很糟糕。
讓我準確展示我的意思。
在你可以構建一個簡單的計算器工具之前,你需要理解:
服務器初始化和配置
const server = new Server({
name: 'my-server',
version: '1.0.0'
}, {
capabilities: {
tools: {},
resources: {},
prompts: {}
}
});
請求模式類型
import {
CallToolRequestSchema,
ListToolsRequestSchema,
ListResourcesRequestSchema,
ReadResourceRequestSchema
} from '@modelcontextprotocol/sdk/types.js';
請求處理器註冊
server.setRequestHandler(ListToolsRequestSchema, async () => {
// 返回工具定义
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
// 执行工具逻辑
});
用於輸入驗證的 JSON Schema
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string' },
param2: { type: 'number' }
},
required: ['param1', 'param2']
}
響應格式化
return {
content: [{
type: 'text',
text: JSON.stringify(result)
}]
};
傳輸層設置
const transport = new StdioServerTransport();
await server.connect(transport);
這至少是 6 個不同的概念,僅僅是為了構建一個 “Hello World” 工具。
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 倍。
讓我們用兩種方法構建相同的功能,並計算代碼行數。
官方 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 構建的每個工具都需要:
每個工具有 55-90 行樣板代碼。
使用 @zhama/mcp-server:**0 行樣板代碼。**只需編寫業務邏輯。
官方 SDK 完全將錯誤處理留給你。這意味著:
輸入驗證錯誤
if (!params.email || typeof params.email !== 'string') {
throw new Error('无效的邮箱参数');
}
業務邏輯錯誤
try {
const result = await performOperation();
} catch (error) {
// 这里应该返回什么?
}
響應格式化
return {
content: [{
type: 'text',
text: JSON.stringify({ error: error.message })
}],
isError: true // 别忘了这个!
};
日誌記錄
console.error('工具失败:', error); // 希望这就够了
在生產環境中,我們發現使用官方 SDK 時,錯誤處理代碼經常超過業務邏輯代碼。一個典型的工具看起來像:
只有 25% 的代碼是實際功能。
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
// 只需编写你的逻辑
// 错误自动捕获
// 日志自动记录
// 响应自动格式化
const result = await performOperation(params);
return result; // 就这样!
}
80-90% 的代碼是實際功能。
官方 SDK 提供零開發者體驗優化:
官方 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
};
// 立即使用 - 验证是自动的
}
}
隨著 MCP 服務器的增長,官方 SDK 的問題會複合:
官方 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
}
});
問題:
@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();
好處:
官方 SDK 設計上是最小化的。它不包括生產必需品:
結構化日誌
指標和監控
配置管理
優雅關閉
速率限制
緩存
在 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 個工具來幫助客戶支持
這就是我們為什麼構建 @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,遷移很簡單:
npm install @zhama/mcp-server
之前:
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);
}
}
之前:
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();
加上:新工具的生產力立即提升。
✅ 你在構建 MCP 基礎設施
✅ 你需要協議級控制
✅ 你在實現自定義擴展
✅ 你有非常特定的需求
✅ 你在構建自己的框架
✅ 你在構建業務工具(99% 的情況)
✅ 你想快速交付
✅ 你重視開發者體驗
✅ 你在構建生產服務
✅ 你有一個開發團隊
✅ 你想要可維護的代碼
我們在 Zhama 的目標不是取代官方 SDK - 而是在它之上構建。@zhama/mcp-server 在底層使用官方 SDK,添加了缺失的開發者體驗層。
我們正在積極開發:
模型上下文協議是革命性的。官方 SDK 是可靠的。但它是為協議實現者設計的,而不是應用程序開發者。
如果你在構建:
官方 SDK:
@zhama/mcp-server:
選擇是顯而易見的。
準備好擺脫樣板地獄了嗎?5 分鐘開始:
npm install @zhama/mcp-server
訪問:
由 Zhama 用 ❤️ 打造 - 因為開發者應該擁有更好的工具。
對這個分析有想法?加入 GitHub 的討論或通過 team@zhama.com 聯繫我們
Muse 讓雲端 Agent 走到臺前。TeGo 把數字分身帶進中國企業的真實工作:接任務、用工具、交結果,也讓關鍵操作回到人的判斷中。
TeGo v3.0.0 在桌面端做了三件事:常駐置頂的 Mini Chat 浮窗、統一的下載中心、Windows NSIS 安裝器全面重寫。本文聚焦體驗細節,解釋這套組合是怎麼把數字分身真正「裝進每天的工作流」的。
TeGo v3.0.0 一次性補齊了 16 個 TeGo 系列模板技能,覆蓋 IT 運維與跨境電商兩條最高頻的產業鏈路。每個技能都附帶可執行 bash 腳本,不是「提示詞模板」,而是真正能跑——本文系統介紹這 16 個技能、對應業務流程,以及與 per_user / 模板治理 / BusinessMonitor 是怎麼聯動的。