内容
# 从Python应用程序到MCP服务器
一个适合初学者的项目，演示如何将传统的Python应用程序转换为**模型上下文协议（MCP）**兼容的服务器。
示例应用程序使用简单的客户支持工作流程，但主要目标更广泛：展示现有的Python业务逻辑如何作为MCP工具公开，并被 **Cline**、**Claude Desktop**、**Cursor** 等AI客户端以及其他MCP兼容的代理使用。
## 目录
- [从Python应用程序到MCP服务器](#从python应用程序到mcp服务器)
- [概述](#概述)
- [为什么选择MCP？](#为什么选择mcp)
- [架构](#架构)
- [本项目适用于哪些人？](#本项目适用于哪些人)
- [本项目演示的内容](#本项目演示的内容)
- [示例工作流程](#示例工作流程)
- [用户请求](#用户请求)
- [AI客户端行为](#ai客户端行为)
- [MCP服务器行为](#mcp服务器行为)
- [最终AI响应](#最终ai响应)
- [可用工具](#可用工具)
- [项目结构](#项目结构)
- [快速入门](#快速入门)
- [1. 克隆仓库](#1-克隆仓库)
- [2. 创建虚拟环境](#2-创建虚拟环境)
- [3. 安装依赖项](#3-安装依赖项)
- [4. 运行MCP服务器](#4-运行mcp服务器)
- [配置MCP AI客户端](#配置mcp-ai客户端)
- [试用演示](#试用演示)
- [现实世界应用](#现实世界应用)
- [未来增强功能](#未来增强功能)
- [关键要点](#关键要点)
- [参考文献](#参考文献)
## 概述
传统应用程序通常通过用户界面、REST API、SDK或自定义集成公开功能。MCP提供了一种标准化的方式，让AI代理直接发现和调用应用程序功能。
本项目展示了如何使用 **FastMCP** 将常规Python函数公开为MCP服务器。
在本仓库中，示例领域是客户支持：
- 查询订单详情
- 检查产品库存
- 处理退款
该领域故意设计得很简单，以便于理解MCP架构。
## 为什么选择MCP？
没有MCP，每个AI集成通常需要自定义路由逻辑、自定义API包装器和特定于应用程序的编排。
```text
AI助手
|
v
自定义API集成
|
v
应用程序
```
使用MCP，任何兼容的AI客户端都可以通过共享协议发现和调用工具。
```text
AI客户端
|
v
MCP协议
|
v
MCP服务器
|
v
应用程序逻辑
```
这减少了集成复杂性，并使应用程序功能更容易在不同AI客户端中重用。
## 架构
## 本项目适用于哪些人？
本项目适用于：
- 学习MCP的开发人员
- 探索Agent AI的数据科学家
- 对AI工具集成感兴趣的工程师
- 希望将现有Python应用程序公开给AI代理的任何人
不需要先前的MCP经验。
在高层次上：
1. 用户在AI客户端中提出问题。
2. AI客户端发现MCP服务器公开的工具。
3. AI选择适合任务的工具。
4. MCP服务器运行底层Python应用程序逻辑。
5. 结果返回给AI客户端。
6. AI将结果转换为自然语言响应。
## 本项目演示的内容
本项目演示如何：
- 使用FastMCP构建MCP服务器
- 将Python函数公开为MCP工具
- 将MCP服务器连接到AI客户端
- 让AI代理自动发现工具
- 实现与应用程序逻辑的自然语言交互
- 了解Agent AI集成的架构
## 示例工作流程
### 用户请求
```text
我可以更换我的键盘吗？
```
### AI客户端行为
AI客户端分析请求并发现MCP服务器公开的工具。
它可能会选择调用：
```python
check_inventory("Keyboard")
```
### MCP服务器行为
MCP服务器执行Python函数并返回结果。
示例结果：
```text
键盘目前缺货。
```
### 最终AI响应
```text
键盘目前缺货，因此目前无法更换。
```
## 可用工具
示例MCP服务器公开了以下工具：
```python
get_order_details()
check_inventory()
process_refund()
```
这些是AI客户端可以通过MCP发现和调用的业务功能示例。
## 项目结构
```text
project/
|-- src/
| `-- server.py
|-- mermaid-mcp-architecture.png
|-- requirements.txt
|-- README.md
`-- .gitignore
```
## 快速入门
### 1. 克隆仓库
```bash
git clone <repository-url>
cd <repository-name>
```
### 2. 创建虚拟环境
```bash
python -m venv .venv
```
激活它：
```bash
source .venv/bin/activate
```
在Windows上：
```bash
.venv\Scripts\activate
```
### 3. 安装依赖项
```bash
pip install -r requirements.txt
```
### 4. 运行MCP服务器
```bash
python src/server.py
```
## 配置MCP AI客户端
将此服务器添加到您的MCP兼容AI客户端配置中。
示例Cline配置：
```json
{
"mcpServers": {
"customer-support": {
"command": "python",
"args": ["src/server.py"]
}
}
}
```
## 试用演示
配置好MCP客户端后，询问：
```text
你们有哪些MCP工具可用？
```
客户端应该会发现：
```text
get_order_details
check_inventory
process_refund
```
然后尝试使用自然语言请求：
```text
我可以更换我的键盘吗？
```
AI客户端应该：
1. 发现可用的MCP工具
2. 选择最相关的工具
3. 通过MCP服务器执行工具
4. 解释返回的结果
5. 以自然语言响应
## 现实世界应用
相同的MCP模式可以应用于许多系统，包括：
- Adobe Analytics
- Adobe Target
- Jira
- GitHub
- CRM系统
- 数据库
- 内部报告平台
- 库存管理系统
- 企业应用程序
任何具有可调用功能的应用程序都可以转换为MCP兼容的服务器。
## 未来增强功能
可能的下一步：
- 添加真实的数据库集成
- 添加身份验证和授权
- 连接到外部MCP服务器
- 远程部署MCP服务器
- 与企业系统集成
## 关键要点
本项目并不仅仅是关于客户支持。
它是关于演示如何将传统的Python应用程序转换为MCP兼容的服务，并通过自然语言使之对AI代理可用。
## 参考文献
1. 模型上下文协议. *入门指南*. 可在：https://modelcontextprotocol.io/docs/getting-started/intro 访问
2. Cyanheads. *模型上下文协议资源仓库*. GitHub. 可在：https://github.com/cyanheads/model-context-protocol-resources 访问
3. FastMCP. *入门文档*. 可在：https://gofastmcp.com/getting-started/welcome 访问
4. Cline. *Cline概述文档*. 可在：https://docs.cline.bot/cline-overview 访问
