# Local Machine MCP Server 🖥️ (Agent Edition · GUI + .exe + ngrok)

برنامج سطح مكتب بسيط بواجهة رسومية بيحوّل جهازك لـ "MCP server" بيشتغل عبر **HTTP endpoint**، عشان عملاء زي **Traycer / Claude / Cline** (اللي بيطلبوا **Endpoint URL**) يتصلوا بيه ويتصرفوا كأنهم agent كامل على جهازك: قراءة/كتابة ملفات، تنفيذ أوامر (عادية أو admin)، تشغيل عمليات في الخلفية، والاتصال بقواعد البيانات. كل ده بضغطة زرار، ومع دعم **ngrok** لتطليع لينك عام.

> ⚠️ **تحذير أمني:** البرنامج ده بيدّي صلاحية تنفيذ أوامر وتعديل ملفات على جهازك، ولو فعّلت ngrok بيعرّضه على النت. استخدمه بحذر شديد، فعّل ngrok فقط وقت الحاجة، استخدم **API Token**، ووصّله بعملاء موثوقين. كل عمليات الملفات مقيّدة بالفولدر اللي تختاره.

## ✨ المميزات
- 🖱️ واجهة رسومية بسيطة (تشغيل/إيقاف بضغطة)
- 📁 اختيار الفولدر المسموح بالـ Browse
- 🔐 **API Token** اختياري لحماية الـ endpoint
- 🌐 خانة لـ **ngrok API key** عشان تطلّع Endpoint URL عام
- 📋 الـ Endpoint URL بيظهر جاهز للنسخ بضغطة
- 📜 شاشة Log حيّة
- 📦 يتبني لملف **.exe** واحد

## التشغيل من السورس
```bash
git clone https://github.com/authmeonline/local-machine-mcp.git
cd local-machine-mcp
pip install -r requirements.txt
python gui.py
```

## بناء ملف .exe
شغّل:
```bash
build_exe.bat
```
هتلاقي البرنامج في: `dist\LocalMachineMCP.exe`

## طريقة الاستخدام
1. افتح البرنامج (أو الـ .exe).
2. اختار **الفولدر المسموح** (مثلاً مشروعك).
3. (اختياري لكن مهم مع ngrok) حط **API Token** عشان تأمّن الوصول.
4. لو عايز لينك عام: فعّل **Expose publicly via ngrok** وحط **ngrok API key** بتاعك.
   - تجيب الـ authtoken من: https://dashboard.ngrok.com/get-started/your-authtoken
5. اضغط **▶ Start Server**.
6. انسخ **Endpoint URL** اللي ظهر وحطه في العميل (Traycer/Claude/...).

## الأدوات اللي بيعرضها
**ملفات:** `list_allowed_dirs` · `list_directory` · `read_file` · `write_file` · `append_file` · `patch_file` · `delete_file` · `make_dir` · `delete_dir` · `move_file` · `copy_file`
**بحث:** `grep_search` (بحث regex جوه الملفات زي ripgrep، بدعم سطور السياق `before_context`/`after_context`/`context`) · `find_files` (البحث عن ملفات بـ glob)
**أوامر/عمليات:** `run_command` (يدعم `elevated=True` للصلاحيات الإدارية) · `run_background` · `kill_process`
**قواعد بيانات:** `db_query` (يدعم `sqlite` / `postgres` / `mysql`)

> لو فعّلت API Token، لازم تمرّر `api_token` مع كل أداة.

## أمثلة سريعة
- تعديل سطر في ملف: `patch_file(path, old_text, new_text)`
- تشغيل سيرفر تطوير في الخلفية: `run_background("npm run dev")`
- استعلام قاعدة بيانات: `db_query(engine="postgres", query="SELECT * FROM users", dsn="postgresql://user:pass@localhost/db")`

## ملاحظة مهمة عن العمل مع Traycer
سلوك Traycer (تخطيط vs تنفيذ) متحكم فيه من Traycer نفسه. Traycer بينفّذ الكود عن طريق **Execution Agent** المدمج جواه مباشرةً على الـ workspace المفتوح. السيرفر ده مفيد أكتر مع عملاء MCP تانيين (Claude/Cline)، أو لتنفيذ على جهاز remote، أو للوصول لقواعد بيانات.

## الأمان
- كل عمليات الملفات مقيّدة بالفولدر المختار.
- `run_command` بينفّذ بصلاحيات المستخدم الحالي (أو admin لو `elevated=True`).
- استخدم **API Token** دايماً لما تفعّل ngrok.
- ngrok بيعرّض جهازك على النت — فعّله بحذر.
- متشغّلش البرنامج بصلاحيات admin إلا للضرورة.