零基础构建MCP服务器TypeScriptPython双语言实战指南

💝💝💝欢迎莅临我的博客，很高兴能够在这里和您见面！希望您在这里可以感受到一份轻松愉快的氛围，不仅可以获得有趣的内容和知识，也可以畅所欲言、分享您的想法和见解。
持续学习，不断总结，共同进步，为了踏实，做好当下事儿~
非常期待和您一起在这个小小的网络世界里共同探索、学习和成长。💝💝💝 ✨✨ 欢迎订阅本专栏 ✨✨

---

在人工智能助手日益普及的今天，Model Context Protocol（MCP）作为连接AI模型与外部工具的重要桥梁，正成为开发者生态中的关键组件。MCP服务器允许AI助手安全地访问文件系统、数据库、API等外部资源，极大地扩展了其能力边界。本文将从零开始，引导你使用TypeScript和Python两种流行语言构建功能完整的MCP服务器，无需任何MCP或AI开发经验。

一、MCP协议基础与核心概念

1.1 MCP协议概述

Model Context Protocol是由Anthropic公司提出的开放协议，旨在标准化AI助手与外部工具之间的通信方式。它采用JSON-RPC 2.0规范，通过标准输入输出或SSE（Server-Sent Events）进行通信。MCP的核心价值在于提供了一种安全、可控的方式让AI模型与外部世界交互，同时保持了良好的跨平台兼容性。

1.2 核心组件解析

一个完整的MCP生态系统包含三个主要组件：客户端（通常是AI助手）、服务器（提供工具和能力）和传输层（处理通信）。服务器需要实现几个关键功能：资源（Resources）提供数据读取能力，工具（Tools）执行特定操作，提示模板（Prompts）提供可重用的交互模式。

1.3 协议消息流

MCP通信遵循严格的请求-响应模式。初始化阶段，客户端发送initialize请求，服务器返回其能力配置。随后，客户端可以列出可用资源、工具，并调用它们。所有消息都遵循JSON-RPC格式，包含jsonrpc、id、method和params等标准字段。

二、开发环境配置

2.1 TypeScript环境搭建

对于TypeScript实现，首先需要安装Node.js（v18以上）和npm。创建新项目后，安装关键依赖：

npm init -y
npm install @modelcontextprotocol/server-node
npm install -D typescript @types/node ts-node

配置tsconfig.json文件，设置target为ES2022，module为CommonJS，并确保启用严格类型检查。

2.2 Python环境准备

Python实现需要3.9以上版本。建议使用虚拟环境：

python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# 或
mcp-env\\Scripts\\activate  # Windowspip install modelcontextprotocol
pip install pyright  # 可选，用于类型检查

2.3 开发工具配置

无论选择哪种语言，都推荐配置合适的IDE（VSCode或PyCharm）并安装相应的语言支持扩展。设置调试配置，便于开发过程中测试和排查问题。

三、TypeScript实现详解

3.1 服务器骨架构建

首先创建基本的服务器结构：

import { McpServer } from '@modelcontextprotocol/server-node';const server = new McpServer({name: 'example-server',version: '1.0.0'
});// 启动服务器
server.start().catch(error => {console.error('Server error:', error);process.exit(1);
});

3.2 资源管理实现

资源允许AI助手读取外部数据。添加文件系统资源示例：

import { ResourceTemplate } from '@modelcontextprotocol/server-node';server.resource('readFile',new ResourceTemplate('file://{path}', {list: async () => {// 返回可用文件列表return [{ uri: 'file:///documents/readme.md' },{ uri: 'file:///documents/config.json' }];},read: async (uri) => {const path = uri.pathname;// 实际的文件读取逻辑return {contents: await fs.readFile(path, 'utf-8'),mimeType: 'text/plain'};}})
);

3.3 工具功能开发

工具允许AI助手执行操作。创建计算器工具示例：

server.tool('calculate', '执行数学计算', {expression: {type: 'string',description: '数学表达式，如 2+3*4'}
}, async ({ expression }) => {try {const result = eval(expression); // 注意：生产环境应使用安全的方式return {content: [{type: 'text',text: `${expression} = ${result}`}]};} catch (error) {return {content: [{type: 'text',text: `计算错误: ${error.message}`}]};}
});

四、Python实现详解

4.1 Python服务器基础

使用Python构建MCP服务器同样直观：

from modelcontextprotocol import McpServerserver = McpServer("example-server", "1.0.0")if __name__ == "__main__":server.run()

4.2 资源管理实现

Python版的文件资源管理：

from modelcontextprotocol import ResourceTemplate
import aiofiles@server.resource("file://{path}")
async def file_resource(uri: str):async with aiofiles.open(uri.path, 'r') as f:content = await f.read()return {"contents": content,"mimeType": "text/plain"}@server.resource_list("file")
async def list_files():return [{"uri": "file:///documents/readme.md"},{"uri": "file:///documents/config.json"}]

4.3 工具功能开发

Python版的工具实现：

@server.tool("calculate", "执行数学计算")
async def calculate_tool(expression: str):try:# 使用ast.literal_eval更安全import astresult = ast.literal_eval(expression)return {"content": [{"type": "text","text": f"{expression} = {result}"}]}except Exception as e:return {"content": [{"type": "text","text": f"计算错误: {str(e)}"}]}

五、高级功能与最佳实践

5.1 错误处理与日志记录

健壮的MCP服务器需要完善的错误处理机制。在TypeScript中：

// 全局错误处理
process.on('uncaughtException', (error) => {console.error('未捕获异常:', error);
});process.on('unhandledRejection', (reason, promise) => {console.error('未处理的Promise拒绝:', reason);
});

在Python中，使用logging模块：

import logginglogging.basicConfig(level=logging.INFO,format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

5.2 安全性考虑

MCP服务器可能处理敏感数据，安全性至关重要：

• 验证所有输入参数
• 实施适当的访问控制
• 使用环境变量管理敏感信息
• 定期更新依赖包以修复安全漏洞

5.3 性能优化技巧

对于高性能需求的场景：

• 实现连接池管理数据库连接
• 使用缓存减少重复计算
• 采用异步处理避免阻塞操作
• 监控资源使用情况并设置限制

六、测试与部署

6.1 单元测试策略

为MCP服务器编写全面的测试：

TypeScript中使用Jest：

describe('Calculator Tool', () => {it('should correctly add numbers', async () => {const result = await calculateTool({ expression: '2+3' });expect(result.content[0].text).toBe('2+3 = 5');});
});

Python中使用pytest：

def test_calculate_tool():result = asyncio.run(calculate_tool("2+3"))assert "2+3 = 5" in result["content"][0]["text"]

6.2 部署方案

根据使用场景选择部署方式：

• 本地开发：直接运行服务器进程
• 容器化：使用Docker打包应用
• 云部署：部署到AWS Lambda、Azure Functions等无服务平台
• 自托管：在自有服务器上运行

6.3 监控与维护

生产环境需要监控服务器健康状态：

• 实现健康检查端点
• 设置性能指标收集
• 配置告警机制
• 定期日志分析和审计

总结

通过本文的详细指导，你已经掌握了使用TypeScript和Python两种语言构建MCP服务器的完整流程。从协议基础到具体实现，从基础功能到高级特性，我们覆盖了构建生产级MCP服务器所需的关键知识。

TypeScript版本提供了强大的类型系统和丰富的生态系统，适合大型复杂项目；Python版本则以简洁直观著称，快速原型开发的理想选择。无论选择哪种语言，M协议的核心概念和最佳实践都是相通的。

在实际项目中，建议根据团队技术栈、性能要求和维护成本等因素选择合适的实现语言。重要的是遵循协议规范，确保与各种MCP客户端的兼容性，同时注重安全性和可靠性。

随着AI技术的快速发展，MCP生态系统也在不断演进。保持对协议更新的关注，积极参与社区讨论，将帮助你构建更加先进和有用的MCP服务器，为AI助手提供强大的外部能力扩展。

---

🔥🔥🔥道阻且长,行则将至,让我们一起加油吧！🌙🌙🌙

---