# 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.

[![CI](https://github.com/USERNAME/almoutmag-1.0/actions/workflows/ci.yml/badge.svg)](https://github.com/USERNAME/almoutmag-1.0/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2026--07--28-green.svg)](https://modelcontextprotocol.io)
[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](#)
[![Tests](https://img.shields.io/badge/tests-213%20passed-brightgreen.svg)](#tests)

---

## 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](#v11-new-features-coding-tools--performance)
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

```powershell
# 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:

```bash
# 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`](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`](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

```powershell
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`](docs/ARCHITECTURE.md) — System architecture
- [`docs/SECURITY.md`](docs/SECURITY.md) — 10-layer security model
- [`docs/MCP_COMPATIBILITY.md`](docs/MCP_COMPATIBILITY.md) — How z.ai/Claude/Cursor connect
- [`docs/API.md`](docs/API.md) — REST API reference
- [`docs/CODING_TOOLS.md`](docs/CODING_TOOLS.md) — v1.1 coding tools reference (40+ tools)

### Build .exe

```powershell
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`](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   │
                                          │  (ملفات، تطبيقات│
                                          │   متصفح، ...)   │
                                          └─────────────────┘
```

### البدء السريع

```powershell
# 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`.

### الاختبارات

```powershell
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/ARCHITECTURE.md) — بنية النظام
- [`docs/SECURITY.md`](docs/SECURITY.md) — نموذج الأمان ذو الـ 10 طبقات
- [`docs/MCP_COMPATIBILITY.md`](docs/MCP_COMPATIBILITY.md) — كيف يتصل z.ai/Claude/Cursor
- [`docs/API.md`](docs/API.md) — مرجع REST API
- [`docs/CODING_TOOLS.md`](docs/CODING_TOOLS.md) — مرجع أدوات البرمجة في 1.1 (40+ أداة)

### بناء .exe

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

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

انظر [`docs/SECURITY.md`](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](LICENSE) — © 2026 AlMoutmag Team