# 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
```