<div align="center">

<img src="assets/ms-ar.png" alt="mcp-arabic-ms-word Logo" width="200" style="border-radius: 16px; margin-bottom: 15px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);" />

# خادم خبير وورد العربي — MCP Arabic Microsoft Word Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/mcp-arabic-ms-word.svg)](https://www.npmjs.com/package/mcp-arabic-ms-word)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol--v1.0-purple.svg)](https://modelcontextprotocol.io)
[![Author](https://img.shields.io/badge/Author-MarwanDevSpace-orange.svg)](https://github.com/MarwanDevSpace)
[![mcp-arabic-ms-word MCP server](https://glama.ai/mcp/servers/MarwanDevSpace/mcp-arabic-ms-word/badges/score.svg)](https://glama.ai/mcp/servers/MarwanDevSpace/mcp-arabic-ms-word)

**خادم بروتوكول MCP المتقدم (WordMasterAgent) المتخصص في إنشاء وتنسيق وحقن وفحص وإصلاح نصوص وتفكيك شفرات XML لمستندات Microsoft Word بدعم كامل ودقيق للغة العربية والاتجاه من اليمين إلى اليسار (RTL)، مزود بنظام RAG للتفكير المنطقي، وجراحة OpenXML وضبط BiDi، وفحص الصفحات الصوري (Pages/)، وبروتوكول نظافة مساحة العمل.**

</div>

---

## 🌟 المحتويات | Table of Contents

- [العربية (Arabic)](#-العربية)
  - [المميزات الرئيسية](#-المميزات-الرئيسية)
  - [نظام التفكير المنطقي RAG واستدعاء المقاصد الذكية](#-نظام-التفكير-المنطقي-rag-واستدعاء-المقاصد-الذكية)
  - [حل معضلة انحراف العناوين (BiDi OpenXML Surgery)](#-حل-معضلة-انحراف-العناوين-bidi-openxml-surgery)
  - [المعاينة الصورية للصفحات ونظافة المجلد (Pages/)](#-المعاينة-الصورية-للصفحات-ونظافة-المجلد-pages)
  - [فهرس الأدوات المتاحة (15 Tools)](#-فهرس-الأدوات-المتاحة-15-tools)
  - [طريقة التركيب والتشغيل عبر npx](#-طريقة-التركيب-والتشغيل-عبر-npx)
  - [إعدادات العميل (mcp_config.json)](#-إعدادات-العميل-mcp_configjson)
- [English Section](#-english-version)
  - [Key Features](#key-features)
  - [Tools Inventory (15 Tools)](#tools-inventory)
  - [Installation & Setup](#installation--setup)

---

## 🇸🇦 العربية

### 🚀 المميزات الرئيسية

1. **نظام التفكير المنطقي واسترجاع المعرفة التوليدي (`RAG Knowledge & Intent Engine`)**:
   - استرجاع دلالي لأنماط المستندات (خطاب رسمي، بحث أكاديمي، تقرير تنفيذي، عقد قانوني، دليل سياسات، محضر اجتماع).
   - استنتاج الهيكل المناسب، تدرج العناوين، توزيع الجداول، وحساب معامل الثقة وخطوات التفكير المنطقي.
2. **جراحة OpenXML وإصلاح انحراف العناوين والنصوص (`BiDi OpenXML Surgery`)**:
   - القضاء التام على انحراف العناوين نحو اليسار بفضل ضبط خصائص الفقرة `<w:jc w:val="right"/>` ومنع تضارب `<w:bidi/>`.
   - منع انفصال العناوين المعلقة عن متونها في نهايات الصفحات (`w:keepNext`).
   - حماية الآيات القرآنية والأحاديث الشريفة من الانشطار عبر فواصل الصفحات (`w:keepLines`).
   - ضبط محاذاة المتون العربية بهوامش متطابقة (`w:bidi` + `w:jc="both"`).
3. **نظام المعاينة الصورية للصفحات (`Pages/` Directory)**:
   - تحويل المستند إلى PDF وتوليد صور عالية الدقة (150/300 DPI) لكل صفحة داخل مجلد فرعي نظيف ومستقل باسم **`Pages/`**.
   - فحص وكشف العيوب البصرية (العناوين المعلقة، الفراغات الزائدة، توازن الأسطر).
4. **بروتوكول نظافة مساحة العمل (Clean Workspace Protocol)**:
   - عدم إنشاء أي ملفات بايثون أو سكربتات مبعثرة في مجلد المستخدم الأساسي، وحصر مخرجات العمل في المستند الأصلي وملف PDF ومجلد `Pages/`.
5. **دعم كامل للتيبوغرافيا وإصلاح النصوص العربية**:
   - تصحيح الأقواس المقلوبة، توحيد الأرقام (شرقية/غربية)، وتنسيق همزات الألف والياء.
6. **أتمتة ذكية دون الحاجة لأوامر نصية (`Zero Slash-Commands`)**:
   - محرك تحليل المقاصد (`resolve_and_execute_document_intent`) يفهم طلباتك النصية العادية ويقوم بتوليد وتصحيح المستند تلقائياً استناداً للـ RAG.

---

### 🧠 نظام التفكير المنطقي RAG واستدعاء المقاصد الذكية

يحتوي السيرفر على محرك معرفي RAG داخلي يقوم بتفسير وصف المستخدم وتحويله إلى خطة توليد هندسية دقيقة:
- **تحديد النمط المعماري (Archetype)**: مطابقة الطلب مع أنماط الوثائق المعتمدة.
- **اختيار الخط والألوان**: ضبط الخطوط العربية (`Amiri` للخطابات، `Traditional Arabic` للأبحاث، `Cairo` للتقارير) ودرجات الألوان الرسمية (`#003366`, `#1F4E78`).
- **بناء الأقسام والجداول والترقيم**: إنشاء الهيكل الكامل تلقائياً مع تذييل الصفحات الديناميكي.
- **جراحة BiDi التلقائية**: تطبيق مسار الجراحة فوراً لضمان خلو المستند من أي انحراف.

---

### 🔬 حل معضلة انحراف العناوين (BiDi OpenXML Surgery)

في بنية OpenXML، يؤدي وضع `<w:bidi/>` داخل خصائص الفقرة مع `<w:jc w:val="right"/>` إلى تفسيره كجهة يمنى منطقية لقارئ LTR، مما يجعله يعرض فيزيائياً في أقصى يسار الصفحة!

**المعادلة المعتمدة في السيرفر**:
- **العناوين**: `<w:jc w:val="right"/>` + `<w:keepNext/>` + `<w:widowControl/>` مع وسم `<w:rtl/>` في مسارات النصوص.
- **متون الفقرات**: `<w:bidi/>` + `<w:jc w:val="both"/>` مع وسم `<w:rtl/>`.
- **الآيات والأحاديث**: `<w:keepLines/>` + `<w:bidi/>` + تمييز لوني.
- **المقاطع الإنجليزية**: `<w:jc w:val="left"/>` خالية تماماً من وسوم `bidi` و `rtl`.

---

### 🛠️ فهرس الأدوات المتاحة (15 Tools)

| اسم الأداة | الوصف والتطبيق |
|---|---|
| `resolve_and_execute_document_intent` | توليد مستند كامل مبني على نظام RAG للتفكير المنطقي من خلال الوصف العادي. |
| `enforce_arabic_bidi_and_typography` | جراحة OpenXML وضبط محاذاة العناوين لليمين ومنع انشطار الآيات وحماية المتون وتوليد الترقيم. |
| `audit_and_render_document_pages` | تحويل المستند لصور عالية الدقة داخل مجلد `Pages/` وفحص العيوب البصرية والهيكلية. |
| `repair_arabic_text_formatting` | فحص وإصلاح عيوب التيبوغرافيا العربية للأقواس المقلوبة والأرقام والألف والياء والمسافات. |
| `decompress_and_modify_word_xml` | تفكيك أرشيف docx والتعديل الجراحي بالـ Regex على أي ملف XML داخلي (document, styles, numbering). |
| `create_word_document` | إنشاء مستند `.docx` جديد بتحديد المقاس والبهامش والخط والاتجاه الافتراضي. |
| `add_paragraph_to_document` | إدراج فقرة نصية منسقة (الخط، الحجم، اللون، الاتجاه، الكشيدة، المسافات). |
| `add_heading_to_document` | إدراج عناوين رئيسية أو فرعية (H1-H6) بلون وتنسيق مخصص. |
| `add_table_to_document` | إدراج جدول بيانات متوافق مع الاتجاه العربي مع ألوان الهيدر والصفوف. |
| `add_image_to_document` | تضمين صور (PNG/JPEG) داخل المستند بأبعاد ومحاذاة محددة. |
| `add_header_footer_to_document` | ضبط رأس وتذييل المستند وترقيم الصفحات العربي (`صفحة X من Y`). |
| `inspect_word_document` | فحص مستند وورد واستخراج عدد الفقرات والعناوين والجداول والخطوط المكتشفة. |
| `convert_word_to_markdown` | استخراج محتوى مستند الوورد وتحويله إلى صيغة Markdown منظمة. |
| `inject_template_data` | دمج بيانات JSON في قالب وورد يحتوي على متغيرات `{placeholder}`. |
| `modify_word_xml_element` | استبدال نصوص أو عناصر شفرة WordprocessingML XML مباشرة. |

---

### 📦 طريقة التركيب والتشغيل عبر npx

```bash
npx -y mcp-arabic-ms-word@latest
```

---

### ⚙️ إعدادات العميل القياسية (`mcp_config.json`)

```json
{
  "mcpServers": {
    "mcp-arabic-ms-word": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-arabic-ms-word@latest"
      ]
    }
  }
}
```

---

## 🇬🇧 English Version

### Key Features

- **RAG Knowledge & Cognitive Intent Engine**: Semantic archetype retrieval for instant high-precision document synthesis with structured reasoning plans.
- **BiDi OpenXML Surgery Engine**: Deep OpenXML surgery preventing heading drift, orphan headings (`keepNext`), split verses (`keepLines`), and ensuring clean margin-to-margin body justification.
- **Visual Page Audit & `Pages/` Workflow**: Automatically renders Word documents to high-resolution page images into an isolated `Pages/` directory with automated layout defect diagnostics.
- **Clean Workspace Protocol**: Prevents file pollution by keeping all scratch files internal and delivering pristine `.docx`, `.pdf`, and `Pages/` artifacts.
- **Arabic Text Repair Engine**: Automatic correction of inverted brackets in RTL text, digit standardization (Eastern/Western), whitespace trimming, and Alef/Yeh normalization.
- **Universal WordMasterAgent Architecture**: Governed by [`AGENTS.md`](AGENTS.md) orchestrating 15 specialized MCP tools across 7 master skills.

---

## 📜 الترخيص والملكية | License & Author

- **المؤلف والحقوق | Author**: **[MarwanDevSpace](https://github.com/MarwanDevSpace)**
- **الترخيص | License**: [MIT License](LICENSE)