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

Endpoint	Method	Description
/mcp	POST	MCP JSON-RPC 2.0 (initialize, tools/list, tools/call, ...)
/auth/token	POST	OAuth 2.1 token endpoint (DPoP-bound)
/auth/revoke	POST	Revoke access/refresh token
/auth/protected-resource	GET	RFC9728 metadata
/execute	POST	Execute single tool (REST)
/execute/stream	POST	SSE stream of tool output (v1.1)
/batch	POST	Execute multiple tools (REST)
/workflow	POST	Execute multi-step workflow
/tools	GET	List all tools
/openapi.json	GET	OpenAPI 3.1 spec
/docs	GET	Swagger UI
/health	GET	Liveness (no auth, includes tools_loaded)
/health/ready	GET	Readiness (no auth)
/metrics	GET	Prometheus metrics
/ws/monitor	WS	Real-time CPU/RAM/disk
/ws/events	WS	File/process/network events
/ws/audit	WS	Live audit log stream
/ws/code_session	WS	Live coding session (v1.1)

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.

Feature	Where	What it does
40+ coding tools	docs/CODING_TOOLS.md	Code reading, writing, execution, git, analysis, debugging, documentation. Defined in tools/ai/coding.py.
Caching layer	core/registry.py @cached_tool	Per-tool TTL cache. Inspect via cache_stats, clear via cache_clear (tools/system/cache.py).
SSE streaming	POST /execute/stream	Server-Sent Events stream of tool output — emits start, complete, error, blocked events. Ideal for code_run_python, code_run_tests, git_log.
WebSocket live coding	WS /ws/code_session	Per-session tempdir + write_file / read_file / list_files / run / close actions. Isolated and cleaned up on disconnect.
Tool composition	tools/workflows/pipes.py	pipe_run chains tools Unix-pipe-style (output of step N → _input of step N+1). filter_field and sort_by_field are post-processing steps.
Background jobs	tools/workflows/background_jobs.py	job_start_background, job_status, job_result, job_cancel, job_list — fire-and-poll for long-running tools.
Bearer dev shortcut	server/middleware.py	In dev_mode, Authorization: Bearer $DEV_TOKEN bypasses the DPoP proof requirement. Production traffic is unaffected.
tools_loaded field	GET /health	Health response now reports whether the tool registry finished loading.
AppKey migration	core/auth.py	Existing 1.0 AppKey clients continue to work; migration is automatic on first token refresh.
213 LIVE tests	tests/test_coding.py (+49)	Up from 164 in 1.0. All tests are LIVE HTTP — no static grep assertions.

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

Dependencies (12 — strict)

Package	Purpose
fastmcp	MCP server framework
aiohttp	HTTP server + WebSocket
aiosqlite	Async SQLite (audit log)
cryptography	AES-256-GCM, Ed25519, HMAC
pydantic	Settings + validation
structlog	Structured JSON logging
psutil	System info
pyyaml	YAML config
pywinauto	Windows UI automation
playwright	Browser automation
Pillow	Image processing
pytesseract	OCR

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 فقط — صارم)

الحزمة	الغرض
fastmcp	إطار خادم MCP
aiohttp	خادم HTTP + WebSocket
aiosqlite	SQLite غير متزامن (سجل التدقيق)
cryptography	AES-256-GCM، Ed25519، HMAC
pydantic	الإعدادات + التحقق
structlog	سجل JSON منظّم
psutil	معلومات النظام
pyyaml	إعدادات YAML
pywinauto	أتمتة واجهة Windows
playwright	أتمتة المتصفح
Pillow	معالجة الصور
pytesseract	OCR

للتطوير: 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