C 1、什么是MCP

C 01、什么是mcp

全程是模型上下文协议，mcp server 作为 ai 与外部工具的中间层，取代人类访问或操作外部工具。MCP 本质上就是一段 python 程序，大模型通过操作系统的 STDIO(标准输入输出通道或 SSE 协议调用某个 MCP Server，通过指定的消息格式。MCP Server 接收到这些消息后，通过代码或调用 api 来访问外部工具并且完成任务。mcp 简单来说就是 ai 大模型的标准化工具箱，mcp server 对接到 aip 客户端里实现各种智能体与工作流。

C 02、mcp使用流程

python 可以使用 uvx 命令，通过 stdio 协议，pypi 发布；也可以使用远程调用，通过 sse 协议，通过服务器部署来发布

nodejs 可以通过 npx 命令，通过 stdio 协议，np #MCPm 发布；也可以使用远程调用，通过 sse 协议，通过服务器部署来发布

C 03、mcp协议，理解stdio与sse

• stdio本地调用，ai客户端直接调用mcp server
• sse远程调用，ai客户端经过网络调用mcp server

mcp 官方仓库，关注 python-sdk 和 pytescript-sdk 这两个开发工具包 github.com/orgs/modelc…

下面使用 python-sdk 来实现一个 sdk

C 2、实现一个MCP

01、安装uv

第一，安装 uv，uv 是目录热度最高的 python 环境管理工具，登录官网找到所在系统的安装命令 docs.astral.sh/uv/#highlig…

# mac和Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

# uv安装成功后，可以通过下面的命令查看一下系统上安装的python版本

uv python list

# 通过uv安装python

uv python install 3.13.7

02、初始化项目

uv 初始化项目

# 初始化项目

uv init 01_mcp_getting_started -p 3.13 cd 01_mcp_getting_started

# 创建虚拟环境并进入虚拟环境

uv venv .venvScriptsactivate.bat

# mac执行如下命令进入虚拟环境

source .venv/bin/activate

# 安装mcp python sdk开发工具包及其他依赖

uv add "mcp[cli]" httpx openai python-dotenv

简单配置一下 vscode：

1. vscode安装python与python debugger插件
2. 使用vscode打开这个文件夹

.env文件夹是python的虚拟环境
pyproject.toml定义了项目的基本信息
main.py是基础的代码样例

C 03、编写MCP

这里我们会用 dotenv 来管理我们相关的环境变量。.env 文件内容如下：

ZHI_PU_AI_API_KEY=xxx

创建文件 web_search.py

import httpx
from mcp.server import FastMCP
import platform
import json
import os  # 导入 os 模块

import logging from dotenv import load_dotenv

# 加载.env文件中的环境变量

load_dotenv()

# 配置日志

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# 初始化 FastMCP 服务器

app = FastMCP('web-search')

# 从环境变量中读取 API 密钥

# ZHI_PU_AI_API_KEY = os.environ.get("ZHI_PU_AI_API_KEY")  #替换成你的环境变量名

ZHI_PU_AI_API_KEY = os.getenv("ZHI_PU_AI_API_KEY") if not ZHI_PU_AI_API_KEY: logging.error("未找到 ZHI_PU_AI_API_KEY 环境变量") raise ValueError("请设置 ZHI_PU_AI_API_KEY 环境变量")

@app.tool() async def web_search(query: str) -> str: """ 搜索互联网内容

Args: query: 要搜索内容

Returns: 搜索结果的总结 """ async with httpx.AsyncClient() as client: try: response = await client.post( 'https://open.bigmodel.cn/api/paas/v4/tools', headers={'Authorization': ZHI_PU_AI_API_KEY}, json={ 'tool': 'web-search-pro', 'messages': [ {'role': 'user', 'content': query} ], 'stream': False } ) response.raise_for_status() # 抛出 HTTPError，以处理非 200 状态码

res_data = [] for choice in response.json()['choices']: for message in choice['message']['tool_calls']: search_results = message.get('search_result') if not search_results: continue for result in search_results: res_data.append(result['content'])

return '


'.join(res_data)

except httpx.HTTPStatusError as e: logging.error(f"HTTP 错误: {e}") return f"搜索失败：HTTP 错误 - {e}" except httpx.RequestError as e: logging.error(f"请求错误: {e}") return f"搜索失败：请求错误 - {e}" except json.JSONDecodeError as e: logging.error(f"JSON 解析错误: {e}, 响应内容: {response.text}") # 记录响应内容

return "搜索失败：无法解析 JSON 响应" except Exception as e: logging.exception("发生未知的错误") return "搜索失败：发生未知的错误"

@app.tool() def add(a: int, b: int) -> int: """Add two numbers""" return a + b

@app.tool() def get_host_info() -> str: """ Get host information Returns: str: the host information in JSON string format """ info: dict[str, str] = { "system": platform.system(), "node": platform.node(), "release": platform.release(), "version": platform.version(), "machine": platform.machine(), "processor": platform.processor(), }

return json.dumps(info, indent=4)

# @app.resoruce("greeting://{name}")

# def get_greeting(name: str) -> str:

# """Get a personalized greeting"""

# return f"Hello, {name}!"

if __name__ == "__main__": app.run(transport='stdio')

关键点：1、mcp 函数第一行的这个注释必须要写的，使用自然语言告知大模型这个函数的功能是什么 2、mcp 函数的类型修饰符必定要写，有助于大模型理解工具的传参是什么类型，可以帮大模型更精准的调用 mcp 工具 3、@mcp.tool() 类似于 Http Rest API 中的 post 方法，会产生副作用 4、@mcp.resource() 类似于 get 方法，为大模型提供只读数据，不会产生副作用

C 04、调试mcp

# 通过npx, node版本v20.19.2

npx -y @modelcontextprotocol/inspector uv run web_search.py

# 通过mcp dev来运行

# mcp dev web_search.py

C 3、接入MCP Server

01、使用Cherry Studio接入MCP Server

路径：设置 - MCP 服务器

注意：

1. 如果右上角有一个三角形的红色三角，需要先安装uv和bun，由于Chery Studio使用的是它内置的uv和bun

添加 mcp

--directory
/Users/snddfhv/03learn/mcp-servers/01_mcp_getting_started
run
web_search.py

02、验证

4、PS

01、使用环境变量管理API Key

我们会申请多个平台的多个 API Key，为了方便在控制台快速使用，我们可以将其添加到环境变量中。添加永久性环境变量

# 1、执行如下命令将环境变量设置追加到~/.zshrc文件中(或～/.bashrc)

echo "export ZHI_PU_AI_API_KEY='xxx'" >> ~/.zshrc

# 2、使变更生效

要 ource ~/.zshrc

# 3、重新打开一个终端端口，检查环境变量是否生效

echo $ZHI_PU_AI_API_KEY

添加临时性环境变量

# 1、设置环境变量

export ZHI_PU_AI_API_KEY='xxx'

# 2、验证环境变量是否生效

echo $ZHI_PU_AI_API_KEY

Python 02、使用python-dotenv管理API Key

安装 python-dotenv

pip3 install python-dotenv

创建 .env 文件 在项目根目录下创建一个名为 .env 的文件，并在其中添加环境变量

ZHI_PU_AI_API_KEY=xxx

在 Python 代码中使用环境变量

import os
from dotenv import load_dotenv

# 加载.env文件中的环境变量

load_dotenv()

# 获取ZHI_PU_AI_API_KEY

api_key = os.getenv("ZHI_PU_AI_API_KEY") if api_key: print(f"ZHI_PU_AI_API_KEY: {api_key}") else: print("环境变量 ZHI_PU_AI_API_KEY 未设置或未加载")

03、uv的使用

001、安装

# 推荐使用` pipx `进行安装，以将其隔离

pip install pipx pipx ensurepath pipx install uv

下面介绍一下 uv 的主要使用场景和命令

002、虚拟环境管理

# 创建虚拟环境

uv venv

# 指定虚拟环境的名称或路径

uv venv my_env uv venv /path/to/my_env

# 激活虚拟环境

source .venv/bin/activate

# 退出虚拟环境

deactivate

# 列出所有虚拟环境

uv venv list

# 移除虚拟环境

uv venv remove .venv uv venv remove my_env

003、包管理

# 安装包

uv pip install python-dotenv uv pip install requests beautifulsoup4 uv pip install "Django=4.2"

# 从requirements.txt安装

uv pip install -r requirements.txt

# 升级包

uv pip install --upgrade python-dotenv uv pip install --upgrade -r requirements.txt

# 卸载包

uv pip uninstall python-dotenv uv pip uninstall requests beautifulsoup4

# 列出已安装的包

uv pip list uv pip freeze # 一般用于生成 requirements.txt

# 缓存管理

uv pip cache purge

004、运行命令

uv run python my_script.py

005、 pyproject.toml 支持

uv 很好地支持现代 Python 项目中推荐的 pyproject.toml 文件来定义项目依赖

[project]
name = "your-awesome-project"
version = "0.1.0"
dependencies = [
  "fastapi",
  "uvicorn[standard]",
]
[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

安装项目依赖

# 在包含pyproject.toml的项目根目录中

# 安装核心依赖

uv pip install .

# 安装开发依赖

uv pip install ".[dev]"

006、uv的优势

• 极快的性能：Rust的编译速度带来了显著的性能提升，尤其在处理复杂依赖图时
• 一致性：旨在消除pip和pip-tools在依赖解析方面的一些不一致行为
• 依赖解析能力：采用最先进的依赖解析算法，能够更准确地解决复杂的依赖冲突
• 缓存：有效利用缓存，进一步回事安装过程

07、总结

uv 是 Python 包管理领域的一个强劲而有前途的新工具。通过整合虚拟环境和包管理功能，并提供卓越的速度，它为 Python 开发者提供了一个更高效、更愉悦的工作流程。如果你正在寻找 pip 的快速替代吕，并希望简化 Python 项目的依赖管理，uv 绝对值得一试。