Back to search
codex-token-monitor
MCP serverGitHub
Native Go MCP server for comparing Codex usage across named computers, with offline Persian HTML reports and interactive installers.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/alirezadadrass--codex-token-monitor)HTML
<a href="/listings/alirezadadrass--codex-token-monitor"><img src="/api/listings/alirezadadrass--codex-token-monitor/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 204 lines
- # Codex Token Monitor — Go MCP
- [نصب توسط ایجنت](docs/AGENT_INSTALL.md) · [نصب تعاملی سرور](docs/SERVER.md) · [تنظیمات و رفع اشکال](docs/CONFIGURATION.md) · [دریافت نسخهٔ آماده](https://github.com/AlirezaDadrass/codex-token-monitor/releases/tag/v0.1.2)
- مقایسهٔ مصرف یک اکانت کدکس روی چند کامپیوتر. روی هر دستگاه یک جمعکنندهٔ Go لاگهای محلی را میخواند؛ یک Hub مشترک آمار را جمع میکند و از طریق MCP گزارش میدهد. تعداد دستگاهها محدود نیست و از گزارشهای دریافتی شناسایی میشود. سرور رابط مدیریتی ندارد؛ وقتی از ایجنت گزارش بخواهید، ابزار یک **فایل HTML فارسی و مستقل** میسازد و فقط لینک آن را برمیگرداند.
- ساخت HTML و همهٔ نمودارها با قالب و محاسبات خود Go انجام میشود و هیچ فراخوانی مدل ندارد. خود درخواست کاربر، تعریف ابزارها و فراخوانی ابزار توسط ایجنت همچنان میتواند مقدار کمی توکن مصرف کند. محتوای کامل HTML برای ایجنت برگردانده نمیشود.
- این پروژه با ابزارهای بومی Go ساخته و اجرا میشود و به سرویس پایگاه داده نیاز ندارد. وضعیت جمعکننده و snapshotها در فایلهای محلی با نوشتن اتمی و قفل بین پردازشها ذخیره میشوند.
- ## گزارش چه چیزی را نشان میدهد؟
- - تعداد توکن هر دستگاه، تفکیک ورودی، ورودی کششده، خروجی و reasoning؛ تفکیک مدل و تعداد چتهای فعال در بازه.
- - رتبهبندی دستگاهها و سهم هر دستگاه از **توکنهای مشاهدهشده**.
- - درصد مصرف و باقیماندهٔ هفتگی اکانت و زمان ریست، طبق آخرین مشاهده در لاگ کدکس. این مقدار از OpenAI بهصورت زنده استعلام نمیشود.
- - تازگی گزارش هر دستگاه و مشخص بودن دادههای ناقص یا دستگاههای قطعشده.
- - تخمین سهم هر دستگاه از لیمیت، فقط وقتی دادهٔ دستگاههای ثبتشده تازه، دادهها بدون ابهام و لیمیت زیر ۱۰۰٪ باشد. این تخمین، سهم توکن ضربدر درصد مصرف اکانت است و **سهم واقعی از سهمیهٔ OpenAI نیست**. پس از رسیدن به لیمیت، احتمال مصرف با اعتبار خریداریشده وجود دارد و تخمین ارائه نمیشود.
- توکن خام معادل ثابتی برای لیمیت اشتراک ندارد. مدل، کش، حالت سرعت، اعتبار خریداریشده و مصرف ابری/سایر قابلیتهای مشترک ممکن است روی سهمیه اثر بگذارند. نرخ اعتباری مدلها نیز بهتنهایی مصرف لیمیت اشتراک را تعیین نمیکند. [راهنمای رسمی قیمتگذاری و مصرف](https://learn.chatgpt.com/docs/pricing)
- مثلاً اگر مصرف اکانت ۶۰٪ و سهم دستگاه A از توکنهای مشاهدهشده ۵۰٪ باشد، تخمین ۳۰ **واحد درصد از لیمیت** است. این عدد، اندازهگیری مستقیم سهم دستگاه از لیمیت نیست.
- ## نصب سریع سرور
- روی میزبان Linux دارای systemd، اسکریپت تعاملی نام مرکز، آدرس/پورت و توکن را میگیرد؛ اگر توکن را خالی بگذارید، کلید جدید میسازد:
- ```sh
- git clone https://github.com/AlirezaDadrass/codex-token-monitor.git
- cd codex-token-monitor
- git checkout v0.1.2
- sudo bash scripts/install-server.sh
- ```
- نصبکننده باینری همان نسخه را با بررسی checksum دریافت میکند و سرویس بومی میسازد. Go برای اجرای نسخهٔ آماده لازم نیست. برای جزئیات TLS، آدرس شبکه، نصب از باینری محلی، dry-run و نگهداری سرویس، [راهنمای سرور](docs/SERVER.md) را بخوانید.
- ## نصب ویندوز بدون کامپایل
- اسکریپت [install-windows.ps1](scripts/install-windows.ps1) نسخهٔ آمادهٔ x64 یا ARM64 را دانلود و checksum را بررسی میکند. برای کلاینت اجرا کنید `./install-windows.ps1` و برای سرور، در PowerShell با دسترسی Administrator، `./install-windows.ps1 -Mode Server`. [راهنمای کامل ویندوز](docs/WINDOWS.md) شامل دریافت مستقیم اسکریپت، نصب آفلاین و روش غیرتعاملی ایجنت است.
- ## نصب سریع روی کامپیوترها
- فایل اجرایی سیستم خود را از [انتشار آماده](https://github.com/AlirezaDadrass/codex-token-monitor/releases/tag/v0.1.2) دریافت و checksum آن را بررسی کنید. سپس:
- ```sh
- token-monitor install
- ```
- نصب، **نام این کامپیوتر، آدرس سرور و توکن اتصال** را میپرسد. اتصال با توکن بررسی و MCP در Codex ثبت میشود. به ایجنت میتوانید فقط لینک ریپو را بدهید و بخواهید طبق [راهنمای نصب ایجنت](docs/AGENT_INSTALL.md) اطلاعات را از شما بگیرد و خودش نصب را کامل کند.
- ## ساخت از سورس و اجرای محلی
- برای ساخت از سورس، Go 1.26 یا جدیدتر لازم است:
- ```sh
- go build -o bin/token-monitor ./cmd/token-monitor
- ./bin/token-monitor init --name PC-1
- ./bin/token-monitor report
- ./bin/token-monitor report --html
- ```
- گزارش HTML فونت فارسی همراه، نمودار روند روزانه با انتخاب معیار، نمودار سهمیه، مقایسهٔ دستگاهها، ترکیب کش/ورودی/خروجی، تفکیک مدلها، جدول جزئیات و دیاگرام پوشش داده دارد. به اینترنت یا کتابخانهٔ نمودار خارجی نیاز ندارد. چاپ/PDF و دریافت دادهٔ JSON از خود فایل ممکن است. مسیر خروجی دلخواه را میتوان با `report --html --output /path/report.html` داد.
- برای نصب و ثبت خودکار در Codex:
- ```sh
- ./bin/token-monitor install
- ```
- نصب نام کامپیوتر، آدرس سرور و توکن را میپرسد؛ با `--name "لپتاپ خانه"` میتوان نام را مستقیم داد و بقیهٔ اطلاعات را تعاملی وارد کرد. توکن در ترمینال مخفی است. برای نصب مستقل بدون مرکز، صریحاً `install --local` را اجرا کنید. این نام در نمودار، رتبهبندی و جدول گزارش ثبت میشود. `install` تنظیمات را ایجاد و فایل اجرایی فعلی را در Codex ثبت میکند؛ `init` فقط تنظیمات میسازد. در نصب مجدد، شناسه و نام قبلی حفظ میشود. اگر روی این دستگاه Codex CLI نصب نیست، از تنظیمات نمونه برای ثبت دستی استفاده کنید.
- پیکربندی پیشفرض زیر پوشهٔ `codex-token-monitor` در پوشهٔ تنظیمات کاربر ساخته میشود: در لینوکس معمولاً `~/.config/codex-token-monitor/config.json` و در ویندوز زیر `%AppData%`. مسیر دادههای کدکس از `CODEX_HOME` یا `~/.codex` گرفته میشود. میتوان مسیرها را با `--config`، `--codex-home` و `--data-dir` تعیین کرد.
- اولین اسکن لاگهای موجود را میخواند؛ دفعات بعد فقط ادامهٔ فایلها خوانده میشود. مهلت نگهداری آمار پیشفرض ۱۴ روز است. گزارش، هفتهٔ اکانت را از زمان ریست و طول بازهٔ ۱۰۰۸۰ دقیقهای پیدا میکند؛ فرقی ندارد لیمیت در `primary` یا `secondary` باشد. اگر مشاهدهٔ معتبر این هفته موجود نباشد، تعداد توکن ۷ روز اخیر همراه با توضیح محدودیت داده نشان داده میشود.
- ## راهاندازی چند کامپیوتر
- یک کامپیوتر باید تا زمان استفاده از گزارش مشترک روشن و قابل دسترس باشد. Hub را میتوان روی همان PC-1 اجرا کرد.
- ### PC-1: مرکز و جمعکننده
- روی هر کامپیوتر فایل اجرایی مناسب همان سیستم را داشته باشید. روی PC-1:
- ```sh
- ./bin/token-monitor init --name PC-1 --hub-url http://127.0.0.1:8787 --create-token
- ./bin/token-monitor hub
- ```
- دستور `init` فایل `hub-token` را کنار فایل تنظیمات میسازد؛ مقدار آن در خروجی چاپ نمیشود. این کلید مربوط به همین ابزار است و ارتباطی با توکن ورود OpenAI ندارد. دستور `hub` باید در حال اجرا بماند. در ترمینال دیگر:
- ```sh
- ./bin/token-monitor watch
- ```
- اگر قبلاً `init` اجرا شده، همان فایل `config.json` را ویرایش کنید؛ اجرای دوباره آن را بازنویسی نمیکند. `machine_id` هر دستگاه باید یکتا و پایدار بماند؛ فایل تنظیمات یک دستگاه را برای بقیه کپی نکنید.
- ### دستگاههای دیگر: اتصال به مرکز
- فایل `hub-token` را بهصورت امن برای هر دستگاه جدید فراهم کنید. یک راه اتصال، تونل SSH است؛ روی هر دستگاه اجرا کنید و باز نگه دارید:
- ```sh
- ssh -N -L 8787:127.0.0.1:8787 USER@PC1
- ```
- سپس روی PC-2 با مسیر واقعی فایل کلید:
- ```sh
- ./bin/token-monitor init --name PC-2 --hub-url http://127.0.0.1:8787 --token-file /absolute/path/hub-token
- ./bin/token-monitor watch
- ```
- همین مراحل را با نام مستقل برای هر دستگاه دیگر تکرار کنید؛ نیازی به تعیین تعداد کل یا تغییر تنظیمات سرور نیست. اکنون روی هر دستگاه:
- ```sh
- ./bin/token-monitor report
- ./bin/token-monitor report --metric non_cached_tokens
- ```
- نام `account` در تنظیمات Hub و جمعکنندهها باید یکسان باشد. هر دستگاه با شناسهٔ مستقل خودکار به گزارش اضافه میشود. بدون تونل نیز میتوان Hub را روی آدرس شبکه اجرا کرد؛ برای ارتباط بیرون از loopback از HTTPS یا شبکهٔ رمزگذاریشده استفاده کنید. Hub از TLS مستقیم هم پشتیبانی میکند:
- ```sh
- ./bin/token-monitor hub --listen 0.0.0.0:8787 --tls-cert /path/server.crt --tls-key /path/server.key
- ```
- در این حالت `hub_url` دستگاهها را روی آدرس `https://...:8787` قرار دهید. اعتبار گواهی بررسی میشود.
- همهٔ اتصالهای شبکهای با `Authorization: Bearer ...` بررسی میشوند؛ دریافت/ارسال آمار، مسیر MCP و health بدون توکن پاسخ ۴۰۱ میدهند. کلید تولیدشده ۲۵۶ بیت تصادفی است و فایل آن با دسترسی محدود کاربر نوشته میشود. سرور بدون کلید معتبر بالا نمیآید. اتصال محلی stdio شبکهای نیست و کلید نمیخواهد، اما ارتباط همین جمعکننده با Hub به کلید نیاز دارد.
- ## اتصال به Codex
- ### MCP محلی با stdio
- روی هر دستگاه مسیر فایل اجرایی همان دستگاه را ثبت کنید:
- ```sh
- codex mcp add token-monitor -- /absolute/path/token-monitor mcp --config /absolute/path/config.json
- ```
- یا تنظیمات نمونهٔ [examples/codex-local.toml](examples/codex-local.toml) را با مسیرهای خود به فایل تنظیمات کدکس اضافه کنید. در حالت `mcp` جمعکننده در پسزمینه هم اجرا میشود. اگر همیشه یک Codex باز است، اجرای جداگانهٔ `watch` الزامی نیست؛ `watch` امکان همگامسازی مستقل از Codex را میدهد. اجرای همزمان این دو نیز با قفل و snapshot جایگزینشونده، مصرف را دوباره جمع نمیکند.
- بعد از اتصال میتوان به کدکس گفت:
- > گزارش مصرف هفتگی کامپیوترها را نشان بده.
- ابزار `generate_usage_report` یکبار اجرا میشود و ایجنت فقط لینک خروجی را نشان میدهد. تولید متن گزارش و نمودارها به خود مدل سپرده نمیشود. تنظیمات نمونه فقط همین ابزار و ابزار وضعیت را فعال میکنند تا تعریف ابزارهای غیرضروری وارد گفتگو نشود.
- ### MCP مشترک با Streamable HTTP
- Hub خودش در مسیر `/mcp` سرور MCP دارد. نمونهٔ تنظیمات در [examples/codex-http.toml](examples/codex-http.toml) آمده است. متغیر `TOKEN_MONITOR_HUB_TOKEN` باید در محیطی که Codex را اجرا میکند تنظیم شده باشد. ابزار MCP روی Hub فقط آخرین snapshotهای دریافتشده را میخواند؛ روی هر دستگاه همچنان `watch` یا MCP محلی باید فعال باشد.
- گزارش ساختهشده از MCP محلی، یک مسیر فایل روی همان دستگاه دارد. گزارش ساختهشده روی Hub، لینک دانلود دارای امضای موقت یکساعته میدهد. این امضا فقط برای همان فایل معتبر است و کلید اصلی سرور در آن قرار نمیگیرد. بدون توکن اصلی یا امضای معتبر، دانلود فایل هم ممکن نیست. پشت reverse proxy باید HTTPS و Host واقعی بهدرستی تنظیم شوند؛ ارتباط مستقیم TLS یا تونل SSH سادهتر است.
- ابزارهای MCP:
- | ابزار | کارکرد |
- | --- | --- |
- | `generate_usage_report` | ابزار پیشفرض ایجنت؛ ساخت HTML کامل و برگرداندن فقط مسیر/لینک کوتاه، بدون فراخوانی مدل |
- | `get_weekly_usage` | گزارش هفته، رتبهبندی دستگاهها، سهم توکن و وضعیت سهمیه؛ `metric` اختیاری و `refresh` پیشفرض true است |
- | `get_monitor_status` | مشخصات دستگاه، گروه اکانت و حالت اجرای ابزار |
- | `sync_usage` | خواندن تغییرات لاگ و ارسال آمار؛ فقط در MCP محلی |
- ## پیکربندی
- فایل [examples/config.example.json](examples/config.example.json) فیلدهای اصلی را نشان میدهد. برای ساخت تنظیمات واقعی، از `init` استفاده کنید تا شناسهٔ یکتا تولید شود.
- - `machine_id`: شناسهٔ ثابت و یکتای نصب؛ تغییر نام دستگاه این شناسه را عوض نمیکند.
- - `machine_name`: نام نمایشی، مانند `PC-1` یا `Laptop`.
- - `account`: گروه مشترک برای یک اکانت؛ پیشفرض `personal`.
- - `hub_url`: آدرس مرکز مشترک برای کلاینت؛ حذف آن فقط در پروفایل مستقلِ صریح مجاز است.
- - `public_url`: آدرس بیرونی مرکز برای لینک دانلود گزارش، مخصوص reverse proxy.
- - `token_file`: مسیر فایل کلید Hub؛ متغیر محیطی `TOKEN_MONITOR_HUB_TOKEN` بر آن اولویت دارد.
- - `interval_seconds`: فاصلهٔ همگامسازی؛ پیشفرض ۶۰ ثانیه.
- - `retention_days`: نگهداری آمار؛ پیشفرض ۱۴ و حداقل ۸ روز.
- - `limit_id`: سبد سهمیهٔ مورد گزارش؛ پیشفرض `codex`. درصد سبدهای متفاوت با هم جمع نمیشود.
- - `account_fingerprint`: فیلتر اختیاری حساب. اگر لاگها متعلق به چند اکانت باشند، گزارش بهجای ترکیب آنها خطا و fingerprintهای قابل انتخاب را نشان میدهد؛ مقدار حساب مدنظر را در تنظیمات هر جمعکننده قرار دهید و دوباره sync کنید.
- تغییرات تنظیمات برای پردازشهای در حال اجرا به راهاندازی دوباره نیاز دارند. با `report --no-refresh` میتوان آمار ذخیرهشده را بدون اسکن مجدد خواند.
- ## دقت شمارش و محدودیتها
- - فایلهای `sessions` و `archived_sessions` کدکس خوانده میشوند؛ فایل ورود و پایگاه دادهٔ خود کدکس خوانده یا تغییر داده نمیشود.
- - فقط شمارندهها، زمان، مدل، fingerprint حساب و هش شناسهٔ چت به مرکز ارسال میشود. متن چت، کد، مسیر پروژه و کلید ورود ارسال نمیشود. فایل کش محلی مسیر لاگها را برای نگهداری cursor ذخیره میکند و دسترسی آن محدود به کاربر است.
- - ورودی کششده زیرمجموعهٔ ورودی است و reasoning زیرمجموعهٔ خروجی؛ دوباره به جمع کل اضافه نمیشوند. معیار `non_cached_tokens` برابر ورودی غیرکششده بهعلاوهٔ خروجی است؛ معادل صورتحساب یا فرمول لیمیت نیست.
- - افزایش شمارندهٔ تجمعی هر چت محاسبه میشود؛ تکرار همان شمارنده مصرف اضافه ایجاد نمیکند. اعلان صرفاً مربوط به اندازهٔ context مصرف محسوب نمیشود.
- - در اولین رویداد لاگ ناقص/ادامهدادهشده، فقط مصرف آخرین درخواست حساب میشود؛ مصرف تاریخیِ بهارثرسیده به دستگاه جدید نسبت داده نمیشود و ناقص بودن داده اعلام میشود.
- - اگر یک لاگ روی چند دستگاه کپی/همگام شده باشد، رویداد مشترک یکبار در مجموع میآید و سهم آن در `unattributed_tokens` باقی میماند؛ از روی لاگ کپیشده نمیتوان دستگاه اصلی را قطعی شناخت.
- - قطع مرکز باعث از دست رفتن کش محلی نمیشود؛ ارسال بعدی snapshot شامل دادهٔ نگهداریشده است. گزارش هنگام قطعی با `scope=local_fallback` مشخص میشود و ادعای پوشش تمام دستگاههای مرکز را ندارد.
- - مشاهدهٔ منقضی سهمیه، سهمیهٔ هفتهٔ جدید فرض نمیشود. درصد اکانت، یک مشاهدهٔ مشترک است و درصدهای دریافتشده از دستگاهها با هم جمع نمیشوند.
- - مصرف ابری یا دستگاههایی که جمعکننده ندارند در توکن محلی دیده نمیشود. حذف لاگهای اصلی، اسکن خطایدار، اختلاف ساعت یا نسخههای آیندهٔ قالب لاگ ممکن است داده را ناقص کند. ساعت دستگاهها باید همگام باشد.
- - در حالت عادی حداکثر اندازهٔ هر snapshot برابر ۳۲ MiB است؛ اگر داده بیشتر شود، خطا نمایش داده میشود. این نسخه برای یک اکانت شخصی و چند دستگاه طراحی شده است.
- ## بررسی و تست
- ```sh
- go test -race ./...
- go vet ./...
- go build -o bin/token-monitor ./cmd/token-monitor
- ```
- تستها خواندن افزایشی، خطوط نیمهنوشته، شمارندهٔ تکراری، اعلان context، ادامهٔ چت، ریست شمارنده، فیلتر اکانت، هفتهٔ اکانت، تعداد متغیر دستگاهها از جمله بیش از ۱۰۰ دستگاه، احراز هویت، ارسال تکراری/همزمان، دادهٔ نامعتبر، قطعی Hub و اتصال واقعی MCP با stdio و HTTP را پوشش میدهند.
- گزارش HTML نیز برای نامهای نامطمئن، صحت دادهٔ داخل فایل، نبود وابستگی شبکه، حالت بدون داده و دانلود با امضای معتبر/منقضی/دستکاریشده بررسی میشود. فونت همراه [وزیرمتن](https://github.com/google/fonts/tree/main/ofl/vazirmatn) با مجوز OFL در فایل گزارش هم گنجانده میشود.
- پیادهسازی بر پایهٔ [SDK رسمی Go برای MCP](https://github.com/modelcontextprotocol/go-sdk) است. قالب لاگ از لاگهای محلی و [ساختارهای پروتکل Codex](https://github.com/openai/codex/blob/main/codex-rs/protocol/src/protocol.rs) بررسی شده است؛ لاگ کدکس یک API تضمینشده برای انتساب مصرف دستگاهها نیست. [تنظیم MCP در Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.