[![CI](https://github.com/marsaplatform/erx-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/marsaplatform/erx-mcp/actions/workflows/ci.yml)

![واجهة ERX الحالية](docs/media/current-home.png)

<h1 align="center">ERX — Egypt Research Commons</h1>

<p align="center"><strong>تابع الشأن المصري. ارجع إلى المصدر. · Follow Egyptian public affairs. Return to the source.</strong></p>

<p align="center">
  محرك بحث وأرشيف للأخبار المصرية والوثائق والبيانات العامة، للباحثين والصحفيين.<br>
  Search Egyptian news, public records and data with every result tied to its source.
</p>

<p align="center">
  <a href="https://egypt-research.marsaplatform.com">الموقع</a> ·
  <a href="https://egypt-research.marsaplatform.com/explore">البحث</a> ·
  <a href="https://egypt-research.marsaplatform.com/docs">التوثيق</a> ·
  <a href="BRAND.md">الهوية</a> ·
  <a href="docs/architecture.md">المعمارية</a>
</p>

![انتقال فعلي من الرئيسية إلى مستكشف المصادر](docs/media/current-tour.gif)

لقطات محلية بتاريخ 24 أكتوبر 2026، بكتالوج المصادر المرفق ومن دون استيراد وثائق. الأرقام في الصور تخص هذه النسخة التجريبية، وليست إحصاءات الخدمة المستضافة.

نتائج الفحص موثقة بتاريخها في [تقرير المراجعة](docs/CODE_REVIEW_2026-10-24.md).

## ابحث في مصر، لا في الضوضاء

ERX موجه للباحث والصحفي الذي يبدأ بسؤال عن الشأن المصري: قرار حكومي، مؤشر
اقتصادي، تشريع، قضية حقوقية، خدمة عامة، أو طريقة تناول المصادر لخبر واحد.
يجمع المواد الإخبارية والوثائق الرسمية والقانونية والأكاديمية والبيانات العامة،
ثم يربط كل نتيجة بالرابط الأصلي وتاريخ النشر وسياق الظهور وسبب الترتيب.

ERX ليس وسيلة إعلام ولا يقرر صحة الادعاء نيابة عن الباحث. هو مساحة بحث قابلة
للمراجعة تساعدك على الانتقال من **السؤال → المصادر → الأدلة → الاستشهاد**.

## ماذا يمكنك أن تبحث؟

| الملف | أمثلة عملية |
|---|---|
| السياسة والاقتصاد | تتبع قرار حكومي، مقارنة التغطية، وربطه بالموازنة أو المؤشرات العامة |
| القانون والحقوق | الوصول إلى التشريع أو الحكم أو البيان الأصلي ومتابعة تطور القضية |
| المجتمع والخدمات العامة | بحث الصحة والتعليم والعمل والسكان عبر الأخبار والبيانات |
| الإعلام والخطاب العام | مقارنة العناوين والمواقف وتنوع الناشرين عبر فترة زمنية |

ابدأ من [واجهة البحث](https://egypt-research.marsaplatform.com/explore) دون حساب. ويمكن للمطورين
ووكلاء الذكاء الاصطناعي استخدام طبقة MCP وREST نفسها بعد ذلك — مع
[مكتبتَي عميل Python وTypeScript](clients/)، و[دليل الاستخدام](docs/USAGE.md)،
ومعرّفات استشهاد ثابتة وأمر `dataset-dump` لتصدير نسخة أرشيف قابلة للاستشهاد.

| ما الذي يقدمه ERX؟ | كيف يبقى قابلًا للمراجعة؟ |
|---|---|
| بحث عربي نصي ودلالي | سبب ترتيب واضح لكل نتيجة |
| مقارنة التغطيات والادعاءات | رابط الوثيقة والناشر والتاريخ |
| خط زمني وكيانات وأحداث | فصل تاريخ الحدث عن النشر والأرشفة |
| بيانات عامة حية | الترخيص ووقت الجلب والرابط الأصلي |
| تصدير RIS وBibTeX وCSV وJSONL | نقل المراجع دون فقدان المصدر |

## ابدأ خلال دقيقة

- **في المتصفح:** [واجهة البحث](https://egypt-research.marsaplatform.com/explore) مفتوحة دون حساب.
- **لوكيلك الذكي (MCP) أو REST:** النسخة المستضافة تحتاج **مفتاحًا مجانيًا**: سجّل بريدك من
  [صفحة البداية](https://egypt-research.marsaplatform.com/#signup)، وأنشئ مفتاحًا من لوحة المشترك
  (يظهر مرة واحدة)، ثم أرسله في ترويسة `Authorization: Bearer <key>` (أو `X-API-Key`).
  الخطة المجانية: 50,000 استدعاء شهريًا. التشغيل الذاتي لا يحتاج مفتاحًا.

نقطة MCP المستضافة (Streamable HTTP):

```text
https://egypt-research.marsaplatform.com/mcp
```

**Claude Code**

```bash
claude mcp add --transport http egypt-research https://egypt-research.marsaplatform.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**Cursor** (`~/.cursor/mcp.json`) و**VS Code** (`.vscode/mcp.json` مع `"servers"` و`"type": "http"`):

```json
{
  "mcpServers": {
    "egypt-research": {
      "url": "https://egypt-research.marsaplatform.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`، عبر `mcp-remote`):

```json
{
  "mcpServers": {
    "egypt-research": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://egypt-research.marsaplatform.com/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}
```

أو شغّله محليًا عبر stdio دون مفتاح (Node.js 24 أو أحدث):

```bash
npx -y egypt-research-mcp serve --transport stdio
```

جرّب أن تسأل وكيلك: «تتبّع تغطية قرار رفع أسعار الوقود خلال الشهر الماضي مع المصادر»، أو
«قارن كيف تناولت المصادر الرسمية والصحفية قانون العمل الجديد، وصدّر المراجع بصيغة BibTeX».

### English quick start

ERX (Egypt Research Commons) is a source-grounded research archive and MCP server for Egyptian
public affairs: 35 operational sources, 21 read-only `egypt_*` MCP tools, and every result tied to
its original URL, publisher and dates.

- **Web search:** <https://egypt-research.marsaplatform.com/explore> — open, no account.
- **Hosted MCP:** `https://egypt-research.marsaplatform.com/mcp` and REST `…/api/v1` need a
  **free API key** (sign up at <https://egypt-research.marsaplatform.com/#signup>, create a key in
  the dashboard, send `Authorization: Bearer <key>`). Free plan: 50,000 calls/month.
- **Self-hosted (no key):** `npx -y egypt-research-mcp serve --transport stdio` (Node ≥ 24).
- Connect snippets for Claude Code, Claude Desktop, Cursor and VS Code are above and in
  [docs/USAGE.md](docs/USAGE.md). Health: `/health` · status: `/status.html` · API docs: `/docs`.

## السطوح المتاحة

| السطح | المسار | الاستخدام |
|---|---|---|
| الصفحة الرئيسية | `/` | تعريف المنتج وحالة الأرشيف |
| واجهة الباحث | `/explore` | بحث عربي دون حساب، مع أمثلة استعلامات موجّهة |
| خريطة المعرفة | `/knowledge` | كيانات وأحداث وادعاءات |
| من نحن | `/about` | المهمة والمنهجية والجهة المشغّلة |
| الخصوصية | `/privacy` | ما لا نسجّله ولا نتتبعه |
| السلامة للباحثين | `/safety` | إرشادات البحث في الموضوعات الحساسة |
| توثيق API | `/docs` | المسارات وأمثلة الاستخدام مع سنيبتات التثبيت |
| MCP | `/mcp` | Streamable HTTP للوكلاء |
| REST API | `/api/v1` | تكاملات مستقرة، ترقيم، OpenAPI 3.1، رؤوس معدّل |
| خلاصة RSS | `/feed.xml` | أحدث الوثائق للمتابعة |
| الحالة | `/status.html` | لوحة حالة بشرية للأرشيف |
| الجاهزية | `/readyz` | فحص سلامة قاعدة البيانات |
| المقاييس | `/metrics` | مقاييس Prometheus |

## أدوات MCP

### البحث والتتبع

| الأداة | الوظيفة |
|---|---|
| `egypt_search` | بحث حسب النص ونوع المصدر والفترة |
| `egypt_hybrid_search` | بحث نصي ودلالي مع تفسير الترتيب |
| `egypt_get_document` | وثيقة كاملة مع بيانات الاستشهاد |
| `egypt_research_dossier` | نتائج وخط زمني وكيانات وادعاءات في طلب واحد |
| `egypt_trace_claim` | تتبع الادعاء إلى الأدلة التي أوردته |
| `egypt_compare_claims` | تجميع الادعاءات المتشابهة ومقارنة المواقف |

### المقارنة والتنظيم

| الأداة | الوظيفة |
|---|---|
| `egypt_compare_sources` | مقارنة التغطية حسب نوع المصدر |
| `egypt_build_timeline` | بناء خط زمني موثق |
| `egypt_list_stories` | قصص متقاربة مع تنوع الناشرين |
| `egypt_find_entities` | الكيانات ومواضع ظهورها |
| `egypt_list_events` | الأحداث المؤرخة ووثائقها |
| `egypt_get_daily_brief` | مواد يوم محدد وتنوع مصادرها |
| `egypt_list_sources` | عرض كتالوج المصادر التشغيلية |
| `egypt_get_source_profile` | بيانات المصدر وصحة الجمع |

### البيانات والتصدير

| الأداة | الوظيفة |
|---|---|
| `egypt_list_live_datasets` | كتالوج مجموعات البيانات العامة |
| `egypt_get_live_data` | جلب مؤشر أو سجل حي مع بيانات المصدر |
| `egypt_compare_live_data` | مقارنة سلاسل مع تنبيه اختلاف المنهجيات |
| `egypt_live_source_health` | فحص صحة موفري البيانات الحية |
| `egypt_export_references` | تصدير RIS وBibTeX وCSV وJSONL |
| `egypt_get_coverage` | تغطية الأرشيف وصحة المصادر |
| `egypt_save_research_query` | حفظ استعلام متابعة محليًا؛ معطلة على نقطة MCP العامة |

توجد أيضًا موارد `egypt://sources` و`egypt://taxonomy` و`egypt://methodology`،
وprompts للبحث المنظم والتحقق من الادعاءات. راجع [`src/mcp.ts`](src/mcp.ts)
للتعريف التنفيذي الكامل.

## كيف يعمل

<p align="center">
  <img src="docs/media/erx-data-flow.svg" width="960" alt="تدفق بيانات ERX من المصادر المباشرة إلى واجهة الويب وMCP وREST والتصدير">
</p>

- يجمع ERX من 35 مصدرًا تشغيليًا رسميًا وقانونيًا وأكاديميًا وإحصائيًا وحقوقيًا
  وإخباريًا وحقوقيًا. المصدر المغلق أو المتوقف لا يظهر في الكتالوج التشغيلي.
- يحترم `robots.txt`، ويطبّق تأخيرًا مستقلًا لكل مصدر وحدودًا للحجم والصفحات.
- يستخرج HTML وPDF، ويستخدم OCR عربيًا محدود الموارد عند غياب طبقة النص.
- يحتفظ بإصدارات الوثيقة عند تغير محتواها وبسجل لكل عملية جمع.
- يستبعد الرياضة والترفيه والأخبار الدولية غير المرتبطة بمصر من البحث مع إبقائها
  في الأرشيف للمراجعة.
- يستخدم SQLite FTS5 وتمثيلًا دلاليًا محليًا قابلًا للتفسير، مع دعم اختياري لـ
  Gemini Embeddings عبر `GEMINI_API_KEY`.

التفاصيل: [المعمارية](docs/architecture.md) · [التشغيل](docs/operations.md) ·
[نموذج التهديد](docs/threat-model.md).

## التطوير المحلي

يتطلب Node.js 24 أو أحدث وnpm.

```bash
git clone https://github.com/marsaplatform/erx-mcp.git
cd erx-mcp
npm ci
npm run build
node dist/cli.js init
node dist/cli.js seed
node dist/cli.js serve --transport http --host 127.0.0.1 --port 8000
```

جمع البيانات وبناء الفهرس:

```bash
node dist/cli.js ingest
node dist/cli.js audit-sources --concurrency 10
node dist/cli.js index --provider local
node dist/cli.js rebuild-stories
node dist/cli.js rebuild-events
node dist/cli.js restore-excluded
node dist/cli.js health
node dist/cli.js status
```

أو عبر Docker:

```bash
docker compose build
docker compose run --rm egypt-research node dist/cli.js seed
docker compose up -d
```

## الاختبارات والإصدار

```bash
npm run check
npm test
npm run test:coverage
npm run build
npm run release:check
```

عند إنشاء tag، ينشر المشروع حزمة npm وبيانات MCP Registry وصورة متعددة
المعماريات على GitHub Container Registry. راجع
[قائمة الإطلاق](docs/launch-checklist.md) و[تقرير المراجعة الحالي](docs/CODE_REVIEW_2026-10-24.md).

## حدود المنهجية

- ERX لا يمنح المصادر درجة حقيقة آلية.
- تكرار الادعاء لا يعني تحققًا مستقلًا.
- تجميع القصص تشابه نصي مساعد، وليس حكمًا تحريريًا.
- الرابط الأصلي يظل المرجع النهائي.
- الكود مرخص MIT؛ حقوق المواد المفهرسة تبقى لأصحابها.

## مشاريع مرسى الشقيقة · Sibling Marsa projects

| المشروع | ما هو | الرابط |
|---|---|---|
| **Atlas MCP · أطلس** | معلومات الخدمات والإحالة للهجرة واللجوء في مصر بمصادرها · service & referral information for migration and asylum in Egypt | MCP: <https://atlas.marsaplatform.com/mcp> · [GitHub](https://github.com/marsaplatform/atlas-mcp) |
| **Malja MCP · ملجأ** | بيانات إنسانية موثّقة (UNHCR، البنك الدولي، HDX، ReliefWeb) · trusted humanitarian open data | <https://spaces.marsaplatform.com/s/k3sb9ww3dj/> |
| **Marsa Spaces · مساحات مرسى** | نشر صفحات ثابتة بروابط عامة، مع خادم MCP لكل مساحة · static publishing with a per-space MCP server | <https://spaces.marsaplatform.com> · [GitHub](https://github.com/marsaplatform/marsa) |

كل المشاريع من [مرسى](https://marsaplatform.com/products). · All projects: <https://marsaplatform.com/products>.

## الهوية والمساهمة

يشرح [دليل الهوية](BRAND.md) العلامة، الألوان، نبرة الصوت، والاستخدام الصحيح
للشعار. للمساهمة راجع [CONTRIBUTING.md](CONTRIBUTING.md) و
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). للإبلاغ الأمني استخدم
[SECURITY.md](SECURITY.md).

<p align="center">
  <img src="docs/media/brand-board.png" width="100%" alt="لوحة الهوية البصرية لـ ERX">
</p>

<p align="center"><strong>اسأل. قارن. استشهد.</strong></p>

## Repository resources · موارد المستودع

- [License / الترخيص](LICENSE)

## Company container image

The maintained container is published under the company account and linked to
[`marsaplatform/erx-mcp`](https://github.com/marsaplatform/erx-mcp).

```sh
docker pull ghcr.io/marsaplatform/erx-mcp:latest
```

Use the **container-release** workflow to publish the current source.
`latest` tracks stable releases and manual snapshots; `sha-…` tags identify
the source commit. The old personal-account packages have been removed; use
the company installation URL above. Publishing does not change repository visibility.

### Versioned updates

See [container releases and migration](docs/container-releases.md) for numbered
versions, automatic release publishing, runtime verification, and the updated
company installation commands.