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. 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

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ì

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)

{
  "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)

{
  "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).

Related MCP server: Gmail MCP Server

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

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.

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

Trong gói

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

Phát triển

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.