maton

通过 Maton AI 连接到 SaaS 工具。包括 Clawdbot 网关仪表板的完整 UI 集成。在设置 Maton 集成、连接应用程序（Gmail、Slack、Notion、HubSpot 等）或管理 OAuth 连接时使用。

# Maton AI

Connect your AI agent to SaaS tools via Maton's OAuth connection management. This skill provides:

- **Full UI Dashboard** — Configure API key, view connections, initiate OAuth flows
- **Multi-App Support** — Gmail, Slack, Notion, HubSpot, Jira, Google Workspace, and more
- **Connection Management** — Create, monitor, and delete app connections
- **API Keys Integration** — Maton API key appears in the API Keys tab for easy configuration

## Overview

Maton provides a unified API for connecting to SaaS tools via OAuth. Once connected, you can interact with these tools through Maton's AI capabilities or directly via their API.

## Prerequisites

1. **Maton Account** — Sign up at [maton.ai](https://maton.ai)
2. **API Key** — Get your API key from the Maton dashboard
3. **Clawdbot Gateway** — v2026.1.0 or later with UI enabled

## Quick Start

### Step 1: Get Your API Key

1. Go to [maton.ai](https://maton.ai) and sign in
2. Navigate to Settings → API Keys
3. Create or copy your API key

### Step 2: Configure in Clawdbot UI

**Option A: Via API Keys tab**
1. Open Clawdbot Dashboard → **Settings** → **API Keys**
2. Find "Maton" in the Environment Keys section
3. Enter your API key and click Save

**Option B: Via Maton tab**
1. Open Clawdbot Dashboard → **Tools** → **Maton**
2. Click **Configure**
3. Paste your API key
4. Click **Save**

### Step 3: Connect Apps

1. Go to **Tools** → **Maton**
2. Click **Connect App** and select an app (e.g., Gmail, Slack)
3. Complete the OAuth flow in the popup window
4. Once status shows **ACTIVE**, the connection is ready

## Supported Apps

Maton supports 50+ SaaS applications including:

| Category | Apps |
|----------|------|
| **Google Workspace** | Gmail, Calendar, Docs, Sheets, Drive, Slides, Ads, Analytics |
| **Productivity** | Notion, Airtable, Jira, Calendly |
| **Communication** | Slack, Outlook |
| **CRM** | HubSpot, Apollo |
| **Media** | YouTube |

## API Reference

### Base URL
```
https://ctrl.maton.ai
```

### Authentication
All requests require a Bearer token:
```bash
curl https://ctrl.maton.ai/connections \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/connections` | List all connections |
| POST | `/connections` | Create new connection |
| GET | `/connections/{id}` | Get connection details |
| DELETE | `/connections/{id}` | Delete connection |

### Connection Status

| Status | Description |
|--------|-------------|
| `PENDING` | OAuth flow not completed; `url` contains OAuth link |
| `ACTIVE` | Connection established and ready to use |
| `FAILED` | Connection failed; reconnection required |

## Architecture

### Configuration Storage

The Maton API key is stored in the main Clawdbot config file:

```json
{
  "env": {
    "MATON_API_KEY": "your-api-key-here"
  }
}
```

This integrates with the API Keys tab for centralized key management.

### Backend RPC Methods

| Method | Purpose |
|--------|---------|
| `maton.status` | Get API key status and connection count |
| `maton.save` | Validate and store API key |
| `maton.test` | Test the API key |
| `maton.disconnect` | Remove API key |
| `maton.connections` | List all connections |
| `maton.connect` | Create a new connection (returns OAuth URL) |
| `maton.delete` | Delete a connection |
| `maton.apps` | List supported apps |

### UI Components

| File | Purpose |
|------|---------|
| `maton-backend.ts` | Gateway RPC handlers |
| `maton-controller.ts` | UI state management |
| `maton-views.ts` | Lit HTML templates |

## Installation

See `reference/README.md` for detailed integration instructions.

### Quick Integration

1. Copy backend handler to `src/gateway/server-methods/maton.ts`
2. Copy UI files to `ui/src/ui/views/` and `ui/src/ui/controllers/`
3. Add "maton" tab to navigation
4. Add `MATON_API_KEY` to API keys discovery
5. Rebuild and restart

## UI Features

### Maton Tab (Tools → Maton)
- Connection status with active/pending counts
- API key configuration form
- Connected apps list with status badges
- App picker modal for new connections
- One-click OAuth flow initiation

### API Keys Tab Integration
- Shows "Maton" in Environment Keys section
- Direct input field for API key
- Save/Clear functionality

## Security

| Aspect | Implementation |
|--------|----------------|
| **Key Storage** | Main config file (`~/.clawdbot/clawdbot.json`) |
| **Key Access** | Never exposed to AI agent |
| **OAuth Tokens** | Managed by Maton (automatic refresh) |

**Best practices:**
- Rotate API keys periodically
- Review connected apps regularly
- Disconnect unused connections

## Troubleshooting

### "Unauthorized" error
- Verify your API key is correct
- Check that the key hasn't been revoked
- Regenerate in Maton dashboard if needed

### Connection stuck in PENDING
- OAuth flow wasn't completed
- Try the OAuth URL again
- Delete and recreate if URL expired

### Connection shows FAILED
- OAuth token may have expired
- Delete the connection and create new one

### Maton not in API Keys tab
- Ensure you're on Clawdbot v2026.1.0+
- Refresh the page after gateway restart

## Reference Files

- `reference/maton-backend.ts` — Gateway RPC handlers
- `reference/maton-controller.ts` — UI controller logic  
- `reference/maton-views.ts` — UI rendering (Lit)
- `reference/README.md` — Installation guide

## Support

- **Maton**: [maton.ai](https://maton.ai)
- **ClawdHub**: [clawdhub.com/skills/maton](https://clawdhub.com/skills/maton)
- **Discord**: [discord.com/invite/clawd](https://discord.com/invite/clawd)

---

## 中文说明

# Maton AI

通过 Maton 的 OAuth 连接管理，将你的 AI agent 连接到 SaaS 工具。本技能提供：

- **完整 UI 仪表板** —— 配置 API key、查看连接、发起 OAuth 流程
- **多应用支持** —— Gmail、Slack、Notion、HubSpot、Jira、Google Workspace 等
- **连接管理** —— 创建、监控和删除应用连接
- **API Keys 集成** —— Maton API key 出现在 API Keys 标签页中，便于配置

## 概述

Maton 提供统一的 API，通过 OAuth 连接 SaaS 工具。连接后，你可以通过 Maton 的 AI 能力或直接通过其 API 与这些工具交互。

## 前置条件

1. **Maton 账户** —— 在 [maton.ai](https://maton.ai) 注册
2. **API Key** —— 从 Maton 仪表板获取你的 API key
3. **Clawdbot Gateway** —— v2026.1.0 或更高版本，并启用 UI

## 快速开始

### 步骤 1：获取你的 API Key

1. 前往 [maton.ai](https://maton.ai) 并登录
2. 导航到 Settings → API Keys
3. 创建或复制你的 API key

### 步骤 2：在 Clawdbot UI 中配置

**选项 A：通过 API Keys 标签页**
1. 打开 Clawdbot Dashboard → **Settings** → **API Keys**
2. 在 Environment Keys 区域找到 "Maton"
3. 输入你的 API key 并点击 Save

**选项 B：通过 Maton 标签页**
1. 打开 Clawdbot Dashboard → **Tools** → **Maton**
2. 点击 **Configure**
3. 粘贴你的 API key
4. 点击 **Save**

### 步骤 3：连接应用

1. 前往 **Tools** → **Maton**
2. 点击 **Connect App** 并选择一个应用（如 Gmail、Slack）
3. 在弹出窗口中完成 OAuth 流程
4. 当状态显示 **ACTIVE** 时，连接即就绪

## 支持的应用

Maton 支持 50 多个 SaaS 应用，包括：

| 类别 | 应用 |
|----------|------|
| **Google Workspace** | Gmail、Calendar、Docs、Sheets、Drive、Slides、Ads、Analytics |
| **效率工具** | Notion、Airtable、Jira、Calendly |
| **通讯** | Slack、Outlook |
| **CRM** | HubSpot、Apollo |
| **媒体** | YouTube |

## API 参考

### 基址
```
https://ctrl.maton.ai
```

### 认证
所有请求都需要 Bearer token：
```bash
curl https://ctrl.maton.ai/connections \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 端点

| 方法 | 端点 | 说明 |
|--------|----------|-------------|
| GET | `/connections` | 列出所有连接 |
| POST | `/connections` | 创建新连接 |
| GET | `/connections/{id}` | 获取连接详情 |
| DELETE | `/connections/{id}` | 删除连接 |

### 连接状态

| 状态 | 说明 |
|--------|-------------|
| `PENDING` | OAuth 流程未完成；`url` 包含 OAuth 链接 |
| `ACTIVE` | 连接已建立并可使用 |
| `FAILED` | 连接失败；需要重新连接 |

## 架构

### 配置存储

Maton API key 存储在 Clawdbot 主配置文件中：

```json
{
  "env": {
    "MATON_API_KEY": "your-api-key-here"
  }
}
```

这与 API Keys 标签页集成，实现集中式的密钥管理。

### 后端 RPC 方法

| 方法 | 用途 |
|--------|---------|
| `maton.status` | 获取 API key 状态和连接数量 |
| `maton.save` | 验证并存储 API key |
| `maton.test` | 测试 API key |
| `maton.disconnect` | 移除 API key |
| `maton.connections` | 列出所有连接 |
| `maton.connect` | 创建新连接（返回 OAuth URL） |
| `maton.delete` | 删除一个连接 |
| `maton.apps` | 列出支持的应用 |

### UI 组件

| 文件 | 用途 |
|------|---------|
| `mat