使用说明

MCP 101：模型上下文协议学习项目

一个全面的实践学习项目，旨在理解和实施（某技术/理念/方法） 模型上下文协议（MCP） - 由Anthropic开发的一种开放标准，使人工智能模型能够安全地连接到外部工具、服务器和数据源。

🌟 什么是MCP？

模型上下文协议（MCP） 就像“AI的USB-C接口”——一种AI模型和代理与外部系统通信的标准化方式。它定义了AI模型如何能够：

连接到外部工具和服务
从API获取实时数据
与文件系统和数据库进行交互
控制浏览器和自动化工具
扩展模型内置功能之外的能力

🏗️ 项目结构

mcp_101/
├── src/                          # Source code and notebooks
│   ├── 1_lab1.ipynb             # Introduction to MCP concepts
│   ├── 2_lab2.ipynb             # Building custom MCP servers
│   ├── 3_lab3.ipynb             # Advanced MCP implementations
│   ├── 4_lab4.ipynb             # Multi-server coordination with AsyncExitStack
│   ├── my_custom_mcp_server.py   # Custom MCP server with tools, resources, and prompts
│   ├── filesystem_mcp.py         # FileSystem MCP server integration
│   ├── playwright_mcp.py         # Playwright MCP server integration
│   └── mcp_servers_tools_and_agent.py  # Multi-server agent implementation
├── sandbox/                      # Working directory for file operations
│   └── Chicken_Tikka_Masala_Recipe.md  # Example output file
├── pyproject.toml               # Project dependencies
├── env.example                 # Environment variables template
└── README.md                   # This file

🚀 快速入门

先决条件

Python 3.13及以上版本
Node.js（用于基于NPX的MCP服务器）
OpenAI API密钥

安装

克隆并设置项目：
```
git clone <repository-url>
cd mcp_101
```

安装依赖项：

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

设置环境变量：

cp env.example .env
# Edit .env with your API keys

激活虚拟环境：

source .venv/bin/activate  # On Unix/Mac
# or
.venv\Scripts\activate     # On Windows

📚 学习路径

实验1：MCP基础（MCP为某专业或技术的缩写，具体含义需根据上下文确定，此处保留原样）`1_lab1.ipynb`)

你将学到：

理解MCP（可能指某种特定系统、框架或协议，具体需根据上下文确定，此处直译为“MCP”）的概念和架构
MCP服务器如何扩展AI代理的功能
使用现有的MCP服务器（Fetch、Playwright、FileSystem）
使用OpenAI Agents SDK实现多服务器协调
使用OpenAI Traces追踪代理行为

关键概念：

MCP服务器 vs MCP客户端
工具发现与执行
协议标准化
代理-服务器通信

实验2：构建自定义MCP服务器（`2_lab2.ipynb`)

你将学到：

使用FastMCP创建自定义MCP服务器
实施工具、资源和提示
使用 ClientSession 连接到 MCP 服务器
使用MCPServerStdio与OpenAI智能体
在Jupyter笔记本中使用Asyncio的最佳实践

已实现的功能：

工具： get_date()， get_time()
资源动态问候资源greeting://{name}）
提示个性化的问候提示
客户集成直接客户端和代理集成两者都支持

实验3：高级MCP（微控制器协议栈/模块控制器协议栈，具体含义根据上下文确定）实现`3_lab3.ipynb`)

你将学到：

本地MCP服务器（离线，内存中）
本地+网络MCP服务器（调用外部API）
远程/托管MCP服务器概念
环境变量管理
API集成模式

实验4：使用AsyncExitStack实现多服务器协调`4_lab4.ipynb`)

你将学到：

使用 AsyncExitStack 同时管理多个MCP服务器
协调本地和外部MCP服务器（日期服务器+网页搜索）
为多个异步上下文管理器提供干净的资源管理
代理与多服务器功能的集成
实际应用示例：结合日期/时间和天气信息

关键概念：

AsyncExitStack 用于简洁的多服务器管理
避免嵌套 async with 声明
服务器协调与工具选择
外部服务的环境变量配置

🛠️ 核心组件

自定义MCP服务器`my_custom_mcp_server.py`）

一个全面的MCP服务器，展示了MCP的所有三种功能：

# Tools - executable functions
@mcp.tool()
def get_date() -> str:
    """Return current date in YYYY-MM-DD format"""
    return datetime.now().strftime("%Y-%m-%d")

# Resources - data sources with URIs
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

# Prompts - template-based prompts
@mcp.prompt()
def get_greeting_prompt(name: str) -> str:
    """Get a personalized greeting prompt"""
    return f"Please write a warm, friendly greeting to {name}!"

文件系统集成（`filesystem_mcp.py`)

展示如何连接到官方的FileSystem MCP服务器：

# Uses NPX to run the official filesystem server
filesystem_params = {
    "command": "npx", 
    "args": ["-y", "@modelcontextprotocol/server-filesystem", sandbox_path]
}

能力：

在沙盒目录中读取/写入文件
目录列表和导航
文件元数据访问
安全的文件操作

剧作家集成（`playwright_mcp.py`）

展示如何集成浏览器自动化功能：

# Uses NPX to run the Playwright MCP server
playwright_params = {
    "command": "npx", 
    "args": ["@playwright/mcp@latest"]
}

能力：

网页导航与交互
屏幕截图捕获
填写并提交表格
JavaScript 执行
浏览器自动化

多服务器代理（`mcp_servers_tools_and_agent.py`）

展示了一个AI代理同时使用多个MCP服务器的情况：

# Agent with both filesystem and browser capabilities
agent = Agent(
    name="investigator",
    instructions="You browse the internet to accomplish your instructions...",
    model="gpt-4o-mini",
    mcp_servers=[mcp_server_filesystem, mcp_server_browser]
)

示例任务： 在网上找到一个食谱，并将其保存为Markdown文件。

🔧 技术实现

MCP服务器架构

graph TD
    A[AI Agent] --> B[MCP Client]
    B --> C[Custom MCP Server]
    B --> D[FileSystem MCP Server]
    B --> E[Playwright MCP Server]
    C --> F[Tools/Resources/Prompts]
    D --> G[File Operations]
    E --> H[Browser Automation]

关键技术

FastMCP用于构建MCP服务器的Python框架
**OpenAI智能体软件开发工具包（SDK）**集成MCP的代理框架
**MCPServerStdio（注：这个名称可能是特定软件或系统的名称，直接翻译为中文可能无法准确传达其原意，但按照字面意思可翻译为“MCPServer标准控制台/标准输入输出”，具体翻译需根据上下文或该名称的实际用途来确定。）**标准I/O通信协议
客户端会话直接MCP客户端实现
**Asyncio（异步I/O）**MCP操作的异步编程

在Jupyter Notebook中使用Asyncio

该项目包含了在Jupyter笔记本中运行asyncio代码的全面示例：

# Method 1: asyncio.run() (Recommended)
async def test_mcp_client():
    # Your async MCP code here
    pass

asyncio.run(test_mcp_client())

# Method 2: nest_asyncio (For multiple async calls)
import nest_asyncio
nest_asyncio.apply()
# Now you can use await directly

📖 使用示例

运行自定义MCP服务器

# Start the custom server
python src/my_custom_mcp_server.py

# In another terminal, test with client
python -c "
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test():
    server_params = StdioServerParameters(
        command='python', 
        args=['src/my_custom_mcp_server.py']
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as client:
            await client.initialize()
            tools = await client.list_tools()
            print('Available tools:', tools)

asyncio.run(test())
"

使用带有代理的MCP服务器

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

# Define server parameters
server_params = {"command": "python", "args": ["my_custom_mcp_server.py"]}

# Create agent with MCP server
async with MCPServerStdio(params=server_params) as mcp_server:
    agent = Agent(
        name="greeting_assistant",
        instructions="You are a greeting assistant.",
        model="gpt-4o-mini",
        mcp_servers=[mcp_server]
    )
    
    result = await Runner.run(agent, "Greet John Doe using the available tools")
    print(result.final_output)

使用多个MCP服务器与AsyncExitStack

from agents import Agent, Runner
from agents.mcp import MCPServerStdio
from contextlib import AsyncExitStack
import os

# Define multiple server parameters
local_server_params = {
    "command": "python", 
    "args": ["my_custom_mcp_server.py"]
}

web_search_params = {
    "command": os.path.expanduser("~/.local/bin/uvx"), 
    "args": ["serper-mcp-server"],
    "env": {"SERPER_API_KEY": os.getenv("SERPER_API_KEY")}
}

# Use AsyncExitStack to manage multiple servers
async with AsyncExitStack() as stack:
    local_server = await stack.enter_async_context(
        MCPServerStdio(params=local_server_params)
    )
    web_server = await stack.enter_async_context(
        MCPServerStdio(params=web_search_params)
    )
    
    agent = Agent(
        name="multi_server_agent",
        instructions="Use available tools to fulfill requests.",
        model="gpt-4o-mini",
        mcp_servers=[local_server, web_server]
    )
    
    result = await Runner.run(agent, "Get today's date and weather in San Francisco")
    print(result.final_output)

🎯 学习成果

完成这个项目后，你将理解：

MCP建筑事务所MCP服务器和客户端如何通信
工具开发创建自定义工具、资源和提示
代理集成将MCP服务器连接到AI代理
多服务器协调同时使用多个MCP服务器
实际应用文件操作、网页自动化、API集成
最佳实践异步I/O（Asyncio）、错误处理和调试

🔍 故障排除

常见问题

使用 nest_asyncio 时出现的“连接已关闭”错误
- 使用 asyncio.run() 而不是 nest_asyncio
- 确保正确清理异步资源
“TaskGroup”错误
- 检查服务器文件是否存在且可访问
- 使用服务器文件的绝对路径
- 确保在异步上下文中正确处理错误
导入错误
- 激活虚拟环境
- 安装缺失的依赖项
- 检查Python版本兼容性

调试技巧

使用 print() 用于追踪执行的语句
检查服务器路径是否正确 os.path.abspath()
在集成之前，独立测试MCP服务器
使用OpenAI Traces监控代理行为

📚 额外资源

🤝 贡献

这是一个学习项目。请随意：

添加新的MCP服务器示例
改进文档
分享你的实现方法
报告问题并提出改进建议

📄 许可证

此项目仅用于教育目的。请尊重所使用的依赖项和外部服务的许可协议。

学习快乐！ 🚀

探索MCP（可能指某种技术或平台，如“机器控制平台”等，具体需根据上下文确定）的强大功能，构建能够与现实世界交互的令人惊叹的AI应用。

使用说明

MCP 101：模型上下文协议学习项目

🌟 什么是MCP？

🏗️ 项目结构

🚀 快速入门

先决条件

安装

📚 学习路径

实验1：MCP基础（MCP为某专业或技术的缩写，具体含义需根据上下文确定，此处保留原样）1_lab1.ipynb)

实验2：构建自定义MCP服务器（2_lab2.ipynb)

实验3：高级MCP（微控制器协议栈/模块控制器协议栈，具体含义根据上下文确定）实现3_lab3.ipynb)

实验4：使用AsyncExitStack实现多服务器协调4_lab4.ipynb)

🛠️ 核心组件

自定义MCP服务器my_custom_mcp_server.py）

文件系统集成（filesystem_mcp.py)

剧作家集成（playwright_mcp.py）

多服务器代理（mcp_servers_tools_and_agent.py）

🔧 技术实现

MCP服务器架构

关键技术

在Jupyter Notebook中使用Asyncio

📖 使用示例

运行自定义MCP服务器

使用带有代理的MCP服务器

使用多个MCP服务器与AsyncExitStack

🎯 学习成果

🔍 故障排除

常见问题

调试技巧

📚 额外资源

🤝 贡献

📄 许可证

相关 MCP

设计文件AI连接服务

MCP配置工具包

MCP协议服务器

MCP服务器框架

MCP服务器构建

模型上下文协议服务器

实验1：MCP基础（MCP为某专业或技术的缩写，具体含义需根据上下文确定，此处保留原样）`1_lab1.ipynb`)

实验2：构建自定义MCP服务器（`2_lab2.ipynb`)

实验3：高级MCP（微控制器协议栈/模块控制器协议栈，具体含义根据上下文确定）实现`3_lab3.ipynb`)

实验4：使用AsyncExitStack实现多服务器协调`4_lab4.ipynb`)

自定义MCP服务器`my_custom_mcp_server.py`）

文件系统集成（`filesystem_mcp.py`)

剧作家集成（`playwright_mcp.py`）

多服务器代理（`mcp_servers_tools_and_agent.py`）