使用 TypeScript 構建生產級 MCP 服務器:完整實戰指南
深入學習如何使用 TypeScript 構建可擴展的模型上下文協議服務器。本指南涵蓋從基礎配置到生產部署的完整流程,包含真實案例和最佳實踐。
本文發佈於 2024年11月16日。產品當前能力參見產品能力。
在快速發展的 AI 開發領域,為 AI 助手擴展自定義能力已經變得至關重要。Claude Desktop 是 Anthropic 推出的強大 AI 助手,通過**模型上下文協議(MCP)**為開發者提供了令人興奮的機會 —— 但從零開始構建 MCP 服務器可能會讓人望而卻步。
這就是 @zhama/mcp-server 的用武之地 —— 一個生產級的 TypeScript 框架,通過優雅的、基於裝飾器的 API 簡化了 MCP 服務器的開發。無論您是要構建數據庫集成、API 連接器,還是自定義業務工具,這個框架都讓一切變得非常簡單。
在這份全面的指南中,我們將詳細介紹為 Claude Desktop 構建自定義 MCP 服務器所需瞭解的一切,從基礎概念到生產部署。
**模型上下文協議(Model Context Protocol)**是一種標準化的通信協議,使 Claude Desktop 等 AI 應用程序能夠與外部工具、資源和數據源進行交互。可以把它想像成一個通用適配器,在 AI 智能和您的自定義功能之間架起橋梁。
MCP 提供三種核心能力:
開箱即用的 Claude Desktop 已經非常強大,但當您使用自定義功能擴展它時,它的真正潛力才會被釋放:
直接使用官方 SDK 構建 MCP 服務器可能會複雜且冗長。由 Zhama 團隊開發的 @zhama/mcp-server 框架通過以下方式解決了這些挑戰:
開始之前,請確保您具備:
創建一個新項目並安裝框架:
# 创建新目录
mkdir my-mcp-server
cd my-mcp-server
# 初始化 Node.js 项目
npm init -y
# 安装框架
npm install @zhama/mcp-server
# 安装 TypeScript 和开发依赖
npm install -D typescript @types/node
# 初始化 TypeScript 配置
npx tsc --init
使用這個推薦的結構組織您的項目:
my-mcp-server/
├── src/
│ ├── tools/ # 工具实现
│ ├── resources/ # 资源处理器
│ ├── prompts/ # 提示生成器
│ └── server.ts # 主服务器文件
├── dist/ # 编译后的 JavaScript
├── package.json
└── tsconfig.json
讓我們從一個實用示例開始 - 一個 Claude 可以用來執行數學運算的計算器工具。
創建 src/tools/calculator.ts:
import { 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
}
]
})
export 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: 'add' | 'subtract' | 'multiply' | 'divide';
a: number;
b: number;
};
// 验证运算类型
const validOperations = ['add', 'subtract', 'multiply', 'divide'];
if (!validOperations.includes(operation)) {
throw new Error(`无效的运算:${operation}。必须是以下之一:${validOperations.join('、')}`);
}
// 执行计算
let result: number;
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;
}
return {
operation,
operands: { a, b },
result,
formatted: `${a} ${this.getOperatorSymbol(operation)} ${b} = ${result}`
};
}
private getOperatorSymbol(operation: string): string {
const symbols = {
add: '+',
subtract: '-',
multiply: '×',
divide: '÷'
};
return symbols[operation] || operation;
}
}
創建 src/server.ts:
import { createMCPServer } from '@zhama/mcp-server';
import { CalculatorTool } from './tools/calculator';
async function main() {
// 创建带有元数据的 MCP 服务器
const server = createMCPServer('my-calculator-server', '1.0.0')
.description('为 Claude Desktop 提供的强大计算器 MCP 服务器')
.author('您的名字')
.license('MIT')
.enableTools({ listChanged: true })
.enableLogging('info')
.addTool(new CalculatorTool());
// 以 STDIO 模式启动服务器(用于 Claude Desktop)
console.error('正在启动计算器 MCP 服务器...');
await server.runStdio();
}
// 运行服务器
main().catch((error) => {
console.error('启动服务器失败:', error);
process.exit(1);
});
在 package.json 中添加構建腳本:
{
"name": "my-mcp-server",
"version": "1.0.0",
"scripts": {
"build": "tsc",
"start": "node dist/server.js",
"dev": "tsc && node dist/server.js"
}
}
構建項目:
npm run build
要在 Claude Desktop 中使用您的 MCP 服務器,需要將其添加到配置文件:
在 macOS 上:~/Library/Application Support/Claude/claude_desktop_config.json
在 Windows 上:%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"calculator": {
"command": "node",
"args": ["/absolute/path/to/your/project/dist/server.js"]
}
}
}
重要提示:使用編譯後的 server.js 文件的絕對路徑。
讓我們構建一些更復雜的東西 - 一個可以安全查詢數據庫的工具。
創建 src/tools/database-query.ts:
import { BaseTool, Tool } from '@zhama/mcp-server';
import { DatabaseConnection } from './db-connection'; // 您的数据库库
@Tool({
name: 'query_customer',
description: '通过邮箱或客户 ID 搜索客户信息。返回客户详细信息,包括姓名、邮箱和账户状态。',
parameters: [
{
name: 'search_type',
type: 'string',
description: '搜索类型:"email"(邮箱)或 "customer_id"(客户ID)',
required: true
},
{
name: 'search_value',
type: 'string',
description: '要搜索的邮箱地址或客户 ID',
required: true
}
]
})
export class CustomerQueryTool extends BaseTool {
private db: DatabaseConnection;
constructor() {
super();
this.db = new DatabaseConnection();
}
protected toolDefinition = {
name: 'query_customer',
description: '搜索客户信息',
parameters: []
};
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
const { search_type, search_value } = params as {
search_type: 'email' | 'customer_id';
search_value: string;
};
// 验证搜索类型
if (!['email', 'customer_id'].includes(search_type)) {
throw new Error('无效的 search_type。必须是 "email" 或 "customer_id"');
}
// 验证搜索值
if (!search_value || search_value.trim() === '') {
throw new Error('search_value 不能为空');
}
try {
// 使用参数化查询防止 SQL 注入
let customer;
if (search_type === 'email') {
customer = await this.db.query(
'SELECT id, name, email, account_status, created_at FROM customers WHERE email = ?',
[search_value]
);
} else {
customer = await this.db.query(
'SELECT id, name, email, account_status, created_at FROM customers WHERE id = ?',
[search_value]
);
}
if (!customer || customer.length === 0) {
return {
found: false,
message: `未找到 ${search_type}:${search_value} 的客户`
};
}
return {
found: true,
customer: {
id: customer[0].id,
name: customer[0].name,
email: customer[0].email,
status: customer[0].account_status,
memberSince: customer[0].created_at
}
};
} catch (error) {
this.logger.error('数据库查询失败', error);
throw new Error('查询客户数据库失败');
}
}
}
資源允許 Claude 訪問動態內容。以下是如何創建文件系統資源:
創建 src/resources/file-reader.ts:
import { BaseResource } from '@zhama/mcp-server';
import * as fs from 'fs/promises';
import * as path from 'path';
export class FileReaderResource extends BaseResource {
private allowedDirectory: string;
constructor(allowedDirectory: string) {
super();
this.allowedDirectory = path.resolve(allowedDirectory);
}
protected resourceDefinition = {
type: 'text/plain' as const,
description: '从允许的目录读取文件内容'
};
protected async executeInternal(filePath: string): Promise<any> {
// 安全性:确保文件在允许的目录内
const resolvedPath = path.resolve(this.allowedDirectory, filePath);
if (!resolvedPath.startsWith(this.allowedDirectory)) {
throw new Error('拒绝访问:文件在允许的目录之外');
}
try {
const content = await fs.readFile(resolvedPath, 'utf-8');
const stats = await fs.stat(resolvedPath);
return {
id: `file-${path.basename(filePath)}`,
uri: `file://${resolvedPath}`,
name: path.basename(filePath),
type: 'text/plain',
content,
metadata: {
size: stats.size,
modified: stats.mtime,
path: resolvedPath
}
};
} catch (error) {
this.logger.error('读取文件失败', error);
throw new Error(`读取文件失败:${error.message}`);
}
}
}
提示幫助用領域特定的指令引導 Claude 的行為:
創建 src/prompts/code-review.ts:
import { BasePrompt } from '@zhama/mcp-server';
export class CodeReviewPrompt extends BasePrompt {
protected promptDefinition = {
type: 'text' as const,
description: '为不同编程语言生成代码审查指令'
};
protected async executeInternal(language: string): Promise<any> {
const guidelines = this.getGuidelinesForLanguage(language);
return {
id: `code-review-${language}`,
name: `代码审查:${language}`,
type: 'text',
content: `您正在对 ${language} 代码进行代码审查。
遵循以下准则:
${guidelines}
重点关注:
1. 代码质量和最佳实践
2. 潜在的错误和边界情况
3. 性能考虑
4. 安全漏洞
5. 可维护性和可读性
提供建设性反馈,并给出具体的改进建议。`
};
}
private getGuidelinesForLanguage(language: string): string {
const guidelinesMap: Record<string, string> = {
typescript: `
- 确保正确的类型注解
- 检查 any 的使用并建议具体类型
- 验证 null/undefined 处理
- 审查 async/await 模式
- 检查适当的错误处理`,
python: `
- 验证 PEP 8 合规性
- 检查类型提示的使用
- 审查异常处理
- 验证文档字符串的完整性
- 检查安全问题(如 SQL 注入)`,
javascript: `
- 检查现代 ES6+ 语法的使用
- 验证适当的错误处理
- 审查异步模式
- 检查内存泄漏
- 验证安全最佳实践`
};
return guidelinesMap[language.toLowerCase()] || '应用一般代码审查最佳实践';
}
}
以下是具有多種功能的生產級 MCP 服務器的完整示例:
創建 src/server.ts:
import { createMCPServer } from '@zhama/mcp-server';
import { CalculatorTool } from './tools/calculator';
import { CustomerQueryTool } from './tools/database-query';
import { FileReaderResource } from './resources/file-reader';
import { CodeReviewPrompt } from './prompts/code-review';
async function main() {
const server = createMCPServer('enterprise-mcp-server', '2.0.0')
.description('具有数据库、文件和分析功能的企业级 MCP 服务器')
.author('您的公司')
.license('MIT')
// 启用所有功能
.enableTools({ listChanged: true })
.enableResources({ subscribe: true, listChanged: true })
.enablePrompts({ listChanged: true })
// 从环境配置日志级别
.enableLogging(process.env.LOG_LEVEL || 'info')
// 添加工具
.addTool(new CalculatorTool())
.addTool(new CustomerQueryTool())
// 添加资源
.addResource(new FileReaderResource(process.env.ALLOWED_DIR || './data'))
// 添加提示生成器
.addPromptGenerator('code-review', async (language: string) => {
const prompt = new CodeReviewPrompt();
return await prompt.execute(language);
});
// 优雅处理关闭
process.on('SIGINT', () => {
console.error('正在关闭 MCP 服务器...');
process.exit(0);
});
// 启动服务器
console.error('正在启动企业级 MCP 服务器...');
console.error(`日志级别:${process.env.LOG_LEVEL || 'info'}`);
await server.runStdio();
}
main().catch((error) => {
console.error('致命错误:', error);
process.exit(1);
});
始終驗證和清理輸入:
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
// 验证必需参数
if (!params.userId || typeof params.userId !== 'string') {
throw new Error('无效的 userId 参数');
}
// 清理输入
const userId = params.userId.trim();
if (!/^[a-zA-Z0-9-]+$/.test(userId)) {
throw new Error('userId 包含无效字符');
}
// 使用参数化查询
const result = await this.db.query('SELECT * FROM users WHERE id = ?', [userId]);
return result;
}
提供清晰、可操作的錯誤消息:
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
try {
return await this.performOperation(params);
} catch (error) {
if (error instanceof ValidationError) {
throw new Error(`无效的输入:${error.message}`);
} else if (error instanceof DatabaseError) {
this.logger.error('数据库错误', error);
throw new Error('发生数据库错误。请稍后重试。');
} else {
this.logger.error('意外错误', error);
throw new Error('发生意外错误');
}
}
}
幫助 Claude 理解何時以及如何使用您的工具:
@Tool({
name: 'send_notification',
description: `通过邮件或短信向用户发送通知。
在以下情况下使用此工具:
- 用户明确要求发送通知
- 重要事件需要用户通知
- 需要发送预定的提醒
不要使用此工具:
- 对于每个细微更新
- 未经明确用户同意
- 用于营销目的`,
parameters: [/* ... */]
})
有效使用異步模式和緩存:
export class DataFetchTool extends BaseTool {
private cache = new Map<string, { data: any; timestamp: number }>();
private cacheDuration = 5 * 60 * 1000; // 5 分钟
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
const key = this.getCacheKey(params);
// 检查缓存
const cached = this.cache.get(key);
if (cached && Date.now() - cached.timestamp < this.cacheDuration) {
return cached.data;
}
// 获取新数据
const data = await this.fetchData(params);
// 更新缓存
this.cache.set(key, { data, timestamp: Date.now() });
return data;
}
}
為您的工具編寫測試:
import { describe, it, expect } from '@jest/globals';
import { CalculatorTool } from './calculator';
describe('CalculatorTool', () => {
const tool = new CalculatorTool();
it('应该正确地将两个数字相加', async () => {
const result = await tool.execute({
operation: 'add',
a: 10,
b: 5
});
expect(result.result).toBe(15);
});
it('除以零应该抛出错误', async () => {
await expect(
tool.execute({ operation: 'divide', a: 10, b: 0 })
).rejects.toThrow('除以零');
});
it('应该拒绝无效的运算', async () => {
await expect(
tool.execute({ operation: 'invalid', a: 10, b: 5 })
).rejects.toThrow('无效的运算');
});
});
構建幫助 Claude 處理客戶查詢的工具:
增強 Claude 的編碼輔助能力:
讓 Claude 能夠處理您的數據:
與內容系統集成:
將日誌級別設置為調試以進行故障排除:
const server = createMCPServer('my-server', '1.0.0')
.enableLogging('debug');
檢查 Claude Desktop 日誌中的錯誤:
macOS:~/Library/Logs/Claude/
查找連接錯誤、工具執行失敗和其他問題。
問題:工具未在 Claude 中顯示
問題:工具執行靜默失敗
問題:參數未正確傳遞
使用 nodemon 進行自動重載:
{
"scripts": {
"dev": "nodemon --watch src --exec 'npm run build && node dist/server.js'"
}
}
npm install -g pm2
pm2 start dist/server.js --name mcp-server
pm2 save
pm2 startup
創建 Dockerfile:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/server.js"]
構建和運行:
docker build -t my-mcp-server .
docker run -d my-mcp-server
使用環境變量進行配置:
const config = {
logLevel: process.env.LOG_LEVEL || 'info',
dbHost: process.env.DB_HOST || 'localhost',
dbPort: parseInt(process.env.DB_PORT || '5432'),
apiKey: process.env.API_KEY
};
創建 .env 文件:
LOG_LEVEL=debug
DB_HOST=localhost
DB_PORT=5432
API_KEY=your-secret-key
同時支持 STDIO 和 SSE:
const mode = process.argv[2] || '--stdio';
if (mode === '--stdio') {
await server.runStdio();
} else if (mode === '--sse') {
const port = parseInt(process.argv[3] || '3000');
await server.runSSE(port);
console.error(`SSE 服务器运行在端口 ${port}`);
}
向請求處理添加自定義邏輯:
export class AuthenticatedTool extends BaseTool {
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
// 检查身份验证
if (!this.validateApiKey(params.apiKey)) {
throw new Error('未授权');
}
// 继续操作
return await this.performAuthenticatedAction(params);
}
private validateApiKey(key: unknown): boolean {
return typeof key === 'string' && key === process.env.API_KEY;
}
}
實現工具使用的速率限制:
export class RateLimitedTool extends BaseTool {
private requests = new Map<string, number[]>();
private maxRequests = 10;
private windowMs = 60000; // 1 分钟
protected async executeInternal(params: Record<string, unknown>): Promise<unknown> {
const userId = params.userId as string;
// 检查速率限制
if (this.isRateLimited(userId)) {
throw new Error('超过速率限制。请稍后重试。');
}
// 记录请求
this.recordRequest(userId);
// 执行操作
return await this.performOperation(params);
}
private isRateLimited(userId: string): boolean {
const requests = this.requests.get(userId) || [];
const now = Date.now();
const recentRequests = requests.filter(time => now - time < this.windowMs);
return recentRequests.length >= this.maxRequests;
}
private recordRequest(userId: string): void {
const requests = this.requests.get(userId) || [];
requests.push(Date.now());
this.requests.set(userId, requests);
}
}
可以,但強烈建議使用 TypeScript 以獲得類型安全和更好的開發體驗。使用 JavaScript 將失去裝飾器和類型檢查的好處。
更新服務器配置或部署新代碼後,需要重啟 Claude Desktop。
可以,您的 MCP 服務器可以處理來自同一個或不同 Claude 實例的多個併發連接。
影響很小 - MCP 服務器作為單獨的進程運行,僅在 Claude 調用時執行。
查看 @zhama/mcp-server 倉庫以獲取完整的工作示例:
為 Claude Desktop 構建自定義 MCP 服務器為擴展 AI 能力開啟了無限可能。藉助 @zhama/mcp-server 框架,曾經需要大量樣板代碼和複雜設置的工作現在只需幾分鐘即可實現。
無論您是構建企業集成、領域特定工具,還是實驗性 AI 擴展,基於裝飾器的方法都提供了:
準備好使用自定義功能擴展 Claude Desktop 了嗎?從一個簡單的工具開始,徹底測試它,然後逐步添加更復雜的功能。框架處理複雜性,您可以專注於構建令人驚歎的 AI 驅動工具。
訪問 github.com/zhama-ai/mcp-server 開始使用,探索示例,並加入構建 AI 集成未來的開發者社區。
由 Zhama 用 ❤️ 打造 - 賦能開發者構建更好的 AI 集成。
有問題或想分享您的 MCP 服務器?在 GitHub 上提出問題或開始討論!
深入學習如何使用 TypeScript 構建可擴展的模型上下文協議服務器。本指南涵蓋從基礎配置到生產部署的完整流程,包含真實案例和最佳實踐。
Muse 讓雲端 Agent 走到臺前。TeGo 把數字分身帶進中國企業的真實工作:接任務、用工具、交結果,也讓關鍵操作回到人的判斷中。
TeGo v3.0.0 在桌面端做了三件事:常駐置頂的 Mini Chat 浮窗、統一的下載中心、Windows NSIS 安裝器全面重寫。本文聚焦體驗細節,解釋這套組合是怎麼把數字分身真正「裝進每天的工作流」的。