<p align="center">
<img src="assets/logo.png" alt="deClawed" width="120" />
</p>

# deClawed

**LLM-powered email triage and workflow automation via the Model Context Protocol**

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

### Requirements

| Dependency | Version |
|------------|---------|
| Node.js | 16+ |
| npm | 8+ |
| Google Cloud Project | With Gmail API enabled |
| MCP Client | Claude Desktop (or any MCP-compatible client) |

### Installation

```bash
git clone https://git.sjdev.online/kjannette/deClawed-Assity-Kitty
cd deClawed-Assity-Kitty
npm install
npm run build
```

### Google Cloud Setup

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

Create `accountsAndCredentials/accounts.json`:

```json
{
  "work": {
    "label": "you@example.com",
    "tokenFile": "token.json",
    "spreadsheetId": "YOUR_GOOGLE_SHEET_ID",
    "calendarId": "primary"
  }
}
```

### Authorize Gmail Access

```bash
npm run auth              # Authorize default account
npm run auth -- secondary # Authorize additional accounts
```

Follow the browser prompts to complete OAuth. Tokens are saved locally and auto-refresh.

### Connect to Claude Desktop

Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "assistant": {
      "command": "/path/to/node",
      "args": ["/path/to/deClawed-Assity-Kitty/build/index.js"]
    }
  }
}
```

Restart Claude Desktop. The server appears under **Connectors**.

---

## Usage

### 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 |
|------|-------------|
| `fetch_new_emails` | Fetch unread emails with classification instructions appended |
| `delete_emails` | Move specified message IDs to trash |
| `star_emails` | Star messages and mark as read |
| `append_to_summary` | Log email metadata to local JSON (auto-purges after 30 days) |
| `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

```
fetch_new_emails(account: "work", maxResults: 50)
```

### Example: Create Calendar Event

```
create_calendar_event(
  account: "work",
  title: "[Interview] Acme Corp - Senior Engineer",
  startDateTime: "2026-09-01T14:00:00-04:00",
  durationMinutes: 60,
  location: "https://zoom.us/j/123456789"
)
```

---

## CLI Commands

| Command | Purpose |
|---------|---------|
| `npm run build` | Compile TypeScript to `build/` |
| `npm run auth` | Authorize the default account |
| `npm run auth -- <name>` | Authorize a named account |
| `npm test` | Run test suite |
| `npm run test:watch` | Run tests in watch mode |

---

## Project Structure

```
deClawed-Assity-Kitty/
├── src/
│   ├── index.ts                 # Entry point
│   ├── McpServer.ts             # MCP server instance
│   ├── auth.ts                  # OAuth setup script
│   ├── loaders/                 # Config and prompt loaders
│   ├── prompts/                 # Classification and action prompts
│   └── tools/                   # MCP tool implementations
├── accountsAndCredentials/      # OAuth credentials and tokens (gitignored)
├── mailSummaries/               # Local email logs (gitignored)
├── test/                        # Unit and integration tests
└── build/                       # Compiled output
```

---

## Security

- All credentials and tokens are stored locally and excluded from version control
- OAuth tokens auto-refresh; re-authorization is only needed if revoked
- The server runs locally via stdio—no network exposure

---

## License

ISC