271 lines
8.2 KiB
Markdown
271 lines
8.2 KiB
Markdown
# Declawed (A Mail Bot)
|
|
|
|
A local Model Context Protocol (MCP) server connecing LLM platform APIs (ie Claude Desktop), or locally hosted models to your mail account.
|
|
Ssimple.
|
|
No Surprises, unlike the blue-plate-special-crustacean of the day.
|
|
Automates review, classification, and action -- response, deletion, archiving -- for inbox items.
|
|
|
|
---
|
|
|
|
# Scope
|
|
|
|
## Current implementaiton contemplates: Claude Desktop + Local Custom Model Context Protocol Server + Goog-MX'ed SMTP for your Registered, DNS'd XXX.YYY domain
|
|
(highly config'able- more to follow)
|
|
|
|
---
|
|
|
|
### 1. Install: Node.js
|
|
|
|
Node.js v16 or higher must be installed.
|
|
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
If not installed, download from [nodejs.org](https://nodejs.org/).
|
|
|
|
### 2. Initialize the Project
|
|
|
|
```bash
|
|
mkdir assistant
|
|
cd assistant
|
|
npm init -y
|
|
```
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
npm install @modelcontextprotocol/sdk zod@3 googleapis
|
|
npm install -D @types/node typescript
|
|
```
|
|
|
|
Create the source directory and entry file:
|
|
|
|
```bash
|
|
mkdir src
|
|
touch src/index.ts
|
|
```
|
|
|
|
### 4. Configure the Project
|
|
|
|
#### 4a. Update `package.json`
|
|
|
|
Set the module type, binary entry, and build scripts:
|
|
|
|
```json
|
|
{
|
|
"type": "module",
|
|
"bin": {
|
|
"assistant": "./build/index.js"
|
|
},
|
|
"scripts": {
|
|
"build": "tsc && chmod 755 build/index.js",
|
|
"auth": "npm run build && node build/auth.js"
|
|
},
|
|
"files": ["build"]
|
|
}
|
|
```
|
|
|
|
#### 4b. Create `tsconfig.json` in the project root
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"target": "ES2022",
|
|
"module": "Node16",
|
|
"moduleResolution": "Node16",
|
|
"outDir": "./build",
|
|
"rootDir": "./src",
|
|
"strict": true,
|
|
"esModuleInterop": true,
|
|
"skipLibCheck": true,
|
|
"forceConsistentCasingInFileNames": true
|
|
},
|
|
"include": ["src/**/*"],
|
|
"exclude": ["node_modules"]
|
|
}
|
|
```
|
|
|
|
### 5. Write the Server Code
|
|
|
|
The server source lives in `src/index.ts`. It registers three tools and one prompt with the MCP server:
|
|
|
|
- **`fetch_new_emails`** -- fetches unread Gmail messages
|
|
- **`delete_emails`** -- trashes messages by ID
|
|
- **`append_to_summary`** -- logs classified emails to `summary.json`
|
|
- **`review_emails`** (prompt) -- feeds Claude the classification instructions
|
|
|
|
The auth helper lives in `src/auth.ts`, used only for the one-time OAuth setup.
|
|
|
|
### 6. Set Up Google Cloud Credentials
|
|
|
|
#### 6a. 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) and select **New Project**
|
|
4. Name it (e.g., `assistant-mcp`) and click **Create**
|
|
5. Select the new project from the dropdown
|
|
|
|
#### 6b. Enable the Gmail API
|
|
|
|
1. Go to **APIs & Services > Library** ([direct link](https://console.cloud.google.com/apis/library))
|
|
2. Search for **Gmail API**
|
|
3. Click it, then click **Enable**
|
|
|
|
#### 6c. 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
|
|
|
|
#### 6d. Add the Gmail Scope
|
|
|
|
1. Go to **Google Auth Platform > Data Access** (or the Scopes page)
|
|
2. Click **Add or remove scopes**
|
|
3. Add: `https://www.googleapis.com/auth/gmail.modify`
|
|
4. Save
|
|
|
|
#### 6e. Add Yourself as a Test User
|
|
|
|
1. Go to **Google Auth Platform > Audience**
|
|
2. Add your Gmail address as a test user
|
|
|
|
#### 6f. Create OAuth Client Credentials
|
|
|
|
1. Go to **Google Auth Platform > Clients** (or **APIs & Services > Credentials**)
|
|
2. Click **Create Client** (or **+ Create Credentials > OAuth client ID**)
|
|
3. Application type: **Desktop app**
|
|
4. Name it anything (e.g., `Assistant MCP Desktop`)
|
|
5. Click **Create**
|
|
6. **Download the JSON** file
|
|
7. Rename it to `credentials.json`
|
|
8. Move it to the project root: `/Users/kjannette/assistant/credentials.json`
|
|
|
|
### 7. Authorize Your Gmail Account
|
|
|
|
Build the project and run the auth script:
|
|
|
|
```bash
|
|
npm run auth
|
|
```
|
|
|
|
This will:
|
|
1. Print a URL -- open it in your browser
|
|
2. Sign in with your Google account and click **Allow**
|
|
3. You'll land on a "localhost refused to connect" page (this is normal)
|
|
4. Copy the **entire URL** from the browser address bar
|
|
5. Paste it into the terminal prompt
|
|
6. The script extracts the auth code and saves `token.json`
|
|
|
|
You only need to do this once. The token auto-refreshes.
|
|
|
|
### 8. Build the Server
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
This compiles `src/*.ts` into `build/*.js`.
|
|
|
|
### 9. Write the Classification Prompt
|
|
|
|
Create a file called `classify-emails.txt` in the project root. This file contains the plain-text instructions that tell Claude how to classify your emails.
|
|
|
|
**Tips for writing the prompt:**
|
|
- Use clear, explicit category definitions with example language for each
|
|
- Handle ambiguous cases (e.g., "If an email both acknowledges receipt AND requests action, classify it as B")
|
|
- Define the exact actions to take for each category (delete, summarize, etc.)
|
|
- Specify what fields to include in summaries
|
|
- Keep it in plain text -- no JSON or special formatting needed
|
|
- The file is loaded at runtime, so you can edit it without rebuilding the server
|
|
|
|
**File location:** Must be at the project root as `classify-emails.txt`.
|
|
|
|
### 10. Configure Claude Desktop
|
|
|
|
Edit the Claude Desktop config file:
|
|
|
|
```bash
|
|
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
```
|
|
|
|
Add the `assistant` server to the `mcpServers` object:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"assistant": {
|
|
"command": "/ABSOLUTE/PATH/TO/node",
|
|
"args": [
|
|
"/Users/kjannette/assistant/build/index.js"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace `/ABSOLUTE/PATH/TO/node` with the output of `which node`.
|
|
|
|
### 11. Restart Claude Desktop
|
|
|
|
Fully quit Claude Desktop (**Cmd+Q**, not just close the window) and reopen it. The `assistant` server should now appear under **Connectors** in the chat input.
|
|
|
|
---
|
|
|
|
## Usage Guide
|
|
|
|
### Prompt Loader
|
|
|
|
The server reads `classify-emails.txt` from the project root at runtime. To change classification behavior, edit that file directly -- no rebuild required. The updated instructions take effect on the next tool call.
|
|
|
|
### MCP Prompt: `review_emails`
|
|
|
|
A registered MCP prompt available in Claude Desktop's Connectors menu. When invoked, it feeds Claude the full contents of `classify-emails.txt` as a user message, giving Claude all the classification criteria before it calls any tools. This is the recommended way to trigger the workflow -- it ensures Claude has the complete instructions every time.
|
|
|
|
### `fetch_new_emails` Enrichment
|
|
|
|
Every time `fetch_new_emails` is called, the classification instructions from `classify-emails.txt` are appended to the response alongside the email data. This means Claude always sees the rules with the data, even if the `review_emails` prompt was not explicitly invoked. Belt and suspenders.
|
|
|
|
### Running the Workflow
|
|
|
|
1. Open Claude Desktop
|
|
2. Type: **"Review my inbox"** (or invoke the `review_emails` prompt from Connectors)
|
|
3. Claude will:
|
|
- Call `fetch_new_emails` to retrieve unread messages
|
|
- Classify each email as A, B, C, or D using the prompt instructions
|
|
- Call `delete_emails` for categories A and C
|
|
- Call `append_to_summary` for categories B and D
|
|
4. Results are displayed in the chat and saved to `summary.json`
|
|
|
|
### Key Commands
|
|
|
|
| Command | Purpose |
|
|
|---------|---------|
|
|
| `npm run build` | Recompile after editing `src/index.ts` |
|
|
| `npm run auth` | Re-authorize Gmail (only if `token.json` deleted/expired) |
|
|
| Cmd+Q Claude Desktop, reopen | Pick up server changes after a rebuild |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
assistant/
|
|
├── src/
|
|
│ ├── index.ts # MCP server source (tools + prompt)
|
|
│ └── auth.ts # One-time OAuth setup script
|
|
├── build/
|
|
│ ├── index.js # Compiled server (Claude Desktop runs this)
|
|
│ └── auth.js # Compiled auth script
|
|
├── classify-emails.txt # Classification prompt (plain text, edit anytime)
|
|
├── credentials.json # Google OAuth client credentials (from Cloud Console)
|
|
├── token.json # Gmail access/refresh token (auto-generated)
|
|
├── summary.json # Output file where B/D emails are logged
|
|
├── package.json # Project config and scripts
|
|
├── tsconfig.json # TypeScript compiler config
|
|
└── README.md # This file
|
|
```
|