189 lines
5.0 KiB
Markdown
189 lines
5.0 KiB
Markdown
<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 your Gmail inbox to any LLM-capable client (such as Claude Desktop). 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
|