内容
# 模型上下文协议 (MCP)
AI 代理系列中的第四个例子。在这里，我构建了一个客户 MCP Server，以使任何 AI 应用程序都可以访问用于人工智能虚拟助手 (AVA) 的工具集。
**链接**
- [Video](https://youtu.be/N3vHJcHBS-w)
- [Blog](https://medium.com/data-science-collective/model-context-protocol-mcp-explained-ef5c33c5fe05)
## 如何运行此示例
1. 克隆此 repo
2. 如果尚未安装，请[安装 uv](https://docs.astral.sh/uv/getting-started/installation/)
```
# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
3. 在开发模式下测试服务器
```
uv run mcp dev mcp-server-example.py
```
4. 将服务器配置添加到 AI 应用程序（例如 Claude Desktop 或 Cursor）。
```
{
"mcpServers": {
"AVA": {
"command": "/Users/shawhin/.local/bin/uv", # replace with global path to your uv installation
"args": [
"--directory",
"/Users/shawhin/Documents/_code/_stv/sandbox/ava-mcp/", # replace with global path to repo
"run",
"mcp-server-example.py"
]
}
}
}
```
## 自定义 AVA 的行为
### 更新个人详细信息和偏好
1. 在您的项目目录中找到 `prompts/ava.md` 文件
2. 使用以下内容自定义文件：
- 沟通偏好
- 处理任务的具体说明
- AVA 的任何其他相关指南
## 环境变量设置 (.env)
1. 在项目的根目录中创建一个 `.env` 文件，其中包含以下变量：
```env
USER_EMAIL=your_email_address
# Google OAuth Credentials
GOOGLE_CREDENTIALS_PATH=.config/ava-agent/credentials.json
GOOGLE_TOKEN_PATH=.config/ava-agent/token.json
```
### 必需的环境变量：
- `USER_EMAIL`: 您要用于此应用程序的 Gmail 地址
- `GOOGLE_CREDENTIALS_PATH`: Google OAuth 凭据文件的路径
- `GOOGLE_TOKEN_PATH`: 将存储 Google OAuth 令牌的路径
## Google OAuth 设置
### 1. 创建项目目录结构
首先，创建所需的目录结构：
```bash
mkdir -p .config/ava-agent
```
### 2. 设置 Google Cloud 项目
1. 转到 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建一个新项目或选择一个现有项目
3. 启用 Gmail API：
- 在导航菜单中，转到“API 和服务”>“库”
- 搜索“Gmail API”
- 点击“启用”
### 3. 创建 OAuth 凭据
1. 在 Google Cloud Console 中：
- 转到“API 和服务”>“凭据”
- 点击“创建凭据”>“OAuth 客户端 ID”
- 选择“桌面应用程序”作为应用程序类型
- 给它一个名称（例如，“AVA Gmail Client”）
- 点击“创建”
2. 下载凭据：
- 创建后，点击“下载 JSON”
- 将下载的文件另存为 `.config/ava-agent/` 中的 `credentials.json`
- 该文件应包含您的客户端 ID 和客户端密钥
### 4. 配置 OAuth 同意屏幕
1. 在 Google Cloud Console 中：
- 转到“API 和服务”>“OAuth 同意屏幕”
- 选择“外部”用户类型
- 填写所需信息：
- 应用名称
- 用户支持电子邮件
- 开发者联系信息
- 添加 Gmail API 范围：`https://www.googleapis.com/auth/gmail.modify`
- 将您的电子邮件添加为测试用户
- 完成配置
## 登录 Google
在服务器可以访问您的 Gmail 帐户之前，您需要对其进行授权。您可以通过运行 `uv run oauth.py` 来执行此操作，它执行以下操作。
1. 检查是否存在 `token.json`
2. 如果未找到，它将启动 Google OAuth 身份验证流程
3. 指导您完成浏览器中的身份验证过程：
- 系统会要求您登录您的 Google 帐户
- 授予请求的权限
- 应用程序将自动保存令牌
4. 自动生成并存储令牌
## 安全注意事项
### 文件保护
- 永远不要将您的 `.env` 文件或 `token.json` 提交到版本控制
- 确保您的 Google 凭据安全
- 将以下内容添加到您的 `.gitignore`：
```
.env
.config/ava-agent/token.json
.config/ava-agent/credentials.json
```
