AlMoutmag 1.1

AlMoutmag 1.1 — Secure MCP (Model Context Protocol) bridge between cloud AI agents (z.ai / Claude / Cursor) and the local Windows machine.

AlMoutmag 1.1 — جسر آمن بين وكلاء الذكاء الاصطناعي السحابيين (z.ai / Claude / Cursor) وجهاز Windows المحلي، عبر بروتوكول MCP.

Backwards-compatible with 1.0 clients — the /v12/health alias and the 1.0 OAuth/DPoP flow are unchanged. See CHANGELOG sections below for what 1.1 adds.

English

What it is

AlMoutmag 1.1 is a Python 3.12+ server that runs on Windows 11 and exposes a local MCP (Model Context Protocol) endpoint. Cloud AI agents (z.ai / Claude / Cursor, running on Linux) connect to it through a Cloudflare Tunnel and execute tools on the user's machine — system info, file operations, browser automation, computer use, 40+ coding tools, etc. — with results returned to the AI.

It is security-first by design: 10 protective layers, deny-by-default tool allowlists, tamper-evident audit log, file-integrity monitor with kill switch, OAuth 2.1 + DPoP token binding, and structured JSON logging.

What's new in 1.1 — see the v1.1 New Features section below for the full list. Highlights: 40+ coding tools, @cached_tool performance layer, SSE streaming for long-running tools, a live-coding WebSocket, Unix-pipe-style tool composition, and background jobs.

Architecture

┌──────────────┐    Cloudflare Tunnel    ┌─────────────────┐
│  z.ai / GLM  │ ◄──────────────────────►│  AlMoutmag 1.1  │
│  Claude      │   MCP Streamable HTTP   │  (Windows 11)   │
│  Cursor      │   OAuth 2.1 + DPoP      │                 │
└──────────────┘                          └────────┬────────┘
                                                   │
                                          ┌────────┴────────┐
                                          │  Tool registry  │
                                          │  (31 categories)│
                                          │  350+ tools     │
                                          └────────┬────────┘
                                                   │
                                          ┌────────┴────────┐
                                          │ Windows machine │
                                          │ (files, apps,   │
                                          │  browser, code) │
                                          └─────────────────┘

Quick start

# 1. Clone and create venv
git clone https://github.com/USERNAME/almoutmag-1.0.git
cd almoutmag-1.0
python -m venv venv
.\venv\Scripts\Activate.ps1

# 2. Install dependencies
pip install -e ".[dev]"
playwright install chromium

# 3. Generate OAuth keys (Ed25519)
python scripts/gen_keys.py

# 4. Copy config and edit
Copy-Item config.yaml.example config.yaml
Copy-Item .env.example .env
# Edit config.yaml — set dev_mode: true for first run

# 5. Run dev server
python scripts/dev_start.py
# Server now listening on http://127.0.0.1:8452
# dev_token is printed to stderr — export it:
#   $env:ALMOUTMAG_DEV_TOKEN="<paste token>"

In dev_mode, you can now use Bearer instead of DPoP (1.1 shortcut — useful for local curl/PowerShell scripts). Production traffic still requires DPoP <token> + the DPoP proof header:

# In dev_mode, you can now use Bearer instead of DPoP:
curl -H "Authorization: Bearer $ALMOUTMAG_DEV_TOKEN" http://127.0.0.1:8452/info

# Production path is unchanged (OAuth 2.1 + DPoP):
curl -H "Authorization: DPoP $ACCESS_TOKEN" -H "DPoP: $DPoP_PROOF" \
  http://127.0.0.1:8452/info

MCP endpoints

Related MCP server: WinCommander

v1.1 New Features (Coding Tools + Performance)

The 1.1 release turns AlMoutmag into a powerful programming assistant on the user's Windows machine, while preserving every 1.0 behaviour.

See docs/CODING_TOOLS.md for the full tool reference with example MCP requests/responses for every tool.

Dependencies (12 — strict)

Dev: pytest, pytest-asyncio, ruff, mypy, pyinstaller.

Tests

python -m pytest tests/ -v
python -m ruff check .
python -m mypy core/ server/

All tests are LIVE integration tests — they send real HTTP requests to a aiohttp.test_utils.TestClient instance. No static grep tests.

213 passed (up from 164 in 1.0 — the 49 new tests cover the coding tools, caching, SSE stream, WebSocket code session, pipe_run, and background jobs in tests/test_coding.py).

Documentation

• docs/ARCHITECTURE.md — System architecture

• docs/SECURITY.md — 10-layer security model

• docs/MCP_COMPATIBILITY.md — How z.ai/Claude/Cursor connect

• docs/API.md — REST API reference

• docs/CODING_TOOLS.md — v1.1 coding tools reference (40+ tools)

Build .exe

python scripts/build_exe.py
# Output: dist/AlMoutmag.exe

العربية

ما هو AlMoutmag 1.1؟

خادم Python 3.12+ يعمل على Windows 11 ويوفّر نقطة نهاية MCP محلية. يتصل به وكلاء الذكاء الاصطناعي السحابيون (z.ai / Claude / Cursor، العاملون على Linux) عبر نفق Cloudflare Tunnel، وينفّذون أدوات على جهاز المستخدم — معلومات النظام، عمليات الملفات، أتمتة المتصفح، التحكم بالحاسوب، أكثر من 40 أداة برمجة، إلخ — وتُعاد النتائج للـ AI.

متوافق تماماً مع إصدار 1.0 (نقطة /v12/health ومسار OAuth/DPoP لم يتغيّرا).

الجديد في 1.1 — 40+ أداة برمجة، طبقة تخزين مؤقت @cached_tool، بث SSE للأدوات طويلة التشغيل، WebSocket للبرمجة الحيّة، تركيب الأدوات بطريقة pipe، والمهام في الخلفية. التفاصيل في docs/CODING_TOOLS.md.

مبني بالأمان أولاً بالتصميم: 10 طبقات حماية، قوائم سماح deny-by-default، سجل تدقيق tamper-evident، مراقب سلامة الملفات مع kill switch، ربط OAuth 2.1 + DPoP، وسجلّات JSON منظمة.

البنية

┌──────────────┐    Cloudflare Tunnel    ┌─────────────────┐
│  z.ai / GLM  │ ◄──────────────────────►│  AlMoutmag 1.0  │
│  Claude      │   MCP Streamable HTTP   │  (Windows 11)   │
│  Cursor      │   OAuth 2.1 + DPoP      │                 │
└──────────────┘                          └────────┬────────┘
                                                   │
                                          ┌────────┴────────┐
                                          │  سجل الأدوات    │
                                          │  (30 فئة)       │
                                          └────────┬────────┘
                                                   │
                                          ┌────────┴────────┐
                                          │  جهاز Windows   │
                                          │  (ملفات، تطبيقات│
                                          │   متصفح، ...)   │
                                          └─────────────────┘

البدء السريع

# 1. استنساخ وإنشاء venv
git clone https://github.com/USERNAME/almoutmag-1.0.git
cd almoutmag-1.0
python -m venv venv
.\venv\Scripts\Activate.ps1

# 2. تثبيت التبعيات
pip install -e ".[dev]"
playwright install chromium

# 3. توليد مفاتيح OAuth (Ed25519)
python scripts/gen_keys.py

# 4. نسخ الإعدادات وتعديلها
Copy-Item config.yaml.example config.yaml
Copy-Item .env.example .env
# عدّل config.yaml — اضبط dev_mode: true لأول تشغيل

# 5. تشغيل خادم التطوير
python scripts/dev_start.py
# الخادم يستمع على http://127.0.0.1:8452

طبقات الأمان العشر

1. OAuth 2.1 + DPoP — ربط الـ token بمفتاح Ed25519 من العميل

2. 5 مستويات danger_level (0=public، 4=دائماً مرفوض)

3. Safety Layer — deny by default، 60+ أمر آمن فقط

4. Audit Log — SQLite WAL + AES-256-GCM + HMAC-SHA256 chain

5. FIM — مراقب سلامة الملفات + kill switch (os._exit(99))

6. Rate Limiting — 100/دقيقة per IP، 1000/ساعة per token

7. Anomaly Detection — تنبيه عند 3x، حظر عند 5x

8. Honeytokens — مفاتيح وهمية للكشف عن الاختراق

9. Network Security — localhost فقط افتراضياً، Cloudflare Tunnel اختياري

10. Request ID + Structured Logging — UUID لكل طلب + إخفاء الـ secrets

الاعتماديات (12 فقط — صارم)

للتطوير: pytest، pytest-asyncio، ruff، mypy، pyinstaller.

الاختبارات

python -m pytest tests/ -v
python -m ruff check .
python -m mypy core/ server/

كل الاختبارات حيّة (LIVE) — ترسل طلبات HTTP فعلية عبر aiohttp.test_utils.TestClient. 213 ناجح (مقابل 164 في 1.0 — 49 اختباراً جديداً في tests/test_coding.py).

التوثيق

• docs/ARCHITECTURE.md — بنية النظام

• docs/SECURITY.md — نموذج الأمان ذو الـ 10 طبقات

• docs/MCP_COMPATIBILITY.md — كيف يتصل z.ai/Claude/Cursor

• docs/API.md — مرجع REST API

• docs/CODING_TOOLS.md — مرجع أدوات البرمجة في 1.1 (40+ أداة)

بناء .exe

python scripts/build_exe.py
# الناتج: dist/AlMoutmag.exe

المُحرّمات (18)

انظر docs/SECURITY.md للقائمة الكاملة. أبرزها:

• لا AI/LLM محلي

• لا subprocess مع shell=True

• لا eval()/exec() على مدخلات المستخدم بدون sandboxing

• لا danger_level=4 قابل للتجاوز

• لا middlewares بدون @web.middleware decorator

• لا اختبارات static grep فقط (كلها LIVE HTTP)

• لا dependencies إضافية خارج الـ 12 المحددة

License

MIT — © 2026 AlMoutmag Team