Model Context Protocol (MCP)

How to run this example

1. Clone this repo
2. Install uv if you haven't already

# 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. Test the server in dev mode

uv run mcp dev mcp-server-example.py

4. Add server config to your AI app.

   Cursor: The config is already in this repo at .cursor/mcp.json. Cursor reads that file when you open this project. If your uv or project path is different, edit .cursor/mcp.json and update command (path to uv) and args[1] (path to this repo). Then restart Cursor (or reload the window) so it picks up the MCP server. MCP tools run in Agent/Composer mode.

   Alternative in Cursor (UI): Open Settings (Cmd + , / Ctrl + ,) → Tools & MCP → Add new MCP server. Set name to AVA, type to command, command to the full path to uv (e.g. /Users/sobby/.local/bin/uv), and args to: --directory, /Users/sobby/Workspace/mcp-demo, run, mcp-server-example.py (exact order). Save and restart Cursor.

   Claude Desktop: Put the same JSON under the MCP config file used by Claude Desktop (see Claude Desktop MCP docs).

{
  "mcpServers": {
    "AVA": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/mcp-demo", "run", "mcp-server-example.py"]
    }
  }
}

Recruiting pipeline (MVP)

Trigger: upload new resumes to a directory. No Gmail read. You provide:

• applicants.csv — columns: Name, Email, LinkedIn, Resume name, Job (optional). Job = job ID (filename stem in jobs/, e.g. senior-software-engineer or product-manager). Defaults to senior-software-engineer if missing. Add a row when you add a new resume.
• resumes/ — one file per resume; filenames must match "Resume name" in the CSV (e.g. jane-doe-sse.txt).
• jobs/ — one .md file per role (e.g. senior-software-engineer.md, product-manager.md). The job ID is the filename without .md. Each applicant is evaluated against the job indicated in their CSV row.
• linkedin/ — (optional, for demo) One .md file per candidate; filename = resume stem without extension (e.g. jane-doe-sse.md). Used to compare resume vs LinkedIn when you ask: the read_linkedin(resume_name) tool loads a profile; comparison appears in the evaluation response.
• A Google Sheet with a tab named "Candidates" (or set GOOGLE_SHEET_NAME) and headers: Name, Email, Job Applied, AI Score, Key Strengths, Gaps, Recommended Action, Status.

Flow:

1. Upload new resume(s) to resumes/ and add the corresponding row(s) to applicants.csv. Optionally add a matching file in linkedin/ (e.g. jane-doe-sse.md) so evaluation can compare resume vs LinkedIn when you ask.
2. Ask AVA to "Process new applications" (or "Sync applicants to the sheet"). AVA runs process_new_applications(): evaluates each applicant and adds or updates rows. For LinkedIn comparison, ask explicitly (e.g. "Process new applications and compare with LinkedIn").
3. Open the sheet, filter/sort by score, strengths, gaps, status.
4. Ask AVA to draft email only for the candidates you choose (e.g. "Draft email to Jane Doe", "Create drafts for these 5"). AVA creates Gmail drafts; you send after review.

Email draft template: Drafts use the template in email-templates/candidate-draft.txt (greeting, body from the evaluator, sign-off). Edit that file to change wording; set RECRUITER_NAME in .env for the sign-off name.

LinkedIn comparison (demo, opt-in)

The read_linkedin(resume_name) tool reads a markdown file from linkedin/ whose filename matches the resume stem (e.g. jane-doe-sse.md for jane-doe-sse.txt). LinkedIn is only used when you explicitly ask for it: use evaluate_candidate_with_linkedin or process_new_applications_with_linkedin (e.g. "evaluate Jane Doe and compare with her LinkedIn"). The comparison appears in the evaluation response (linkedin_notes); it is not written to the Google Sheet. No real LinkedIn API is used; the demo uses sample .md profiles in linkedin/.

Customizing AVA's Behavior

Update Personal Details and Preferences

1. Locate the prompts/ava.md file in your project directory
2. Customize the file with:
   • Communication preferences
   • Specific instructions for handling tasks
   • Any other relevant guidelines for AVA

Environment Setup (.env)

1. Create a .env file in the root directory of the project with the following 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

# Recruiting pipeline (MVP) — Claude for evaluation
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-3-5-haiku-20241022
GOOGLE_SHEET_ID=your_google_sheet_id
RECRUITER_NAME=Your Name
RESUME_DIR=resumes
APPLICANTS_CSV=applicants.csv

Required Environment Variables:

• USER_EMAIL: The Gmail address you want to use for this application
• GOOGLE_CREDENTIALS_PATH: Path to your Google OAuth credentials file
• GOOGLE_TOKEN_PATH: Path where the Google OAuth token will be stored
• ANTHROPIC_API_KEY (or CLAUDE_API_KEY): For candidate evaluation via Claude (recruiting pipeline)
• GOOGLE_SHEET_ID: Spreadsheet ID for the candidate tracking sheet (recruiting; create the sheet first and use the ID from the URL)
• RECRUITER_NAME: Name used in draft email sign-off (e.g. "Jane Smith"). Optional; defaults to "The Hiring Team"

Google OAuth Setup

1. Create Project Directory Structure

First, create the required directory structure:

mkdir -p .config/ava-agent

2. Set Up Google Cloud Project

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable APIs:
   • In the navigation menu, go to "APIs & Services" > "Library"
   • Enable Gmail API (search "Gmail API" > Enable)
   • Enable Google Sheets API (search "Google Sheets API" > Enable)

3. Create OAuth Credentials

1. In the Google Cloud Console:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop application" as the application type
   • Give it a name (e.g., "AVA Gmail Client")
   • Click "Create"

2. Download the credentials:

   • After creation, click "Download JSON"
   • Save the downloaded file as credentials.json in .config/ava-agent/
   • The file should contain your client ID and client secret

4. Configure OAuth Consent Screen

1. In the Google Cloud Console:
   • Go to "APIs & Services" > "OAuth consent screen"
   • Choose "External" user type
   • Fill in the required information:
     • App name
     • User support email
     • Developer contact information
   • Add scopes: https://www.googleapis.com/auth/gmail.compose and https://www.googleapis.com/auth/spreadsheets
   • Add your email as a test user
   • Complete the configuration

Note: If you add the Sheets scope after already having a token, delete token.json and run uv run oauth.py again.

Signing into Google

Before the server can access you Gmail account you will need to authorize it. You can do this by running uv run oauth.py which does the following.

1. Check for the presence of token.json
2. If not found, it will initiate the Google OAuth authentication flow
3. Guide you through the authentication process in your browser:
   • You'll be asked to sign in to your Google account
   • Grant the requested permissions
   • The application will automatically save the token
4. Generate and store the token automatically

Security Notes

File Protection

• Never commit your .env file or token.json to version control
• Keep your Google credentials secure
• Add the following to your .gitignore:

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