所有版权归于： https://github.com/ShawhinT/YouTube-Blog/
这是 AI 代理系列的第四个示例。在这里，我构建了一个客户端 MCP 服务器，以便任何 AI 应用都可以访问人工智能虚拟助手 (AVA) 的工具集。
链接
克隆此 repo
如果还没有安装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"在开发模式下测试服务器
uv run mcp dev mcp-server-example.py将服务器配置添加到 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"
]
}
}
}Related MCP server: Gmail AutoAuth MCP Server
在项目目录中找到prompts/ava.md文件
使用以下方式自定义文件：
沟通偏好
处理任务的具体说明
AVA 的任何其他相关指南
在项目根目录中创建一个.env文件，其中包含以下变量：
USER_EMAIL=your_email_address
# Google OAuth Credentials
GOOGLE_CREDENTIALS_PATH=.config/ava-agent/credentials.json
GOOGLE_TOKEN_PATH=.config/ava-agent/token.jsonUSER_EMAIL ：您要用于此应用程序的 Gmail 地址
GOOGLE_CREDENTIALS_PATH ：您的 Google OAuth 凭据文件的路径
GOOGLE_TOKEN_PATH ：存储 Google OAuth 令牌的路径
首先，创建所需的目录结构：
mkdir -p .config/ava-agent创建新项目或选择现有项目
启用 Gmail API：
在导航菜单中，转到“API 和服务”>“库”
搜索“Gmail API”
点击“启用”
在 Google Cloud Console 中：
前往“API 和服务”>“凭证”
点击“创建凭证”>“OAuth 客户端 ID”
选择“桌面应用程序”作为应用程序类型
给它起一个名字（例如，“AVA Gmail 客户端”）
点击“创建”
下载凭证：
创建完成后，点击“下载JSON”
将下载的文件保存为.config/ava-agent/中的credentials.json
该文件应包含您的客户端 ID 和客户端密钥
在 Google Cloud Console 中：
前往“API 和服务”>“OAuth 同意屏幕”
选择“外部”用户类型
填写所需信息：
应用程序名称
用户支持电子邮件
开发者联系信息
添加 Gmail API 范围： https://www.googleapis.com/auth/gmail.modify
将您的电子邮件添加为测试用户
完成配置
在服务器访问你的 Gmail 账户之前，你需要先授权。你可以运行uv run oauth.py来执行此操作，它会执行以下操作。
检查token.json是否存在
如果未找到，它将启动 Google OAuth 身份验证流程
指导您完成浏览器中的身份验证过程：
系统会要求您登录 Google 帐户
授予请求的权限
应用程序将自动保存令牌
自动生成并存储令牌
切勿将.env文件或token.json提交到版本控制
确保您的 Google 凭据安全
将以下内容添加到您的.gitignore中：
.env
.config/ava-agent/token.json
.config/ava-agent/credentials.jsonCreate a draft email using the Gmail API.
Args:
recipient_email (str): The email address of the recipient.
subject (str): The subject line of the email.
body (str): The main content/body of the email.
Returns:
dict or None: A dictionary containing the draft information including 'id' and 'message'
if successful, None if an error occurs.
Raises:
HttpError: If there is an error communicating with the Gmail API.
Note:
This function requires:
- Gmail API credentials to be properly configured
- USER_EMAIL environment variable to be set with the sender's email address
- Appropriate Gmail API permissions for creating drafts
| Name | Required | Description | Default |
|---|---|---|---|
| recipient_email | Yes | ||
| subject | Yes | ||
| body | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the operation's purpose, return values (success dictionary with id/message or None), error conditions (HttpError), and prerequisites (credentials, environment variable, permissions). It doesn't mention rate limits, retry behavior, or concurrency considerations, but covers the essential behavioral aspects for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, Raises, Note) and efficiently conveys necessary information. While slightly longer than minimal, each section earns its place by providing valuable context. The information is front-loaded with the core purpose stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation with API dependencies), no annotations, and no output schema, the description does a good job of providing context. It explains the operation, parameters, return values, errors, and prerequisites. While it could mention more about the Gmail API context or provide examples, it covers the essential information needed to understand and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the lack of parameter documentation in the schema. It provides clear parameter descriptions in the Args section, explaining what each parameter represents (recipient_email, subject, body). While it doesn't specify format constraints or examples, it adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a draft email') and resource ('using the Gmail API'), with no sibling tools to differentiate from. It provides a complete verb+resource+scope statement that leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While it mentions prerequisites (Gmail API credentials, environment variable, permissions), it doesn't indicate scenarios where this tool is appropriate or when other email-related tools might be preferred. No explicit when/when-not/alternatives information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
write_email_draftScored across 1 tool
With only one tool, there is no possibility of confusion or overlap between tools. The tool's purpose is singular and clearly defined as creating email drafts via Gmail API.
The single tool name follows a clear verb_noun pattern (write_email_draft). With only one tool, consistency is inherently perfect as there are no other names to compare against.
A single tool is insufficient for an email/Gmail server's scope. Basic email operations like sending, reading, listing, or deleting emails are missing, making this server feel incomplete and thin for its apparent domain.
The server is severely incomplete for email management. While write_email_draft covers draft creation, it lacks essential operations like send_email, list_emails, get_email, delete_email, or manage labels, creating significant gaps that will cause agent failures.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
