MCP (Model Context Protocol) 高级开发实战：从 Server 开发到生产部署的完整指南——让 AI Agent 真正「长出手脚」的终极协议

引言：为什么 MCP 是 2026 年最值得掌握的 AI 开发技能？

如果你在 2025 年错过了 MCP 的第一波浪潮，2026 年是补课的最佳时机。这个由 Anthropic 在 2024 年底开源的协议，已经从「实验性项目」成长为 AI Agent 生态的基础设施标准。

截至 2026 年 6 月，MCP 官方组织在 GitHub 上拥有 48.3K+ followers，推出了 10 种语言的官方 SDK（TypeScript、Python、Java、Kotlin、C#、Go、PHP、Ruby、Rust、Swift），并且被 GitHub 官方内置为 Copilot 的工具调用标准。

但市面上的 MCP 教程大多停留在「Hello World」级别——教你写一个简单的 echo server，跑通基本流程就结束了。本文要做的，是从生产级开发视角，深度解析 MCP 协议的核心机制、高级特性、性能优化和部署实战。

读完这篇文章，你将掌握：

• MCP 协议的核心架构与通信流程
• 从零开发一个完整的生产级 MCP Server
• Resources、Prompts、Sampling、Roots 等高级特性的实战应用
• 多语言 SDK 的选型与性能对比
• 生产环境部署的最佳实践与踩坑经验

一、MCP 协议深度剖析：不只是「工具调用」

1.1 协议定位：AI 世界的 USB 接口

理解 MCP，最好用类比：在 MCP 出现之前，让 LLM 调用外部工具就像是在没有 USB 标准的年代连接外设——每个设备都需要专门的驱动程序和接口。

# 没有 MCP 的时代：每个工具都是独特的雪花
# 调用天气 API
weather_result = requests.get(
    "https://api.weather.com/v1/current",
    headers={"Authorization": "Bearer " + WEATHER_TOKEN},
    params={"city": city, "unit": "celsius"}
).json()

# 调用股票 API（完全不同的接口风格）
stock_result = requests.post(
    "https://api.stock.com/graphql",
    headers={"X-API-Key": STOCK_KEY},
    json={"query": "{ quote(symbol: \"AAPL\") { price change } }"}
).json()

# 调用日历 API（又是另一种风格）
calendar_result = google_calendar.events().list(
    calendarId='primary',
    timeMin=now,
    maxResults=10
).execute()

MCP 做的事情，就是定义一套统一的消息格式和通信协议，让所有工具都遵循相同的接口规范。开发者只需要实现 MCP Server 一次，任何支持 MCP 的 Client（Claude Code、Cursor、GitHub Copilot 等）都能无缝调用。

// MCP 统一的工具调用格式
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {"city": "Beijing"}
  }
}

1.2 架构全景：Client、Server、Host 三位一体

MCP 的架构设计采用了经典的 Client-Server 模型，但引入了 Host 概念来管理生命周期：

┌─────────────────────────────────────────────────────────────────┐
│                         Host Application                        │
│  (Claude Code / Cursor / VS Code Extension / 自定义应用)        │
│                                                                 │
│  ┌─────────────────────┐        ┌─────────────────────────┐   │
│  │    MCP Client       │        │      MCP Server         │   │
│  │                     │        │                         │   │
│  │  - 连接管理         │◄──────►│  - Tools 定义            │   │
│  │  - 消息路由         │  JSON  │  - Resources 暴露       │   │
│  │  - 能力协商         │  RPC   │  - Prompts 模板         │   │
│  │  - Sampling 请求    │        │  - Sampling 响应        │   │
│  └─────────────────────┘        └─────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

关键概念辨析：

1.3 通信协议详解：基于 JSON-RPC 2.0

MCP 选择 JSON-RPC 2.0 作为底层协议，这个选择非常明智：

• 语言无关：任何语言都能轻松实现
• 语义清晰：request/response/notification 语义明确
• 扩展友好：支持批量请求、渐进式能力协商

完整的 MCP 通信生命周期：

sequenceDiagram
    participant Host
    participant Client
    participant Server
    
    Note over Host,Server: 阶段一：初始化
    Client->>Server: initialize (协议版本、能力声明)
    Server->>Client: initializeResult (服务器能力)
    Client->>Server: initialized (通知)
    
    Note over Host,Server: 阶段二：能力发现
    Client->>Server: tools/list
    Server->>Client: 工具列表
    Client->>Server: resources/list
    Server->>Client: 资源列表
    Client->>Server: prompts/list
    Server->>Client: 提示词模板列表
    
    Note over Host,Server: 阶段三：运行时交互
    Host->>Client: 用户请求（包含工具调用意图）
    Client->>Server: tools/call
    Server->>Client: 执行结果
    Client->>Server: resources/read (可选)
    Server->>Client: 资源内容
    
    Note over Host,Server: 阶段四：服务端请求（可选）
    Server->>Client: sampling/createMessage
    Client->>Server: LLM 响应

1.4 核心能力矩阵：Tools、Resources、Prompts、Sampling

MCP 定义了四大核心能力，每种能力都有特定的应用场景：

二、实战：从零开发一个生产级 MCP Server

2.1 需求定义：项目文档管理 Server

我们要开发一个实用场景的 MCP Server，功能包括：

1. 扫描项目目录，建立文档索引
2. 按关键词搜索文档
3. 读取指定文档内容
4. 自动生成文档摘要（使用 Sampling）

这个 Server 需要涵盖 MCP 的所有核心能力，是一个综合性实战案例。

2.2 技术选型：Python SDK vs TypeScript SDK

推荐选择：

• 快速原型/数据处理场景 → Python + FastMCP
• 生产级服务/前端工具链 → TypeScript SDK

本文选择 TypeScript SDK，因为它更接近 MCP 协议的原始语义，适合深度学习。

2.3 项目初始化

# 创建项目
mkdir mcp-docmanager && cd mcp-docmanager
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# 项目结构
mkdir -p src
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true
  },
  "include": ["src/**/*"]
}
EOF

2.4 核心 Server 实现

// src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
  ListPromptsRequestSchema,
  GetPromptRequestSchema,
  CreateMessageRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
import * as fs from 'fs/promises';
import * as path from 'path';
import { glob } from 'glob';

// ===== 类型定义 =====
interface DocIndex {
  [filePath: string]: {
    title: string;
    headings: string[];
    keywords: string[];
    mtime: number;
    size: number;
  };
}

interface SearchResult {
  file: string;
  title: string;
  matches: string[];
  relevance: number;
}

// ===== 全局状态 =====
let docIndex: DocIndex = {};
let projectRoot: string = process.cwd();
let server: Server;

// ===== 工具定义 =====
const ScanProjectSchema = z.object({
  rootPath: z.string().optional().describe('项目根目录，默认当前目录'),
  extensions: z.array(z.string()).optional().default(['md', 'txt', 'rst']).describe('文档扩展名列表'),
});

const SearchDocsSchema = z.object({
  query: z.string().describe('搜索关键词'),
  limit: z.number().optional().default(10).describe('返回结果数量限制'),
});

const ReadDocSchema = z.object({
  filePath: z.string().describe('文档相对路径'),
});

const tools = [
  {
    name: 'scan_project',
    description: '扫描项目目录，建立文档索引。返回索引的文档数量和统计信息。',
    inputSchema: {
      type: 'object' as const,
      properties: {
        rootPath: { type: 'string', description: '项目根目录' },
        extensions: { 
          type: 'array', 
          items: { type: 'string' },
          description: '文档扩展名列表，如 ["md", "txt"]' 
        },
      },
    },
  },
  {
    name: 'search_docs',
    description: '在文档索引中搜索关键词，返回匹配的文档列表及摘要。',
    inputSchema: {
      type: 'object' as const,
      properties: {
        query: { type: 'string', description: '搜索关键词' },
        limit: { type: 'number', description: '结果数量限制' },
      },
      required: ['query'],
    },
  },
  {
    name: 'read_doc',
    description: '读取指定文档的完整内容。',
    inputSchema: {
      type: 'object' as const,
      properties: {
        filePath: { type: 'string', description: '文档相对路径' },
      },
      required: ['filePath'],
    },
  },
];

// ===== 核心业务逻辑 =====
async function scanProject(rootPath: string, extensions: string[]): Promise<{ count: number; stats: any }> {
  const actualRoot = rootPath || process.cwd();
  projectRoot = actualRoot;
  
  const patterns = extensions.map(ext => `**/*.${ext}`);
  const files: string[] = [];
  
  for (const pattern of patterns) {
    const matches = await glob(pattern, { cwd: actualRoot, nodir: true, ignore: ['**/node_modules/**', '**/.git/**'] });
    files.push(...matches);
  }
  
  docIndex = {};
  
  for (const file of files) {
    const fullPath = path.join(actualRoot, file);
    const stat = await fs.stat(fullPath);
    const content = await fs.readFile(fullPath, 'utf-8');
    
    // 提取标题（第一个 # 标题）
    const titleMatch = content.match(/^#\s+(.+)$/m);
    const title = titleMatch ? titleMatch[1] : path.basename(file);
    
    // 提取所有标题
    const headingMatches = content.match(/^#{1,6}\s+.+$/gm) || [];
    const headings = headingMatches.map(h => h.replace(/^#+\s+/, ''));
    
    // 简单关键词提取（实际项目可用 NLP）
    const keywords = extractKeywords(content);
    
    docIndex[file] = {
      title,
      headings,
      keywords,
      mtime: stat.mtimeMs,
      size: stat.size,
    };
  }
  
  return {
    count: files.length,
    stats: {
      totalSize: Object.values(docIndex).reduce((sum, d) => sum + d.size, 0),
      avgSize: Object.values(docIndex).reduce((sum, d) => sum + d.size, 0) / files.length,
    },
  };
}

function extractKeywords(content: string): string[] {
  // 简单实现：提取所有驼峰/下划线命名的词
  const words = content.match(/[A-Z][a-z]+|[a-z]+|[A-Z]+(?=[A-Z]|$)/g) || [];
  const freq: Record<string, number> = {};
  
  for (const word of words) {
    const w = word.toLowerCase();
    if (w.length < 3) continue; // 过滤短词
    freq[w] = (freq[w] || 0) + 1;
  }
  
  return Object.entries(freq)
    .sort((a, b) => b[1] - a[1])
    .slice(0, 20)
    .map(([word]) => word);
}

async function searchDocs(query: string, limit: number): Promise<SearchResult[]> {
  const queryTerms = query.toLowerCase().split(/\s+/);
  const results: SearchResult[] = [];
  
  for (const [file, meta] of Object.entries(docIndex)) {
    const matches: string[] = [];
    let relevance = 0;
    
    // 标题匹配
    for (const term of queryTerms) {
      if (meta.title.toLowerCase().includes(term)) {
        matches.push(`标题匹配: ${meta.title}`);
        relevance += 10;
      }
    }
    
    // 标题匹配
    for (const heading of meta.headings) {
      for (const term of queryTerms) {
        if (heading.toLowerCase().includes(term)) {
          matches.push(`章节: ${heading}`);
          relevance += 5;
        }
      }
    }
    
    // 关键词匹配
    for (const kw of meta.keywords) {
      for (const term of queryTerms) {
        if (kw.includes(term)) {
          matches.push(`关键词: ${kw}`);
          relevance += 2;
        }
      }
    }
    
    if (matches.length > 0) {
      results.push({ file, title: meta.title, matches, relevance });
    }
  }
  
  return results
    .sort((a, b) => b.relevance - a.relevance)
    .slice(0, limit);
}

async function readDoc(filePath: string): Promise<string> {
  const fullPath = path.join(projectRoot, filePath);
  return fs.readFile(fullPath, 'utf-8');
}

// ===== MCP Server 初始化 =====
async function runServer() {
  server = new Server(
    { name: 'docmanager-mcp', version: '1.0.0' },
    {
      capabilities: {
        tools: {},
        resources: {},
        prompts: {},
        sampling: {},
      },
    }
  );
  
  // 注册请求处理器
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
    resources: Object.entries(docIndex).map(([file, meta]) => ({
      uri: `doc://${file}`,
      name: meta.title,
      description: `${meta.headings.length} 个章节，${meta.size} 字节`,
      mimeType: 'text/markdown',
    })),
  }));
  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
    prompts: [
      {
        name: 'summarize_doc',
        description: '生成文档摘要',
        arguments: [
          { name: 'filePath', description: '文档路径', required: true },
        ],
      },
      {
        name: 'compare_docs',
        description: '对比两个文档的差异',
        arguments: [
          { name: 'file1', description: '第一个文档路径', required: true },
          { name: 'file2', description: '第二个文档路径', required: true },
        ],
      },
    ],
  }));
  
  // 工具调用处理
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    
    try {
      switch (name) {
        case 'scan_project': {
          const parsed = ScanProjectSchema.parse(args);
          const result = await scanProject(parsed.rootPath || process.cwd(), parsed.extensions);
          return {
            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
        }
        case 'search_docs': {
          const parsed = SearchDocsSchema.parse(args);
          const results = await searchDocs(parsed.query, parsed.limit);
          return {
            content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
          };
        }
        case 'read_doc': {
          const parsed = ReadDocSchema.parse(args);
          const content = await readDoc(parsed.filePath);
          return {
            content: [{ type: 'text', text: content }],
          };
        }
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    } catch (error) {
      return {
        content: [{ type: 'text', text: `Error: ${error.message}` }],
        isError: true,
      };
    }
  });
  
  // 资源读取处理
  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
    const uri = request.params.uri;
    const match = uri.match(/^doc:\/\/(.+)$/);
    if (!match) throw new Error('Invalid resource URI');
    
    const filePath = match[1];
    const content = await readDoc(filePath);
    
    return {
      contents: [{
        uri,
        mimeType: 'text/markdown',
        text: content,
      }],
    };
  });
  
  // 提示词处理（使用 Sampling 生成摘要）
  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    
    if (name === 'summarize_doc') {
      const filePath = args?.filePath as string;
      if (!filePath) throw new Error('filePath is required');
      
      const content = await readDoc(filePath);
      
      // 使用 Sampling 让 LLM 生成摘要
      const samplingResult = await server.request({
        method: 'sampling/createMessage',
        params: {
          messages: [{
            role: 'user',
            content: { type: 'text', text: `请为以下文档生成简洁的摘要（200字以内）：\n\n${content.substring(0, 4000)}` },
          }],
          maxTokens: 500,
          temperature: 0.3,
        },
      }, CreateMessageRequestSchema);
      
      return {
        description: `文档摘要: ${filePath}`,
        messages: [{
          role: 'assistant',
          content: { type: 'text', text: samplingResult.content.text },
        }],
      };
    }
    
    if (name === 'compare_docs') {
      const file1 = args?.file1 as string;
      const file2 = args?.file2 as string;
      
      const [content1, content2] = await Promise.all([readDoc(file1), readDoc(file2)]);
      
      return {
        description: `对比文档: ${file1} vs ${file2}`,
        messages: [{
          role: 'user',
          content: {
            type: 'text',
            text: `请对比以下两个文档的差异：\n\n文档1: ${file1}\n\`\`\`\n${content1.substring(0, 2000)}\n\`\`\`\n\n文档2: ${file2}\n\`\`\`\n${content2.substring(0, 2000)}\n\`\`\``,
          },
        }],
      };
    }
    
    throw new Error(`Unknown prompt: ${name}`);
  });
  
  // 启动传输
  const transport = new StdioServerTransport();
  await server.connect(transport);
  
  console.error('DocManager MCP Server started');
}

runServer().catch(console.error);

2.5 配置与运行

// MCP Client 配置（Claude Code / Cursor）
{
  "mcpServers": {
    "docmanager": {
      "command": "node",
      "args": ["/path/to/mcp-docmanager/dist/index.js"],
      "env": {}
    }
  }
}

# 编译与测试
npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

三、高级特性深度解析

3.1 Sampling：Server 主动请求 LLM

Sampling 是 MCP 最具创新性的特性，它打破了传统的「Client 调用 Server」单向模式，允许 Server 主动请求 LLM 生成内容。

典型应用场景：

• 智能代码补全：Server 分析上下文后请求 LLM 生成建议
• 错误诊断：Server 检测到错误后请求 LLM 分析原因
• 数据转换：Server 将原始数据发给 LLM 进行格式化

Sampling 请求格式：

// Server 发起 Sampling 请求
const response = await server.request({
  method: 'sampling/createMessage',
  params: {
    messages: [
      { role: 'user', content: { type: 'text', text: '提示词内容' } },
      { role: 'assistant', content: { type: 'text', text: '之前的响应' } },
    ],
    modelPreferences: {
      hints: [{ name: 'claude-3-sonnet' }], // 模型提示
      intelligencePriority: 0.8, // 优先智能度
      speedPriority: 0.2, // 速度优先级
    },
    maxTokens: 1024,
    temperature: 0.7,
    stopSequences: ['\n\n'],
  },
}, CreateMessageRequestSchema);

安全考量：

• Host 会弹出确认对话框，用户可选择拒绝
• Server 无法知道使用的是哪个具体模型
• 敏感操作需要在 Server 端做权限检查

3.2 Roots：工作空间边界定义

Roots 允许 Client 告知 Server 可访问的目录边界，这对于文件操作类 Server 尤其重要。

// Client 声明 Roots
{
  "roots": [
    {
      "uri": "file:///Users/user/projects/myapp",
      "name": "My Application"
    },
    {
      "uri": "file:///Users/user/docs",
      "name": "Documentation"
    }
  ]
}

// Server 处理 Roots
server.setRequestHandler(ListRootsRequestSchema, async () => ({
  roots: clientProvidedRoots, // 或者返回 Server 自己的边界
}));

// 安全检查：确保路径在 Roots 范围内
function isPathAllowed(filePath: string): boolean {
  const resolved = path.resolve(filePath);
  return roots.some(root => resolved.startsWith(root.uri.replace('file://', '')));
}

3.3 Transports：通信协议扩展

MCP 内置两种传输方式：

• stdio：通过标准输入输出通信，适用于本地进程
• HTTP with SSE：通过 HTTP 发送请求，Server-Sent Events 接收响应，适用于远程服务

实现自定义 Transport：

import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';

class WebSocketTransport implements Transport {
  private ws: WebSocket;
  private messageHandler?: (message: any) => Promise<void>;
  
  constructor(url: string) {
    this.ws = new WebSocket(url);
    this.ws.onmessage = async (event) => {
      if (this.messageHandler) {
        await this.messageHandler(JSON.parse(event.data));
      }
    };
  }
  
  async start() {
    // WebSocket 自动连接
  }
  
  async close() {
    this.ws.close();
  }
  
  async send(message: any) {
    this.ws.send(JSON.stringify(message));
  }
  
  onmessage(handler: (message: any) => Promise<void>) {
    this.messageHandler = handler;
  }
  
  onclose(handler: () => Promise<void>) {
    this.ws.onclose = handler;
  }
  
  onerror(handler: (error: Error) => Promise<void>) {
    this.ws.onerror = (e) => handler(new Error('WebSocket error'));
  }
}

3.4 进度报告与取消

对于长时间运行的操作，MCP 支持进度报告和取消请求：

// 工具调用时携带进度 token
{
  "method": "tools/call",
  "params": {
    "name": "large_file_analysis",
    "arguments": { "file": "big.log" },
    "_meta": {
      "progressToken": "progress-123"
    }
  }
}

// Server 发送进度通知
server.notification({
  method: 'notifications/progress',
  params: {
    progressToken: 'progress-123',
    progress: 50,
    total: 100,
    message: '已处理 50% 的日志行',
  },
});

// Client 取消请求
server.notification({
  method: 'notifications/cancelled',
  params: {
    requestId: 'request-456',
    reason: '用户取消',
  },
});

四、生产部署最佳实践

4.1 错误处理与重试策略

class RobustMCPServer {
  private retryCount = 0;
  private maxRetries = 3;
  
  async handleToolCall(request: any) {
    try {
      const result = await this.executeWithRetry(request);
      return result;
    } catch (error) {
      // 分类错误处理
      if (error.code === 'ECONNREFUSED') {
        return this.createErrorResponse('服务暂不可用，请稍后重试', 'temporary');
      }
      if (error.code === 'ENOENT') {
        return this.createErrorResponse('文件不存在', 'permanent');
      }
      // 未知错误，记录日志
      this.logger.error('Tool call failed', { request, error });
      return this.createErrorResponse('内部错误', 'internal');
    }
  }
  
  private async executeWithRetry(request: any) {
    let lastError: Error;
    for (let i = 0; i < this.maxRetries; i++) {
      try {
        return await this.executeTool(request);
      } catch (error) {
        lastError = error;
        if (!this.isRetryable(error)) break;
        await this.delay(Math.pow(2, i) * 1000); // 指数退避
      }
    }
    throw lastError;
  }
  
  private isRetryable(error: any): boolean {
    // 网络错误、超时等可重试
    return ['ETIMEDOUT', 'ECONNRESET', 'ENOTFOUND'].includes(error.code);
  }
}

4.2 性能优化：并发控制与缓存

import { LRUCache } from 'lru-cache';
import pLimit from 'p-limit';

class OptimizedMCPServer {
  private cache = new LRUCache<string, any>({ max: 1000, ttl: 60000 });
  private limiter = pLimit(10); // 最大并发 10
  
  async readResource(uri: string) {
    // 检查缓存
    const cached = this.cache.get(uri);
    if (cached) return cached;
    
    // 并发控制
    const result = await this.limiter(() => this.actualRead(uri));
    this.cache.set(uri, result);
    return result;
  }
  
  private async actualRead(uri: string) {
    // 实际读取逻辑
    const filePath = this.uriToPath(uri);
    return fs.readFile(filePath, 'utf-8');
  }
}

4.3 安全加固：输入验证与权限控制

import { z } from 'zod';
import fg from 'fast-glob';

class SecureMCPServer {
  private allowedPatterns = ['**/*.md', '**/*.txt', '**/docs/**'];
  private forbiddenPatterns = ['**/.env*', '**/secrets/**', '**/node_modules/**'];
  
  validatePath(filePath: string): boolean {
    const resolved = path.resolve(filePath);
    
    // 检查是否在允许的模式中
    const isAllowed = this.allowedPatterns.some(pattern => 
      fg.isDynamicPattern(pattern) && fg.sync(pattern, { onlyFiles: true }).includes(resolved)
    );
    
    // 检查是否在禁止的模式中
    const isForbidden = this.forbiddenPatterns.some(pattern => 
      fg.isDynamicPattern(pattern) && fg.sync(pattern, { onlyFiles: true }).includes(resolved)
    );
    
    return isAllowed && !isForbidden;
  }
  
  validateInput(schema: z.ZodType, input: unknown) {
    const result = schema.safeParse(input);
    if (!result.success) {
      throw new Error(`输入验证失败: ${result.error.message}`);
    }
    return result.data;
  }
}

4.4 Docker 容器化部署

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]

# docker-compose.yml
version: '3.8'
services:
  mcp-docmanager:
    build: .
    container_name: mcp-docmanager
    restart: unless-stopped
    volumes:
      - ./docs:/app/docs:ro
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

五、多语言 SDK 性能对比与选型建议

5.1 性能基准测试

测试场景：1000 次 tools/call 请求，每个请求处理 1KB 数据

5.2 选型决策树

开始
  │
  ├─ 需要与现有 Node.js 项目集成？
  │   └─ 是 → TypeScript SDK
  │
  ├─ 需要极低延迟 / 高吞吐？
  │   └─ 是 → Go 或 Rust SDK
  │
  ├─ 需要快速原型开发？
  │   └─ 是 → Python + FastMCP
  │
  ├─ 需要企业级生态集成？
  │   └─ 是 → Java 或 Kotlin SDK
  │
  └─ 需要与 Swift/iOS 项目集成？
      └─ 是 → Swift SDK

六、常见问题与排查指南

6.1 连接问题

症状：Server 启动后 Client 无法连接

排查步骤：

1. 检查 stdio 是否正确配置：确保 Server 输出到 stderr 而非 stdout
2. 检查 JSON-RPC 格式：使用 jq 验证消息格式
3. 检查初始化流程：确保发送了 initialized 通知

# 调试命令
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null | jq

6.2 工具调用失败

症状：tools/call 返回错误

常见原因：

• 输入参数类型不匹配：检查 inputSchema 定义
• Server 内部异常：查看 Server 日志
• 权限问题：检查文件系统权限

6.3 Sampling 请求被拒绝

症状：sampling/createMessage 返回错误

原因：

• Host 不支持 Sampling（检查 capabilities）
• 用户拒绝了确认对话框
• 模型参数超出限制

七、总结与展望

7.1 核心要点回顾

1. MCP 是 AI Agent 时代的 USB 标准：统一了工具调用的接口规范
2. 四大能力缺一不可：Tools、Resources、Prompts、Sampling 构成完整生态
3. Sampling 是最大创新：Server 可以主动请求 LLM，开启双向交互
4. 生产部署需要关注：错误处理、性能优化、安全加固

7.2 发展趋势预测

• 2026 下半年：MCP 将成为 AI IDE 的标配协议
• 2027：出现 MCP Server Marketplace，类似 npm 生态
• 2028：企业级 MCP Gateway 出现，支持集中管理和审计

7.3 学习资源

• 官方文档：https://modelcontextprotocol.io
• GitHub 组织：https://github.com/modelcontextprotocol
• TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
• Python SDK：https://github.com/modelcontextprotocol/python-sdk
• Awesome MCP：https://github.com/weekend-project-space/awesome-mcp

字数统计：约 8500 字

标签：MCP, Model Context Protocol, AI Agent, Claude Code, 工具调用, 协议标准, TypeScript, Python, 生产部署

关键词：MCP协议|AI Agent工具调用|Model Context Protocol|Claude Code MCP|Python FastMCP|TypeScript MCP SDK|Sampling机制|MCP Server开发|生产级部署|多语言SDK对比