{"_id":"@aimform/gmail","name":"@aimform/gmail","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aimform/gmail","private":false,"version":"1.0.0","description":"Aimform Gmail App — read, search, send, and manage emails from Gmail. Official app published by Aimform.","type":"module","sideEffects":false,"license":"MIT","author":{"name":"Aimform / Universal Reason LLC"},"repository":{"type":"git","url":"git+https://github.com/adamhalasz/saas-stack.git","directory":"aimform-apps/gmail"},"keywords":["aimform","gmail","email","mcp","app","google"],"main":"src/index.ts","types":"src/index.ts","scripts":{"typecheck":"tsc --noEmit","dev":"wrangler dev","deploy":"wrangler deploy"},"dependencies":{"@aimform/apps":"^0.1.1","googleapis":"^142.0.0","hono":"^4.7.0","zod":"^3.24.0"},"devDependencies":{"@cloudflare/workers-types":"^4.20250224.0","typescript":"^5.7.0","wrangler":"^3.99.0"},"gitHead":"679b65b23d6a7fbbcbe8e6d5de9486688bdb8e0d","_id":"@aimform/gmail@1.0.0","bugs":{"url":"https://github.com/adamhalasz/saas-stack/issues"},"homepage":"https://github.com/adamhalasz/saas-stack#readme","_nodeVersion":"25.6.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-rp8VsvucGJAzrcHWxrFMMqU6aplEOkTmgB99dVaAgNpulTkaMr/KI6R6clvEiDgOS6Pn1mprHEgVIy7UML7fkA==","shasum":"60031987cc64993b4c1531df07a4c5c98102fed4","tarball":"https://registry.npmjs.org/@aimform/gmail/-/gmail-1.0.0.tgz","fileCount":18,"unpackedSize":55117,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD8EwlFdVTT23KItjcQSAX4BXVRgBpFNThS/RZ92IgpLQIgRjnrRFx6gfDPmBxL1IduDG2ErXapVEdZVUGdfBNxDZ0="}]},"_npmUser":{"name":"adamhalasz","email":"mail@adamhalasz.com"},"directories":{},"maintainers":[{"name":"adamhalasz","email":"mail@adamhalasz.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gmail_1.0.0_1786105913569_0.6951028593497013"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T12:31:53.366Z","1.0.0":"2026-08-07T12:31:53.761Z","modified":"2026-08-07T12:31:54.042Z"},"maintainers":[{"name":"adamhalasz","email":"mail@adamhalasz.com"}],"description":"Aimform Gmail App — read, search, send, and manage emails from Gmail. Official app published by Aimform.","homepage":"https://github.com/adamhalasz/saas-stack#readme","keywords":["aimform","gmail","email","mcp","app","google"],"repository":{"type":"git","url":"git+https://github.com/adamhalasz/saas-stack.git","directory":"aimform-apps/gmail"},"author":{"name":"Aimform / Universal Reason LLC"},"bugs":{"url":"https://github.com/adamhalasz/saas-stack/issues"},"license":"MIT","readme":"# @aimform/gmail\n\nOfficial Gmail App for the Aimform platform. Published by Aimform.\n\nAn MCP (Model Context Protocol) server that provides Gmail integration — read, search, send, and manage emails via the Gmail API. Connects as an OAuth2 app to Google and exposes 7 tools to the Aimform platform.\n\n## Tools\n\n| Tool | Description | Risk Tier |\n|------|-------------|-----------|\n| `send_email` | Send a new email | confirm |\n| `read_email` | Read a single email by ID | auto |\n| `list_emails` | List inbox or label emails | auto |\n| `search_emails` | Search with Gmail syntax | auto |\n| `create_draft` | Create a draft email | auto |\n| `manage_labels` | CRUD labels and assignments | auto |\n| `get_thread` | Get all messages in a thread | auto |\n\n## Architecture\n\n```\nsrc/\n├── index.ts            # App entry point — defineApp + Hono app factory\n├── server.ts           # Hono server: CORS, routes, error handling\n├── config.ts           # Environment configuration & mock detection\n├── types.ts            # Domain types (Email, Draft, Label, tool I/O)\n├── gmail-client.ts     # Gmail API wrapper (real + mock implementations)\n└── tools/\n    ├── index.ts        # Barrel export, tool registry\n    ├── send-email.ts\n    ├── read-email.ts\n    ├── list-emails.ts\n    ├── search-emails.ts\n    ├── create-draft.ts\n    ├── manage-labels.ts\n    └── get-thread.ts\n```\n\nThe `GmailClient` wraps the official `googleapis` Gmail v1 API. When no Google OAuth2 credentials are provided (via environment variables), the client falls back to in-memory mock implementations for local development and testing.\n\n## Gmail API Setup\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2. Create a project (or use an existing one).\n3. Enable the **Gmail API**.\n4. Configure the **OAuth consent screen** (external, with scopes for Gmail read/write).\n5. Create an **OAuth 2.0 Web Application** credential.\n6. Add `https://app.aimform.com/oauth/google/callback` as an authorized redirect URI.\n7. Note the **Client ID** and **Client Secret**.\n\n### Required OAuth2 Scopes\n\n- `https://www.googleapis.com/auth/gmail.send` — Send emails\n- `https://www.googleapis.com/auth/gmail.readonly` — Read emails, threads, labels\n- `https://www.googleapis.com/auth/gmail.modify` — Modify labels on messages\n- `https://www.googleapis.com/auth/gmail.compose` — Create drafts\n- `https://www.googleapis.com/auth/gmail.labels` — Manage labels\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GOOGLE_CLIENT_ID` | For prod | Google OAuth2 client ID |\n| `GOOGLE_CLIENT_SECRET` | For prod | Google OAuth2 client secret |\n| `GOOGLE_REDIRECT_URI` | For prod | OAuth2 redirect URI |\n| `GOOGLE_REFRESH_TOKEN` | Optional | Pre-authorized refresh token for server-side flows |\n\nWhen these are not set, the server runs in **mock mode** with in-memory data.\n\n## Local Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Type check\npnpm typecheck\n\n# Run locally (Cloudflare Worker) — uses mock mode by default\npnpm dev\n```\n\nFor live Gmail API access locally, create a `.dev.vars` file:\n\n```\nGOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=your-client-secret\nGOOGLE_REDIRECT_URI=http://localhost:8787/oauth/google/callback\n```\n\n## Deployment\n\nDeploy as a Cloudflare Worker:\n\n```bash\npnpm run deploy\n```\n\nOr deploy via GitHub Actions (push to main).\n\n## MCP API\n\n### Introspection\n\n```\nGET / → JSON with all tool definitions\n```\n\n### Tool Calls\n\n```\nPOST /tools/:toolName → Execute a tool\nContent-Type: application/json\nBody: { ...tool input params... }\n```\n\nResponse:\n\n```json\n{ \"success\": true, \"data\": { ... } }\n```\n\nError response:\n\n```json\n{ \"success\": false, \"error\": \"Error message\" }\n```\n\n## License\n\nPrivate — Aimform official app.\n","readmeFilename":"README.md","_rev":"1-528d04cc0d9bde9f8294e28bf11c40c8"}