WallGold Copilot — دستیار فارسی هوشمند طلا

نسخه: 0.3.0 — OAuth Account Connection — 2026-08-16

این پروژه یک MCP Server + Plugin برای ChatGPT و Codex است که هدفش فقط «نمایش قیمت» نیست؛ یک لایه تصمیم‌یار کامل برای طلا می‌سازد:

• مشاهده بازار و موجودی WallGold
• اتصال امن حساب WallGold با OAuth و صفحه فارسی ورود API Key
• قیمت واقعی قابل معامله خرید/فروش با زمان انقضا
• ارزش‌گذاری پرتفوی و سهم طلا/نقد
• تحلیل شش‌بعدی: طلای جهانی، دلار/ریال، تکنیکال، اقتصاد کلان، اخبار/ژئوپلیتیک، حباب داخلی
• امتیاز -100 تا +100 و درصد اطمینان محاسباتی مبتنی بر پوشش، تازگی و اختلاف شواهد
• سناریوی صعودی / خنثی / نزولی
• «چه چیزی نظر را عوض می‌کند؟» و عامل منتقد مخالف
• سیاست مدیریت ریسک و خزانه
• پیش‌نمایش خرید/فروش با اثر روی موجودی و تخصیص دارایی
• قوانین هشدار، تصویر لحظه‌ای تحلیل، معامله آزمایشی
• بک‌تست سیگنال
• مسیر اجرای خصوصی جدا و خاموش به‌صورت پیش‌فرض

خروجی کاملاً فارسی

تمام عنوان‌ها، توضیح‌ها، تصمیم‌ها و وضعیت‌هایی که کاربر می‌بیند فارسی طراحی شده‌اند. نام داخلی Toolها انگلیسی مانده تا قرارداد MCP پایدار و قابل نگهداری باشد.

نمونه خروجی مورد انتظار:

تصمیم: خرید پله‌ای
درصد اطمینان: ۷۴٪

طلای جهانی: صعودی
دلار / ریال: صعودی
تحلیل تکنیکال: خنثی
اقتصاد کلان: نزولی
اخبار و ژئوپلیتیک: صعودی
حباب و پریمیوم بازار داخلی: خنثی

سناریوی صعودی: ...
سناریوی نزولی: ...
چه چیزی نظر را عوض می‌کند؟ ...

شروع محلی

cp .env.example .env
npm install
npm run typecheck
npm test
npm run dev

MCP روی http://127.0.0.1:3000/mcp و health روی /health بالا می‌آید.

برای local/STDIO می‌توان API Key را فقط در Secret Manager یا WALLGOLD_API_KEY محیط اجرا گذاشت. API Key را داخل ChatGPT/Codex paste نکن.

اتصال ChatGPT با OAuth

در GitHub Codespaces، OAuth به‌صورت پیش‌فرض فعال است. پورت 3000 را Public کن و در ChatGPT Plugin آدرس زیر را با Authentication = OAuth بده:

https://<codespace>-3000.app.github.dev/mcp

ChatGPT باید OAuth metadata را کشف کند و یک صفحه فارسی WallGold AI برای واردکردن API Key باز کند. کلید در آن صفحه مستقیماً با WallGold اعتبارسنجی می‌شود، هرگز به prompt/tool input نمی‌رود و در prototype Codespaces روی دیسک ذخیره نمی‌شود. جزئیات: docs/OAUTH_ONBOARDING.md.

امنیت و اجرای معامله

نسخه عمومی/قابل‌انتشار Plugin هیچ ابزار اجرای معامله‌ای advertise نمی‌کند. preview_trade فقط پیش‌نمایش می‌سازد.

برای محیط خصوصی، کد اجرای واقعی وجود دارد اما سه قفل دارد:

1. PRIVATE_EXECUTION_ENABLED=true
2. تعریف سقف مبلغ یا گرم در env
3. اجرای دستی CLI با --yes-i-understand

npm run trade:private -- --preview-token 'TOKEN' --yes-i-understand

برای MCP خصوصی می‌توان WALLGOLD_MCP_ALLOW_TRADE_EXECUTION=true کرد؛ این حالت برای Plugin عمومی مناسب نیست. مسیر execution بعد از Audit، TTL واقعی قیمت، موجودی قابل‌استفاده (با کسر locked)، محدودیت زنده بازار، سقف‌های ریسک، جلوگیری از retry کور و reconciliation با GET سفارش را بررسی می‌کند.

منبع داده هوشمند

WallGold لایه account/execution/quote را می‌دهد. برای اخبار، طلای جهانی، ماکرو و دلار/ریال، Skill طوری نوشته شده که ChatGPT در صورت داشتن Web Search داده تازه را از وب جمع‌آوری کند و سپس شواهد ساختاریافته را به analyze_gold_market بدهد. این طراحی جلوی ساختن اعداد از روی حدس LLM را می‌گیرد.

برای محصول مستقل خارج از ChatGPT، بعداً Providerهای اختصاصی market/news/macro را می‌توان به همان Evidence contract وصل کرد.

نکته انتشار عمومی

قابلیت‌های وابسته به حساب WallGold برای انتشار عمومی نیازمند integration رسمی/مجاز WallGold و معماری production-grade authorization/credential storage هستند. اجرای واقعی معامله خصوصی می‌ماند و در Codespaces/Plugin عمومی خاموش است.

Audit مستندات WallGold

گزارش کامل Audit و mismatchهای اصلاح‌شده: docs/AUDIT_2026-08-16.md. قرارداد endpointها و فیلدها: docs/WALLGOLD_API_NOTES.md.

اتصال API Key بدون افشای secret

OAuth onboarding کاربر را به صفحه HTTPS خود WallGold AI می‌برد. API Key فقط همان‌جا وارد می‌شود، با WallGold اعتبارسنجی می‌شود و به session OAuth متصل می‌شود؛ مدل و tool schema هیچ فیلدی برای دریافت API Key ندارند.