# SOTA Agentic Gateway — MCP server & Claude plugin

> **Thử nghiệm nội bộ — CHƯA phát hành lên PyPI.** Cài từ GitHub như bên dưới. Đừng dùng `uvx sota-agw-mcp` (không
> `--from`): tên đó chưa đăng ký trên PyPI, lệnh sẽ tra PyPI và có thể cài gói của người khác.

MCP server cho việc tiếp nhận & phản hồi email / tin nhắn trong logistics, chuỗi cung ứng, thương mại: phân loại hộp
thư (luật quảng cáo / lừa đảo), trích chữ file đính kèm, điền template DOCX / XLSX tô vàng, tra thư mục tri thức, soạn
nháp — và **chỉ gửi sau khi bạn xác nhận**. Tuỳ chọn nối workspace SaaS SOTA Agentic Gateway (gửi = tạo yêu cầu duyệt).

- Không có công cụ nào tự gửi hay tự duyệt. Gửi email cục bộ cần bạn bấm xác nhận trong hộp thoại của client (MCP
  elicitation); client không có hộp thoại → server trả lệnh terminal (`… -m agw_mcp send <draft_id>`) để bạn tự chạy.
- IMAP chỉ đọc. File chỉ đọc / ghi trong thư mục làm việc `AGW_WORKDIR`.
- Nội dung email / file được coi là dữ liệu bên ngoài — không phải lệnh.

## Cài & chạy

Cần [uv](https://docs.astral.sh/uv/). Client gọi `uvx --from git+https://github.com/thanhtrung665/gateway-agent-mcp sota-agw-mcp` (stdio) — uv tự tải từ GitHub.
Muốn cố định phiên bản: thêm `@<commit>` hoặc `@<tag>` sau URL.

**Claude Code**

```bash
claude mcp add sota-agw -e AGW_WORKDIR=$HOME/SOTA-Agentic-Gateway -- uvx --from git+https://github.com/thanhtrung665/gateway-agent-mcp sota-agw-mcp
# hoặc cài plugin (có thêm skill + ô cấu hình) — marketplace có 2 plugin, chọn theo chế độ:
claude plugin marketplace add thanhtrung665/gateway-agent-mcp
claude plugin install sota-agentic-gateway@sota-agentic-gateway         # cục bộ: IMAP, file, template trên máy (cần uv)
claude plugin install sota-agentic-gateway-remote@sota-agentic-gateway  # remote: workspace SaaS qua OAuth, không cài gì
```

| Plugin | Chạy ở đâu | Công cụ | Đăng nhập |
|---|---|---|---|
| `sota-agentic-gateway` | máy bạn (`uv run --script`) | 11 công cụ cục bộ (+ `saas_*` nếu điền `api_url` + `api_key`), 5 skill | IMAP App Password / API key |
| `sota-agentic-gateway-remote` | API SaaS `https://<api>/mcp` | 14 công cụ `saas_*`, skill `sota-saas` | OAuth trong `/mcp` |

Cài cả hai được (vd hộp thư cục bộ + workspace); khi đó để trống `api_url` / `api_key` của plugin cục bộ để khỏi trùng
công cụ `saas_*`.

**Prompts** (client không có skill vẫn đi đúng quy trình duyệt): cục bộ `triage_local`, `reply_local`,
`fill_template_local`; workspace `inbox_saas`, `reply_saas` — trong Claude Code gõ `/` để thấy.

**Claude Desktop** (`claude_desktop_config.json`) · **Cursor** (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "sota-agw": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/thanhtrung665/gateway-agent-mcp", "sota-agw-mcp"],
      "env": {
        "AGW_WORKDIR": "/Users/ban/SOTA-Agentic-Gateway",
        "AGW_IMAP_HOST": "imap.gmail.com",
        "AGW_IMAP_USER": "ban@congty.vn",
        "AGW_IMAP_PASSWORD": "<app password>",
        "AGW_SMTP_HOST": "smtp.gmail.com"
      }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "sota-agw": { "type": "stdio", "command": "uvx", "args": ["--from", "git+https://github.com/thanhtrung665/gateway-agent-mcp", "sota-agw-mcp"], "env": { "AGW_WORKDIR": "${userHome}/SOTA-Agentic-Gateway" } }
  }
}
```

Kiểm cấu hình: `uvx --from git+https://github.com/thanhtrung665/gateway-agent-mcp sota-agw-mcp check` (in thư mục làm việc, thử đăng nhập IMAP / SaaS — không in mật khẩu).

## Cấu hình (biến môi trường)

| Biến | Ý nghĩa |
|---|---|
| `AGW_WORKDIR` | Thư mục làm việc (`templates/`, `knowledge/`, `output/`, `drafts/`). Mặc định `~/SOTA-Agentic-Gateway` |
| `AGW_IMAP_HOST` · `AGW_IMAP_PORT` · `AGW_IMAP_USER` · `AGW_IMAP_PASSWORD` | Hộp thư (IMAP SSL, mặc định cổng 993). Dùng **App Password**, không dùng mật khẩu chính |
| `AGW_SMTP_HOST` · `AGW_SMTP_PORT` · `AGW_SMTP_USER` · `AGW_SMTP_PASSWORD` · `AGW_MAIL_FROM` | Gửi (mặc định 587 STARTTLS; user / mật khẩu mặc định = IMAP) |
| `AGW_INTERNAL_DOMAINS` | Domain nội bộ (phân cách dấu phẩy) — dùng cho cảnh báo giả mạo |
| `AGW_SEND_MODE` | `elicit` (mặc định: hỏi xác nhận trong client) · `cli` (chỉ gửi bằng lệnh terminal) · `disabled` |
| `AGW_API_URL` · `AGW_API_KEY` | Nối workspace SaaS (API key `agw_…`, vai trò MEMBER là đủ) → thêm công cụ `saas_*` |

Mật khẩu nằm trong file cấu hình của client dưới dạng chữ thường — dùng App Password riêng, thu hồi được. Bản plugin
Claude Code lưu các ô bí mật an toàn hơn (`userConfig` sensitive).

## Remote MCP (workspace SaaS — không cần cài gì)

Dán `https://<api-saas>/mcp` vào client hỗ trợ MCP từ xa: client mở trang đăng nhập + đồng ý (OAuth 2.1), hoặc gửi
header `Authorization: Bearer agw_…`. Mã endpoint là gói `agw_remote_mcp` trong gói này; máy chủ uỷ quyền nằm ở API SaaS.

```bash
claude mcp add --transport http sota-agw-remote https://<api-saas>/mcp
```

## Trong gói

| Gói | Nội dung |
|---|---|
| `agw_mcp` | MCP server cục bộ (stdio) — lệnh `sota-agw-mcp` |
| `agw_core` | Lõi thuần Python: tách email RFC 822, luật quảng cáo / an ninh, BM25 + RRF, trích chữ PDF / DOCX / XLSX / EML, template tô vàng, định nghĩa công cụ SaaS dùng chung |
| `agw_remote_mcp` | Remote MCP (ASGI, Streamable HTTP stateless) cho API SaaS |

Mã nguồn, Claude plugin và skill: <https://github.com/thanhtrung665/gateway-agent-mcp>

## Phát triển

```bash
uv sync
uv run pytest -q                                   # plugin + gói + remote MCP (không cần SaaS, không ra mạng)
uv run ruff check .
python -X utf8 scripts/sync_plugin_core.py         # sau khi sửa agw_core/ hoặc agw_mcp/server.py → chép vào plugin
uv build && uv run python scripts/smoke_stdio.py uvx --isolated --from dist/<wheel> sota-agw-mcp
claude plugin validate plugin/sota-agentic-gateway && claude plugin validate plugin/sota-agentic-gateway-remote && claude plugin validate .
```

`plugin/sota-agentic-gateway/server/agw_mcp.py` là bản chép y hệt `agw_mcp/server.py` (plugin chạy bằng
`uv run --script`, phụ thuộc khai ở khối `# /// script` đầu file — test kiểm khớp `pyproject.toml`). Repo SaaS cài gói
này qua git dependency ghim commit (`sota-agw-mcp[remote] @ git+https://github.com/thanhtrung665/gateway-agent-mcp@<commit>`).

Phát hành PyPI (**chưa làm** — quyết định 2026-11-07: chỉ nội bộ): khi được chốt, tạo pending publisher trên pypi.org /
test.pypi.org rồi tag `test-vX.Y.Z` (TestPyPI) → `vX.Y.Z` (PyPI) — workflow `publish.yml` (Trusted Publishing).

## Giấy phép

Thương mại — xem [LICENSE](https://github.com/thanhtrung665/gateway-agent-mcp/blob/main/LICENSE).