MCP Server 开发实战：Python + TypeScript 双语言教程

作为一名拥有五年 AI 基础设施开发经验的工程师，我深知很多刚入门的朋友对“模型上下文协议”（MCP Server）感到既好奇又迷茫。今天我就用最通俗易懂的方式，带大家从零开始手把手搭建一个完整的 MCP Server，通过 HolySheep AI 的 API 来实际运行它。整个教程会同时提供 Python 和 TypeScript 两种实现方案，大家可以根据自己的技术栈选择。

一、什么是 MCP Server？

MCP（Model Context Protocol）是一种标准化的通信协议，它允许 AI 模型与外部工具、数据源进行交互。你可以把它想象成 AI 世界的“万能转接头”——无论你的 AI 需要调用什么工具，MCP Server 都能统一管理这些请求和响应。

举一个实际的例子：你正在开发一个智能客服系统，用户问“北京今天天气怎么样？”AI 本身不知道实时天气数据，这时候 MCP Server 就派上用场了——它可以调用天气 API，获取数据后返回给 AI，再由 AI 整理成自然语言回答用户。

二、为什么选择 HolySheep AI？

我自己在生产环境中用过很多 AI API 服务，综合体验下来 HolySheep AI 有几个明显优势：

• 汇率优势：人民币直兑美元，¥1=$1 无损兑换，相比官方渠道节省超过 85%，这对于初学者来说成本极低
• 国内直连：延迟控制在 50ms 以内，响应速度快
• 充值便捷：支持微信、支付宝直接充值，无需信用卡
• 价格透明：DeepSeek V3.2 仅 $0.42/MTok，GPT-4.1 $8/MTok，Claude Sonnet 4.5 $15/MTok

三、Python 实现 MCP Server

3.1 环境准备

首先安装必要的依赖库。我推荐使用虚拟环境来管理项目依赖，避免版本冲突。打开终端，执行以下命令：

# 创建并激活虚拟环境
python -m venv mcp-env
source mcp-env/bin/activate  # Windows 用户使用 mcp-env\Scripts\activate

安装核心依赖
pip install fastapi uvicorn httpx pydantic

安装 HolySheep SDK（推荐）
pip install openai

3.2 基础 MCP Server 框架

下面是一个完整的 Python MCP Server 实现，它包含两个核心工具：获取当前时间和进行简单的数学计算。

import json
from datetime import datetime
from typing import Any, Dict, List
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import httpx

HolySheep API 配置
HOLYSHEEP_API_KEY = "YOUR_HOLYSHEEP_API_KEY"
HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"

app = FastAPI(title="MCP Server Demo")

class ToolCall(BaseModel):
    tool_name: str
    parameters: Dict[str, Any]

class MCPRequest(BaseModel):
    jsonrpc: str = "2.0"
    id: int = 1
    method: str
    params: Dict[str, Any] = {}

注册的工具列表
AVAILABLE_TOOLS = {
    "get_current_time": {
        "description": "获取当前时间",
        "parameters": {
            "timezone": {"type": "string", "default": "Asia/Shanghai"}
        }
    },
    "calculate": {
        "description": "执行数学计算",
        "parameters": {
            "expression": {"type": "string", "description": "数学表达式，如 2+3*4"}
        }
    }
}

def get_current_time(timezone: str = "Asia/Shanghai") -> Dict[str, str]:
    """获取当前时间"""
    now = datetime.now()
    return {
        "current_time": now.strftime("%Y-%m-%d %H:%M:%S"),
        "timezone": timezone,
        "unix_timestamp": int(now.timestamp())
    }

def calculate(expression: str) -> Dict[str, Any]:
    """执行数学计算"""
    try:
        # 安全计算：只允许基本运算
        allowed_chars = set("0123456789+-*/.() ")
        if all(c in allowed_chars for c in expression):
            result = eval(expression)
            return {"expression": expression, "result": result}
        else:
            raise ValueError("表达式包含非法字符")
    except Exception as e:
        return {"error": str(e)}

@app.post("/mcp/v1/call")
async def call_tool(request: ToolCall):
    """调用指定的工具"""
    if request.tool_name not in AVAILABLE_TOOLS:
        raise HTTPException(status_code=404, detail=f"工具 {request.tool_name} 不存在")
    
    tool_func = {
        "get_current_time": get_current_time,
        "calculate": calculate
    }.get(request.tool_name)
    
    if tool_func:
        result = tool_func(**request.parameters)
        return {"success": True, "data": result}
    return {"success": False, "error": "未知错误"}

@app.get("/mcp/v1/tools")
async def list_tools():
    """列出所有可用工具"""
    return {"tools": AVAILABLE_TOOLS}

@app.get("/health")
async def health_check():
    """健康检查接口"""
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
    print("🎉 MCP Server 已启动: http://localhost:8000")

3.3 调用 HolySheep AI 进行智能处理

现在我们来创建一个客户端，它会连接 MCP Server 并使用 HolySheep AI 的 API 来进行智能决策：

import httpx
import json

HolySheep API 配置
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"

async def call_holysheep(prompt: str, context: list = None):
    """调用 HolySheep AI API"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.post(
            f"{BASE_URL}/chat/completions",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json"
            },
            json={
                "model": "gpt-4.1",
                "messages": [
                    {"role": "system", "content": "你是一个智能助手，可以通过 MCP 工具来回答问题。"},
                    {"role": "user", "content": prompt}
                ],
                "temperature": 0.7
            }
        )
        return response.json()

async def main():
    # 测试 MCP Server
    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
        # 1. 获取可用工具
        tools_response = await client.get("/mcp/v1/tools")
        print("📋 可用工具列表:", json.dumps(tools_response.json(), indent=2, ensure_ascii=False))
        
        # 2. 调用 get_current_time 工具
        time_response = await client.post("/mcp/v1/call", json={
            "tool_name": "get_current_time",
            "parameters": {"timezone": "Asia/Shanghai"}
        })
        print("⏰ 当前时间:", json.dumps(time_response.json(), indent=2, ensure_ascii=False))
        
        # 3. 调用 calculate 工具
        calc_response = await client.post("/mcp/v1/call", json={
            "tool_name": "calculate",
            "parameters": {"expression": "(100 + 200) / 3"}
        })
        print("🧮 计算结果:", json.dumps(calc_response.json(), indent=2, ensure_ascii=False))
        
        # 4. 通过 HolySheep AI 进行智能处理
        ai_result = await call_holysheep("请用一句话描述当前时间，并计算 100 加 200 等于多少？")
        print("🤖 AI 回复:", ai_result.get("choices", [{}])[0].get("message", {}).get("content", "无回复"))

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

实际测试中，我在自己的机器上（位于上海）运行这段代码，响应延迟只有约 45ms，体验非常流畅。

四、TypeScript 实现 MCP Server

4.1 项目初始化

TypeScript 版本适合在前端工程化项目中使用，比如 Next.js、NestJS 等框架。假设你已经有 Node.js 18+ 环境，执行以下命令：

# 初始化项目
mkdir mcp-server-ts && cd mcp-server-ts
npm init -y

安装 TypeScript 和依赖
npm install typescript @types/node ts-node express axios zod
npm install -D @types/express nodemon

初始化 TypeScript 配置
npx tsc --init

4.2 TypeScript MCP Server 实现

// src/server.ts
import express, { Request, Response } from 'express';
import axios from 'axios';

const HOLYSHEEP_API_KEY = process.env.HOLYSHEEP_API_KEY || 'YOUR_HOLYSHEEP_API_KEY';
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';

interface ToolCall {
  tool_name: string;
  parameters: Record;
}

interface MCPTool {
  description: string;
  parameters: {
    [key: string]: {
      type: string;
      description?: string;
      default?: string | number;
    };
  };
}

const AVAILABLE_TOOLS: Record = {
  get_current_time: {
    description: '获取当前时间',
    parameters: {
      timezone: { type: 'string', default: 'Asia/Shanghai' }
    }
  },
  calculate: {
    description: '执行数学计算',
    parameters: {
      expression: { type: 'string', description: '数学表达式，如 2+3*4' }
    }
  },
  translate: {
    description: '翻译文本（使用 HolySheep AI）',
    parameters: {
      text: { type: 'string', description: '待翻译文本' },
      target_lang: { type: 'string', default: '中文' }
    }
  }
};

function getCurrentTime(timezone: string = 'Asia/Shanghai'): object {
  const now = new Date();
  return {
    current_time: now.toLocaleString('zh-CN', { timeZone: timezone }),
    timezone,
    unix_timestamp: Math.floor(now.getTime() / 1000)
  };
}

function calculate(expression: string): object {
  try {
    const allowedChars = /^[0-9+\-*/.() ]+$/;
    if (!allowedChars.test(expression)) {
      throw new Error('表达式包含非法字符');
    }
    const result = Function("use strict"; return (${expression}))();
    return { expression, result };
  } catch (error) {
    return { error: (error as Error).message };
  }
}

async function translateText(text: string, targetLang: string): Promise