本案例将 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 差异，简化集成复杂度，便于快速切换和扩展

本步骤用于在本地快速启动 MCP 服务，方便开发和测试。无需部署到云端，即可体验完整功能。

本项目支持两种传输模式：

模式	传输方式	使用场景	优势
SSE	HTTP (Server-Sent Events)	Web 服务器、远程访问	支持 HTTP，可远程调用，适合部署到云端
stdio	标准输入输出	本地开发、Claude Desktop	启动更快，调试更方便，资源占用更少

在开始之前，您需要：

步骤	说明
Python 环境	Python 3.10 或更高版本
安装依赖	安装项目所需的 Python 依赖包
配置环境变量	设置华为云认证信息

# 进入项目目录
cd src/mzmcp

# 安装依赖
pip install -r requirements.txt

或使用 UV 进行更快速的依赖管理：

# 安装 UV（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 UV 安装依赖
cd src/mzmcp
uv pip install -r requirements.txt

在本地设置华为云的认证信息：

Linux/macOS:

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):

$env:HUAWEI_CLOUD_SECRET_ID="your-secret-id"
$env:HUAWEI_CLOUD_SECRET_KEY="your-secret-key"
$env:HUAWEI_CLOUD_REGION="cn-east-3"

适合需要通过 HTTP 访问或部署到服务器的场景。

# 进入项目目录
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 的配置文件中添加本地 MCP 服务器配置：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "huaweicloud-ocr-sse": {
      "url": "http://localhost:8080/sse"
    }
  }
}

适合本地开发和 Claude Desktop 集成，启动更快，资源占用更少。

# 进入项目目录
cd src/mzmcp

# 启动 stdio 服务
python stdio_main.py

服务启动后，MCP 服务器将通过标准输入输出与 Claude Desktop 通信。

在 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

{
  "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 模式启动更快，资源占用更少

本步骤用于完成阿里云账号注册、函数计算服务开通以及华为云密钥获取，为后续部署做好准备。

在开始之前，您需要：

步骤	说明
注册阿里云账号	访问 https://www.aliyun.com 注册
开通函数计算服务	在控制台开通 FC 服务
获取华为云密钥	在华为云控制台获取 Access Key
配置环境变量	设置华为云认证信息

本步骤使用 Serverless Devs 工具将 MCP 服务代码部署到阿里云函数计算平台。

使用 Serverless Devs 工具快速部署：

# 1. 安装 Serverless Devs
npm install -g @serverless-devs/s

# 2. 配置阿里云密钥
s config add

# 3. 部署应用
s deploy

本步骤在函数计算控制台配置华为云的认证信息，确保服务能够正常调用华为云 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

本步骤在 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

{
  "mcpServers": {
    "huaweicloud-ocr": {
      "url": "http://your-fc-url/sse"
    }
  }
}

将 http://your-fc-url/sse 替换为您的函数计算服务 URL。

本步骤演示如何在 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 参数]
识别结果：...

本步骤展示 MCP 服务器提供的可用工具及其参数说明。

MCP 服务器提供以下工具：

工具名称	参数	说明
recognize_web_image	image_url (可选) 或 image (可选)	通过 URL 或 Base64 编码识别图片

注意：image_url 和 image 参数二选一，不能同时提供。

本项目使用 pre-commit 进行代码质量检查，确保代码符合规范。

# 安装 pre-commit
pip install pre-commit

# 安装 git hooks
pre-commit install

Hook	作用	优先级
gitleaks	检测密钥泄露	🔒 必须
pylint	Python 代码质量检查（含 pytest 支持）	🐍 必须
trailing-whitespace	删除行尾空格	🔧 推荐
end-of-file-fixer	修复文件末尾	📄 推荐
shellcheck	Shell 脚本检查	🐚 推荐

# 对所有文件运行
pre-commit run --all-files

# 对特定文件运行
pre-commit run --files src/mzmcp/main.py

# 更新到最新版本
pre-commit autoupdate

# 重新安装
pre-commit install --hook-stage pre-commit

更多详细信息请参阅 Pre-commit 官方文档。

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 流水线说明、Mermaid 可视化图以及各工作流的触发条件，请查看 CI/CD 流水线文档。

该文档包含：

• 完整的 Mermaid 流水线可视化图
• 各工作流的详细触发条件
• 工作流分类和说明