内容
# 🚀 高级MCP实验室：远程HTTP和安全根
---
## 📌 项目概述
本项目演示了**先进的、生产就绪的模型上下文协议（MCP）实现**，从基本的标准输入输出升级到完全远程的**可流式HTTP传输**。
它实现了**文件系统根安全边界**、**服务器发起的LLM采样**和**OpenAI GPT-4o-mini集成**，这些是企业代理AI部署中使用的现实世界模式。
**领域：** 代理AI — 高级MCP架构
**语言：** Python 3.11
**服务器：** HTTP，地址为 `http://127.0.0.1:8000/mcp`
**工作空间：** 严格沙箱化的 `workspace/` 目录
---
## 🏗️ 系统架构
```
┌──────────────────────────────────────────────────┐
│ AI 主机应用 │
│ OpenAI GPT-4o-mini │
│ 自然语言 → OpenAI 函数调用 │
│ → MCP 工具调用 → 结果 → 用户 │
└─────────────────────┬────────────────────────────┘
│
┌─────────────────────▼────────────────────────────┐
│ 基础 HTTP 客户端（MCPHTTPClient） │
│ streamablehttp_client → /mcp 端点 │
│ list_tools / call_tool / list_resources │
│ list_prompts / get_prompt / read_resource │
└─────────────────────┬────────────────────────────┘
│ 可流式HTTP端口 8000
┌─────────────────────▼────────────────────────────┐
│ FastMCP HTTP 服务器（127.0.0.1:8000） │
│ │
│ 🔧 工具 📦 资源 │
│ ├── read_file file://workspace/{file} │
│ ├── write_file │
│ ├── list_files 💬 提示 │
│ └── analyze_code ├── review_code │
│ （采样） └── analyze_security │
│ │
│ 🛡️ 根：仅限 workspace/ — is_within_roots() │
└──────────────────────────────────────────────────┘
```
---
## 📂 项目结构
```
advanced-mcp-lab/
│
├── mcp_http_server.py # FastMCP HTTP 服务器 — 工具、资源、提示
├── mcp_http_client_base.py # 基础客户端 — 可流式HTTP传输层
├── mcp_http_client_app.py # Gradio GUI 客户端 — 手动工具/资源测试
├── mcp_http_host_app.py # OpenAI GPT-4o-mini AI 主机应用
│
└── workspace/ # 安全沙箱 — 仅可访问目录
├── test.txt # 示例测试文件
└── README.md # 工作空间描述
```
---
## 🛠️ 技术栈
| 组件 | 技术 | 版本 |
|---|---|---|
| MCP 框架 | FastMCP | 2.12.5 |
| MCP 协议 | 模型上下文协议 | 1.16.0 |
| 语言 | Python | 3.11+ |
| HTTP 传输 | streamablehttp_client | httpx 0.28.1 |
| UI 框架 | Gradio | 5.49.1 |
| LLM 集成 | OpenAI GPT-4o-mini | openai 1.26.1 |
| 服务器端点 | http://127.0.0.1:8000/mcp | 可流式HTTP |
---
## 🔧 MCP 服务器 — 工具、资源和提示
### 工具（共4个）
| 工具 | 描述 | 根检查 |
|---|---|---|
| `read_file` | 从工作空间读取文件 | ✅ 是 |
| `write_file` | 写入工作空间文件 | ✅ 是 |
| `list_files` | 列出工作空间中的文件/目录 | ✅ 是 |
| `analyze_code` | 触发服务器发起的采样 | ✅ 是 |
### 资源
| URI模式 | 描述 |
|---|---|
| `file://workspace/{filename}` | 读取任意工作空间文件作为资源 |
### 提示
| 提示 | 目的 |
|---|---|
| `review_code` | 为文件生成代码审查提示 |
| `analyze_security` | 为文件生成安全分析提示 |
---
## 🛡️ 根安全实现
所有工具操作都针对 `workspace/` 目录进行验证：
```python
def is_within_roots(path: Path) -> bool:
try:
path.resolve().relative_to(BASE_DIR.resolve())
return True
except ValueError:
return False
```
**它能防止：**
- 路径遍历攻击 (`../../etc/passwd`)
- 访问工作空间外的系统文件
- 对主机文件系统的未经授权读取/写入
---
## 🤖 服务器发起的采样
`analyze_code` 工具演示了**采样模式**:
```
工具调用：analyze_code(code, focus)
│
▼
服务器构建采样/createMessage请求
│
▼
请求发送回客户端：
{
"method": "sampling/createMessage",
"params": {
"messages": [{"role": "user", "content": "分析此代码..."}],
"maxTokens": 500
}
}
│
▼
客户端显示确认 → 用户确认
│
▼
客户端调用LLM → 将分析结果返回给服务器
```
**关键好处：** LLM API 密钥从未离开客户端！ ✅
---
## 🚀 如何运行
**步骤 1 — 安装依赖：**
```bash
pip install mcp==1.16.0 fastmcp==2.12.5 httpx==0.28.1 gradio==5.49.1 openai==1.26.1
```
**步骤 2 — 设置 OpenAI API 密钥：**
```bash
export OPENAI_API_KEY="your-api-key-here"
```
**步骤 3 — 启动 MCP HTTP 服务器（终端 1）：**
```bash
python mcp_http_server.py
# 输出：启动 HTTP MCP 服务器，地址为 http://127.0.0.1:8000
# 输出：工作空间根目录：./workspace
```
**步骤 4 — 启动 GUI 客户端（终端 2）：**
```bash
python mcp_http_client_app.py
```
**步骤 5 — 启动 AI 主机应用（终端 3）：**
```bash
python mcp_http_host_app.py
```
---
## 🌐 HTTP vs STDIO 传输
| 功能 | STDIO（基本MCP） | HTTP（本项目） |
|---|---|---|
| 连接性 | 仅限本地进程 | 远程/云就绪 |
| 客户端 | 单个客户端 | 多个并发客户端 |
| 服务器生命周期 | 与客户端绑定 | 独立进程 |
| 部署 | 相同机器 | 任意服务器/云 |
| 端点 | 标准输入/标准输出 | `http://host:port/mcp` |
---
## 🎓 展示的技能
- 高级模型上下文协议（MCP），使用HTTP传输
- 可流式HTTP客户端-服务器通信
- 文件系统根安全边界实现
- 服务器发起的LLM采样模式
- OpenAI GPT-4o-mini函数调用集成
- MCP工具、资源和提示实现
- 合成工具 — 将MCP资源包装为OpenAI函数
- 用于AI应用开发的Gradio UI
- 基础/派生类架构（MCPHTTPClient → 主机/GUI应用）
- 异步Python — asyncio、AsyncExitStack、httpx
- 生产就绪的代理AI系统设计
---
## 🔗 相关项目
| 项目 | 传输 | 焦点 |
|---|---|---|
| [MCP安全性和权限](https://github.com/Leelaissakattaota/MCP-Security-with-Permissions-and-Elicitation) | STDIO | 权限管理和诱导 |
| **高级MCP实验室** ← 您当前所在 | HTTP | 根安全性和采样 |
---
## 📜 认证
| 认证 | 发行者 | 平台 |
|---|---|---|
| IBM数据科学专业认证 | IBM | Coursera |
| IBM生成式AI专业认证 | IBM | Coursera |
| IBM RAG和代理AI专业认证 | IBM | Coursera |
---
## 🤝 与我联系
[](https://www.linkedin.com/in/leela-a)
[](mailto:attotaleelaissak@gmail.com)
[](https://github.com/Leelaissakattaota)
