mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-04 22:49:23 +00:00
a237ebabba
* feat: adopt directory-based docs versioning with Edge channel Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com> * style: resolve linter issues --------- Co-authored-by: Cursor <cursoragent@cursor.com>
137 lines
8.3 KiB
Plaintext
137 lines
8.3 KiB
Plaintext
---
|
|
title: "خوادم MCP المخصصة"
|
|
description: "اربط خوادم MCP الخاصة بك بـ CrewAI AMP مع وصول عام أو مصادقة بمفتاح API أو OAuth 2.0"
|
|
icon: "plug"
|
|
mode: "wide"
|
|
---
|
|
|
|
يدعم CrewAI AMP الاتصال بأي خادم MCP يُنفّذ [Model Context Protocol](https://modelcontextprotocol.io/). يمكنك إحضار خوادم عامة لا تتطلب مصادقة، وخوادم محمية بمفتاح API أو رمز حامل، وخوادم تستخدم OAuth 2.0 للوصول المفوّض الآمن.
|
|
|
|
## المتطلبات المسبقة
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="حساب CrewAI AMP" icon="user">
|
|
تحتاج إلى حساب [CrewAI AMP](https://app.crewai.com) نشط.
|
|
</Card>
|
|
<Card title="رابط خادم MCP" icon="link">
|
|
رابط خادم MCP الذي تريد الاتصال به. يجب أن يكون الخادم متاحاً من الإنترنت ويدعم نقل Streamable HTTP.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## إضافة خادم MCP مخصص
|
|
|
|
<Steps>
|
|
<Step title="فتح الأدوات والتكاملات">
|
|
انتقل إلى **Tools & Integrations** في الشريط الجانبي الأيسر لـ CrewAI AMP، ثم اختر علامة تبويب **Connections**.
|
|
</Step>
|
|
|
|
<Step title="بدء إضافة خادم MCP مخصص">
|
|
انقر على زر **Add Custom MCP Server**. سيظهر مربع حوار مع نموذج التهيئة.
|
|
</Step>
|
|
|
|
<Step title="ملء المعلومات الأساسية">
|
|
- **Name** (مطلوب): اسم وصفي لخادم MCP (مثل "My Internal Tools Server").
|
|
- **Description**: ملخص اختياري لما يقدمه خادم MCP هذا.
|
|
- **Server URL** (مطلوب): الرابط الكامل لنقطة نهاية خادم MCP (مثل `https://my-server.example.com/mcp`).
|
|
</Step>
|
|
|
|
<Step title="اختيار طريقة المصادقة">
|
|
اختر إحدى طرق المصادقة الثلاث المتاحة بناءً على كيفية تأمين خادم MCP. راجع الأقسام أدناه لتفاصيل كل طريقة.
|
|
</Step>
|
|
|
|
<Step title="إضافة رؤوس مخصصة (اختياري)">
|
|
إذا كان خادم MCP يتطلب رؤوساً إضافية في كل طلب (مثل معرّفات المستأجر أو رؤوس التوجيه)، انقر على **+ Add Header** وقدم اسم الرأس وقيمته. يمكنك إضافة رؤوس مخصصة متعددة.
|
|
</Step>
|
|
|
|
<Step title="إنشاء الاتصال">
|
|
انقر على **Create MCP Server** لحفظ الاتصال. سيظهر خادم MCP المخصص الآن في قائمة الاتصالات وستكون أدواته متاحة للاستخدام في طواقمك.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## طرق المصادقة
|
|
|
|
### بدون مصادقة
|
|
|
|
اختر هذا الخيار عندما يكون خادم MCP متاحاً للجمهور ولا يتطلب أي بيانات اعتماد. هذا شائع للخوادم مفتوحة المصدر أو الخوادم الداخلية العاملة خلف VPN.
|
|
|
|
### رمز المصادقة
|
|
|
|
استخدم هذه الطريقة عندما يكون خادم MCP محمياً بمفتاح API أو رمز حامل.
|
|
|
|
<Frame>
|
|
<img src="/images/enterprise/custom-mcp-auth-token.png" alt="خادم MCP مخصص برمز مصادقة" />
|
|
</Frame>
|
|
|
|
| الحقل | مطلوب | الوصف |
|
|
|-------|-------|-------|
|
|
| **Header Name** | نعم | اسم رأس HTTP الذي يحمل الرمز (مثل `X-API-Key`، `Authorization`). |
|
|
| **Value** | نعم | مفتاح API أو رمز الحامل الخاص بك. |
|
|
| **Add to** | لا | أين يتم إرفاق بيانات الاعتماد — **Header** (افتراضي) أو **Query parameter**. |
|
|
|
|
<Tip>
|
|
إذا كان خادمك يتوقع رمز `Bearer` في رأس `Authorization`، عيّن Header Name إلى `Authorization` والقيمة إلى `Bearer <your-token>`.
|
|
</Tip>
|
|
|
|
### OAuth 2.0
|
|
|
|
استخدم هذه الطريقة لخوادم MCP التي تتطلب تفويض OAuth 2.0. سيتعامل CrewAI مع تدفق OAuth الكامل، بما في ذلك تحديث الرمز.
|
|
|
|
<Frame>
|
|
<img src="/images/enterprise/custom-mcp-oauth.png" alt="خادم MCP مخصص مع OAuth 2.0" />
|
|
</Frame>
|
|
|
|
| الحقل | مطلوب | الوصف |
|
|
|-------|-------|-------|
|
|
| **Redirect URI** | — | مُعبأ مسبقاً وللقراءة فقط. انسخ هذا الرابط وسجّله كرابط إعادة توجيه مصرّح به في مزود OAuth. |
|
|
| **Authorization Endpoint** | نعم | الرابط الذي يُوجَّه إليه المستخدمون لتفويض الوصول (مثل `https://auth.example.com/oauth/authorize`). |
|
|
| **Token Endpoint** | نعم | الرابط المستخدم لتبادل رمز التفويض برمز وصول (مثل `https://auth.example.com/oauth/token`). |
|
|
| **Client ID** | نعم | معرّف عميل OAuth الصادر من مزودك. |
|
|
| **Client Secret** | لا | سر عميل OAuth. غير مطلوب للعملاء العامين باستخدام PKCE. |
|
|
| **Scopes** | لا | قائمة نطاقات مفصولة بمسافات للطلب (مثل `read write`). |
|
|
| **Token Auth Method** | لا | كيفية إرسال بيانات اعتماد العميل عند تبادل الرموز — **Standard (POST body)** أو **Basic Auth (header)**. الافتراضي هو Standard. |
|
|
| **PKCE Supported** | لا | فعّل إذا كان مزود OAuth يدعم Proof Key for Code Exchange. موصى به لتحسين الأمان. |
|
|
|
|
<Info>
|
|
**اكتشاف تهيئة OAuth**: إذا كان مزود OAuth يدعم OpenID Connect Discovery، انقر على رابط **Discover OAuth Config** لملء نقاط نهاية التفويض والرمز تلقائياً من رابط `/.well-known/openid-configuration` الخاص بالمزود.
|
|
</Info>
|
|
|
|
#### إعداد OAuth 2.0 خطوة بخطوة
|
|
|
|
<Steps>
|
|
<Step title="تسجيل رابط إعادة التوجيه">
|
|
انسخ **Redirect URI** المعروض في النموذج وأضفه كرابط إعادة توجيه مصرّح به في إعدادات تطبيق مزود OAuth.
|
|
</Step>
|
|
|
|
<Step title="إدخال نقاط النهاية وبيانات الاعتماد">
|
|
املأ **Authorization Endpoint** و**Token Endpoint** و**Client ID**، واختيارياً **Client Secret** و**Scopes**.
|
|
</Step>
|
|
|
|
<Step title="تهيئة طريقة تبادل الرمز">
|
|
اختر **Token Auth Method** المناسبة. معظم المزودين يستخدمون الافتراضي **Standard (POST body)**. بعض المزودين القدامى يتطلبون **Basic Auth (header)**.
|
|
</Step>
|
|
|
|
<Step title="تفعيل PKCE (موصى به)">
|
|
حدد **PKCE Supported** إذا كان مزودك يدعمه. يضيف PKCE طبقة أمان إضافية لتدفق رمز التفويض وموصى به لجميع التكاملات الجديدة.
|
|
</Step>
|
|
|
|
<Step title="الإنشاء والتفويض">
|
|
انقر على **Create MCP Server**. سيتم توجيهك إلى مزود OAuth لتفويض الوصول. بمجرد التفويض، سيخزن CrewAI الرموز ويحدّثها تلقائياً حسب الحاجة.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## استخدام خادم MCP المخصص
|
|
|
|
بمجرد الاتصال، تظهر أدوات خادم MCP المخصص جنباً إلى جنب مع الاتصالات المدمجة في صفحة **Tools & Integrations**. يمكنك:
|
|
|
|
- **تعيين الأدوات للوكلاء** في طواقمك تماماً كأي أداة CrewAI أخرى.
|
|
- **إدارة الرؤية** للتحكم في أعضاء الفريق الذين يمكنهم استخدام الخادم.
|
|
- **تعديل أو إزالة** الاتصال في أي وقت من قائمة الاتصالات.
|
|
|
|
<Warning>
|
|
إذا أصبح خادم MCP غير قابل للوصول أو انتهت صلاحية بيانات الاعتماد، ستفشل استدعاءات الأدوات التي تستخدم ذلك الخادم. تأكد من استقرار رابط الخادم وتحديث بيانات الاعتماد.
|
|
</Warning>
|
|
|
|
<Card title="تحتاج مساعدة؟" icon="headset" href="mailto:support@crewai.com">
|
|
تواصل مع فريق الدعم للمساعدة في تهيئة خادم MCP المخصص أو استكشاف الأخطاء.
|
|
</Card>
|