# Mizito AI Connector

[![tests](https://github.com/Erfouni/mizito-ai-connector/actions/workflows/tests.yml/badge.svg)](https://github.com/Erfouni/mizito-ai-connector/actions/workflows/tests.yml) [![release](https://img.shields.io/github/v/release/Erfouni/mizito-ai-connector)](https://github.com/Erfouni/mizito-ai-connector/releases) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

یک MCP Server که حساب [میزیتو](https://mizito.ir) را به **Claude** و **ChatGPT** وصل می‌کند. با آن می‌توانید در چت این‌ها را بخوانید و تحلیل کنید: گفتگوها، پروژه‌ها، وظایف، تقویم، نامه‌ها، صورتجلسه‌ها، نظرسنجی‌ها، یادداشت‌ها و فایل‌ها (PDF، Word، Excel، عکس). اگر بخواهید، تقریباً هر کاری را هم که در وب میزیتو ممکن است انجام می‌دهد: پیام، نامه و پاراف؛ وظیفه با تکرار و یادآوری؛ کانبان و گانت؛ صورتجلسه و نظرسنجی؛ آپلود و پیوست فایل؛ CRM و مدیریت میزکار. **۱۰۵ ابزار** با توضیح کامل دارد که فهرستشان در [docs/TOOLS.md](docs/TOOLS.md) است.

*An MCP server that connects a Mizito workspace to Claude and ChatGPT (read, analyse, and optionally act).*

> **راه‌اندازی سریع · Quick setup: [SETUP.md](SETUP.md).** برای راه‌اندازی فقط یک دامنه و حساب میزیتوی خودتان لازم است و نصب روی سرور یک دستور است: `sudo bash deploy/install.sh`. *All you need is a domain and your Mizito account; the server install is one command.*

> این پروژه از API داخلی وب‌اپ میزیتو استفاده می‌کند که رسمی نیست. ممکن است با به‌روزرسانی میزیتو تغییر کند. جزئیات API در [API_MAP.md](API_MAP.md) آمده است.

```
Claude.ai / ChatGPT ──HTTPS (MCP)──► سرور شما (این پروژه) ──► app.mizito.ir
```

هر نفر سرور و توکن خودش را دارد. سرور فقط به حساب میزیتوی صاحبش دسترسی دارد.

## پیش‌نیازها

- Python 3.11 یا بالاتر و [uv](https://docs.astral.sh/uv/)
- یک حساب میزیتو
- برای استفاده در **Claude.ai یا ChatGPT** (نسخه‌ی وب و موبایل): یک سرور لینوکسی با دامنه و HTTPS. این سرور باید دو شرط را داشته باشد:
  1. به `app.mizito.ir` دسترسی داشته باشد.
  2. از خارج از ایران در دسترس باشد، چون سرورهای Anthropic و OpenAI از آنجا وصل می‌شوند. این را با [check-host.net](https://check-host.net) تست کنید.

  سرورهای ایرانی معمولاً هر دو شرط را دارند.
- برای connector سفارشی، پلن پولی Claude یا ChatGPT لازم است.

## ۱. نصب و تنظیم ورود

```bash
git clone https://github.com/Erfouni/mizito-ai-connector.git
cd mizito-ai-connector
uv sync
cp .env.example .env
```

در `.env` **یکی** از این دو روش ورود را پر کنید:

- **توکن (تست‌شده):** در تب `office.mizito.ir` دکمه‌ی F12 را بزنید و در Console این را اجرا کنید:
  `copy(localStorage.token)`
  توکن در کلیپ‌بورد کپی می‌شود. آن را جلوی `MIZITO_TOKEN=` بچسبانید. اگر از میزیتو Logout کنید، توکن باطل می‌شود.
- **نام کاربری و رمز (تست‌شده، ماندگارتر):** `MIZITO_USERNAME` و `MIZITO_PASSWORD` را پر کنید. سرور خودش وارد میزیتو می‌شود و هر وقت نشستش منقضی شد، خودکار دوباره وارد می‌شود. اگر توکن و رمز را با هم بگذارید، سرور اول از توکن استفاده می‌کند و فقط وقتی توکن باطل شد با رمز وارد می‌شود. ورود خودکار با ورود دومرحله‌ای کار نمی‌کند، چون کدش هر بار عوض می‌شود. در آن حالت از توکن استفاده کنید. برای امتحان ورود با رمز این را اجرا کنید: `uv run python check_login.py`. رمز را جایی ذخیره نمی‌کند.

تست اتصال:

```bash
uv run python check.py
```

## ۲. استفاده روی کامپیوتر خودتان (Claude Desktop یا Claude Code)

برای Claude Desktop این بخش را به `claude_desktop_config.json` اضافه کنید. در ویندوز این فایل در `%APPDATA%\Claude\` است.

```json
{
  "mcpServers": {
    "mizito": {
      "command": "uv",
      "args": ["--directory", "/path/to/mizito-ai-connector", "run", "server.py"]
    }
  }
}
```

برای Claude Code:

```bash
claude mcp add mizito -- uv --directory /path/to/mizito-ai-connector run server.py
```

## ۳. استقرار روی سرور (برای Claude.ai و ChatGPT)

**ساده‌ترین راه:** دستور `sudo bash deploy/install.sh` همه‌ی مراحل زیر را خودکار انجام می‌دهد. فقط دامنه و توکن میزیتو را می‌پرسد. برای به‌روزرسانی، `git pull` و بعد همین دستور را اجرا کنید. راهنمای قدم‌به‌قدم در [SETUP.md](SETUP.md) است. مراحل دستی زیر برای کسی است که می‌خواهد همه‌چیز را خودش تنظیم کند.

روی Ubuntu. اول یک رکورد DNS از نوع A برای دامنه‌تان بسازید، مثلاً `mcp.example.com`، که به IP سرور اشاره کند.

```bash
sudo apt install -y python3-venv nginx certbot
sudo useradd --system --home-dir /opt/mizito-mcp --no-create-home --shell /usr/sbin/nologin mizito-mcp

# کد: git clone https://github.com/Erfouni/mizito-ai-connector.git و بعد داخل پوشه‌اش:
sudo mkdir -p /opt/mizito-mcp && sudo cp -r server.py mizito_client.py mizito deploy/requirements.txt .env.example /opt/mizito-mcp/
cd /opt/mizito-mcp
sudo python3 -m venv .venv
sudo .venv/bin/pip install --require-hashes -r requirements.txt
```

**تنظیمات سرور.** ابتدا یک مسیر مخفی بسازید:

```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

بعد `.env.example` را به `.env` کپی کنید (`sudo cp .env.example .env && sudo nano .env`) و این مقدارها را بگذارید:

```
MIZITO_TOKEN=...                 # یا نام کاربری و رمز
MIZITO_ENABLE_WRITE=0            # با 1 ابزارهای نوشتنی روشن می‌شوند
MIZITO_ENABLE_CRM=0              # با 1 ابزارهای CRM (اگر پلن میزکار CRM دارد)
MIZITO_ENABLE_ADMIN=0            # با 1 ابزارهای مدیریت میزکار (اگر مدیر میزکار هستید)
MCP_TRANSPORT=streamable-http
MCP_HOST=127.0.0.1
MCP_PORT=8765
MCP_HTTP_PATH=/mcp-<رشته‌ی مخفی>
MCP_PUBLIC_HOST=mcp.example.com
```

```bash
# ترتیب مهم است: اول کل پوشه، بعد .env که فقط کاربر سرویس بخواند
sudo chown -R root:mizito-mcp /opt/mizito-mcp && sudo chmod -R o-rwx /opt/mizito-mcp
sudo chown mizito-mcp:mizito-mcp .env && sudo chmod 600 .env

# سرویس
sudo cp /path/to/repo/deploy/mizito-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now mizito-mcp

# گواهی HTTPS (nginx برای چند ثانیه متوقف می‌شود)
sudo certbot certonly --standalone -d mcp.example.com \
  --pre-hook "systemctl stop nginx" --post-hook "systemctl start nginx"

# nginx: در فایل، mcp.example.com را با دامنه‌ی خودتان عوض کنید
sudo cp /path/to/repo/deploy/nginx.conf.example /etc/nginx/sites-available/mizito
sudo ln -s /etc/nginx/sites-available/mizito /etc/nginx/sites-enabled/mizito
sudo nginx -t && sudo systemctl reload nginx
```

اگر سرور به Let's Encrypt دسترسی ندارد (بعضی سرورهای ایرانی)، certbot را با `HTTPS_PROXY` اجرا کنید. اگر DNS روی Cloudflare است، از افزونه‌ی `dns-cloudflare` هم می‌توانید استفاده کنید.

آدرس connector شما این است و **مثل رمز** با آن رفتار کنید:

```
https://mcp.example.com/mcp-<رشته‌ی مخفی>
```

## ۴. اضافه کردن به Claude.ai و ChatGPT

- **Claude.ai:** به Settings ← Connectors ← **Add custom connector** بروید، آدرس بالا را وارد کنید و OAuth را خالی بگذارید. در چت، connector را از منوی **+** روشن کنید.
- **ChatGPT:** به Settings ← Apps & Connectors ← Advanced بروید و **Developer mode** را روشن کنید. بعد **Create** را بزنید، آدرس را وارد کنید و Authentication را روی **No authentication** بگذارید. در چت، از منوی **+** گزینه‌ی Developer mode را انتخاب کنید.

ChatGPT فهرست ابزارها را فقط موقع ساخت connector می‌گیرد. هر بار ابزارها عوض شدند (مثلاً بعد از روشن کردن `MIZITO_ENABLE_WRITE`)، روی connector **Refresh** بزنید.

## ابزارها

۱۰۵ ابزار در ۱۶ بخش. توضیح کامل هر ابزار، پارامترهایش و وضعیت تستش در **[docs/TOOLS.md](docs/TOOLS.md)** است. این فایل خودکار از روی کد ساخته می‌شود.

هر ابزار سه چیز دارد: یک عنوان فارسی، یک توضیح کامل برای هوش مصنوعی و توضیح تک‌تک پارامترها. سرور علاوه بر این یک راهنمای کلی (`instructions`) به هوش مصنوعی می‌دهد که ساختار میزیتو، قالب تاریخ‌ها و قواعد ایمنی را توضیح می‌دهد.

| بخش | خواندن (همیشه فعال) | نوشتن (با `MIZITO_ENABLE_WRITE=1`) |
|---|---|---|
| حساب و میزکار | من کیستم، داشبورد، اعضا، اطلاعات پلن و دعوت‌ها | تعویض میزکار، پذیرش دعوت، دعوت عضو جدید، وضعیت و «مزاحم نشوید» |
| گفتگو | فهرست گفتگوها، پیام‌ها (صفحه‌به‌صفحه یا از یک تاریخ و ساعت)، جستجو، اینکه چه کسی دیده، اعضای گفتگو | ارسال پیام با فایل، ویرایش و حذف و سنجاق پیام، ساخت گروه، اعضا و مدیران گروه، بی‌صدا کردن، حذف گروه |
| نظرسنجی و صورتجلسه | نتایج نظرسنجی، صورتجلسه و سابقه‌اش، الگوها | ساخت نظرسنجی، رأی و پایان، ثبت صورتجلسه با مصوبات (که وظیفه می‌شوند)، ویرایش؛ صورتجلسه‌ی پیشرفته (دعوت، امضا، پیامک) |
| پروژه‌ها و کانبان | فهرست و نمای کامل پروژه با آمار هر ستون، فایل‌های پروژه | ساخت پروژه؛ نام، رنگ، اعضا و برچسب؛ ستون‌ها (افزودن، تغییر، جابه‌جایی، مرتب‌سازی، حذف)؛ کپی؛ آرشیو؛ امکانات پیشرفته |
| وظایف و تقویم | وظایف من، پیگیری‌ها، وظایف پروژه و انجام‌شده‌ها؛ جزئیات، گزارش‌ها، اینکه چه کسی دیده؛ تقویم شمسی؛ سابقه | ساخت با همه‌ی امکانات فرم وب (شروع، مهلت، یادآوری، **تکرار**، چک‌لیست، ستون، برچسب، تأییدکننده، وزن، فایل، الگو)؛ ویرایش؛ گزارش با فایل؛ جابه‌جایی بین ستون‌ها؛ لینک اشتراک؛ الگوی وظیفه |
| گانت | فازها، زمان‌بندی و وابستگی‌ها | فاز، افزودن وظیفه، تاریخ شروع و پایان، وابستگی |
| نامه‌ها | فهرست و جستجو با فیلتر، رشته‌ی کامل با خوانندگان | ارسال با فایل، پاسخ و **پاراف**، آرشیو، برچسب، اتصال به گفتگو، حذف با تأیید، ثبت در دبیرخانه |
| یادداشت و برچسب | یادداشت‌ها و برچسب‌های هر نوع | ساخت، ویرایش و مدیریت یادداشت؛ ساخت، تغییر و حذف برچسب |
| فایل‌ها | **خواندن متن PDF، Word، Excel و PowerPoint**، دیدن عکس، لینک دانلود | آپلود فایل برای پیوست |
| حضور و غیاب، گزارش‌ها | ساعات کار، گزارش‌های مانیتورینگ (مدیر) | اعلام حضور و پایان حضور |
| اتوماسیون و فرم‌ها | قوانین، فیلدهای سفارشی، گردش کار، فرم‌های درخواست | ثبت فرم درخواست، دکمه‌ی اتوماسیون روی وظیفه، ویرایش اتوماسیون |
| CRM (با `MIZITO_ENABLE_CRM=1`) | مشتریان، فرصت‌های فروش، آمار مالی | پرونده‌ی مشتری، فرصت فروش، سند مالی، گزارش تماس |
| مدیریت (با `MIZITO_ENABLE_ADMIN=1`) | همه‌ی پروژه‌ها، گروه‌ها و پرونده‌ها | نقش و مجوز اعضا، تنظیمات، دسترسی، انتقال کار یک عضو، بازگردانی پروژه |
| پشتیبانی میزیتو | گفتگو با پشتیبانی | پیام و پیشنهاد به پشتیبانی |
| دسترسی مستقیم | هر endpoint فقط‌خواندنی (`mizito_api_read`) | — |

تاریخ‌ها را می‌شود **شمسی** (`1405/07/09 14:30`) یا میلادی داد. خروجی‌ها کنار هر تاریخ، معادل شمسی‌اش به وقت تهران را هم دارند. خواندن پیام‌ها آن‌ها را «دیده‌شده» علامت نمی‌زند.

**نکته‌های رفتاری میزیتو** (روی حساب واقعی پیدا شده‌اند):
- تقویم وظیفه را بر اساس **زمان یادآوری** نشان می‌دهد. وظیفه‌ای که فقط مهلت دارد در فهرست «بدون زمان» می‌ماند.
- وظیفه‌ی تکمیل‌شده را نمی‌شود ویرایش کرد یا برایش یادآوری گذاشت. اول باید دوباره بازش کرد.
- پیام یا گزارش وظیفه را فقط تا وقتی دیگران ندیده‌اند می‌شود ویرایش کرد.
- تب «پروژه‌ها» فقط پروژه‌هایی را نشان می‌دهد که گفتگوی پروژه دارند. `mizito_create_project` هر دو را با هم می‌سازد.
- آرشیو کردن پروژه همه‌ی اعضا را از آن بیرون می‌برد، و فقط مدیر میزکار می‌تواند برش گرداند.
- فقط مدیر گروه (یا مدیر پروژه‌ی پیشرفته) می‌تواند نظرسنجی بسازد.
- نامه‌ی تازه چند ثانیه بعد از ارسال در جستجو دیده می‌شود.
- این قابلیت‌ها پلن سازمانی یا دسترسی مدیر لازم دارند: گانت، اتوماسیون، صورتجلسه‌ی پیشرفته، الگوی وظیفه، کپی پروژه، دبیرخانه، CRM و گزارش‌های مانیتورینگ. روی پلن آزمایشی خطای 400 می‌دهند و پیام خطا علتش را می‌گوید.

**وضعیت تست** (۵ تا ۷ مهر ۱۴۰۵، روی یک حساب واقعی با پلن آزمایشی و بدون دسترسی مدیر):
- **۷۱ ابزار** اجرا و بررسی شدند: همه‌ی ابزارهای خواندنی و بیشتر ابزارهای نوشتنی.
- **۲۱ ابزار** دقیقاً مطابق کد وب میزیتو ساخته شدند، ولی پلن یا نقش حساب تست اجازه‌شان را نداد (گانت، اتوماسیون، CRM، مدیریت، دبیرخانه و...).
- **۱۳ ابزار** عمداً تست نشدند، چون روی افراد دیگر یا پروفایل اثر دارند (دعوت عضو، حضور و غیاب، وضعیت، پیام به پشتیبانی، ویرایش مشتری و...).
- وضعیت تک‌تک endpointها در [docs/site-map/api.md](docs/site-map/api.md) است.

**عمداً ابزار ندارند:** ورود و خروج و حذف حساب؛ رمز، ورود دومرحله‌ای و نشست‌ها؛ خرید پلن و پرداخت اشتراک؛ تماس تصویری؛ حذف میزکار و تغییر مالک؛ ورود از Excel؛ و پنل کارکنان پشتیبانی میزیتو. دلیل هر کدام در انتهای [docs/TOOLS.md](docs/TOOLS.md) آمده است.

## امنیت

- **آدرس connector:** مسیر مخفی داخلش تنها چیزی است که جلوی دسترسی دیگران را می‌گیرد. آن را به کسی ندهید. اگر لو رفت، `MCP_HTTP_PATH` را عوض کنید.
- **فایل `.env`:** یعنی دسترسی کامل به حساب میزیتو. هرگز commit نشود (در `.gitignore` هست).
- **ابزارهای نوشتنی:** ChatGPT و Claude قبل از هر عمل نوشتنی از کاربر تأیید می‌گیرند. با این حال متن پیام‌ها را داده‌ی غیرقابل‌اعتماد بدانید و فقط وقتی لازم است نوشتن را روشن کنید.
- **حذف دائمی:** حذف گروه، نامه، برچسب یا عضو میزکار فقط وقتی انجام می‌شود که هوش مصنوعی عنوان دقیق همان مورد را در پارامتر `confirm` تکرار کند.
- **فایل‌ها:** کلید دسترسی فایل‌ها (یک JWT) از سرور بیرون نمی‌رود. لینکی که `mizito_get_file_link` می‌دهد فقط برای همان فایل است، ولی هر کس آن را داشته باشد می‌تواند فایل را دانلود کند. هر لینکی قبل از تحویل بررسی می‌شود که نشست حساب داخلش نباشد.
- **توکن وظیفه‌ها:** `access_token` وظیفه‌ها در میزیتو توکن نشست حساب را بدون رمزگذاری داخل خودش دارد. این سرور وظیفه‌ها را فقط با `_id` آدرس‌دهی می‌کند و هر JWT را از خروجی‌ها حذف می‌کند.
- **لاگ‌ها:** سرور access log ندارد و nginx هم برای این سایت لاگ دسترسی ثبت نمی‌کند، تا مسیر مخفی جایی ثبت نشود.
- **حریم خصوصی:** محتوای میزیتو به Anthropic یا OpenAI فرستاده می‌شود. این را با سیاست سازمان‌تان هماهنگ کنید.

## عیب‌یابی

| مشکل | علت و راه‌حل |
|---|---|
| `No credentials` | `MIZITO_TOKEN` در `.env` خالی است |
| `401` / `token expired` | توکن باطل شده است. توکن تازه بگذارید و سرویس را ری‌استارت کنید |
| ChatGPT ابزار جدید را نمی‌بیند | روی connector **Refresh** بزنید و یک چت جدید باز کنید |
| ساخت وظیفه رد می‌شود | `project_id` لازم است، و مسئولان باید عضو همان پروژه باشند |
| اسمی پیدا نمی‌شود | بعضی اسم‌ها با «ي» و «ك» عربی نوشته شده‌اند |
| خطای 400 یا 405 با اشاره به plan یا admin | آن قابلیت در پلن میزکار نیست یا دسترسی مدیر لازم دارد. متن خطا علت احتمالی را می‌گوید |
| متن PDF خالی است | PDF اسکن‌شده است؛ صفحه‌ها را به‌صورت عکس با `mizito_view_image` ببینید |

## فایل‌ها

| فایل | کار |
|---|---|
| `server.py` | اجرای سرور، از طریق stdio یا HTTP |
| `mizito/` | ابزارها، هر بخش در یک فایل (`chat.py`، `tasks.py`، `letters.py`، ...). بخش مشترک در `app.py` است: کلاینت، تاریخ شمسی، ثبت ابزار و راهنمای کلی |
| `mizito_client.py` | کلاینت API میزیتو: ورود، فراخوانی، آپلود و دانلود فایل، و حذف اسرار از خروجی |
| `check.py` | تست سریع اتصال و ابزارهای خواندنی |
| `check_login.py` | امتحان ورود با نام کاربری و رمز؛ چیزی ذخیره نمی‌کند |
| `tests/test_offline.py` | تست بدون اینترنت: تاریخ شمسی، تکرار وظیفه، و خواندن Word، Excel و PowerPoint |
| `docs/TOOLS.md` | راهنمای کامل ابزارها؛ با `tools/build_tools_doc.py` ساخته می‌شود |
| `docs/site-map/` | نقشه‌ی کامل وب‌اپ میزیتو و وضعیت هر endpoint در MCP |
| `SETUP.md` | راهنمای ساده‌ی دوزبانه (فارسی و انگلیسی) برای وصل کردن حساب خودتان |
| `CHANGELOG.md` | تغییرات هر نسخه |
| `deploy/install.sh` | نصب و به‌روزرسانی خودکار روی سرور Ubuntu یا Debian |
| `deploy/` | سرویس systemd، نمونه‌ی nginx و `requirements.txt` با hash |
| `API_MAP.md` | نقشه‌ی API داخلی میزیتو |

## لایسنس · License

[MIT](LICENSE): استفاده، تغییر و انتشار آزاد است، به شرط اینکه متن لایسنس همراهش بماند. این پروژه غیررسمی است و به شرکت میزیتو وابسته نیست.

*MIT licensed. This is an unofficial project, not affiliated with Mizito.*