Content
# Mizito AI Connector
یک 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` را پر کنید. سرور خودش وارد می‌شود و توکن را تمدید می‌کند. اگر ورود دومرحله‌ای دارید، `MIZITO_LOGIN_CODE` هم لازم است.
تست اتصال:
```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` | تست سریع اتصال و ابزارهای خواندنی |
| `tests/test_offline.py` | تست بدون اینترنت: تاریخ شمسی، تکرار وظیفه، و خواندن Word، Excel و PowerPoint |
| `docs/TOOLS.md` | راهنمای کامل ابزارها؛ با `tools/build_tools_doc.py` ساخته می‌شود |
| `docs/site-map/` | نقشه‌ی کامل وب‌اپ میزیتو و وضعیت هر endpoint در MCP |
| `SETUP.md` | راهنمای ساده‌ی دوزبانه (فارسی و انگلیسی) برای وصل کردن حساب خودتان |
| `deploy/install.sh` | نصب و به‌روزرسانی خودکار روی سرور Ubuntu یا Debian |
| `deploy/` | سرویس systemd، نمونه‌ی nginx و `requirements.txt` با hash |
| `API_MAP.md` | نقشه‌ی API داخلی میزیتو |
Connection Info
You Might Also Like
No recommendations available