matimo-gmail 0.1.0__tar.gz

matimo_gmail-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+**/node_modules/
+package-lock.json
+yarn.lock
+
+# Build output
+**/dist/
+*.tsbuildinfo
+
+# Python compiled / build
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+**/build/
+**/.eggs/
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# Test coverage
+**/coverage/
+**/.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+typescript/examples/mcp/matimo-tools/.matimo-approvals.json
+typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
+typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
+typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/matimo-health-check/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/moltbook-identity/SKILL.md
+typescript/packages/cli/.matimo/certs/server.crt
+typescript/packages/cli/.matimo/certs/server.key
+typescript/examples/mcp/.matimo/certs/server.crt
+typescript/examples/mcp/.matimo/certs/server.key

matimo_gmail-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: matimo-gmail
+Version: 0.1.0
+Summary: Matimo provider — Gmail tools (send, list, read, delete emails)
+License: MIT
+Keywords: agents,ai,gmail,matimo,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# matimo-gmail
+
+> Gmail tools for [Matimo](https://matimo.dev) — send, list, read, and delete emails.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-gmail)](https://pypi.org/project/matimo-gmail/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-gmail
+```
+
+---
+
+## Available Tools (6 Total)
+
+| Tool | Description |
+|------|-------------|
+| `send-email` | Send an email (to, subject, body, cc, bcc, html) |
+| `list-messages` | List messages with optional query/label filters |
+| `get-message` | Get full message content by ID |
+| `create-draft` | Create a draft email |
+| `delete-message` | Move message to trash |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_gmail import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Send an email
+    await matimo.execute('send-email', {
+        'to': 'user@example.com',
+        'subject': 'Hello from Matimo',
+        'body': 'This message was sent by an AI agent.',
+    })
+
+    # List recent messages
+    result = await matimo.execute('list-messages', {
+        'query': 'is:unread',
+        'max_results': 10,
+    })
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+Gmail tools use OAuth2. Set your credentials via environment variables:
+
+```bash
+export GMAIL_ACCESS_TOKEN="ya29.your-oauth2-access-token"
+# Or use a service account
+export GMAIL_SERVICE_ACCOUNT_JSON="/path/to/service-account.json"
+```
+
+### Getting an Access Token (OAuth2)
+
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the **Gmail API**
+3. Create OAuth 2.0 credentials (Desktop app)
+4. Run the OAuth flow to get an access token
+
+---
+
+## Documentation
+
+- [Gmail API Reference](https://developers.google.com/gmail/api/reference/rest)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/gmail)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-gmail/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Gmail API Docs:** https://developers.google.com/gmail/api
+

matimo_gmail-0.1.0/README.md

@@ -0,0 +1,89 @@
+# matimo-gmail
+
+> Gmail tools for [Matimo](https://matimo.dev) — send, list, read, and delete emails.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-gmail)](https://pypi.org/project/matimo-gmail/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-gmail
+```
+
+---
+
+## Available Tools (6 Total)
+
+| Tool | Description |
+|------|-------------|
+| `send-email` | Send an email (to, subject, body, cc, bcc, html) |
+| `list-messages` | List messages with optional query/label filters |
+| `get-message` | Get full message content by ID |
+| `create-draft` | Create a draft email |
+| `delete-message` | Move message to trash |
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_gmail import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Send an email
+    await matimo.execute('send-email', {
+        'to': 'user@example.com',
+        'subject': 'Hello from Matimo',
+        'body': 'This message was sent by an AI agent.',
+    })
+
+    # List recent messages
+    result = await matimo.execute('list-messages', {
+        'query': 'is:unread',
+        'max_results': 10,
+    })
+
+asyncio.run(main())
+```
+
+---
+
+## Authentication
+
+Gmail tools use OAuth2. Set your credentials via environment variables:
+
+```bash
+export GMAIL_ACCESS_TOKEN="ya29.your-oauth2-access-token"
+# Or use a service account
+export GMAIL_SERVICE_ACCOUNT_JSON="/path/to/service-account.json"
+```
+
+### Getting an Access Token (OAuth2)
+
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable the **Gmail API**
+3. Create OAuth 2.0 credentials (Desktop app)
+4. Run the OAuth flow to get an access token
+
+---
+
+## Documentation
+
+- [Gmail API Reference](https://developers.google.com/gmail/api/reference/rest)
+- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/native/gmail)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-gmail/
+- **GitHub:** https://github.com/tallclub/matimo
+- **Gmail API Docs:** https://developers.google.com/gmail/api
+

matimo_gmail-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-gmail"
+version = "0.1.0"
+description = "Matimo provider — Gmail tools (send, list, read, delete emails)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "tools", "agents", "matimo", "gmail"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "matimo-core>=0.1.0,<0.2.0",
+]
+
+[project.entry-points."matimo.providers"]
+gmail = "matimo_gmail:get_tools_path"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_gmail"]

matimo_gmail-0.1.0/src/matimo_gmail/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo gmail provider — exposes the path to YAML tool definitions."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_tools_path() -> str:
+    """Return the absolute path to the bundled gmail tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_gmail") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_gmail-0.1.0/src/matimo_gmail/tools/create-draft/definition.yaml

@@ -0,0 +1,99 @@
+name: gmail-create-draft
+description: Create a draft email in Gmail without sending it
+version: '1.0.0'
+
+parameters:
+  to:
+    type: string
+    description: Email address of the recipient(s), comma-separated for multiple recipients
+    required: true
+    example: 'user@example.com'
+
+  subject:
+    type: string
+    description: Subject line of the draft email
+    required: true
+    example: 'Draft Email'
+
+  body:
+    type: string
+    description: Email body content (plain text or HTML)
+    required: true
+    example: 'This is a draft email'
+
+  cc:
+    type: string
+    description: CC email addresses, comma-separated
+    required: false
+    example: 'cc@example.com'
+
+  bcc:
+    type: string
+    description: BCC email addresses, comma-separated
+    required: false
+    example: 'bcc@example.com'
+
+  isHtml:
+    type: boolean
+    description: Whether the body content is HTML (default is plain text)
+    required: false
+    default: false
+
+  raw:
+    type: string
+    description: 'Base64url-encoded MIME message (RFC 2822 format). If provided, overrides to/subject/body/cc/bcc parameters.'
+    required: false
+    example: 'VG8...'
+
+execution:
+  type: http
+  method: POST
+  url: 'https://www.googleapis.com/gmail/v1/users/me/drafts'
+  headers:
+    Content-Type: 'application/json'
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+  # Parameter encoding: automatically convert to/subject/body to MIME format
+  parameter_encoding:
+    - source: [to, subject, body, cc, bcc, isHtml]
+      target: raw
+      encoding: mime_rfc2822_base64url
+
+  body:
+    message:
+      raw: '{raw}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.compose'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Draft ID
+    message:
+      type: object
+      description: The created message object
+      properties:
+        id:
+          type: string
+        threadId:
+          type: string
+        labelIds:
+          type: array
+          items:
+            type: string
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

matimo_gmail-0.1.0/src/matimo_gmail/tools/delete-message/definition.yaml

@@ -0,0 +1,38 @@
+name: gmail-delete-message
+description: Permanently delete a message from Gmail (cannot be undone)
+version: '1.0.0'
+
+parameters:
+  messageId:
+    type: string
+    description: ID of the message to delete
+    required: true
+    example: '187a65b7f3f2f11e'
+
+execution:
+  type: http
+  method: DELETE
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/{messageId}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+  note: 'Immediately and permanently deletes the message. This operation cannot be undone. Use trash instead if you want to allow recovery.'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.modify'
+
+output_schema:
+  type: object
+  description: Empty response on successful deletion (204 No Content). The executor may return an empty body for 204 responses.
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

matimo_gmail-0.1.0/src/matimo_gmail/tools/get-message/definition.yaml

@@ -0,0 +1,90 @@
+name: gmail-get-message
+description: Get full details of a specific Gmail message including headers and body
+version: '1.0.0'
+
+parameters:
+  messageId:
+    type: string
+    description: ID of the message to retrieve
+    required: true
+    example: '187a65b7f3f2f11e'
+
+  format:
+    type: string
+    enum:
+      - minimal
+      - full
+      - raw
+    description: Format of the message to return
+    required: false
+    default: full
+    example: full
+
+  metadataHeaders:
+    type: string
+    description: Comma-separated headers to include in metadata (when format=minimal)
+    required: false
+    example: 'From,Subject,Date'
+
+execution:
+  type: http
+  method: GET
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/{messageId}'
+  query_params:
+    format: '{format}'
+    metadataHeaders: '{metadataHeaders}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+    Accept: 'application/json'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.readonly'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Message ID
+    threadId:
+      type: string
+      description: Thread ID
+    labelIds:
+      type: array
+      items:
+        type: string
+      description: Array of label IDs applied to this message
+    snippet:
+      type: string
+      description: Short snippet of the message text
+    sizeEstimate:
+      type: number
+      description: Estimated size of the message in bytes
+    headers:
+      type: object
+      description: Message headers (From, To, Subject, Date, etc.)
+    body:
+      type: object
+      description: Message body with data and mimeType
+      properties:
+        mimeType:
+          type: string
+        data:
+          type: string
+          description: Message body data (base64 encoded if raw format)
+    error:
+      type: string
+      description: Error message if request failed
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

matimo_gmail-0.1.0/src/matimo_gmail/tools/list-messages/definition.yaml

@@ -0,0 +1,84 @@
+name: gmail-list-messages
+description: List messages from Gmail mailbox with filtering and pagination
+version: '1.0.0'
+
+parameters:
+  query:
+    type: string
+    description: Gmail search query (e.g., 'from:user@example.com', 'subject:hello', 'is:unread')
+    required: false
+    example: 'is:unread'
+
+  maxResults:
+    type: number
+    description: Maximum number of messages to return (1-500, defaults to 100)
+    required: false
+    default: 100
+    example: 20
+
+  pageToken:
+    type: string
+    description: Page token for pagination
+    required: false
+    example: 'NEXT_PAGE_TOKEN'
+
+  includeSpamTrash:
+    type: boolean
+    description: Include spam and trash in results (defaults to false)
+    required: false
+    default: false
+
+  labelIds:
+    type: string
+    description: Comma-separated label IDs to filter by
+    required: false
+    example: 'INBOX,IMPORTANT'
+
+execution:
+  type: http
+  method: GET
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages'
+  query_params:
+    q: '{query}'
+    maxResults: '{maxResults}'
+    pageToken: '{pageToken}'
+    includeSpamTrash: '{includeSpamTrash}'
+    labelIds: '{labelIds}'
+  headers:
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.readonly'
+
+output_schema:
+  type: object
+  properties:
+    messages:
+      type: array
+      description: List of message objects (contains only id and threadId)
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          threadId:
+            type: string
+    nextPageToken:
+      type: string
+      description: Token for fetching next page of results
+    resultSizeEstimate:
+      type: number
+      description: Estimated total number of results
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503

matimo_gmail-0.1.0/src/matimo_gmail/tools/send-email/definition.yaml

@@ -0,0 +1,95 @@
+name: gmail-send-email
+description: Send an email using Gmail API with MIME format encoding
+version: '1.0.0'
+
+parameters:
+  to:
+    type: string
+    description: Email address of the recipient(s), comma-separated for multiple recipients
+    required: true
+    example: 'user@example.com'
+
+  subject:
+    type: string
+    description: Subject line of the email
+    required: true
+    example: 'Hello from Matimo'
+
+  body:
+    type: string
+    description: Email body content (plain text or HTML)
+    required: true
+    example: 'This is a test email from Matimo'
+
+  cc:
+    type: string
+    description: CC email addresses, comma-separated
+    required: false
+    example: 'cc@example.com'
+
+  bcc:
+    type: string
+    description: BCC email addresses, comma-separated
+    required: false
+    example: 'bcc@example.com'
+
+  isHtml:
+    type: boolean
+    description: Whether the body content is HTML (default is plain text)
+    required: false
+    default: false
+
+  raw:
+    type: string
+    description: 'Base64url-encoded MIME message (RFC 2822 format). If provided, overrides to/subject/body/cc/bcc parameters.'
+    required: false
+    example: 'VG8...'
+
+execution:
+  type: http
+  method: POST
+  url: 'https://www.googleapis.com/gmail/v1/users/me/messages/send'
+  headers:
+    Content-Type: 'application/json'
+    Authorization: 'Bearer {GMAIL_ACCESS_TOKEN}'
+
+  # Parameter encoding: automatically convert to/subject/body to MIME format
+  parameter_encoding:
+    - source: [to, subject, body, cc, bcc, isHtml]
+      target: raw
+      encoding: mime_rfc2822_base64url
+
+  body:
+    raw: '{raw}'
+
+authentication:
+  type: oauth2
+  provider: google
+  scopes:
+    - 'https://www.googleapis.com/auth/gmail.send'
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Message ID of the sent email
+    threadId:
+      type: string
+      description: Thread ID of the sent email
+    labelIds:
+      type: array
+      items:
+        type: string
+      description: Label IDs applied to the message
+
+error_handling:
+  retry: 3
+  backoff_type: exponential
+  initial_delay_ms: 1000
+  max_delay_ms: 10000
+  retryable_status_codes:
+    - 429
+    - 500
+    - 502
+    - 503