# MZMCP - MCP 服务集成平台
[](https://github.com/xiaomizhoubaobei/MCP/actions/workflows/[publish-to-pypi.yml](.github/workflows/publish-to-pypi.yml))
[](https://github.com/xiaomizhoubaobei/MCP/actions/workflows/codeql.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/xiaomizhoubaobei/MCP)
[](https://www.bestpractices.dev/projects/11826)
[](LICENSE)
[](https://github.com/xiaomizhoubaobei/MCP/releases/latest)
[](https://www.python.org/downloads/)
[](https://github.com/xiaomizhoubaobei/MCP/issues)
[](https://github.com/xiaomizhoubaobei/MCP/pulls)
[](https://github.com/xiaomizhoubaobei/MCP/commits/main)
[](https://github.com/xiaomizhoubaobei/MCP/commits/main)
[](https://modelcontextprotocol.io/)
[](https://www.serverless-devs.com/)
[](https://www.aliyun.com/product/fc)
## 项目架构图
## 案例介绍
本案例将 MCP (Model Context Protocol) 服务器部署到阿里云函数计算 FC，提供多种 AI 服务能力的统一接口。通过本案例，您可以快捷地部署、使用 MCP 服务，让 Claude 等 AI 助手具备调用华为云 OCR 等多种 AI 服务的能力。
本案例支持华为云 OCR 文字识别功能，用户可以通过 URL 或 Base64 编码识别图片中的文字内容。采用 SSE 传输方式实现实时通信，支持模块化设计，可按需扩展其他云服务提供商的 AI 服务。
本案例适用于需要让 AI 助手具备 OCR 文字识别能力的场景，可作为 AI 服务集成平台，实现多云服务统一接入，基于 Serverless 架构构建 AI 应用。
MCP 协议正在成为 AI 服务集成的标准协议，获得 Anthropic、OpenAI 等主流 AI 厂商的支持。Serverless 架构已成为云原生应用的主流选择，阿里云函数计算 FC 服务稳定可靠，支持百万级并发请求，99.99% 的服务可用性。
## 技术架构
本项目采用以下技术框架：
| 技术组件 | 版本/说明 | 用途 |
|----------------------------------|---------------------|----------------------------|
| **MCP (Model Context Protocol)** | 最新标准 | AI 服务集成协议，标准化 AI 能力调用 |
| **FastMCP** | Python SDK | MCP 服务器开发框架，简化 MCP 协议实现 |
| **Serverless Devs** | 最新版 | Serverless 应用开发部署框架 |
| **阿里云函数计算 FC** | - | Serverless 计算平台，按需计费，自动扩缩容 |
| **Python** | 3.10/3.11/3.12/3.13/3.14 | 开发语言 |
| **华为云 OCR SDK** | Python 3.x | 华为云 OCR 服务 SDK |
| **SSE (Server-Sent Events)** | - | 实时通信协议，用于 MCP 传输 |
**框架优势**：
- **MCP 协议**：统一 AI 服务接入标准，获得 Anthropic、OpenAI 等主流厂商支持
- **FastMCP 框架**：开箱即用的 MCP 服务器实现，支持自动工具注册和类型提示
- **Serverless Devs**：声明式配置，一键部署，支持多云平台
- **阿里云函数计算 FC**：零运维、高可用、自动扩缩容，99.99% 服务可用性
本案例通过 Serverless 开发平台实现了以下核心价值：
- **降低开发门槛**：无需关注底层基础设施、服务器运维和资源管理，开发者可以专注于业务逻辑和 AI 服务集成，大幅缩短学习曲线和开发时间
- **快速迭代**：Serverless 架构支持代码的快速部署和更新，从开发到上线仅需几分钟，支持敏捷开发和持续集成
- **成本优化**：采用按需付费模式，只为实际使用的资源付费，避免服务器闲置造成的资源浪费，显著降低运营成本
- **弹性扩展**：自动应对流量波动，从零到百万级并发无缝扩展，无需手动配置和干预，确保服务始终可用
- **统一接入**：通过 MCP 协议统一多种 AI 服务接口，屏蔽不同云服务商的 API 差异，简化集成复杂度，便于快速切换和扩展
## 使用流程
### 0. 快速体验 - 本地启动 MCP 服务
本步骤用于在本地快速启动 MCP 服务，方便开发和测试。无需部署到云端，即可体验完整功能。
本项目支持两种传输模式：
| 模式 | 传输方式 | 使用场景 | 优势 |
|-----------|---------------------------|---------------------|-----------------------|
| **SSE** | HTTP (Server-Sent Events) | Web 服务器、远程访问 | 支持 HTTP，可远程调用，适合部署到云端 |
| **stdio** | 标准输入输出 | 本地开发、Claude Desktop | 启动更快，调试更方便，资源占用更少 |
在开始之前，您需要：
| 步骤 | 说明 |
|-----------|--------------------|
| Python 环境 | Python 3.10 或更高版本 |
| 安装依赖 | 安装项目所需的 Python 依赖包 |
| 配置环境变量 | 设置华为云认证信息 |
#### 安装依赖
```bash
# 进入项目目录
cd src/mzmcp
# 安装依赖
pip install -r requirements.txt
```
或使用 UV 进行更快速的依赖管理：
```bash
# 安装 UV（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 使用 UV 安装依赖
cd src/mzmcp
uv pip install -r requirements.txt
```
#### 配置环境变量
在本地设置华为云的认证信息：
**Linux/macOS:**
```bash
export HUAWEI_CLOUD_SECRET_ID=your-secret-id
export HUAWEI_CLOUD_SECRET_KEY=your-secret-key
export HUAWEI_CLOUD_REGION=cn-east-3
```
**Windows (PowerShell):**
```powershell
$env:HUAWEI_CLOUD_SECRET_ID="your-secret-id"
$env:HUAWEI_CLOUD_SECRET_KEY="your-secret-key"
$env:HUAWEI_CLOUD_REGION="cn-east-3"
```
#### 模式一：启动 SSE 服务（HTTP 服务器）
适合需要通过 HTTP 访问或部署到服务器的场景。
```bash
# 进入项目目录
cd src/mzmcp
# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8080
```
服务启动后，您会看到类似以下输出：
```
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
INFO: Started reloader process [xxxxx] using StatReload
INFO: Started server process [xxxxx]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
##### 配置 Claude Desktop 连接 SSE 服务
在 Claude Desktop 的配置文件中添加本地 MCP 服务器配置：
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"huaweicloud-ocr-sse": {
"url": "http://localhost:8080/sse"
}
}
}
```
#### 模式二：启动 stdio 服务（推荐用于本地开发）
适合本地开发和 Claude Desktop 集成，启动更快，资源占用更少。
```bash
# 进入项目目录
cd src/mzmcp
# 启动 stdio 服务
python stdio_main.py
```
服务启动后，MCP 服务器将通过标准输入输出与 Claude Desktop 通信。
##### 配置 Claude Desktop 连接 stdio 服务
在 Claude Desktop 的配置文件中添加 stdio MCP 服务器配置：
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"huaweicloud-ocr-stdio": {
"command": "uvx",
"args": ["mzmcp"],
"env": {
"HUAWEI_CLOUD_SECRET_ID": "your-secret-id",
"HUAWEI_CLOUD_SECRET_KEY": "your-secret-key",
"HUAWEI_CLOUD_REGION": "cn-east-3"
}
}
}
}
```
**说明：**
- **uvx mzmcp** 是 MCP 工具链的标准运行方式，会自动下载并运行最新版本的 mzmcp
- 如果 uv 命令不可用，可以先使用 `pip install uv` 安装 uv 工具
**注意：**
- `uvx` 会自动处理虚拟环境，无需预先配置
- 可以在 `env` 中直接配置环境变量，无需预先设置
- 如果已通过 `pip install mzmcp` 安装，也可以使用 `mzmcp` 命令代替 `uvx mzmcp`
**本地开发优势：**
- 🚀 快速迭代，实时查看修改效果
- 💡 方便调试，直接查看日志输出
- 🎯 无需云端资源，零成本开发
- 🔧 支持热重载，修改代码自动生效
- ⚡ stdio 模式启动更快，资源占用更少
### 1. 准备工作 - 完成账号注册和服务开通
本步骤用于完成阿里云账号注册、函数计算服务开通以及华为云密钥获取，为后续部署做好准备。
在开始之前，您需要：
| 步骤 | 说明 |
|----------|------------------------------|
| 注册阿里云账号 | 访问 https://www.aliyun.com 注册 |
| 开通函数计算服务 | 在控制台开通 FC 服务 |
| 获取华为云密钥 | 在华为云控制台获取 Access Key |
| 配置环境变量 | 设置华为云认证信息 |
### 2. 部署应用 - 将 MCP 服务部署到阿里云函数计算
本步骤使用 Serverless Devs 工具将 MCP 服务代码部署到阿里云函数计算平台。
使用 Serverless Devs 工具快速部署：
```bash
# 1. 安装 Serverless Devs
npm install -g @serverless-devs/s
# 2. 配置阿里云密钥
s config add
# 3. 部署应用
s deploy
```
### 3. 配置环境变量 - 设置华为云认证信息
本步骤在函数计算控制台配置华为云的认证信息，确保服务能够正常调用华为云 OCR API。
在函数计算控制台配置以下环境变量：
| 变量名 | 说明 | 是否必需 | 示例值 |
|-------------------------|-------------|------|---------------------|
| HUAWEI_CLOUD_SECRET_ID | 华为云访问密钥 ID | 是 | `<your-secret-id>` |
| HUAWEI_CLOUD_SECRET_KEY | 华为云访问密钥 Key | 是 | `<your-secret-key>` |
| HUAWEI_CLOUD_REGION | 华为云服务区域 | 否 | `cn-east-3` |
**支持的华为云区域**：
| 区域名称 | 区域代码 |
|------------|----------------|
| 非洲-john内斯堡 | af-south-1 |
| 中国-香港 | ap-southeast-1 |
| 亚太-曼谷 | ap-southeast-2 |
| 亚太-新加坡 | ap-southeast-3 |
| 华东-上海一 | cn-east-3 |
| 华北-北京一 | cn-north-1 |
| 华北-北京四 | cn-north-4 |
| 华南-广州 | cn-south-1 |
| 西南-贵阳一 | cn-southwest-2 |
| 拉美-墨西哥城二 | la-north-2 |
### 4. 在 Claude Desktop 中配置 MCP 服务器 - 连接 Claude 与 MCP 服务
本步骤在 Claude Desktop 客户端中配置 MCP 服务器，建立 Claude 与阿里云函数计算服务的连接。
部署完成后，在 Claude Desktop 的配置文件中添加 MCP 服务器配置：
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"huaweicloud-ocr": {
"url": "http://your-fc-url/sse"
}
}
}
```
将 `http://your-fc-url/sse` 替换为您的函数计算服务 URL。
### 5. 使用 OCR 服务 - 通过 Claude 调用 OCR 功能
本步骤演示如何在 Claude Desktop 中使用 MCP 服务调用 OCR 功能识别图片文字。
配置完成后，重启 Claude Desktop，您就可以直接与 Claude 对话，让它调用 OCR 服务：
**示例对话：**
```
用户：请帮我识别这张图片中的文字内容
Claude：好的，我来帮您识别这张图片...
[Claude 自动调用 recognize_web_image 工具]
识别结果：图片中包含以下文字内容："..."
```
或者明确指定：
```
用户：使用 URL 识别这张图片：https://example.com/image.png
Claude：我来帮您识别这张网络图片...
[Claude 调用 recognize_web_image 工具，传入 image_url 参数]
识别结果：...
```
### 6. 可用工具 - 查看 MCP 服务提供的工具列表
本步骤展示 MCP 服务器提供的可用工具及其参数说明。
MCP 服务器提供以下工具：
| 工具名称 | 参数 | 说明 |
|---------------------|-----------------------------|------------------------|
| recognize_web_image | image_url (可选) 或 image (可选) | 通过 URL 或 Base64 编码识别图片 |
**注意**：`image_url` 和 `image` 参数二选一，不能同时提供。
## 贡献指南
本项目使用 pre-commit 进行代码质量检查，确保代码符合规范。
### 安装 Pre-commit
```bash
# 安装 pre-commit
pip install pre-commit
# 安装 git hooks
pre-commit install
```
### 配置的 Hooks
| Hook | 作用 | 优先级 |
|-------------------------|----------------------------|-------|
| **gitleaks** | 检测密钥泄露 | 🔒 必须 |
| **pylint** | Python 代码质量检查（含 pytest 支持） | 🐍 必须 |
| **trailing-whitespace** | 删除行尾空格 | 🔧 推荐 |
| **end-of-file-fixer** | 修复文件末尾 | 📄 推荐 |
| **shellcheck** | Shell 脚本检查 | 🐚 推荐 |
### 手动运行 Hooks
```bash
# 对所有文件运行
pre-commit run --all-files
# 对特定文件运行
pre-commit run --files src/mzmcp/main.py
```
### 更新 Hooks
```bash
# 更新到最新版本
pre-commit autoupdate
# 重新安装
pre-commit install --hook-stage pre-commit
```
更多详细信息请参阅 [Pre-commit 官方文档](https://pre-commit.com/)。
## 注意事项
1. **环境变量配置**：确保正确配置华为云的 Access Key 和 Secret Key，否则 OCR 服务无法正常调用
2. **网络访问**：如果使用 URL 识别，确保图片 URL 可公开访问
3. **图片格式**：支持常见的图片格式（JPG、PNG、BMP 等），建议使用清晰的图片以提高识别准确率
4. **并发限制**：函数计算有并发限制，大量并发请求可能触发限流
5. **费用说明**：
- 函数计算按实际使用量计费
- 华为云 OCR 服务按调用次数计费
- 建议合理使用，避免不必要的调用
6. **区域选择**：建议选择与目标用户接近的区域，降低网络延迟
7. **安全建议**：
- 不要将 Access Key 和 Secret Key 提交到代码仓库
- 使用环境变量或密钥管理服务存储敏感信息
- 定期轮换密钥
## CI/CD 流水线
本项目采用完整的 CI/CD 流水线，确保代码质量和安全性。
详细的 CI/CD 流水线说明、Mermaid 可视化图以及各工作流的触发条件，请查看 [CI/CD 流水线文档](pipeline-diagram.md)。
该文档包含：
- 完整的 Mermaid 流水线可视化图
- 各工作流的详细触发条件
- 工作流分类和说明
