Skip to main content
Glama
enesjakozh
ramaiyaKushal

AVA MCP Server

by ramaiyaKushal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Protocolo de Contexto Modelo (MCP)

Todos los créditos a: https://github.com/ShawhinT/YouTube-Blog/

Cuarto ejemplo de la serie de agentes de IA. Aquí, construyo un servidor MCP de cliente para que cualquier aplicación de IA tenga acceso a un conjunto de herramientas para un Asistente Virtual Artificial (AVA).

Campo de golf

Cómo ejecutar este ejemplo

  1. Clonar este repositorio

  2. Instala uv si aún no lo has hecho

# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  1. Pruebe el servidor en modo de desarrollo

uv run mcp dev mcp-server-example.py

  1. Agregue la configuración del servidor a la aplicación AI (por ejemplo, Claude Desktop o 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

Personalizar el comportamiento de AVA

Actualizar datos personales y preferencias

  1. Localice el archivo prompts/ava.md en el directorio de su proyecto

  2. Personaliza el archivo con:

    • Preferencias de comunicación

    • Instrucciones específicas para el manejo de tareas

    • ¿Alguna otra directriz relevante para AVA?

Configuración del entorno (.env)

  1. Cree un archivo .env en el directorio raíz del proyecto con las siguientes variables:

USER_EMAIL=your_email_address

# Google OAuth Credentials
GOOGLE_CREDENTIALS_PATH=.config/ava-agent/credentials.json
GOOGLE_TOKEN_PATH=.config/ava-agent/token.json

Variables de entorno requeridas:

  • USER_EMAIL : La dirección de Gmail que desea utilizar para esta aplicación

  • GOOGLE_CREDENTIALS_PATH : Ruta a su archivo de credenciales de Google OAuth

  • GOOGLE_TOKEN_PATH : Ruta donde se almacenará el token OAuth de Google

Configuración de Google OAuth

1. Crear la estructura del directorio del proyecto

Primero, cree la estructura de directorio requerida:

mkdir -p .config/ava-agent

2. Configurar el proyecto de Google Cloud

  1. Vaya a la consola de Google Cloud

  2. Crea un nuevo proyecto o selecciona uno existente

  3. Habilitar la API de Gmail:

    • En el menú de navegación, vaya a "API y servicios" > "Biblioteca".

    • Buscar "API de Gmail"

    • Haga clic en "Habilitar"

3. Crear credenciales OAuth

  1. En la consola de Google Cloud:

    • Vaya a "API y servicios" > "Credenciales".

    • Haga clic en "Crear credenciales" > "ID de cliente OAuth".

    • Elija "Aplicación de escritorio" como tipo de aplicación

    • Asígnele un nombre (por ejemplo, "Cliente de Gmail AVA")

    • Haga clic en "Crear"

  2. Descargar las credenciales:

    • Después de la creación, haga clic en "Descargar JSON".

    • Guarde el archivo descargado como credentials.json en .config/ava-agent/

    • El archivo debe contener su ID de cliente y su secreto de cliente.

4. Configurar la pantalla de consentimiento de OAuth

  1. En la consola de Google Cloud:

    • Vaya a "API y servicios" > "Pantalla de consentimiento de OAuth".

    • Seleccione el tipo de usuario "Externo"

    • Complete la información requerida:

      • Nombre de la aplicación

      • Correo electrónico de soporte al usuario

      • Información de contacto del desarrollador

    • Agregue el alcance de la API de Gmail: https://www.googleapis.com/auth/gmail.modify

    • Añade tu correo electrónico como usuario de prueba

    • Completar la configuración

Iniciar sesión en Google

Para que el servidor pueda acceder a tu cuenta de Gmail, deberás autorizarla. Puedes hacerlo ejecutando uv run oauth.py que realiza lo siguiente.

  1. Verificar la presencia de token.json

  2. Si no se encuentra, se iniciará el flujo de autenticación de Google OAuth.

  3. Le guiaremos a través del proceso de autenticación en su navegador:

    • Se le pedirá que inicie sesión en su cuenta de Google.

    • Conceder los permisos solicitados

    • La aplicación guardará automáticamente el token.

  4. Generar y almacenar el token automáticamente

Notas de seguridad

Protección de archivos

  • Nunca envíe su archivo .env o token.json al control de versiones

  • Mantenga sus credenciales de Google seguras

  • Añade lo siguiente a tu .gitignore :

    .env
.config/ava-agent/token.json
.config/ava-agent/credentials.json

Available Tools

1 tool
write_email_draftA

Create 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
ParametersJSON Schema
NameRequiredDescriptionDefault
recipient_emailYes
subjectYes
bodyYes

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • First observedwrite_email_draft
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count2/5

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.

Completeness2/5

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Artificial Virtual Assistant

    Ayoub-etoullali
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides AI applications with a toolset for an Artificial Virtual Assistant (AVA) integrated with the Gmail API. It enables users to automate email management and personal tasks through secure Google OAuth authentication.
    1
    Apache 2.0

  • Gmail AutoAuth MCP Server

    SepehrShapouri
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server enabling AI assistants to manage Gmail through natural language, including sending, reading, searching, labeling, and handling attachments with auto authentication.
    1
    MIT

  • Google Calendar Gmail MCP

    AaKa5204
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI assistants to interact with Google Calendar and Gmail, allowing users to manage events, send emails, and organize their inbox through natural language.
    MIT

  • Google Workspace MCP Server

    risvan1605
    A
    license
    A
    quality
    D
    maintenance
    An MCP-compliant server that exposes Gmail and Google Docs as tools, enabling AI agents to draft, send, and manage emails, as well as create, read, and append to documents through natural language.
    9
    MIT