Skip to content

Commit 2d11f01

Browse files
wyattjohwyattjoh
committed
feat: initial implementation of JMAP MCP server
- Add complete JMAP MCP server with email management tools - Implement email search, retrieval, marking, moving, and deletion - Add mailbox management and email composition features - Support JMAP RFC 8620/8621 with jmap-jam client library - Include GitHub Actions workflow for JSR publishing - Add comprehensive documentation and VS Code configuration
0 parents  commit 2d11f01

File tree

11 files changed

+1863
-0
lines changed

11 files changed

+1863
-0
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Publish to JSR
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
release:
8+
types: [published]
9+
10+
jobs:
11+
publish:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: read
15+
id-token: write # Required for OIDC authentication with JSR
16+
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Deno
22+
uses: denoland/setup-deno@v2
23+
with:
24+
deno-version: v2.x
25+
26+
- name: Check formatting
27+
run: deno task fmt --check
28+
29+
- name: Lint code
30+
run: deno task lint
31+
32+
- name: Type check
33+
run: deno task check
34+
35+
- name: Publish packages to JSR
36+
run: deno publish

‎.vscode/settings.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"biome.enabled": false,
3+
"[typescript]": {
4+
"editor.defaultFormatter": "denoland.vscode-deno"
5+
},
6+
"deno.enable": true,
7+
"deno.lint": true
8+
}

‎CLAUDE.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with
4+
code in this repository.
5+
6+
## Project Overview
7+
8+
This is a Model Context Protocol (MCP) server that provides JMAP (JSON Meta
9+
Application Protocol) email management tools. It's built with Deno and
10+
integrates with JMAP-compliant email servers like FastMail, Cyrus IMAP, and
11+
Stalwart Mail Server.
12+
13+
## Development Commands
14+
15+
### Building and Running
16+
17+
- `deno task start` - Run the MCP server in development
18+
- `deno task watch` - Run with file watching for development
19+
20+
### Testing Connection
21+
22+
- `deno run --allow-env --allow-net src/mod.ts` - Test JMAP server connection
23+
24+
### Required Environment Variables
25+
26+
```bash
27+
JMAP_SESSION_URL="https://your-jmap-server.com/.well-known/jmap"
28+
JMAP_BEARER_TOKEN="your-bearer-token"
29+
JMAP_ACCOUNT_ID="account-id" # Optional, auto-detected if not provided
30+
```
31+
32+
## Architecture
33+
34+
### Core Structure
35+
36+
- **Entry point**: `src/mod.ts` - MCP server setup, JMAP client initialization,
37+
and tool registration
38+
- **Tool modules**: `src/tools/` - Modular tool implementations
39+
- `email.ts` - Email search, retrieval, mailbox management, and basic
40+
operations
41+
- `submission.ts` - Email composition and sending (when JMAP submission
42+
capability is available)
43+
- **Utilities**: `src/utils.ts` - Common utilities like error formatting
44+
45+
### Key Design Patterns
46+
47+
- **Functional programming style** - Functions are pure where possible, side
48+
effects are contained
49+
- **Runtime validation** - All inputs validated with Zod schemas before
50+
processing
51+
- **Capability-based registration** - Tools are registered based on JMAP server
52+
capabilities
53+
- **Graceful degradation** - Server adapts to read-only accounts and limited
54+
JMAP capabilities
55+
56+
### JMAP Integration
57+
58+
- Uses `jmap-jam` client library for JMAP RFC 8620/8621 compliance
59+
- Automatically detects account capabilities and registers appropriate tools
60+
- Supports both read-only and full-access JMAP accounts
61+
- Handles JMAP mail (`urn:ietf:params:jmap:mail`) and submission
62+
(`urn:ietf:params:jmap:submission`) capabilities
63+
64+
### Tool Categories
65+
66+
1. **Email Search & Retrieval**: `search_emails`, `get_emails`, `get_threads`
67+
2. **Mailbox Management**: `get_mailboxes`
68+
3. **Email Actions** (non-read-only): `mark_emails`, `move_emails`,
69+
`delete_emails`
70+
4. **Email Composition** (submission capability): `send_email`, `reply_to_email`
71+
72+
## Development Guidelines
73+
74+
### Adding New Tools
75+
76+
1. Create Zod validation schemas for input parameters
77+
2. Implement tool logic with proper error handling using `formatError()`
78+
3. Register tools in appropriate module (`email.ts` vs `submission.ts`)
79+
4. Tools should be registered conditionally based on JMAP capabilities
80+
81+
### Code Style
82+
83+
- Follow functional programming patterns throughout the codebase
84+
- Use TypeScript types imported from `jmap-jam` for JMAP objects
85+
- All external inputs must be validated with Zod schemas
86+
- Error handling should use the `formatError()` utility
87+
- Console output uses `console.warn()` for server status messages
88+
89+
### JMAP Considerations
90+
91+
- Email IDs and thread IDs are server-specific strings, not UUIDs
92+
- Mailbox hierarchies use parent-child relationships via `parentId`
93+
- Keywords like `$seen`, `$flagged`, `$draft` control email state
94+
- Date filters must use ISO 8601 format
95+
- Pagination is handled via `position` and `limit` parameters
96+
97+
## Security Notes
98+
99+
- Bearer tokens are provided via environment variables, never hardcoded
100+
- No secrets are logged or exposed in MCP responses
101+
- Input validation prevents injection attacks
102+
- JMAP protocol provides built-in security through proper authentication

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Wyatt Johnson
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)