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

码界奇点2025-08-27 20:41

💝💝💝欢迎莅临我的博客，很高兴能够在这里和您见面！希望您在这里可以感受到一份轻松愉快的氛围，不仅可以获得有趣的内容和知识，也可以畅所欲言、分享您的想法和见解。

持续学习，不断总结，共同进步，为了踏实，做好当下事儿~

非常期待和您一起在这个小小的网络世界里共同探索、学习和成长。💝💝💝 ✨✨ 欢迎订阅本专栏 ✨✨

|-----------------------------|
| 💖The Start💖点点关注，收藏不迷路💖 |

📒文章目录

    • 一、MCP协议基础与核心概念
      • [1.1 MCP协议概述](#1.1 MCP协议概述)
      • [1.2 核心组件解析](#1.2 核心组件解析)
      • [1.3 协议消息流](#1.3 协议消息流)
    • 二、开发环境配置
      • [2.1 TypeScript环境搭建](#2.1 TypeScript环境搭建)
      • [2.2 Python环境准备](#2.2 Python环境准备)
      • [2.3 开发工具配置](#2.3 开发工具配置)
    • 三、TypeScript实现详解
      • [3.1 服务器骨架构建](#3.1 服务器骨架构建)
      • [3.2 资源管理实现](#3.2 资源管理实现)
      • [3.3 工具功能开发](#3.3 工具功能开发)
    • 四、Python实现详解
      • [4.1 Python服务器基础](#4.1 Python服务器基础)
      • [4.2 资源管理实现](#4.2 资源管理实现)
      • [4.3 工具功能开发](#4.3 工具功能开发)
    • 五、高级功能与最佳实践
      • [5.1 错误处理与日志记录](#5.1 错误处理与日志记录)
      • [5.2 安全性考虑](#5.2 安全性考虑)
      • [5.3 性能优化技巧](#5.3 性能优化技巧)
    • 六、测试与部署
      • [6.1 单元测试策略](#6.1 单元测试策略)
      • [6.2 部署方案](#6.2 部署方案)
      • [6.3 监控与维护](#6.3 监控与维护)
    • 总结

在人工智能助手日益普及的今天，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。创建新项目后，安装关键依赖：

bash 复制代码 
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以上版本。建议使用虚拟环境：

bash 复制代码 
python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# 或
mcp-env\\Scripts\\activate  # Windows

pip install modelcontextprotocol
pip install pyright  # 可选，用于类型检查

2.3 开发工具配置

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

三、TypeScript实现详解

3.1 服务器骨架构建

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

typescript 复制代码 
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助手读取外部数据。添加文件系统资源示例：

typescript 复制代码 
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助手执行操作。创建计算器工具示例：

typescript 复制代码 
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服务器同样直观：

python 复制代码 
from modelcontextprotocol import McpServer

server = McpServer("example-server", "1.0.0")

if __name__ == "__main__":
    server.run()

4.2 资源管理实现

Python版的文件资源管理：

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版的工具实现：

python 复制代码 
@server.tool("calculate", "执行数学计算")
async def calculate_tool(expression: str):
    try:
        # 使用ast.literal_eval更安全
        import ast
        result = 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中：

typescript 复制代码 
// 全局错误处理
process.on('uncaughtException', (error) => {
  console.error('未捕获异常:', error);
});

process.on('unhandledRejection', (reason, promise) => {
  console.error('未处理的Promise拒绝:', reason);
});

在Python中，使用logging模块：

python 复制代码 
import logging

logging.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：

typescript 复制代码 
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：

python 复制代码 
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助手提供强大的外部能力扩展。

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

|-----------------------------|
| 💖The Start💖点点关注，收藏不迷路💖 |

热门推荐
01UV安装并设置国内源02KGG转MP3工具|非KGM文件|解密音频03不再让Windows更新！&Edge游戏助手卸载及关闭自动更新04Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code05【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）06Claude Code VSCode集成开发指南：AI编程助手完整配置07突破百度网盘的下载限速，两种方法教会你【超详细】08Linux下V2Ray安装配置指南09jdk21下载、安装（Windows、Linux、macOS）10如何在Windows/Linux系统上安装adb