189 lines
5.1 KiB
Markdown
189 lines
5.1 KiB
Markdown
<p align="center">
|
|
<img src="assets/logo.png" alt="deClawed" width="120" />
|
|
</p>
|
|
|
|
# deClawed
|
|
|
|
**LLM-powered email, meeting, teleconference and event 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
|