Model Context Protocol (MCP)

模型上下文协议（MCP）

感谢：https://github.com/ShawhinT/YouTube-Blog/

这是 AI Agent 系列的第四个示例。在这里，我构建了一个客户 MCP 服务，让任何 AI 应用都能使用一套工具，为人工虚拟助手（AVA）提供支持。

链接

• 视频
• 博客

如何运行此示例

1. 克隆此仓库
2. 如果尚未安装，请安装 uv

# 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 文件，并添加以下变量：

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. 创建项目目录结构

首先，创建所需的目录结构：

mkdir -p .config/ava-agent

2. 设置 Google Cloud 项目

1. 前往 Google Cloud 控制台
2. 创建新项目或选择现有项目
3. 启用 Gmail API：
   • 在导航菜单中，前往“API 和服务” > “库”
   • 搜索“Gmail API”
   • 点击“启用”

3. 创建 OAuth 凭据

1. 在 Google Cloud 控制台中：

   • 前往“API 和服务” > “凭据”
   • 点击“创建凭据” > “OAuth 客户端 ID”
   • 选择“桌面应用”作为应用类型
   • 为其命名（例如“AVA Gmail Client”）
   • 点击“创建”

2. 下载凭据：

   • 创建后，点击“下载 JSON”
   • 将下载的文件保存为 .config/ava-agent/ 中的 credentials.json
   • 文件应包含您的客户端 ID 和客户端密钥

4. 配置 OAuth 同意屏幕

1. 在 Google Cloud 控制台中：
   • 前往“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