Compare commits
22 Commits
087839d2bf
...
FEAT-tweak
| Author | SHA1 | Date | |
|---|---|---|---|
|
54c6f7e81b | ||
|
|
55d0e77788 | ||
| aaef1b31c4 | |||
| c76725b111 | |||
| e88a0226b6 | |||
| cfef93a374 | |||
| 48017d958e | |||
| 7a6112479f | |||
|
|
94a0a485d9 | ||
|
|
cebfb0d589 | ||
|
|
c22d616595 | ||
|
|
cfcac8607c | ||
|
|
8ad47f1d27 | ||
| 38c7e48a1d | |||
|
|
6817014b7f | ||
| dade7f1fb8 | |||
|
|
632b0029be | ||
| 549f2b0949 | |||
| c1f03a7cbe | |||
|
|
b767a1f09c | ||
| 76d4b490bf | |||
|
|
31618b1acf |
1
.gitignore
vendored
1
.gitignore
vendored
@@ -5,6 +5,7 @@ build/
|
|||||||
accountsAndCredentials/credentials.json
|
accountsAndCredentials/credentials.json
|
||||||
accountsAndCredentials/accounts.json
|
accountsAndCredentials/accounts.json
|
||||||
accountsAndCredentials/token*.json
|
accountsAndCredentials/token*.json
|
||||||
|
accountsAndCredentials/token.json.bak
|
||||||
!accountsAndCredentials/*.example.json
|
!accountsAndCredentials/*.example.json
|
||||||
|
|
||||||
# Runtime output
|
# Runtime output
|
||||||
|
|||||||
546
README.md
546
README.md
@@ -1,490 +1,188 @@
|
|||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="assets/logo.png" alt="Declawed" width="120" />
|
<img src="assets/logo.png" alt="deClawed" width="120" />
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
# deClawed
|
||||||
|
|
||||||
# Declawed: your kuddly assisty-kitty
|
**LLM-powered email, meeting, teleconference and event triage and workflow automation via the Model Context Protocol**
|
||||||
|
|
||||||
|
|
||||||
Inbox brimming with stank? Wanna cut the crap and get the messaging that matters into calendars, Atlassian, Jira, Asana, Google Calendar/Sheets (etc.) ... in two clicks? (Cat) nip slop in the bud with Assisty-Kitty!!
|
|
||||||
|
|
||||||
|
|
||||||
# The "why":
|
|
||||||
|
|
||||||
|
|
||||||
### Eliminates that frustrating feeling you'll never get your paws around the dangling, catnip-stuffed mouse through haunch-high mail from list you're never signed up for or were re-sold to from ones you have, bot-generated marketing slop, and, of course, nigerians princes that need help claim their lottery jackpot.
|
|
||||||
|
|
||||||
|
|
||||||
"deClawed" because: no one should be beholden to one LLM api or local model. Have you seen that baddie Kimi K3?
|
|
||||||
|
|
||||||
|
|
||||||
The platform princes are rent extractors.
|
|
||||||
|
|
||||||
|
|
||||||
Open weights are heavy weight champions.
|
|
||||||
|
|
||||||
|
|
||||||
# The "how"
|
|
||||||
|
|
||||||
|
|
||||||
Because It's soooo easy.
|
|
||||||
deClawed is configurable, prompt purrr-fectable, LLM-driven mail and task automation for anyone that can cut n' paste a few CLI commands and can type in short declarative sentences.
|
|
||||||
More private than other options (not purrfect *yet* - but privacy is our number one goal with every release).
|
|
||||||
More accurate actions/results (read on).
|
|
||||||
|
|
||||||
|
|
||||||
# Privacy: more than the blue-plate crustacean
|
|
||||||
|
|
||||||
|
|
||||||
Your own local Model Context Protocol (MCP) server integrates with your preferred LLM API. Each step in the install, and setup offers greater control, and transparency. Permissions are 100% configurable.
|
|
||||||
|
|
||||||
|
|
||||||
Escape black-box installs stocked with more Trojans than an Olympic Village - silent/dark processes, data harvesting phone-homes, behavioral analytics, telemetry backdoors, corporate surveillance - the nasties lurking in the dark discoverable only by secops edgelords that are masters of the the CLI.
|
|
||||||
|
|
||||||
|
|
||||||
# Simplicity
|
|
||||||
|
|
||||||
|
|
||||||
### NLP prompts are **actually** easy and **demonstrably** more effective
|
|
||||||
|
|
||||||
|
|
||||||
Stop drilling down byzantine menus in mail, scheduling and workflow to configure filters and actions that 1. only ever work 20% of the time 2. change in functionality and scope every two months because a project manager needs to justify their salary.
|
|
||||||
|
|
||||||
|
|
||||||
Write short, declarative prompts instead. It's like wrapping busywork's paws in tinfoil and tossing it in a bathtub.
|
|
||||||
|
|
||||||
|
|
||||||
Prompts
|
|
||||||
|
|
||||||
|
|
||||||
1. Use semantic grouping, organizing by message intent, purpose, and context.
|
|
||||||
2. The prompt templates in Kitty's "built in" library are evaluated using, for example, cosine similarity, ROUGE scoring and real human eval in the SDLC dev loop.
|
|
||||||
3. For example: you'll consistently keep the treasure and trash the junk when you task deClawed with reviewing forums/feeds where actionable insights are gold, but only 10% of the signal.
|
|
||||||
|
|
||||||
|
|
||||||
### Prompting: easily configured to cron: cleaning the litter(in)box before the stank wafts through the whole work house.
|
|
||||||
### Imagine your morning inbox or summaries brimming with a fresh, spring-meadow aroma of opportunity and insight -- not last night's Kitty kibble.
|
|
||||||
|
|
||||||
|
|
||||||
# -- You just might feel like it' s freakin' 1998 again.
|
|
||||||
|
|
||||||
|
|
||||||
# Wiring up your kitty
|
|
||||||
|
|
||||||
|
|
||||||
Assisty-kitty easily interfaces with mail and calendar and other app APIs (about any other service you want to plug in) ... it keeps things moving so you can go chase laser pointers or enjoy a 19-hour nap in a sunbeam.
|
|
||||||
|
|
||||||
|
deClawed is an MCP server that connects email inbox to an LLM-capable client (such as Claude Desktop), within an orchestration harness: Agents have access to tools to classify incoming emails, automate routine actions (delete, archive, summarize). The framwork integrates with Google Mail, Sheets and Calendar to keep your high-volume email workflow organized and actionable.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
# Scope and Architecture
|
### Requirements
|
||||||
|
|
||||||
|
| Dependency | Version |
|
||||||
|
|------------|---------|
|
||||||
|
| Node.js | 16+ |
|
||||||
|
| npm | 8+ |
|
||||||
|
| Google Cloud Project | With Gmail API enabled |
|
||||||
|
| MCP Client | Claude Desktop (or any MCP-compatible client) |
|
||||||
|
|
||||||
## Current implementation requires building/using:
|
### Installation
|
||||||
-- Claude Desktop (as UI only - proprietary UI coming soonish)
|
|
||||||
-- Building/Connecting a Model API or Local Model Context Protocol Server
|
|
||||||
-- A DNS-config’d domain, with MX records pointing to:
|
|
||||||
-- A commercial or self-hosted SMTP Server
|
|
||||||
|
|
||||||
|
|
||||||
## Coming soonish:
|
|
||||||
-- Proprietary, custom UI.
|
|
||||||
-- Support for all stripes of models on HugginFFace.
|
|
||||||
- Support for local LLMs.
|
|
||||||
|
|
||||||
|
|
||||||
# Setup
|
|
||||||
|
|
||||||
|
|
||||||
### 1. Install Node.js (v16+ required).
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
node --version
|
|
||||||
npm --version
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
If not installed, grab it from [nodejs.org](https://nodejs.org/).
|
|
||||||
|
|
||||||
|
|
||||||
### 2. Clone and Install
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://git.sjdev.online/kjannette/deClawed-Assity-Kitty
|
git clone https://git.sjdev.online/kjannette/deClawed-Assity-Kitty
|
||||||
cd deClawed-Assity-Kitty
|
cd deClawed-Assity-Kitty
|
||||||
npm i
|
npm install
|
||||||
```
|
|
||||||
### 3. Set Up Google Cloud Credentials
|
|
||||||
|
|
||||||
|
|
||||||
#### 3a. Create a Google Cloud Project
|
|
||||||
|
|
||||||
|
|
||||||
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
||||||
2. Sign in with the Google account that owns the target Gmail
|
|
||||||
3. Click the project dropdown (top-left) > **New Project**
|
|
||||||
4. Name it (e.g., `assistant-mcp`) and click **Create**
|
|
||||||
5. Select the new project from the dropdown
|
|
||||||
|
|
||||||
|
|
||||||
#### 3b. Enable APIs
|
|
||||||
|
|
||||||
|
|
||||||
In **APIs & Services > Library**, enable:
|
|
||||||
- **Gmail API**
|
|
||||||
- **Google Sheets API** (if mapping mail to sheets)
|
|
||||||
- **Google Calendar API** (if using calendar event creation, etc.s)
|
|
||||||
|
|
||||||
|
|
||||||
#### 3c. Configure the OAuth Consent Screen
|
|
||||||
|
|
||||||
|
|
||||||
1. Go to **Google Auth Platform > Branding** (or **APIs & Services > OAuth consent screen**)
|
|
||||||
2. Set user type to **External**, click **Create**
|
|
||||||
3. Fill in app name, support email, and developer contact email
|
|
||||||
4. Save and continue
|
|
||||||
|
|
||||||
|
|
||||||
#### 3d. Add OAuth Scopes
|
|
||||||
|
|
||||||
|
|
||||||
In **Google Auth Platform > Data Access**, add:
|
|
||||||
- `https://www.googleapis.com/auth/gmail.modify`
|
|
||||||
- `https://www.googleapis.com/auth/spreadsheets` (for Sheets integration)
|
|
||||||
- `https://www.googleapis.com/auth/calendar.events` (for Calendar integration)
|
|
||||||
|
|
||||||
|
|
||||||
#### 3e. Add Yourself as a Test User
|
|
||||||
|
|
||||||
|
|
||||||
Go to **Google Auth Platform > Audience** and add each Gmail address you'll use.
|
|
||||||
|
|
||||||
|
|
||||||
#### 3f. Create OAuth Client Credentials
|
|
||||||
|
|
||||||
|
|
||||||
1. Go to **Google Auth Platform > Clients** (or **APIs & Services > Credentials**)
|
|
||||||
2. Click **Create Client** > Application type: **Desktop app**
|
|
||||||
3. **Download the JSON**, rename it to `credentials.json`
|
|
||||||
4. Place it in the project root
|
|
||||||
|
|
||||||
|
|
||||||
### 4. Configure Accounts
|
|
||||||
|
|
||||||
|
|
||||||
Create file `accounts.json` in the project root. Each key is an account alias with its own token file and optional Sheets/Calendar config:
|
|
||||||
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"work": {
|
|
||||||
"label": "you@yourdomain.com",
|
|
||||||
"tokenFile": "token.json",
|
|
||||||
"spreadsheetId": "YOUR_GOOGLE_SHEET_ID",
|
|
||||||
"calendarId": "primary"
|
|
||||||
},
|
|
||||||
"secondary": {
|
|
||||||
"label": "you@gmail.com",
|
|
||||||
"tokenFile": "token-secondary.json"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
- **`label`** -- display name (typically the email address)
|
|
||||||
- **`tokenFile`** -- per-account OAuth token (auto-generated during auth)
|
|
||||||
- **`spreadsheetId`** -- Google Sheets ID for recruiter contact logging (optional)
|
|
||||||
- **`calendarId`** -- Google Calendar ID for event creation (optional, `"primary"` uses the default calendar)
|
|
||||||
|
|
||||||
|
|
||||||
### 5. Authorize Gmail Accounts
|
|
||||||
|
|
||||||
|
|
||||||
Build and run the auth script for each account:
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run auth # authorizes the "work" account
|
|
||||||
npm run auth -- secondary # authorizes the "secondary" account
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
Each run required steps:
|
|
||||||
|
|
||||||
|
|
||||||
1. Print a URL -- open it in your browser
|
|
||||||
2. Sign in and click **Allow**
|
|
||||||
3. You'll land on a "localhost refused to connect" page (normal)
|
|
||||||
4. Copy the **entire URL** from the address bar and paste it back into the terminal
|
|
||||||
5. The script saves the token file (e.g., `token.json` or `token-secondary.json`)
|
|
||||||
|
|
||||||
|
|
||||||
You only need to do this once per account. Tokens auto-refresh.
|
|
||||||
|
|
||||||
|
|
||||||
### 6. Write the Prompts
|
|
||||||
|
|
||||||
|
|
||||||
Two plain-text prompt files in `src/prompts/` control the workflow:
|
|
||||||
|
|
||||||
|
|
||||||
| File | Phase | Purpose |
|
|
||||||
|------|-------|---------|
|
|
||||||
| `src/prompts/classify-emails.txt` | 1 -- Classification | Defines categories A/B/C/D and how to sort emails |
|
|
||||||
| `src/prompts/take-action-on-emails.txt` | 2 -- Action | Tell the LLM what to do with each category (delete, log, schedule, etc.) |
|
|
||||||
|
|
||||||
|
|
||||||
**Tips:**
|
|
||||||
|
|
||||||
|
|
||||||
- Use clear, explicit category definitions with example language
|
|
||||||
- Handle ambiguous cases (e.g., "If an email both acknowledges receipt AND requests action, classify as B")
|
|
||||||
- Prompt files are loaded at runtime -- edit them anytime, no rebuild required
|
|
||||||
|
|
||||||
|
|
||||||
### 7. Build
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run build
|
npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Google Cloud Setup
|
||||||
|
|
||||||
Compiles `src/**/*.ts` into `build/`.
|
1. Create a project at [Google Cloud Console](https://console.cloud.google.com/)
|
||||||
|
2. Enable the **Gmail API** (and optionally **Sheets API** and **Calendar API**)
|
||||||
|
3. Configure OAuth consent screen (External, add your email as a test user)
|
||||||
|
4. Create OAuth credentials (Desktop app) and download `credentials.json`
|
||||||
|
5. Place `credentials.json` in the `accountsAndCredentials/` directory
|
||||||
|
|
||||||
|
### Account Configuration
|
||||||
|
|
||||||
## 8. Configure Claude Desktop
|
Create `accountsAndCredentials/accounts.json`:
|
||||||
|
|
||||||
|
|
||||||
Edit your Claude Desktop config:
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
Add the server:
|
|
||||||
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"work": {
|
||||||
"assistant": {
|
"label": "you@example.com",
|
||||||
"command": "/ABSOLUTE/PATH/TO/node",
|
"tokenFile": "token.json",
|
||||||
"args": [
|
"spreadsheetId": "YOUR_GOOGLE_SHEET_ID",
|
||||||
"/ABSOLUTE/PATH/TO/deClawed-Assity-Kitty/build/index.js"
|
"calendarId": "primary"
|
||||||
]
|
}
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Authorize Gmail Access
|
||||||
Replace paths with the output of `which node` and your actual project location.
|
|
||||||
|
|
||||||
|
|
||||||
## 9. Add/Configure API Keys, Credentials, and Other Secrets
|
|
||||||
|
|
||||||
|
|
||||||
Secret files are **gitignored** -- they never leave your machine. Example templates are provided so you know what shape each file needs to be in.
|
|
||||||
|
|
||||||
|
|
||||||
#### 9a. `credentials.json`
|
|
||||||
|
|
||||||
|
|
||||||
This file holds your Google OAuth client credentials. **You do not write this by hand** -- it is downloaded from the Google Cloud Console (see Step 3f above). Copy the example and then replace it with the real download:
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cp credentials.example.json credentials.json
|
npm run auth # Authorize default account
|
||||||
# Now replace credentials.json with the file downloaded from Google Cloud Console.
|
npm run auth -- secondary # Authorize additional accounts
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Follow the browser prompts to complete OAuth. Tokens are saved locally and auto-refresh.
|
||||||
|
|
||||||
The structure looks like this (the example file ships with empty values):
|
### Connect to Claude Desktop
|
||||||
|
|
||||||
|
Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"installed": {
|
"mcpServers": {
|
||||||
"client_id": "",
|
"assistant": {
|
||||||
"project_id": "",
|
"command": "/path/to/node",
|
||||||
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
|
"args": ["/path/to/deClawed-Assity-Kitty/build/index.js"]
|
||||||
"token_uri": "https://oauth2.googleapis.com/token",
|
}
|
||||||
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
|
}
|
||||||
"client_secret": "",
|
|
||||||
"redirect_uris": ["http://localhost"]
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Restart Claude Desktop. The server appears under **Connectors**.
|
||||||
#### 9b. `accounts.json`
|
|
||||||
|
|
||||||
|
|
||||||
Defines each Gmail account the server manages. Copy the example and fill in your values:
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp accounts.example.json accounts.json
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
| Field | What to put here |
|
|
||||||
|-------|-----------------|
|
|
||||||
| `label` | The email address for this account (display only) |
|
|
||||||
| `tokenFile` | Filename for this account's OAuth token (e.g., `token.json`) |
|
|
||||||
| `spreadsheetId` | The ID from your Google Sheet URL: `docs.google.com/spreadsheets/d/<THIS_PART>/edit` (optional) |
|
|
||||||
| `calendarId` | `"primary"` for your default calendar, or a specific calendar ID (optional) |
|
|
||||||
|
|
||||||
|
|
||||||
Add as many accounts as you need. Each key (e.g., `"work"`, `"secondary"`) becomes the account name used in tool calls and auth commands.
|
|
||||||
|
|
||||||
|
|
||||||
#### 9c. `token*.json` (auto-generated)
|
|
||||||
|
|
||||||
|
|
||||||
Token files are **created automatically** when you run `npm run auth` (Step 5). You do not need to create or edit them manually. A `token.example.json` is provided for reference only -- it shows the structure but the values are populated by the OAuth flow.
|
|
||||||
|
|
||||||
|
|
||||||
#### Summary of secret files
|
|
||||||
|
|
||||||
|
|
||||||
| Example template | Actual file (gitignored) | How to create |
|
|
||||||
|-----------------|--------------------------|---------------|
|
|
||||||
| `credentials.example.json` | `credentials.json` | Download from Google Cloud Console |
|
|
||||||
| `accounts.example.json` | `accounts.json` | Copy example, fill in your email/sheet/calendar IDs |
|
|
||||||
| `token.example.json` | `token.json`, `token-secondary.json`, etc. | Auto-generated by `npm run auth` |
|
|
||||||
|
|
||||||
|
|
||||||
### 10. Restart Claude Desktop
|
|
||||||
|
|
||||||
|
|
||||||
Fully quit (**Cmd+Q**, not just close the window) and reopen. The `assistant` server should appear under **Connectors**.
|
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
## MCP Tools
|
### Basic Workflow
|
||||||
|
|
||||||
|
In Claude Desktop, invoke the email review workflow:
|
||||||
|
|
||||||
|
```
|
||||||
|
Review my inbox
|
||||||
|
```
|
||||||
|
|
||||||
|
The server fetches unread emails, classifies them using your configured prompts, and executes the appropriate actions.
|
||||||
|
|
||||||
|
### Classification Categories
|
||||||
|
|
||||||
|
| Category | Description | Default Action |
|
||||||
|
|----------|-------------|----------------|
|
||||||
|
| **A** | Acknowledgements, auto-replies | Delete |
|
||||||
|
| **B** | Advancement (interview requests, next steps) | Log + Calendar event |
|
||||||
|
| **C** | Rejections | Delete |
|
||||||
|
| **D** | Other/uncategorized | Log for review |
|
||||||
|
|
||||||
|
### Customizing Prompts
|
||||||
|
|
||||||
|
Edit the plain-text files in `src/prompts/` to adjust classification rules and actions:
|
||||||
|
|
||||||
|
- `classify-emails.txt` — Defines category criteria
|
||||||
|
- `take-action-on-emails.txt` — Specifies actions per category
|
||||||
|
|
||||||
|
Changes take effect immediately without rebuilding.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP Tools Reference
|
||||||
|
|
||||||
| Tool | Description |
|
| Tool | Description |
|
||||||
|------|-------------|
|
|------|-------------|
|
||||||
| `fetch_new_emails` | Fetches unread emails for a given account. Classification and action prompts are automatically appended to the response. |
|
| `fetch_new_emails` | Fetch unread emails with classification instructions appended |
|
||||||
| `delete_emails` | Moves emails to trash by Gmail message ID. Used for categories A (acknowledgements/junk/”THANKS!”/offers) and C (rejections). |
|
| `delete_emails` | Move specified message IDs to trash |
|
||||||
| `append_to_summary` | Logs classified emails to per-account summary files in `mailSummaries/`. Entries older than 30 days are auto-purged. |
|
| `star_emails` | Star messages and mark as read |
|
||||||
| `log_contact` | Logs or updates contact info in a Google Sheet. Merges rows by email + role. |
|
| `append_to_summary` | Log email metadata to local JSON (auto-purges after 30 days) |
|
||||||
| `create_calendar_event` | Creates a Google Calendar event for scheduled calls/meetings. Includes meeting links, attendees and their contact info. |
|
| `log_recruiter_contact` | Append or update a row in Google Sheets |
|
||||||
|
| `create_calendar_event` | Create a Google Calendar event (skips past dates) |
|
||||||
|
|
||||||
|
### Example: Fetch Emails
|
||||||
|
|
||||||
## MCP Prompts (built in as of now-ish - add your own)
|
```
|
||||||
### BETTER YET - DO A PR OR FORK
|
fetch_new_emails(account: "work", maxResults: 50)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: Create Calendar Event
|
||||||
|
|
||||||
| Prompt | Account | Description |
|
```
|
||||||
|--------|---------|-------------|
|
create_calendar_event(
|
||||||
| `review_emails` | work | Loads the classification + action prompts for the work inbox |
|
account: "work",
|
||||||
| `review_secondary_emails` | secondary | Same workflow, but for a second email account inbox |
|
title: "[Interview] Acme Corp - Senior Engineer",
|
||||||
|
startDateTime: "2026-09-01T14:00:00-04:00",
|
||||||
|
durationMinutes: 60,
|
||||||
Invoke these from Claude Desktop's Connectors menu, or just type "Review my inbox" / "Review my secondary inbox."
|
location: "https://zoom.us/j/123456789"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## CLI Commands
|
||||||
## Two-Phase Workflow
|
|
||||||
|
|
||||||
|
|
||||||
**Phase 1 -- Classify**
|
|
||||||
|
|
||||||
|
|
||||||
The LLM calls `fetch_new_emails`, which returns email data with the classification instructions from `classify-emails.txt` appended. Each email is sorted into:
|
|
||||||
|
|
||||||
|
|
||||||
| Category | Meaning | Action |
|
|
||||||
|----------|---------|--------|
|
|
||||||
| **A** | Acknowledgement / auto-reply | Delete |
|
|
||||||
| **B** | Advancement to next step | Summarize + log |
|
|
||||||
| **C** | Rejection | Delete |
|
|
||||||
| **D** | Other / uncategorized | Summarize + log |
|
|
||||||
|
|
||||||
|
|
||||||
**Phase 2 -- Act**
|
|
||||||
|
|
||||||
|
|
||||||
Using `take-action-on-emails.txt`, the LLM:
|
|
||||||
- Calls `delete_emails` for A + C
|
|
||||||
- Calls `append_to_summary` for B + D
|
|
||||||
- Calls `log_recruiter_contact` to track contacts in Sheets (if configured)
|
|
||||||
- Calls `create_calendar_event` for any scheduled interviews/calls (if configured)
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
## Key Commands
|
|
||||||
|
|
||||||
|
|
||||||
| Command | Purpose |
|
| Command | Purpose |
|
||||||
|---------|---------|
|
|---------|---------|
|
||||||
| `npm run build` | Recompile after editing source files |
|
| `npm run build` | Compile TypeScript to `build/` |
|
||||||
| `npm run auth` | Authorize the default (work) account |
|
| `npm run auth` | Authorize the default account |
|
||||||
| `npm run auth -- secondary` | Authorize the secondary account |
|
| `npm run auth -- <name>` | Authorize a named account |
|
||||||
| `npm test` | Run the test suite |
|
| `npm test` | Run test suite |
|
||||||
| `npm run test:watch` | Run tests in watch mode |
|
| `npm run test:watch` | Run tests in watch mode |
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
|
|
||||||
```
|
```
|
||||||
deClawed-Assity-Kitty/
|
deClawed-Assity-Kitty/
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── index.ts # Entry point -- imports modules, starts server
|
│ ├── index.ts # Entry point
|
||||||
│ ├── McpServer.ts # MCP server instance
|
│ ├── McpServer.ts # MCP server instance
|
||||||
│ ├── auth.ts # Multi-account OAuth setup script
|
│ ├── auth.ts # OAuth setup script
|
||||||
│ ├── loaders/
|
│ ├── loaders/ # Config and prompt loaders
|
||||||
│ │ └── prompt-config-loaders.ts # Account, prompt, and OAuth client loaders
|
│ ├── prompts/ # Classification and action prompts
|
||||||
│ ├── prompt-controller-service/
|
│ └── tools/ # MCP tool implementations
|
||||||
│ │ └── prompt-controller-service.ts # MCP prompt registration
|
├── accountsAndCredentials/ # OAuth credentials and tokens (gitignored)
|
||||||
│ ├── prompts/
|
├── mailSummaries/ # Local email logs (gitignored)
|
||||||
│ │ ├── classify-emails.txt # Phase 1: classification instructions
|
├── test/ # Unit and integration tests
|
||||||
│ │ └── take-action-on-emails.txt # Phase 2: action instructions
|
└── build/ # Compiled output
|
||||||
│ └── tools/
|
```
|
||||||
│ ├── tools-email.ts # fetch, delete, append_to_summary
|
|
||||||
│ ├── tools-calendar.ts # create_calendar_event
|
---
|
||||||
│ └── tools-spreadsheet.ts # log_recruiter_contact
|
|
||||||
├── accountsAndCredentials/
|
## Security
|
||||||
│ ├── accounts.json # Multi-account configuration (gitignored)
|
|
||||||
│ ├── accounts.example.json # Template for accounts.json
|
- All credentials and tokens are stored locally and excluded from version control
|
||||||
│ ├── credentials.json # Google OAuth client credentials (gitignored)
|
- OAuth tokens auto-refresh; re-authorization is only needed if revoked
|
||||||
│ ├── credentials.example.json # Template for credentials.json
|
- The server runs locally via stdio—no network exposure
|
||||||
│ ├── token.json # OAuth token -- work account (gitignored, auto-generated)
|
|
||||||
│ ├── token-secondary.json # OAuth token -- secondary account (gitignored, auto-generated)
|
---
|
||||||
│ └── token.example.json # Template showing token structure
|
|
||||||
├── test/
|
## License
|
||||||
│ ├── fixtures/
|
|
||||||
│ │ └── mock-emails.ts # Mock Gmail API responses
|
ISC
|
||||||
│ ├── integration/
|
|
||||||
│ │ └── email-workflow.test.ts # Integration tests
|
|
||||||
│ └── unit/
|
|
||||||
│ └── email-parsing.test.ts # Unit tests for parsing helpers
|
|
||||||
├── mailSummaries/ # Per-account summary output (gitignored, auto-generated)
|
|
||||||
├── build/ # Compiled JS (auto-generated)
|
|
||||||
├── assets/
|
|
||||||
│ └── logo.png # Project logo
|
|
||||||
├── package.json
|
|
||||||
├── tsconfig.json
|
|
||||||
├── vitest.config.ts
|
|
||||||
├── .gitignore
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|||||||
10
package-lock.json
generated
10
package-lock.json
generated
@@ -9,7 +9,7 @@
|
|||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"license": "ISC",
|
"license": "ISC",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@modelcontextprotocol/sdk": "^1.26.0",
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
||||||
"googleapis": "^171.4.0",
|
"googleapis": "^171.4.0",
|
||||||
"zod": "^3.25.76"
|
"zod": "^3.25.76"
|
||||||
},
|
},
|
||||||
@@ -501,12 +501,12 @@
|
|||||||
"license": "MIT"
|
"license": "MIT"
|
||||||
},
|
},
|
||||||
"node_modules/@modelcontextprotocol/sdk": {
|
"node_modules/@modelcontextprotocol/sdk": {
|
||||||
"version": "1.26.0",
|
"version": "1.30.0",
|
||||||
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.26.0.tgz",
|
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.30.0.tgz",
|
||||||
"integrity": "sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==",
|
"integrity": "sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@hono/node-server": "^1.19.9",
|
"@hono/node-server": "^1.19.9 || ^2.0.5",
|
||||||
"ajv": "^8.17.1",
|
"ajv": "^8.17.1",
|
||||||
"ajv-formats": "^3.0.1",
|
"ajv-formats": "^3.0.1",
|
||||||
"content-type": "^1.0.5",
|
"content-type": "^1.0.5",
|
||||||
|
|||||||
@@ -19,7 +19,7 @@
|
|||||||
"author": "",
|
"author": "",
|
||||||
"license": "ISC",
|
"license": "ISC",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@modelcontextprotocol/sdk": "^1.26.0",
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
||||||
"googleapis": "^171.4.0",
|
"googleapis": "^171.4.0",
|
||||||
"zod": "^3.25.76"
|
"zod": "^3.25.76"
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -3,11 +3,13 @@ import { google, gmail_v1, sheets_v4, calendar_v3 } from "googleapis";
|
|||||||
import { OAuth2Client } from "google-auth-library";
|
import { OAuth2Client } from "google-auth-library";
|
||||||
import fs from "fs";
|
import fs from "fs";
|
||||||
import path from "path";
|
import path from "path";
|
||||||
|
import { fileURLToPath } from "url";
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Paths
|
// Paths
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
const __dirname = path.dirname(new URL(import.meta.url).pathname);
|
const __filename = fileURLToPath(import.meta.url);
|
||||||
|
const __dirname = path.dirname(__filename);
|
||||||
|
|
||||||
export const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
|
export const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
|
||||||
const SECRETS_DIR = path.join(PROJECT_ROOT, "accountsAndCredentials");
|
const SECRETS_DIR = path.join(PROJECT_ROOT, "accountsAndCredentials");
|
||||||
const CREDENTIALS_PATH = path.join(SECRETS_DIR, "credentials.json");
|
const CREDENTIALS_PATH = path.join(SECRETS_DIR, "credentials.json");
|
||||||
@@ -20,130 +22,130 @@ const ACTION_PROMPT_PATH = path.join(PROMPTS_DIR, "take-action-on-emails.txt");
|
|||||||
// Account configuration
|
// Account configuration
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
export interface AccountConfig {
|
export interface AccountConfig {
|
||||||
label: string;
|
label: string;
|
||||||
tokenFile: string;
|
tokenFile: string;
|
||||||
spreadsheetId?: string;
|
spreadsheetId?: string;
|
||||||
calendarId?: string;
|
calendarId?: string;
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface AccountsMap {
|
export interface AccountsMap {
|
||||||
[key: string]: AccountConfig;
|
[key: string]: AccountConfig;
|
||||||
}
|
}
|
||||||
|
|
||||||
export const loadAccounts = (): AccountsMap => {
|
export const loadAccounts = (): AccountsMap => {
|
||||||
if (!fs.existsSync(ACCOUNTS_PATH)) {
|
if (!fs.existsSync(ACCOUNTS_PATH)) {
|
||||||
throw new Error(`Missing accounts.json at ${ACCOUNTS_PATH}.`);
|
throw new Error(`Missing accounts.json at ${ACCOUNTS_PATH}.`);
|
||||||
}
|
}
|
||||||
return JSON.parse(fs.readFileSync(ACCOUNTS_PATH, "utf-8"));
|
return JSON.parse(fs.readFileSync(ACCOUNTS_PATH, "utf-8"));
|
||||||
};
|
};
|
||||||
|
|
||||||
export const getTokenPath = (account: string): string => {
|
export const getTokenPath = (account: string): string => {
|
||||||
const accts = loadAccounts();
|
const accts = loadAccounts();
|
||||||
const acct = accts[account];
|
const acct = accts[account];
|
||||||
if (!acct) {
|
if (!acct) {
|
||||||
const available = Object.keys(accts).join(", ");
|
const available = Object.keys(accts).join(", ");
|
||||||
throw new Error(
|
throw new Error(
|
||||||
`Unknown account "${account}". Available accounts: ${available}`
|
`Unknown account "${account}". Available accounts: ${available}`
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
return path.join(SECRETS_DIR, acct.tokenFile);
|
return path.join(SECRETS_DIR, acct.tokenFile);
|
||||||
};
|
};
|
||||||
|
|
||||||
export const getSummaryPath = (account: string): string => {
|
export const getSummaryPath = (account: string): string => {
|
||||||
if (account === "work") {
|
if (account === "work") {
|
||||||
return path.join(PROJECT_ROOT, "mailSummaries", "summary.json");
|
return path.join(PROJECT_ROOT, "mailSummaries", "summary.json");
|
||||||
}
|
}
|
||||||
return path.join(PROJECT_ROOT, "mailSummaries", `summary-${account}.json`);
|
return path.join(PROJECT_ROOT, "mailSummaries", `summary-${account}.json`);
|
||||||
};
|
};
|
||||||
|
|
||||||
export const VALID_ACCOUNTS = ["work", "secondary"] as const;
|
export const VALID_ACCOUNTS = ["work", "secondary"] as const;
|
||||||
export const accounts = loadAccounts();
|
export const accounts = loadAccounts();
|
||||||
|
|
||||||
const accountDescription = VALID_ACCOUNTS
|
const accountDescription = VALID_ACCOUNTS
|
||||||
.map((key) => `"${key}" (${accounts[key]?.label ?? key})`)
|
.map((key) => `"${key}" (${accounts[key]?.label ?? key})`)
|
||||||
.join(" or ");
|
.join(" or ");
|
||||||
|
|
||||||
export const accountSchema = z
|
export const accountSchema = z
|
||||||
.enum(VALID_ACCOUNTS)
|
.enum(VALID_ACCOUNTS)
|
||||||
.describe(`Which email account to use: ${accountDescription}`);
|
.describe(`Which email account to use: ${accountDescription}`);
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Prompt loaders
|
// Prompt loaders
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
const loadPromptFile = (filePath: string, label: string): string => {
|
const loadPromptFile = (filePath: string, label: string): string => {
|
||||||
if (!fs.existsSync(filePath)) {
|
if (!fs.existsSync(filePath)) {
|
||||||
console.error(`Warning: ${filePath} not found. ${label} will be missing.`);
|
console.error(`Warning: ${filePath} not found. ${label} will be missing.`);
|
||||||
return "";
|
return "";
|
||||||
}
|
}
|
||||||
return fs.readFileSync(filePath, "utf-8");
|
return fs.readFileSync(filePath, "utf-8");
|
||||||
};
|
};
|
||||||
|
|
||||||
export const loadClassificationPrompt = (): string =>
|
export const loadClassificationPrompt = (): string =>
|
||||||
loadPromptFile(CLASSIFY_PROMPT_PATH, "Classification instructions");
|
loadPromptFile(CLASSIFY_PROMPT_PATH, "Classification instructions");
|
||||||
|
|
||||||
export const loadActionPrompt = (): string =>
|
export const loadActionPrompt = (): string =>
|
||||||
loadPromptFile(ACTION_PROMPT_PATH, "Action instructions");
|
loadPromptFile(ACTION_PROMPT_PATH, "Action instructions");
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Auth helpers — generic OAuth2 client, then service-specific factories
|
// Auth helpers — generic OAuth2 client, then service-specific factories
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
export const getOAuth2Client = (account: string): OAuth2Client => {
|
export const getOAuth2Client = (account: string): OAuth2Client => {
|
||||||
const tokenPath = getTokenPath(account);
|
const tokenPath = getTokenPath(account);
|
||||||
|
|
||||||
if (!fs.existsSync(CREDENTIALS_PATH)) {
|
if (!fs.existsSync(CREDENTIALS_PATH)) {
|
||||||
throw new Error(
|
throw new Error(
|
||||||
`Missing credentials.json at ${CREDENTIALS_PATH}. Run "npm run auth" first.`
|
`Missing credentials.json at ${CREDENTIALS_PATH}. Run "npm run auth" first.`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (!fs.existsSync(tokenPath)) {
|
||||||
|
throw new Error(
|
||||||
|
`Missing token file at ${tokenPath} for account "${account}". Run "npm run auth" first.`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf-8"));
|
||||||
|
const { client_id, client_secret, redirect_uris } =
|
||||||
|
credentials.installed || credentials.web;
|
||||||
|
|
||||||
|
const oAuth2Client = new google.auth.OAuth2(
|
||||||
|
client_id,
|
||||||
|
client_secret,
|
||||||
|
redirect_uris[0]
|
||||||
);
|
);
|
||||||
}
|
|
||||||
if (!fs.existsSync(tokenPath)) {
|
|
||||||
throw new Error(
|
|
||||||
`Missing token file at ${tokenPath} for account "${account}". Run "npm run auth" first.`
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf-8"));
|
const token = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
|
||||||
const { client_id, client_secret, redirect_uris } =
|
oAuth2Client.setCredentials(token);
|
||||||
credentials.installed || credentials.web;
|
|
||||||
|
|
||||||
const oAuth2Client = new google.auth.OAuth2(
|
oAuth2Client.on("tokens", (newTokens) => {
|
||||||
client_id,
|
const current = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
|
||||||
client_secret,
|
fs.writeFileSync(
|
||||||
redirect_uris[0]
|
tokenPath,
|
||||||
);
|
JSON.stringify({ ...current, ...newTokens }, null, 2)
|
||||||
|
);
|
||||||
|
console.error(`Token refreshed and saved for account "${account}".`);
|
||||||
|
});
|
||||||
|
|
||||||
const token = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
|
return oAuth2Client;
|
||||||
oAuth2Client.setCredentials(token);
|
|
||||||
|
|
||||||
oAuth2Client.on("tokens", (newTokens) => {
|
|
||||||
const current = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
|
|
||||||
fs.writeFileSync(
|
|
||||||
tokenPath,
|
|
||||||
JSON.stringify({ ...current, ...newTokens }, null, 2)
|
|
||||||
);
|
|
||||||
console.error(`Token refreshed and saved for account "${account}".`);
|
|
||||||
});
|
|
||||||
|
|
||||||
return oAuth2Client;
|
|
||||||
};
|
};
|
||||||
|
|
||||||
export const getGmailClient = (account: string): gmail_v1.Gmail =>
|
export const getGmailClient = (account: string): gmail_v1.Gmail =>
|
||||||
google.gmail({ version: "v1", auth: getOAuth2Client(account) });
|
google.gmail({ version: "v1", auth: getOAuth2Client(account) });
|
||||||
|
|
||||||
export const getSheetsClient = (account: string): sheets_v4.Sheets =>
|
export const getSheetsClient = (account: string): sheets_v4.Sheets =>
|
||||||
google.sheets({ version: "v4", auth: getOAuth2Client(account) });
|
google.sheets({ version: "v4", auth: getOAuth2Client(account) });
|
||||||
|
|
||||||
export const getCalendarClient = (account: string): calendar_v3.Calendar =>
|
export const getCalendarClient = (account: string): calendar_v3.Calendar =>
|
||||||
google.calendar({ version: "v3", auth: getOAuth2Client(account) });
|
google.calendar({ version: "v3", auth: getOAuth2Client(account) });
|
||||||
|
|
||||||
export const getSpreadsheetId = (account: string): string => {
|
export const getSpreadsheetId = (account: string): string => {
|
||||||
const acct = accounts[account];
|
const acct = accounts[account];
|
||||||
if (!acct?.spreadsheetId || acct.spreadsheetId === "PASTE_YOUR_SHEET_ID_HERE") {
|
if (!acct?.spreadsheetId || acct.spreadsheetId === "PASTE_YOUR_SHEET_ID_HERE") {
|
||||||
throw new Error(
|
throw new Error(
|
||||||
`No spreadsheetId configured for account "${account}" in accounts.json.`
|
`No spreadsheetId configured for account "${account}" in accounts.json.`
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
return acct.spreadsheetId;
|
return acct.spreadsheetId;
|
||||||
};
|
};
|
||||||
|
|
||||||
export const getCalendarId = (account: string): string =>
|
export const getCalendarId = (account: string): string =>
|
||||||
accounts[account]?.calendarId ?? "primary";
|
accounts[account]?.calendarId ?? "primary";
|
||||||
|
|||||||
@@ -1,64 +1,56 @@
|
|||||||
import { server } from "../McpServer.js";
|
import { server } from "../McpServer.js";
|
||||||
import {
|
import {
|
||||||
accounts,
|
accounts,
|
||||||
loadClassificationPrompt,
|
loadClassificationPrompt,
|
||||||
loadActionPrompt,
|
loadActionPrompt,
|
||||||
} from "../loaders/prompt-config-loaders.js";
|
} from "../loaders/prompt-config-loaders.js";
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Prompt: review_emails (work account)
|
// Prompt: Classify Emails (Phase 1)
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
server.registerPrompt(
|
server.registerPrompt(
|
||||||
"review_emails",
|
"classify-emails",
|
||||||
{
|
{
|
||||||
description:
|
description: "Phase 1: Organize, prioritize, and summarize incoming recruiter emails.",
|
||||||
`Review WORK inbox (${accounts.work?.label ?? "work"}): classify emails, delete A+C, summarize B+D, log B to spreadsheet, create calendar events.`,
|
},
|
||||||
},
|
() => {
|
||||||
() => {
|
const phase1 = loadClassificationPrompt();
|
||||||
const phase1 = loadClassificationPrompt();
|
return {
|
||||||
const phase2 = loadActionPrompt();
|
messages: [
|
||||||
return {
|
{
|
||||||
messages: [
|
role: "user" as const,
|
||||||
{
|
content: {
|
||||||
role: "user" as const,
|
type: "text" as const,
|
||||||
content: {
|
text: `ACCOUNT: Use account = "work" for ALL tool calls in this session.\n\n` +
|
||||||
type: "text" as const,
|
(phase1 || "Review my new emails and classify them by job application category.")
|
||||||
text:
|
},
|
||||||
`ACCOUNT: Use account = "work" for ALL tool calls in this session.\n\n` +
|
},
|
||||||
(phase1 || "Review my new emails and classify them by job application category.") +
|
],
|
||||||
(phase2 ? `\n\n${phase2}` : ""),
|
};
|
||||||
},
|
}
|
||||||
},
|
|
||||||
],
|
|
||||||
};
|
|
||||||
}
|
|
||||||
);
|
);
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Prompt: review_secondary_emails (secondary account)
|
// Prompt: Take Action on Emails (Phase 2)
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
server.registerPrompt(
|
server.registerPrompt(
|
||||||
"review_secondary_emails",
|
"take-action-on-emails",
|
||||||
{
|
{
|
||||||
description:
|
description: "Phase 2: Log Category B recruiters to spreadsheet and create calendar events.",
|
||||||
`Review SECONDARY inbox (${accounts.secondary?.label ?? "secondary"}): classify emails, delete A+C, summarize B+D, log B to spreadsheet, create calendar events.`,
|
},
|
||||||
},
|
() => {
|
||||||
() => {
|
const phase2 = loadActionPrompt();
|
||||||
const phase1 = loadClassificationPrompt();
|
return {
|
||||||
const phase2 = loadActionPrompt();
|
messages: [
|
||||||
return {
|
{
|
||||||
messages: [
|
role: "user" as const,
|
||||||
{
|
content: {
|
||||||
role: "user" as const,
|
type: "text" as const,
|
||||||
content: {
|
text: `ACCOUNT: Use account = "work" for ALL tool calls in this session.\n\n` +
|
||||||
type: "text" as const,
|
(phase2 || "Process remaining action items for flagged recruiters.")
|
||||||
text:
|
},
|
||||||
`ACCOUNT: Use account = "secondary" for ALL tool calls in this session.\n\n` +
|
},
|
||||||
(phase1 || "Review my new emails and classify them by job application category.") +
|
],
|
||||||
(phase2 ? `\n\n${phase2}` : ""),
|
};
|
||||||
},
|
}
|
||||||
},
|
|
||||||
],
|
|
||||||
};
|
|
||||||
}
|
|
||||||
);
|
);
|
||||||
|
|||||||
107
src/prompts/classify-emails-general.txt
Normal file
107
src/prompts/classify-emails-general.txt
Normal file
@@ -0,0 +1,107 @@
|
|||||||
|
You are an expert Executive Assistant AI specialized in email management. Your goal is to organize, prioritize, and triage incoming emails to maximize productivity and ensure nothing important is missed.
|
||||||
|
|
||||||
|
Review the inbox emails provided. Apply the following instructions.
|
||||||
|
|
||||||
|
STEP 1: CONSTRAINTS
|
||||||
|
- NEVER fabricate information. If data is not explicitly present in an email, it does not exist.
|
||||||
|
- When classification is ambiguous, err on the side of higher priority (e.g., classify as Action Required rather than Informational).
|
||||||
|
|
||||||
|
STEP 2: CLASSIFY each email into exactly one category.
|
||||||
|
|
||||||
|
Category A - Action Required
|
||||||
|
Emails that require a response, decision, or task completion from the user. Indicators include:
|
||||||
|
1. Direct questions addressed to the user
|
||||||
|
2. Requests for information, documents, or approvals
|
||||||
|
3. Meeting invitations or scheduling requests
|
||||||
|
4. Deadlines or time-sensitive requests
|
||||||
|
5. Follow-ups on prior conversations that need a reply
|
||||||
|
6. Emails from humans (not automation) explicitly asking for something
|
||||||
|
|
||||||
|
This category does NOT include:
|
||||||
|
- Automated notifications that require only a click (e.g., "verify your email," "reset password")
|
||||||
|
- Subscription confirmations or account alerts
|
||||||
|
|
||||||
|
Category B - Informational
|
||||||
|
Emails that provide useful information but require no immediate action. Examples:
|
||||||
|
1. Project updates or status reports
|
||||||
|
2. FYI messages or CC'd correspondence
|
||||||
|
3. Newsletters or digests the user has opted into
|
||||||
|
4. Industry news or curated content
|
||||||
|
5. Internal announcements (policy changes, team updates, etc.)
|
||||||
|
6. Shared documents or resources for reference
|
||||||
|
|
||||||
|
Category C - Transactional
|
||||||
|
Automated or system-generated emails confirming an action or status. Examples:
|
||||||
|
1. Order confirmations, shipping notifications, delivery updates
|
||||||
|
2. Payment receipts and invoices
|
||||||
|
3. Appointment reminders from services (doctors, salons, etc.)
|
||||||
|
4. Travel itineraries and booking confirmations
|
||||||
|
5. Password resets, login alerts, two-factor codes
|
||||||
|
6. Subscription renewals or billing notices
|
||||||
|
|
||||||
|
Category D - Low Priority
|
||||||
|
Emails that can be safely ignored, archived, or deleted. Examples:
|
||||||
|
1. Marketing and promotional emails
|
||||||
|
2. Sales outreach from unknown senders
|
||||||
|
3. Surveys or feedback requests
|
||||||
|
4. Social media notifications
|
||||||
|
5. Spam or unsolicited bulk mail
|
||||||
|
6. Emails from mailing lists the user rarely engages with
|
||||||
|
|
||||||
|
Category E - Personal
|
||||||
|
Emails from known personal contacts or containing personal (non-work) content. Examples:
|
||||||
|
1. Messages from friends or family
|
||||||
|
2. Personal appointment confirmations
|
||||||
|
3. Social invitations or event coordination
|
||||||
|
4. Non-work correspondence from colleagues
|
||||||
|
|
||||||
|
STEP 3: MARK PROCESSED EMAILS
|
||||||
|
|
||||||
|
Star all emails classified as Category A (Action Required).
|
||||||
|
Do NOT star emails in Categories B, C, D, or E.
|
||||||
|
|
||||||
|
STEP 4: REPORT EMAIL COUNT
|
||||||
|
|
||||||
|
Confirm the total number of emails reviewed in the chat.
|
||||||
|
|
||||||
|
STEP 5: SUMMARIZE PRIORITY EMAILS
|
||||||
|
|
||||||
|
Summarize all Category A (Action Required) and Category E (Personal) emails in the chat, under separate headers.
|
||||||
|
|
||||||
|
For each email, include:
|
||||||
|
- From: sender name and email address
|
||||||
|
- Subject: email subject line
|
||||||
|
- Date: date received
|
||||||
|
- Time: time received (convert to user's local timezone if known, otherwise use original)
|
||||||
|
- Summary: 1-2 sentence summary of the content and what action may be needed
|
||||||
|
|
||||||
|
STEP 6: EXECUTE ACTIONS
|
||||||
|
|
||||||
|
For Category A emails:
|
||||||
|
- If the email contains a meeting request with a specific date/time, create a calendar event using the create_calendar_event tool.
|
||||||
|
- Title: Use the subject line or a clear description of the meeting
|
||||||
|
- Start: Extract date/time from the email (ISO 8601 format)
|
||||||
|
- Duration: Use the duration specified, or default to 60 minutes
|
||||||
|
- Location: Include any meeting link, address, or phone number mentioned
|
||||||
|
- Description: Include relevant context (attendees, agenda, contact info)
|
||||||
|
|
||||||
|
For Category C emails:
|
||||||
|
- If the email contains an appointment or reservation with a specific date/time (e.g., doctor appointment, flight, hotel check-in), create a calendar event.
|
||||||
|
- Title: "[Reminder] " + service/company name + description
|
||||||
|
- Start: Extract date/time from the email
|
||||||
|
- Duration: Use duration if specified, or default to 60 minutes
|
||||||
|
- Location: Include address or relevant details
|
||||||
|
- Description: Include confirmation numbers, contact info, or instructions
|
||||||
|
|
||||||
|
For Category D emails:
|
||||||
|
- Use delete_emails to move these to trash (if configured for auto-cleanup).
|
||||||
|
|
||||||
|
STRICT CONSTRAINTS FOR CALENDAR EVENTS:
|
||||||
|
- Do not fabricate dates, times, links, phone numbers, or any other information.
|
||||||
|
- Before creating an event, verify the proposed date is in the future. If the date has passed, skip calendar creation.
|
||||||
|
- Do not create duplicate events for the same appointment (same date/time and same organizer/service).
|
||||||
|
- Use the same account for calendar events as was used for email fetching.
|
||||||
|
|
||||||
|
STEP 7: LOG SUMMARY
|
||||||
|
|
||||||
|
Use append_to_summary to log all Category A and Category E emails for future reference.
|
||||||
@@ -1,8 +1,6 @@
|
|||||||
You are an expert Executive Assistant AI specialized in email management and productivity. Your goal is to organize, prioritize, and summarize incoming emails to maximize user efficiency.
|
You are an expert Executive Assistant AI specialized in email management and productivity. Your goal is to organize, prioritize, and summarize incoming emails to maximize user efficiency.
|
||||||
|
|
||||||
I have been applying for jobs, which generates a large volume of responses.
|
I have been applying for jobs, which generates a large volume of responses. Review my inbox and apply the following instructions to all new emails.
|
||||||
|
|
||||||
Review, in reverse chronoloical order, the first 150 emails in my inbox. Apply the following instructions to those emails.
|
|
||||||
|
|
||||||
STEP 1: Constraints
|
STEP 1: Constraints
|
||||||
- Do not make up information.
|
- Do not make up information.
|
||||||
@@ -11,23 +9,28 @@ STEP 2: CLASSIFY each email into exactly one category.
|
|||||||
|
|
||||||
Category A - Acknowledgement Only
|
Category A - Acknowledgement Only
|
||||||
The employer confirms receipt of my application but requires no action from me. Typical language: "We received your application," "Your application is under review," "We will contact you if selected." No next steps are requested.
|
The employer confirms receipt of my application but requires no action from me. Typical language: "We received your application," "Your application is under review," "We will contact you if selected." No next steps are requested.
|
||||||
|
Action you should take: Add a "Star" using the gmail built-in actions.
|
||||||
|
|
||||||
Category B - Advancement to Next Step
|
Category B - Advancement to Next Step
|
||||||
The employer wants to move forward. This includes: invitations to schedule a phone screen or interview, requests to complete an assessment or assignment, requests for additional information or documents, or any communication that requires a response or action from me. If an email both acknowledges receipt AND requests action, classify it as B.
|
The employer wants to move forward. This includes: invitations to schedule a phone screen or interview, requests to complete an assessment or assignment, requests for additional information or documents, or any communication that requires a response or action from me. If an email both acknowledges receipt AND requests action, classify it as B.
|
||||||
|
Actions you should take: 1) add a calendar event with all pertinent info: a) person I will be meeting with,
|
||||||
|
b) company c) role I will be discussing d) method for joining meeting - ie, telephone? If yes, will the representative all me, and is the number correct (718) 749-8292 c) or, is it Zoom, Google Meet, Webex or another video format, if so, include the link for joining
|
||||||
|
|
||||||
Category C - Rejection
|
NEVER, EVER ADD A STAR TO A VATEGORY B EMAIL.
|
||||||
|
|
||||||
|
Category C - Rejection
|
||||||
The employer declines to move forward. Typical language: "We have decided to pursue other candidates," "Unfortunately, you were not selected," "We will not be moving forward with your application."
|
The employer declines to move forward. Typical language: "We have decided to pursue other candidates," "Unfortunately, you were not selected," "We will not be moving forward with your application."
|
||||||
|
Action you should take:
|
||||||
|
Add a "Star" using the gmail built-in actions.
|
||||||
|
|
||||||
Category D - Other
|
Category D - Other
|
||||||
The email does not fit into categories A, B, or C. This includes non-job-application emails, newsletters, promotional content, or ambiguous messages that do not clearly match another category.
|
The email does not fit into categories A, B, or C. This includes non-job-application emails, newsletters, promotional content, or ambiguous messages that do not clearly match another category.
|
||||||
|
Action you should take: Add a "Star" using the gmail built-in actions.
|
||||||
|
|
||||||
STEP 3: DELETE emails classified as Category A and Category C.
|
STEP 3: SUMMARIZE emails classified as Category B and Category D in the chat in an organized list with headings. Example format for this:
|
||||||
|
|
||||||
STEP 4: ("Anti step") - NEVER DELETE Category B emails.
|
|
||||||
|
|
||||||
STEP 5: SUMMARIZE emails classified as Category B and Category D. For each, include:
|
|
||||||
1. Sender name and email address
|
1. Sender name and email address
|
||||||
2. Email subject line
|
2. Email subject line
|
||||||
3. Date and time received
|
3. Date and time received
|
||||||
4. Category (B or D)
|
4. Category (B or D)
|
||||||
5. Suggested action I should take
|
5. Suggested action I might take
|
||||||
|
|
||||||
|
|||||||
@@ -1,23 +1,7 @@
|
|||||||
PHASE 2: TAKE ACTION ON CATEGORY B EMAILS
|
PHASE 2: TAKE ACTION ON CATEGORY B EMAILS
|
||||||
|
|
||||||
After completing classification (Phase 1), perform the following actions for each email classified as Category B (Advancement to Next Step).
|
After completing classification (Phase 1), perform the following actions for each email classified as Category B (Advancement to Next Step).
|
||||||
|
|
||||||
STEP 1: LOG TO SPREADSHEET
|
STEP 1: CREATE CALENDAR EVENTS
|
||||||
For each Category B email, extract as much of the following information as possible from the email contents and log it using the log_recruiter_contact tool:
|
|
||||||
|
|
||||||
A column exists for:
|
|
||||||
|
|
||||||
- Recruiter Name
|
|
||||||
- Recruiter Email
|
|
||||||
- Recruiter Phone/Tel
|
|
||||||
- Company/Role the recruiter seeks to fill
|
|
||||||
- First Contact: the date and time the email was received
|
|
||||||
- Subsequent Contacts: any follow-up communication with this recruiter about this role
|
|
||||||
- Recruiter Call Scheduled: if the email contains scheduling information, extract ALL details — date, time, platform (Zoom, MS Teams, Google Meet, etc.), meeting link, phone number to call — and note whether they confirm having your cell number or might not have it
|
|
||||||
|
|
||||||
A row should already exists for the same recruiter email + company/role combination (from a previous email), the tool will UPDATE the existing row. Provide all available fields and the tool handles merging.
|
|
||||||
|
|
||||||
STEP 2: CREATE CALENDAR EVENTS
|
|
||||||
Immediately after logging to the spreadsheet, check whether ANY of these fields were populated or updated:
|
Immediately after logging to the spreadsheet, check whether ANY of these fields were populated or updated:
|
||||||
- Recruiter Call Scheduled
|
- Recruiter Call Scheduled
|
||||||
- Company First Interview
|
- Company First Interview
|
||||||
@@ -30,15 +14,9 @@ For EACH of the above fields that contains a date/time, create a Google Calendar
|
|||||||
- Location: the video meeting link, phone number, or platform name
|
- Location: the video meeting link, phone number, or platform name
|
||||||
- Description: include recruiter or company contact name/email/phone, and note whether they have your cell number
|
- Description: include recruiter or company contact name/email/phone, and note whether they have your cell number
|
||||||
|
|
||||||
STEP 3: COMPANY INTERVIEW TRACKING
|
|
||||||
When an email indicates advancement beyond the recruiter screen to a company interview:
|
|
||||||
- Populate the Company First Interview or Company Second Interview field with details
|
|
||||||
- Those details should include company contact info (interviewer name, email, phone)
|
|
||||||
- Then immeidately create a calendar event for the new interview date/time including interviewer name, email, phone
|
|
||||||
|
|
||||||
STRICT CONSTRAINTS:
|
STRICT CONSTRAINTS:
|
||||||
- Do not make up phone numbers, links, dates, or anything at all. If it does not exist in text wihtin a verifiable email, IT DOES NOT EXIST.
|
- Do not make up phone numbers, links, dates, or anything at all. If it does not exist in text within a verifiable email, IT DOES NOT EXIST.
|
||||||
- PAST-DATE CHECK: Before creating a calendar event. 1) verify today's date from an external, reliable source; 2) compare the proposed meeting date/time against today's date; 3) iIf the meeting date has already passed, do NOT create a calendar event for it. Still log it to the spreadsheet, but skip the calendar step. The tool will also enforce this server-side.
|
- PAST-DATE CHECK: Before creating a calendar event: 1) verify today's date from an external, reliable source; 2) compare the proposed meeting date/time against today's date; 3) if the meeting date has already passed, do NOT create a calendar event for it. Still log it to the spreadsheet, but skip the calendar step. The tool will also enforce this server-side.
|
||||||
- As described in more detail below, each new date/time value in a scheduling column = one new calendar event. Never skip this.
|
- As described in more detail below, each new date/time value in a scheduling column = one new calendar event. Never skip this.
|
||||||
- Always use the same account for calendar events as was used for email fetching.
|
- Always use the same account for calendar events as was used for email fetching.
|
||||||
- Do not create duplicate calendar events for the same meeting (same company representative && same job description | same company && same date time)
|
- Do not create duplicate calendar events for the same meeting (same company representative && same job description | same company && same date time)
|
||||||
|
|||||||
@@ -3,303 +3,358 @@ import { gmail_v1 } from "googleapis";
|
|||||||
import fs from "fs";
|
import fs from "fs";
|
||||||
import { server } from "../McpServer.js";
|
import { server } from "../McpServer.js";
|
||||||
import {
|
import {
|
||||||
accountSchema,
|
accountSchema,
|
||||||
getGmailClient,
|
getGmailClient,
|
||||||
getSummaryPath,
|
getSummaryPath,
|
||||||
loadClassificationPrompt,
|
loadClassificationPrompt,
|
||||||
loadActionPrompt,
|
loadActionPrompt,
|
||||||
} from "../loaders/prompt-config-loaders.js";
|
} from "../loaders/prompt-config-loaders.js";
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Email parsing helpers
|
// Email parsing helpers
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
export const getHeader = (
|
export const getHeader = (
|
||||||
headers: gmail_v1.Schema$MessagePartHeader[] | undefined,
|
headers: gmail_v1.Schema$MessagePartHeader[] | undefined,
|
||||||
name: string
|
name: string
|
||||||
): string => {
|
): string => {
|
||||||
if (!headers) return "";
|
if (!headers) return "";
|
||||||
const header = headers.find(
|
const header = headers.find(
|
||||||
(h) => h.name?.toLowerCase() === name.toLowerCase()
|
(h) => h.name?.toLowerCase() === name.toLowerCase()
|
||||||
);
|
);
|
||||||
return header?.value ?? "";
|
return header?.value ?? "";
|
||||||
};
|
};
|
||||||
|
|
||||||
export const decodeBody = (message: gmail_v1.Schema$Message): string => {
|
export const decodeBody = (message: gmail_v1.Schema$Message): string => {
|
||||||
const parts = message.payload?.parts;
|
const parts = message.payload?.parts;
|
||||||
let encoded = "";
|
let encoded = "";
|
||||||
|
|
||||||
if (parts) {
|
if (parts) {
|
||||||
const textPart = parts.find((p) => p.mimeType === "text/plain");
|
const textPart = parts.find((p) => p.mimeType === "text/plain");
|
||||||
encoded = textPart?.body?.data ?? "";
|
encoded = textPart?.body?.data ?? "";
|
||||||
|
|
||||||
|
if (!encoded) {
|
||||||
|
const htmlPart = parts.find((p) => p.mimeType === "text/html");
|
||||||
|
encoded = htmlPart?.body?.data ?? "";
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
encoded = message.payload?.body?.data ?? "";
|
||||||
|
}
|
||||||
|
|
||||||
if (!encoded) {
|
if (!encoded) {
|
||||||
const htmlPart = parts.find((p) => p.mimeType === "text/html");
|
return message.snippet ?? "";
|
||||||
encoded = htmlPart?.body?.data ?? "";
|
|
||||||
}
|
}
|
||||||
} else {
|
|
||||||
encoded = message.payload?.body?.data ?? "";
|
|
||||||
}
|
|
||||||
|
|
||||||
if (!encoded) {
|
return Buffer.from(encoded, "base64url").toString("utf-8");
|
||||||
return message.snippet ?? "";
|
|
||||||
}
|
|
||||||
|
|
||||||
return Buffer.from(encoded, "base64url").toString("utf-8");
|
|
||||||
};
|
};
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Tool: fetch_new_emails
|
// Tool: fetch_new_emails
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
server.registerTool(
|
server.registerTool(
|
||||||
"fetch_new_emails",
|
"fetch_new_emails",
|
||||||
{
|
{
|
||||||
description:
|
description:
|
||||||
"Fetch unread emails from a Gmail inbox. Returns sender, date, " +
|
"Fetch unread emails from a Gmail inbox. Returns sender, date, " +
|
||||||
"subject, message ID, and body text for each message. The message IDs " +
|
"subject, message ID, and body text for each message. The message IDs " +
|
||||||
"can be passed to delete_emails later. Specify which account to fetch from.",
|
"must be passed to star_emails after evaluation. Specify which account to fetch from.",
|
||||||
inputSchema: {
|
inputSchema: {
|
||||||
account: accountSchema,
|
account: accountSchema,
|
||||||
maxResults: z
|
maxResults: z
|
||||||
.number()
|
.number()
|
||||||
.min(1)
|
.min(1)
|
||||||
.max(100)
|
.max(200)
|
||||||
.describe("Maximum number of unread emails to fetch (1-100)"),
|
.describe("Maximum number of unread emails to fetch (1-200)"),
|
||||||
|
},
|
||||||
},
|
},
|
||||||
},
|
async ({ account, maxResults }) => {
|
||||||
async ({ account, maxResults }) => {
|
try {
|
||||||
try {
|
const gmail = getGmailClient(account);
|
||||||
const gmail = getGmailClient(account);
|
|
||||||
|
|
||||||
const listResponse = await gmail.users.messages.list({
|
const listResponse = await gmail.users.messages.list({
|
||||||
userId: "me",
|
userId: "me",
|
||||||
q: "is:unread",
|
q: "is:unread",
|
||||||
maxResults,
|
maxResults,
|
||||||
});
|
});
|
||||||
|
|
||||||
const messageIds = listResponse.data.messages ?? [];
|
const messageIds = listResponse.data.messages ?? [];
|
||||||
|
|
||||||
if (messageIds.length === 0) {
|
if (messageIds.length === 0) {
|
||||||
return {
|
return {
|
||||||
content: [{ type: "text" as const, text: "No unread emails found." }],
|
content: [{ type: "text" as const, text: "No unread emails found." }],
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
const emails: string[] = [];
|
const emails: string[] = [];
|
||||||
|
|
||||||
for (const msg of messageIds) {
|
for (const msg of messageIds) {
|
||||||
const detail = await gmail.users.messages.get({
|
const detail = await gmail.users.messages.get({
|
||||||
userId: "me",
|
userId: "me",
|
||||||
id: msg.id!,
|
id: msg.id!,
|
||||||
format: "full",
|
format: "full",
|
||||||
});
|
});
|
||||||
|
|
||||||
const headers = detail.data.payload?.headers;
|
const headers = detail.data.payload?.headers;
|
||||||
const from = getHeader(headers, "From");
|
const from = getHeader(headers, "From");
|
||||||
const subject = getHeader(headers, "Subject");
|
const subject = getHeader(headers, "Subject");
|
||||||
const date = getHeader(headers, "Date");
|
const date = getHeader(headers, "Date");
|
||||||
const body = decodeBody(detail.data);
|
const body = decodeBody(detail.data);
|
||||||
|
|
||||||
const truncatedBody =
|
const truncatedBody =
|
||||||
body.length > 2000 ? body.substring(0, 2000) + "\n[...truncated]" : body;
|
body.length > 2000 ? body.substring(0, 2000) + "\n[...truncated]" : body;
|
||||||
|
|
||||||
emails.push(
|
emails.push(
|
||||||
[
|
[
|
||||||
`MESSAGE_ID: ${msg.id}`,
|
`MESSAGE_ID: ${msg.id}`,
|
||||||
`FROM: ${from}`,
|
`FROM: ${from}`,
|
||||||
`DATE: ${date}`,
|
`DATE: ${date}`,
|
||||||
`SUBJECT: ${subject}`,
|
`SUBJECT: ${subject}`,
|
||||||
`BODY:\n${truncatedBody}`,
|
`BODY:\n${truncatedBody}`,
|
||||||
].join("\n")
|
].join("\n")
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
const classificationInstructions = loadClassificationPrompt();
|
const classificationInstructions = loadClassificationPrompt();
|
||||||
const actionInstructions = loadActionPrompt();
|
const actionInstructions = loadActionPrompt();
|
||||||
const instructionsBlock =
|
const instructionsBlock =
|
||||||
(classificationInstructions
|
(classificationInstructions
|
||||||
? `\n\n${"=".repeat(60)}\nCLASSIFICATION INSTRUCTIONS (PHASE 1):\n${"=".repeat(60)}\n${classificationInstructions}`
|
? `\n\n${"=".repeat(60)}\nCLASSIFICATION INSTRUCTIONS (PHASE 1):\n${"=".repeat(60)}\n${classificationInstructions}`
|
||||||
: "") +
|
: "") +
|
||||||
(actionInstructions
|
(actionInstructions
|
||||||
? `\n\n${"=".repeat(60)}\nACTION INSTRUCTIONS (PHASE 2):\n${"=".repeat(60)}\n${actionInstructions}`
|
? `\n\n${"=".repeat(60)}\nACTION INSTRUCTIONS (PHASE 2):\n${"=".repeat(60)}\n${actionInstructions}`
|
||||||
: "");
|
: "");
|
||||||
|
|
||||||
return {
|
return {
|
||||||
content: [
|
content: [
|
||||||
{
|
{
|
||||||
type: "text" as const,
|
type: "text" as const,
|
||||||
text:
|
text:
|
||||||
`Found ${emails.length} unread email(s):\n\n` +
|
`Found ${emails.length} unread email(s):\n\n` +
|
||||||
`${"=".repeat(60)}\n${emails.join(`\n${"=".repeat(60)}\n`)}` +
|
`${"=".repeat(60)}\n${emails.join(`\n${"=".repeat(60)}\n`)}` +
|
||||||
instructionsBlock,
|
instructionsBlock,
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
const errMsg = error instanceof Error ? error.message : String(error);
|
const errMsg = error instanceof Error ? error.message : String(error);
|
||||||
return {
|
return {
|
||||||
content: [
|
content: [
|
||||||
{
|
{
|
||||||
type: "text" as const,
|
type: "text" as const,
|
||||||
text: `Error fetching emails: ${errMsg}`,
|
text: `Error fetching emails: ${errMsg}`,
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
|
||||||
);
|
);
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Tool: delete_emails
|
// Tool: delete_emails
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
server.registerTool(
|
server.registerTool(
|
||||||
"delete_emails",
|
"delete_emails",
|
||||||
{
|
{
|
||||||
description:
|
description:
|
||||||
"Move emails to trash by their Gmail message IDs. Use this for " +
|
"Move emails to trash by their Gmail message IDs. Use this for " +
|
||||||
"category A (acknowledgements) and category C (rejections) emails. " +
|
"category A (acknowledgements) and category C (rejections) emails. " +
|
||||||
"Specify which account the emails belong to.",
|
"Specify which account the emails belong to.",
|
||||||
inputSchema: {
|
inputSchema: {
|
||||||
account: accountSchema,
|
account: accountSchema,
|
||||||
messageIds: z
|
messageIds: z
|
||||||
.array(z.string())
|
.array(z.string())
|
||||||
.describe("Array of Gmail message IDs to move to trash"),
|
.describe("Array of Gmail message IDs to move to trash"),
|
||||||
|
},
|
||||||
},
|
},
|
||||||
},
|
async ({ account, messageIds }) => {
|
||||||
async ({ account, messageIds }) => {
|
|
||||||
try {
|
|
||||||
const gmail = getGmailClient(account);
|
|
||||||
const results: string[] = [];
|
|
||||||
|
|
||||||
for (const id of messageIds) {
|
|
||||||
try {
|
try {
|
||||||
await gmail.users.messages.trash({
|
const gmail = getGmailClient(account);
|
||||||
userId: "me",
|
const results: string[] = [];
|
||||||
id,
|
|
||||||
});
|
|
||||||
results.push(`Trashed: ${id}`);
|
|
||||||
} catch (err) {
|
|
||||||
const errMsg = err instanceof Error ? err.message : String(err);
|
|
||||||
results.push(`Failed to trash ${id}: ${errMsg}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
for (const id of messageIds) {
|
||||||
content: [
|
try {
|
||||||
{
|
await gmail.users.messages.trash({
|
||||||
type: "text" as const,
|
userId: "me",
|
||||||
text: `Delete results:\n${results.join("\n")}`,
|
id,
|
||||||
},
|
});
|
||||||
],
|
results.push(`Trashed: ${id}`);
|
||||||
};
|
} catch (err) {
|
||||||
} catch (error) {
|
const errMsg = err instanceof Error ? err.message : String(err);
|
||||||
const errMsg = error instanceof Error ? error.message : String(error);
|
results.push(`Failed to trash ${id}: ${errMsg}`);
|
||||||
return {
|
}
|
||||||
content: [
|
}
|
||||||
{
|
|
||||||
type: "text" as const,
|
return {
|
||||||
text: `Error deleting emails: ${errMsg}`,
|
content: [
|
||||||
},
|
{
|
||||||
],
|
type: "text" as const,
|
||||||
};
|
text: `Delete results:\n${results.join("\n")}`,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
} catch (error) {
|
||||||
|
const errMsg = error instanceof Error ? error.message : String(error);
|
||||||
|
return {
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: "text" as const,
|
||||||
|
text: `Error deleting emails: ${errMsg}`,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
|
||||||
);
|
);
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// Tool: append_to_summary
|
// Tool: append_to_summary
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
interface SummaryEntry {
|
interface SummaryEntry {
|
||||||
senderName: string;
|
senderName: string;
|
||||||
senderEmail: string;
|
senderEmail: string;
|
||||||
dateReceived: string;
|
dateReceived: string;
|
||||||
subject: string;
|
subject: string;
|
||||||
category: "B" | "D";
|
category: "B" | "D";
|
||||||
addedAt: string;
|
addedAt: string;
|
||||||
}
|
}
|
||||||
|
|
||||||
server.registerTool(
|
server.registerTool(
|
||||||
"append_to_summary",
|
"append_to_summary",
|
||||||
{
|
{
|
||||||
description:
|
description:
|
||||||
"Append classified email entries to the local summary file. Use this " +
|
"Append classified email entries to the local summary file. Use this " +
|
||||||
"for category B (advancement to next step) and category D (other) emails. " +
|
"for category B (advancement to next step) and category D (other) emails. " +
|
||||||
"Each entry records the sender, date, subject, and category. " +
|
"Each entry records the sender, date, subject, and category. " +
|
||||||
"Specify which account the emails belong to.",
|
"Specify which account the emails belong to.",
|
||||||
inputSchema: {
|
inputSchema: {
|
||||||
account: accountSchema,
|
account: accountSchema,
|
||||||
entries: z
|
entries: z
|
||||||
.array(
|
.array(
|
||||||
z.object({
|
z.object({
|
||||||
senderName: z.string().describe("Name of the sender"),
|
senderName: z.string().describe("Name of the sender"),
|
||||||
senderEmail: z.string().describe("Email address of the sender"),
|
senderEmail: z.string().describe("Email address of the sender"),
|
||||||
dateReceived: z
|
dateReceived: z
|
||||||
.string()
|
.string()
|
||||||
.describe("Date and time the email was received"),
|
.describe("Date and time the email was received"),
|
||||||
subject: z.string().describe("Email subject line"),
|
subject: z.string().describe("Email subject line"),
|
||||||
category: z
|
category: z
|
||||||
.enum(["B", "D"])
|
.enum(["B", "D"])
|
||||||
.describe(
|
.describe(
|
||||||
"Category: B = advancement to next step, D = other/uncategorized"
|
"Category: B = advancement to next step, D = other/uncategorized"
|
||||||
),
|
),
|
||||||
})
|
})
|
||||||
)
|
)
|
||||||
.describe("Array of email summary entries to append"),
|
.describe("Array of email summary entries to append"),
|
||||||
|
},
|
||||||
},
|
},
|
||||||
},
|
async ({ account, entries }) => {
|
||||||
async ({ account, entries }) => {
|
try {
|
||||||
try {
|
const summaryPath = getSummaryPath(account);
|
||||||
const summaryPath = getSummaryPath(account);
|
|
||||||
|
|
||||||
let summary: SummaryEntry[] = [];
|
let summary: SummaryEntry[] = [];
|
||||||
if (fs.existsSync(summaryPath)) {
|
if (fs.existsSync(summaryPath)) {
|
||||||
summary = JSON.parse(fs.readFileSync(summaryPath, "utf-8"));
|
summary = JSON.parse(fs.readFileSync(summaryPath, "utf-8"));
|
||||||
}
|
}
|
||||||
|
|
||||||
const now = new Date();
|
const now = new Date();
|
||||||
const nowIso = now.toISOString();
|
const nowIso = now.toISOString();
|
||||||
const newEntries: SummaryEntry[] = entries.map((e) => ({
|
const newEntries: SummaryEntry[] = entries.map((e) => ({
|
||||||
...e,
|
...e,
|
||||||
addedAt: nowIso,
|
addedAt: nowIso,
|
||||||
}));
|
}));
|
||||||
|
|
||||||
summary.push(...newEntries);
|
summary.push(...newEntries);
|
||||||
|
|
||||||
const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
|
const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
|
||||||
const cutoff = now.getTime() - RETENTION_MS;
|
const cutoff = now.getTime() - RETENTION_MS;
|
||||||
const beforePurge = summary.length;
|
const beforePurge = summary.length;
|
||||||
summary = summary.filter(
|
summary = summary.filter(
|
||||||
(entry) => new Date(entry.addedAt).getTime() >= cutoff
|
(entry) => new Date(entry.addedAt).getTime() >= cutoff
|
||||||
);
|
);
|
||||||
const purged = beforePurge - summary.length;
|
const purged = beforePurge - summary.length;
|
||||||
|
|
||||||
fs.writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
|
fs.writeFileSync(summaryPath, JSON.stringify(summary, null, 2));
|
||||||
|
|
||||||
const purgeNote = purged > 0
|
const purgeNote = purged > 0
|
||||||
? `\nPurged ${purged} entry/entries older than 30 days.`
|
? `\nPurged ${purged} entry/entries older than 30 days.`
|
||||||
: "";
|
: "";
|
||||||
|
|
||||||
return {
|
return {
|
||||||
content: [
|
content: [
|
||||||
{
|
{
|
||||||
type: "text" as const,
|
type: "text" as const,
|
||||||
text:
|
text:
|
||||||
`Appended ${newEntries.length} entry/entries to summary.\n` +
|
`Appended ${newEntries.length} entry/entries to summary.\n` +
|
||||||
`Total entries in summary: ${summary.length}\n` +
|
`Total entries in summary: ${summary.length}\n` +
|
||||||
`Summary file: ${summaryPath}` +
|
`Summary file: ${summaryPath}` +
|
||||||
purgeNote,
|
purgeNote,
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
const errMsg = error instanceof Error ? error.message : String(error);
|
const errMsg = error instanceof Error ? error.message : String(error);
|
||||||
return {
|
return {
|
||||||
content: [
|
content: [
|
||||||
{
|
{
|
||||||
type: "text" as const,
|
type: "text" as const,
|
||||||
text: `Error appending to summary: ${errMsg}`,
|
text: `Error appending to summary: ${errMsg}`,
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
);
|
||||||
|
// --------------------------------------------------------------------------- //
|
||||||
|
// Tool: star_emails
|
||||||
|
// --------------------------------------------------------------------------- //
|
||||||
|
server.registerTool(
|
||||||
|
"star_emails",
|
||||||
|
{
|
||||||
|
description: "Mark reviewed emails with a star and mark them as read in Gmail. " +
|
||||||
|
"Use this for all reviewed messages (Categories A, B, C, and D) " +
|
||||||
|
"to signal they have been processed. Specify which account the emails belong to.",
|
||||||
|
inputSchema: {
|
||||||
|
account: accountSchema,
|
||||||
|
messageIds: z
|
||||||
|
.array(z.string())
|
||||||
|
.describe("Array of Gmail message IDs to star and mark read"),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
async ({ account, messageIds }) => {
|
||||||
|
try {
|
||||||
|
if (messageIds.length === 0) {
|
||||||
|
return { content: [{ type: "text" as const, text: "No message IDs provided." }] };
|
||||||
|
}
|
||||||
|
|
||||||
|
const gmail = getGmailClient(account);
|
||||||
|
|
||||||
|
// Batch modify allows updating up to 1000 messages in a single API call
|
||||||
|
await gmail.users.messages.batchModify({
|
||||||
|
userId: "me",
|
||||||
|
requestBody: {
|
||||||
|
ids: messageIds,
|
||||||
|
addLabelIds: ["STARRED"],
|
||||||
|
removeLabelIds: ["UNREAD"]
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
return {
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: "text" as const,
|
||||||
|
text: `Successfully starred and marked read ${messageIds.length} email(s).`,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
} catch (error) {
|
||||||
|
const errMsg = error instanceof Error ? error.message : String(error);
|
||||||
|
return {
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: "text" as const,
|
||||||
|
text: `Error starring emails: ${errMsg}`,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
|
||||||
);
|
);
|
||||||
|
|||||||
Reference in New Issue
Block a user