mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-30 13:20:54 +01:00
Leia MarshallandLeia Marshall
e4ce989099
## Thinking Path > - Paperclip separates Gmail capabilities by reviewed OAuth scope and tool policy. > - Existing Gmail connections support reading and draft creation but not bounded archiving. > - Gmail archive requires `gmail.modify`, so it must not widen existing read or draft grants. > - This change adds an opt-in archive profile and limits it to removing only the `INBOX` label. > - A final pre-dispatch check preserves that boundary for approved and replayed calls. ## Linked Issues or Issue Description **What existing behavior does this improve?** This improves the existing Gmail connection and tool-governance behavior. **Subsystem affected** Cross-cutting: `packages/shared` and `server`. **Current behavior** Paperclip can read Gmail and create drafts. It does not provide an opt-in, bounded action for archiving a thread. **Proposed behavior** Paperclip offers a separate Read & archive connection. It exposes `unlabel_thread` only for that connection and accepts only `threadId` with `labelIds: ["INBOX"]`. **Reason and benefit** Users can archive processed Gmail threads while sending, trashing, and other label changes remain disabled. **Breaking changes** None. Existing read and draft methods keep their current scopes and defaults. Related work: #15545 adds a unified Google Workspace connector and keeps Gmail draft-only. #15412 adds a separate Gmail REST server without label mutations. Neither PR adds this bounded archive capability. ## What Changed - Added the `gmail.archive` connector profile. - Added managed and customer-owned archive connection methods. - Added an Inbox-only schema and final pre-dispatch argument guard. - Classified archive as destructive and added Ask-first defaults for the archive methods. - Added permission-review records and focused tests. ## Verification - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/server build` - `pnpm --filter @paperclipai/shared typecheck` - Focused Vitest suites: 42 tests passed. - App-definition ingestion: 103 definitions and 0 review flags. - `git diff --check` ## Risks The main risk is accidental scope or operation expansion. The new profile is opt-in. Existing profiles retain their scopes. The gateway validates the exact Inbox-only payload immediately before dispatch. Production rollout requires separate OAuth configuration and fresh consent. ## Model Used Unverified — reliable runtime model metadata was not available. Confirm the model attribution before publishing. ## Checklist - [x] I have included a concise design rationale - [x] I have specified that model attribution is unverified - [x] I have checked ROADMAP.md and found no Gmail archive entry - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have described the issue in this PR - [x] I have not referenced internal or instance-local issues - [x] My branch name describes the change - [x] Local tests and builds pass - [x] I have added or updated tests - [x] I have updated relevant documentation and permission records - [x] I have documented risks - [ ] All hosted CI gates are green - [ ] Greptile and human review are complete --------- Co-authored-by: Leia Marshall <leia@paperclip.ing>
260 lines
9.5 KiB
JSON
260 lines
9.5 KiB
JSON
{
|
|
"schemaVersion": 1,
|
|
"slug": "gmail",
|
|
"name": "Gmail",
|
|
"description": "Search and read Gmail messages and create drafts without enabling mail sending.",
|
|
"categories": [
|
|
"communication",
|
|
"productivity"
|
|
],
|
|
"featured": true,
|
|
"branding": {
|
|
"logoUrl": "/brands/apps/gmail.svg"
|
|
},
|
|
"urlPatterns": [
|
|
"https://gmailmcp.googleapis.com/*"
|
|
],
|
|
"docsUrl": "https://developers.google.com/workspace/gmail/api/reference/mcp",
|
|
"setupPrerequisite": {
|
|
"title": "Google Developer Preview access required",
|
|
"description": "Google must register both the Workspace email used to authorize Paperclip and the Google Cloud project that owns the OAuth client. Registration is limited to those emails and projects; it does not enable unrelated Paperclip customers.",
|
|
"steps": [
|
|
"Apply with the Workspace email that will sign in and the Google Cloud project that owns the OAuth client.",
|
|
"Wait for the Google Group notification and then Google's final project-registration email, usually within a couple of days.",
|
|
"Add every additional tester email or Cloud project through Google's member request forms before connecting."
|
|
],
|
|
"actionLabel": "Apply or verify Developer Preview enrollment",
|
|
"actionUrl": "https://developers.google.com/workspace/preview"
|
|
},
|
|
"redirectConstraints": "https-or-loopback-http",
|
|
"methods": [
|
|
{
|
|
"key": "paperclip-read",
|
|
"label": "Connect with Paperclip",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"oauthStrategy": "paperclip_cloud_connector",
|
|
"connectorProfile": "gmail.read",
|
|
"capabilityProfile": {
|
|
"key": "read",
|
|
"label": "Read only",
|
|
"description": "Search and read messages, threads, drafts, and labels."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"platform_shared"
|
|
],
|
|
"whenToUse": "Use Paperclip-managed Google OAuth for read-only Gmail access.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly"
|
|
]
|
|
},
|
|
"guidanceMd": "Connect Gmail with read-only access. Sending, deleting, moving, and relabeling mail are not enabled.",
|
|
"warnings": [
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S3"
|
|
},
|
|
{
|
|
"key": "customer-read-oauth",
|
|
"label": "Use your own Google OAuth app",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"capabilityProfile": {
|
|
"key": "read",
|
|
"label": "Read only",
|
|
"description": "Search and read messages, threads, drafts, and labels."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"customer"
|
|
],
|
|
"whenToUse": "Use a customer-owned Google OAuth client for read-only Gmail access.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
|
|
"tokenEndpoint": "https://oauth2.googleapis.com/token",
|
|
"metadataUrl": "https://accounts.google.com/.well-known/openid-configuration",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly"
|
|
],
|
|
"oauthAuthorizationParams": {
|
|
"access_type": "offline",
|
|
"prompt": "consent"
|
|
}
|
|
},
|
|
"guidanceMd": "Enable the Gmail and Gmail MCP APIs in your Google Cloud project, then register Paperclip's callback URI.",
|
|
"consoleLinks": {
|
|
"register": "https://console.cloud.google.com/auth/clients",
|
|
"docs": "https://developers.google.com/workspace/guides/configure-mcp-servers"
|
|
},
|
|
"warnings": [
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S3"
|
|
},
|
|
{
|
|
"key": "paperclip-draft",
|
|
"label": "Connect with Paperclip",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"oauthStrategy": "paperclip_cloud_connector",
|
|
"connectorProfile": "gmail.draft",
|
|
"capabilityProfile": {
|
|
"key": "draft",
|
|
"label": "Read & create drafts",
|
|
"description": "Read Gmail and create drafts for review in Gmail."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"platform_shared"
|
|
],
|
|
"whenToUse": "Use Paperclip-managed Google OAuth to read Gmail and create drafts.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly",
|
|
"https://www.googleapis.com/auth/gmail.compose"
|
|
]
|
|
},
|
|
"guidanceMd": "Connect Gmail to search and read mail and create drafts. Sending mail is permanently disabled.",
|
|
"warnings": [
|
|
"Draft creation requires approval. Sending mail is not enabled.",
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S4"
|
|
},
|
|
{
|
|
"key": "customer-draft-oauth",
|
|
"label": "Use your own Google OAuth app",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"capabilityProfile": {
|
|
"key": "draft",
|
|
"label": "Read & create drafts",
|
|
"description": "Read Gmail and create drafts for review in Gmail."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"customer"
|
|
],
|
|
"whenToUse": "Use a customer-owned Google OAuth client to read Gmail and create drafts.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
|
|
"tokenEndpoint": "https://oauth2.googleapis.com/token",
|
|
"metadataUrl": "https://accounts.google.com/.well-known/openid-configuration",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly",
|
|
"https://www.googleapis.com/auth/gmail.compose"
|
|
],
|
|
"oauthAuthorizationParams": {
|
|
"access_type": "offline",
|
|
"prompt": "consent"
|
|
}
|
|
},
|
|
"guidanceMd": "Enable the Gmail and Gmail MCP APIs in your Google Cloud project, then register Paperclip's callback URI.",
|
|
"consoleLinks": {
|
|
"register": "https://console.cloud.google.com/auth/clients",
|
|
"docs": "https://developers.google.com/workspace/guides/configure-mcp-servers"
|
|
},
|
|
"warnings": [
|
|
"Draft creation requires approval. Sending mail is not enabled.",
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S4"
|
|
},
|
|
{
|
|
"key": "paperclip-archive",
|
|
"label": "Connect with Paperclip",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"oauthStrategy": "paperclip_cloud_connector",
|
|
"connectorProfile": "gmail.archive",
|
|
"capabilityProfile": {
|
|
"key": "archive",
|
|
"label": "Read & archive",
|
|
"description": "Read Gmail and archive threads by removing only the Inbox label."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"platform_shared"
|
|
],
|
|
"whenToUse": "Use Paperclip-managed Google OAuth to read Gmail and archive threads.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly",
|
|
"https://www.googleapis.com/auth/gmail.modify"
|
|
]
|
|
},
|
|
"guidanceMd": "Connect Gmail to search and read mail and archive threads. Archive removes only the Inbox label; sending, trashing, and other label changes remain disabled.",
|
|
"warnings": [
|
|
"Archiving requires approval and only removes the Inbox label.",
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S4"
|
|
},
|
|
{
|
|
"key": "customer-archive-oauth",
|
|
"label": "Use your own Google OAuth app",
|
|
"transport": "mcp_remote",
|
|
"auth": "oauth",
|
|
"capabilityProfile": {
|
|
"key": "archive",
|
|
"label": "Read & archive",
|
|
"description": "Read Gmail and archive threads by removing only the Inbox label."
|
|
},
|
|
"grantKinds": [
|
|
"user",
|
|
"organization"
|
|
],
|
|
"ownershipModes": [
|
|
"customer"
|
|
],
|
|
"whenToUse": "Use a customer-owned Google OAuth client to read Gmail and archive threads.",
|
|
"defaults": {
|
|
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
|
|
"authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
|
|
"tokenEndpoint": "https://oauth2.googleapis.com/token",
|
|
"metadataUrl": "https://accounts.google.com/.well-known/openid-configuration",
|
|
"scopesHint": [
|
|
"https://www.googleapis.com/auth/gmail.readonly",
|
|
"https://www.googleapis.com/auth/gmail.modify"
|
|
],
|
|
"oauthAuthorizationParams": {
|
|
"access_type": "offline",
|
|
"prompt": "consent"
|
|
}
|
|
},
|
|
"guidanceMd": "Enable the Gmail and Gmail MCP APIs in your Google Cloud project, then register Paperclip's callback URI. Archive removes only the Inbox label.",
|
|
"consoleLinks": {
|
|
"register": "https://console.cloud.google.com/auth/clients",
|
|
"docs": "https://developers.google.com/workspace/guides/configure-mcp-servers"
|
|
},
|
|
"warnings": [
|
|
"Archiving requires approval and only removes the Inbox label.",
|
|
"Google Workspace MCP servers are in Developer Preview."
|
|
],
|
|
"riskTier": "S4"
|
|
}
|
|
]
|
|
}
|