使用说明
MCP客户端教程
用Python构建MCP（模型上下文协议）客户端和服务器的最小示例。本教程将教您如何创建可以使用外部工具的AI应用程序。
这是基于https://realpython.com/python-mcp-client
但我已经删除了所有不必要的复杂性（使用 uv，使用 toml 创建可执行文件等）。
所有这些本身都是有用的，但与主题无关。这样做的目的是了解MCP客户端。
什么是MCP？
MCP（模型上下文协议）是将AI模型连接到外部工具和数据的标准。将其视为一种赋予你的人工智能超能力的方式——而不仅仅是聊天，它可以：
- 呼叫工具 -执行搜索、计算或查询数据库等功能
- 使用提示 -访问预定义的提示模板
- 阅读资源 -访问文件、API或其他数据源
项目结构
mcp_client/
├── mcp_client/ # The client package
│ ├── __init__.py # Package marker
│ ├── __main__.py # Entry point (python -m mcp_client)
│ ├── cli.py # Command-line argument parsing
│ ├── mcp_client.py # Core client logic
│ ├── handlers.py # OpenAI integration
│ └── chat.py # Interactive chat loop
├── mcp_server/ # Example server
│ ├── mcp_server.py # Server with tools, prompts, resources
│ └── greeting.txt # Sample resource file
├── .env # Your OpenAI API key (create this)
├── requirements.txt # Python dependencies
└── README.md # This file
运作原理
┌─────────────┐ stdio ┌─────────────┐
│ MCP Client │ ◄────────────► │ MCP Server │
│ (Python) │ JSON-RPC │ (Python) │
└──────┬──────┘ └─────────────┘
│
│ API calls
▼
┌─────────────┐
│ OpenAI │
│ (GPT-4o) │
└─────────────┘
- 这 客户端 开始 服务器 作为子流程
- 它们通过JSON-RPC在stdin/stdout上进行通信
- 客户向OpenAI提问，并提供可用的工具
- 当OpenAI想要使用工具时，客户端通过MCP调用它
- 结果被发送回OpenAI进行最终响应
设置
1.创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
2.安装依赖项
pip install -r requirements.txt
3.设置您的OpenAI API密钥
创建一个 .env 项目根目录中的文件：
OPENAI_API_KEY=your-api-key-here
从以下位置获取API密钥：https://platform.openai.com/api-keys
用法
列出服务器功能
查看服务器公开了哪些工具、提示和资源：
python3 -m mcp_client mcp_server/mcp_server.py --members
输出：
MCP Server Members
==================================================
TOOLS (1):
------------------------------
> echo - Echo back the provided message.
PROMPTS (1):
------------------------------
> greeting_prompt - A prompt template for greeting someone kindly.
RESOURCES (1):
------------------------------
> file://./greeting.txt - Serve the contents of greeting.txt as a resource.
==================================================
开始AI聊天
与可以使用服务器工具的AI聊天：
python3 -m mcp_client mcp_server/mcp_server.py --chat
对话示例：
MCP Chat Started!
Type your questions or 'quit' to exit.
You: Can you echo "Hello MCP!"
[Used echo({'message': 'Hello MCP!'})]
Assistant: Hello MCP!
You: quit
Goodbye!
理解代码
服务器（mcp_Server/mcp_Server.py）
服务器使用 FastMCP 为了展示能力：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my_server")
@mcp.tool()
async def echo(message: str) -> str:
"""Echo back the provided message."""
return message
@mcp.tool()-将函数注册为可调用工具@mcp.prompt()-注册提示模板@mcp.resource("uri")-注册数据资源
客户端（mcp_Client/mcp_Client.py）
客户端使用异步上下文管理器连接到服务器：
async with MCPClient("path/to/server.py") as client:
await client.run_chat()
关键概念：
- 异步堆栈 -管理多个异步资源的清理
- stdio_客户端 -生成服务器并创建通信流
- 客户端会话 -处理MCP协议消息
人工智能集成（mcp_client/handlers.py）
使用MCP工具桥接OpenAI：
- 从MCP服务器获取可用工具
- 将用户查询与工具定义一起发送到OpenAI
- 如果OpenAI请求一个工具，则通过MCP执行它
- 向用户返回最终响应
使用的Python关键概念
本教程使用了一些可能不熟悉的Python功能：
异步/等待
async def my_function():
result = await some_async_operation()
允许非阻塞I/O操作。这 await 关键字暂停，直到操作完成。
上下文管理器
async with MCPClient(...) as client:
# client is set up
...
# client is automatically cleaned up
确保资源得到正确初始化和清理，即使出现错误。
海象操作员 :=
if not (api_key := os.getenv("KEY")):
raise Error("Missing key")
指定一个值并在同一表达式中使用它。相当于：
api_key = os.getenv("KEY")
if not api_key:
raise Error("Missing key")
类型提示
def echo(message: str) -> str:
文件 message 应该是一个字符串，函数返回一个字符串。Python不强制执行这些，但它们有助于可读性和IDE支持。
后续步骤
现在您已经了解了基础知识，请尝试：
- 添加新工具 -编辑
mcp_server.py添加一个有用的工具（例如，获取天气、搜索文件） - 添加对话记忆 -修改
handlers.py记住以前的消息 - 尝试不同的AI -用Anthropic的Claude或本地模型替换OpenAI
